pd4ml 1.0.0 → 1.1.1

data/lib/pd4ml/installer.rb

@@ -9,9 +9,10 @@ require 'time'
 module Pd4ml
   # Downloads a PD4ML build from the PD4ML Maven repository and makes it the gem's default:
   #
-  #   pd4ml install                    the most recent 4.* release
+  #   pd4ml install                    the most recent release from MINIMUM_VERSION (4.2.0) on;
+  #                                    until there is one, the most recent 4.2.x snapshot
   #   pd4ml install --snapshots        the most recent 4.* build, snapshots included
-  #   pd4ml install 4.0.23fx2          an exact version
+  #   pd4ml install 4.1.2              an exact version
   #
   # or Pd4ml.install from code. The jar is stored in the user's cache directory (PD4ML_HOME to
   # choose another) with the Bouncy Castle jars PD4ML needs for encryption and signing, every
@@ -26,6 +27,9 @@ module Pd4ml
     BOUNCYCASTLE = %w[bcprov-jdk18on bcpkix-jdk18on bcutil-jdk18on].freeze
     MANIFEST = 'installed.json'
     VERSION_PATTERN = /\A(\d+)\.(\d+)\.(\d+)(?:fx(\d+)(?:a(\d+))?)?(-jakarta)?(-SNAPSHOT)?\z/
+    # The oldest PD4ML a plain install takes: the gem's PD4ML 4.2 API (read_eml/read_mht,
+    # add_allowed_resource_location, add_metadata, the DOM API) needs it.
+    MINIMUM_VERSION = '4.2.0'
 
     module_function
 
@@ -54,20 +58,55 @@ module Pd4ml
       sort_versions(candidates).last
     end
 
+    # The version a plain install takes: the most recent release of the minimum's major line (4.*)
+    # at least `minimum`; while there is none, the most recent snapshot of the minimum's line
+    # (4.2.x for 4.2.0); while there is none of those either (the -jakarta variant has no 4.2
+    # build yet), the most recent 4.* release, as before. So installs move to the release once it
+    # is out, and snapshots of later lines (or a 5.x) are never picked by accident. With
+    # `jakarta`, a -jakarta variant by that rule if there is one, else the plain build of the same
+    # rule: PD4ML 4.2 publishes no -jakarta variant, its builds contain the Jakarta tag library
+    # (com.pd4ml.taglib.jakarta); only without either, the most recent -jakarta release.
+    def default_version(versions, jakarta: false, minimum: MINIMUM_VERSION)
+      min = version_key(minimum)
+      (jakarta ? [true, false] : [false]).each do |variant|
+        candidates = versions.select do |v|
+          k = version_key(v)
+          k && k[0] == min[0] && v.include?('-jakarta') == variant
+        end
+        releases = candidates.select { |v| !v.end_with?('-SNAPSHOT') && (version_key(v) <=> min) >= 0 }
+        return sort_versions(releases).last unless releases.empty?
+
+        snapshots = candidates.select { |v| v.end_with?('-SNAPSHOT') && version_key(v)[0, 2] == min[0, 2] }
+        return sort_versions(snapshots).last unless snapshots.empty?
+      end
+      select_version(versions, major: min[0], jakarta: jakarta)
+    end
+
     # The versions the repository lists.
     def available_versions(repository = REPOSITORY)
-      fetch("#{repository}/#{GROUP_PATH}/maven-metadata.xml").scan(%r{<version>([^<]+)</version>}).flatten.map(&:strip)
+      parse_versions(fetch("#{repository}/#{GROUP_PATH}/maven-metadata.xml"))
     end
 
+    # The versions a maven-metadata.xml document lists.
+    def parse_versions(xml) = xml.scan(%r{<version>([^<]+)</version>}).flatten.map(&:strip)
+
     # ------------------------------------------------------------------------------ install
 
     # Downloads a PD4ML build (unless already there) and makes it the default one; returns the
-    # jar's path. version: 'latest' (the most recent 4.* release; with snapshots: true, the most
-    # recent 4.* build) or an exact one such as '4.0.23fx2'.
+    # jar's path. version: 'latest' (default_version: the most recent release from MINIMUM_VERSION
+    # on, else the most recent 4.2.x snapshot; with snapshots: true, the most recent 4.* build) or
+    # an exact one such as '4.1.2' or '4.0.23fx2'.
     def install(version = 'latest', snapshots: false, jakarta: false, repository: REPOSITORY, home: nil,
                 force: false, quiet: false, bouncycastle: true)
       home ||= default_home
-      version = select_version(available_versions(repository), snapshots: snapshots, jakarta: jakarta) if version == 'latest'
+      if version == 'latest'
+        versions = available_versions(repository)
+        version = if snapshots
+                    select_version(versions, snapshots: true, jakarta: jakarta)
+                  else
+                    default_version(versions, jakarta: jakarta)
+                  end
+      end
       name = jar_name(version, repository)
       jar = File.join(home, name)
       download("#{repository}/#{GROUP_PATH}/#{version}/#{name}", jar, force, quiet)

data/lib/pd4ml/java.rb

@@ -42,7 +42,9 @@ module Pd4ml
 
   # A Java object living in the bridge. Call its Java methods by their Java names or in Ruby
   # style (`size.rotate`, `pd.set_page_size(...)`, `pd.demo_mode?`). Public fields: `obj[:width]`
-  # / `obj[:width] = v`. Released in Java when garbage collected.
+  # / `obj[:width] = v`. Released in Java when garbage collected. The DOM API's objects
+  # (com.pd4ml.dom) return their Java lists and sets as Ruby Arrays, maps as Hashes
+  # (`doc.query_selector_all('p').each { ... }`); `call_java` returns them as they are.
   class JavaObject < BasicObject
     def initialize(bridge, handle, java_class, enum_name)
       @bridge = bridge
@@ -110,7 +112,9 @@ module Pd4ml
       ::Kernel.raise ::NoMethodError, "set Java fields with obj[:#{name.to_s.chomp('=')}] = value" if name.to_s.end_with?('=')
       ::Kernel.raise ::ArgumentError, 'Java methods take no block' if block
 
-      @bridge.call(self, Naming.resolve(@bridge, @java_class, name, false), args)
+      result = @bridge.call(self, Naming.resolve(@bridge, @java_class, name, false), args)
+      # the DOM API's lists, sets and maps are snapshots: Ruby Arrays and Hashes
+      @java_class.start_with?('com.pd4ml.dom.') ? Java.to_ruby(result) : result
     end
 
     def respond_to_missing?(_name, _include_private = false) = true
@@ -205,5 +209,21 @@ module Pd4ml
 
       Bridge.get.proxy(iface, &block)
     end
+
+    # A Java collection (List, Set...) as a Ruby Array and a Java Map as a Hash, in one or two
+    # bridge calls; any other value as it is.
+    def self.to_ruby(value)
+      return value unless value.is_a?(JavaObject) && value.java_class.start_with?('java.util.')
+
+      if value.instance_of_java?('java.util.Collection')
+        value.call_java('toArray')
+      elsif value.instance_of_java?('java.util.Map')
+        keys = value.call_java('keySet').call_java('toArray')
+        values = value.call_java('values').call_java('toArray')
+        keys.zip(values).to_h
+      else
+        value
+      end
+    end
   end
 end

data/lib/pd4ml/pd4ml.rb

@@ -5,7 +5,9 @@ module Pd4ml
   # engine by default. Every Java method is available by its Java name or in Ruby style
   # (`set_page_size`, `add_style`, `use_ttf`); these take Ruby I/O: read_html (a path, URL or
   # binary String/IO), read_html_string, write_pdf/write_docx/write_rtf (the document returned as
-  # a binary String, or written to a path or IO), render_as_images and monitor_progress_with (a block).
+  # a binary String, or written to a path or IO), render_as_images and monitor_progress_with (a block);
+  # read_eml/read_mht (e-mail messages, saved web pages) as read_html. get_document and layout (the
+  # DOM API, v42 engine) return com.pd4ml.dom objects, whose lists come back as Ruby Arrays.
   #
   #   pd = Pd4ml::PD4ML.new
   #   pd.set_page_size(Pd4ml::PageSize::A4)
@@ -117,6 +119,24 @@ module Pd4ml
     end
     alias readHtmlString read_html_string
 
+    # Reads an e-mail message (.eml) to convert: its body, HTML if it has one, with the images it
+    # embeds, after a block with From, Date, To, Cc, Subject and the attachments, which are
+    # embedded in the PDF. `source` as for read_html: a path or URL, or the message itself (a
+    # binary String or IO). Of resources outside the message only https:// ones are loaded;
+    # add_allowed_resource_location replaces that. read_html recognizes messages too; this is the
+    # way for mail from outside your control. PD4ML 4.2 and later.
+    def read_eml(source)
+      read_mime('readEML', source)
+    end
+    alias readEML read_eml
+
+    # Reads a web page saved as a single file (.mht, .mhtml), with the images, style sheets and
+    # fonts saved in it; `source` as for read_eml. PD4ML 4.2 and later.
+    def read_mht(source)
+      read_mime('readMHT', source)
+    end
+    alias readMHT read_mht
+
     # -------------------------------------------------------------------------------- output
 
     # Writes the PDF: to `target` (a path or an IO), or returned as a binary String. spec: a
@@ -175,6 +195,16 @@ module Pd4ml
 
     private
 
+    def read_mime(method, source)
+      arg = if location?(source)
+              Pd4ml.to_url(source)
+            else
+              source.is_a?(JavaObject) ? source : Pd4ml.binary(source)
+            end
+      Bridge.get.call(@java, method, [arg])
+      nil
+    end
+
     def location?(source)
       source.is_a?(Pathname) || source.is_a?(URI::Generic) ||
         (source.is_a?(String) && source.encoding != Encoding::BINARY && !source.lstrip.start_with?('<')) ||

data/lib/pd4ml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pd4ml
-  VERSION = '1.0.0'
+  VERSION = '1.1.1'
 end

data/lib/pd4ml.rb

@@ -35,6 +35,19 @@ module Pd4ml
   ResourceProvider = Java.type('com.pd4ml.ResourceProvider')
   CustomTag = Java.type('com.pd4ml.CustomTag')
 
+  # The DOM API (com.pd4ml.dom, PD4ML 4.2, v42 engine; DMS and UA editions): PD4ML#get_document and
+  # PD4ML#layout return its objects. Their Java lists and sets come back as Ruby Arrays, maps as Hashes.
+  module Dom
+    Node = Java.type('com.pd4ml.dom.Node')
+    Document = Java.type('com.pd4ml.dom.Document')
+    Element = Java.type('com.pd4ml.dom.Element')
+    Text = Java.type('com.pd4ml.dom.Text')
+    Comment = Java.type('com.pd4ml.dom.Comment')
+    DocumentType = Java.type('com.pd4ml.dom.DocumentType')
+    Layout = Java.type('com.pd4ml.dom.Layout')
+    LayoutBox = Java.type('com.pd4ml.dom.LayoutBox')
+  end
+
   FORMATS = %w[PDF PDFA PDFUA].freeze
 
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pd4ml
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - PD4ML