pd4ml 1.0.0

data/exe/pd4ml

@@ -0,0 +1,132 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The pd4ml command: install/list PD4ML builds, show the version, run a bridge server, convert.
+require 'optparse'
+require_relative '../lib/pd4ml'
+
+USAGE = <<~TEXT
+  usage: pd4ml <command> [options]
+
+    install [VERSION] [--snapshots] [--jakarta] [--home DIR] [--force] [--no-bouncycastle]
+                        download a PD4ML build (default: the most recent 4.* release), or update to it
+    list [--snapshots] [--jakarta]
+                        the versions in the PD4ML repository (* the installed one)
+    version             the PD4ML version the gem runs (downloads it on first use)
+    serve [--port N]    run a bridge server (default port 8723) for PD4ML_BRIDGE=tcp://127.0.0.1:N
+    convert INPUT OUTPUT [--format pdf|docx|rtf|png] [--page-size A4] [--landscape]
+            [--margins 10,10,10,10] [--width PX] [--engine v42|v40] [--spec pdf/a-2b]
+            [--footer HTML] [--bookmarks]
+                        convert a file or URL; the format follows OUTPUT's extension by default
+
+    PD4ML_CLASSPATH / PD4ML_CLASSPATH_FILE / PD4ML_HOME / PD4ML_JAVA choose the build and Java.
+    https://pd4ml.com/docs/
+TEXT
+
+def options(args, &block)
+  opts = {}
+  parser = OptionParser.new { |o| block.call(o, opts) }
+  rest = parser.parse(args)
+  [opts, rest]
+end
+
+def convert(args)
+  opts, (input, output) = options(args) do |o, h|
+    o.on('--format F') { |v| h[:format] = v }
+    o.on('--page-size S') { |v| h[:page_size] = v }
+    o.on('--landscape') { h[:landscape] = true }
+    o.on('--margins M') { |v| h[:margins] = v }
+    o.on('--width PX', Integer) { |v| h[:width] = v }
+    o.on('--engine E') { |v| h[:engine] = v }
+    o.on('--spec S') { |v| h[:spec] = v }
+    o.on('--footer HTML') { |v| h[:footer] = v }
+    o.on('--bookmarks') { h[:bookmarks] = true }
+  end
+  raise ArgumentError, 'convert: INPUT and OUTPUT expected' unless input && output
+
+  format = (opts[:format] || File.extname(output).delete('.')).downcase
+  pd = Pd4ml::PD4ML.new(html_width: opts[:width], engine: opts[:engine])
+  if opts[:page_size]
+    size = Pd4ml::PageSize.get_instance(opts[:page_size].downcase)
+    raise ArgumentError, "unknown page size '#{opts[:page_size]}'" if size.nil?
+
+    pd.set_page_size(opts[:landscape] ? size.rotate : size)
+  elsif opts[:landscape]
+    pd.set_page_size(Pd4ml::PageSize::A4.rotate)
+  end
+  if opts[:margins]
+    mm = opts[:margins].split(',').map { |s| Integer(s.strip) }
+    mm *= 4 if mm.size == 1
+    raise ArgumentError, '--margins: one or four values (mm)' unless mm.size == 4
+
+    pd.set_page_margins(Pd4ml::PageMargins.new(*mm, Pd4ml::Units::MM))
+  end
+  pd.set_page_footer(opts[:footer], 30, '1+') if opts[:footer]
+  pd.generate_bookmarks_from_headings(true) if opts[:bookmarks]
+  pd.read_html(input)
+  case format
+  when 'pdf' then pd.write_pdf(output, spec: opts[:spec])
+  when 'docx' then pd.write_docx(output)
+  when 'rtf' then pd.write_rtf(output)
+  when 'png'
+    pages = pd.render_png
+    if pages.size == 1
+      File.binwrite(output, pages[0])
+    else
+      stem = output.sub(/\.png\z/i, '')
+      pages.each_with_index { |p, i| File.binwrite("#{stem}-#{i + 1}.png", p) }
+    end
+  else raise ArgumentError, "unknown format '#{format}' (pdf, docx, rtf, png)"
+  end
+end
+
+def main(argv)
+  command, *args = argv
+  if command.nil? || %w[-h --help help].include?(command)
+    puts USAGE
+    return command ? 0 : 2
+  end
+  case command
+  when 'install'
+    opts, rest = options(args) do |o, h|
+      o.on('--snapshots') { h[:snapshots] = true }
+      o.on('--jakarta') { h[:jakarta] = true }
+      o.on('--home DIR') { |v| h[:home] = v }
+      o.on('--force') { h[:force] = true }
+      o.on('--no-bouncycastle') { h[:bouncycastle] = false }
+    end
+    puts Pd4ml::Installer.install(rest.first || 'latest', **opts)
+  when 'list'
+    opts, = options(args) do |o, h|
+      o.on('--snapshots') { h[:snapshots] = true }
+      o.on('--jakarta') { h[:jakarta] = true }
+    end
+    installed = Pd4ml::Installer.installed_version
+    Pd4ml::Installer.sort_versions(Pd4ml::Installer.available_versions).each do |v|
+      next if !opts[:snapshots] && v.end_with?('-SNAPSHOT')
+      next if v.include?('-jakarta') != !!opts[:jakarta]
+
+      puts((v == installed ? '* ' : '  ') + v)
+    end
+  when 'version'
+    puts Pd4ml.version
+  when 'serve'
+    opts, = options(args) { |o, h| o.on('--port N', Integer) { |v| h[:port] = v } }
+    port = opts[:port] || 8723
+    cmd = Pd4ml::Bridge.command(port: port)
+    warn "PD4ML bridge on tcp://127.0.0.1:#{port} (Ctrl+C to stop)"
+    exec(*cmd)
+  when 'convert'
+    convert(args)
+  else
+    warn "pd4ml: unknown command '#{command}'\n\n#{USAGE}"
+    return 2
+  end
+  0
+rescue Pd4ml::BridgeError, Pd4ml::InstallError, Pd4ml::JavaError, ArgumentError, OptionParser::ParseError,
+       SystemCallError => e
+  warn "pd4ml: #{e.message}"
+  1
+end
+
+exit main(ARGV)

data/lib/pd4ml/bridge.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'monitor'
+require 'open3'
+require 'socket'
+require 'uri'
+require 'pathname'
+
+module Pd4ml
+  # An OutputStream argument whose content comes back to Ruby (see Bridge#request).
+  Output = Struct.new(:index)
+
+  # The connection to the Java side: a bridge process (pd4ml-bridge.jar, started on first use) or
+  # a bridge server (`pd4ml serve`, PD4ML_BRIDGE=tcp://host:port). One shared bridge serves the
+  # whole process; it is thread-safe, and a callback may call PD4ML itself.
+  class Bridge
+    BRIDGE_JAR = File.expand_path('pd4ml-bridge.jar', __dir__)
+
+    @options = {}
+    @default = nil
+    @lock = Monitor.new
+
+    class << self
+      # Sets up the shared bridge; call before the first use of PD4ML.
+      # Options: classpath (Array), java, jvm_options (Array), server ('tcp://127.0.0.1:8723'), log_file.
+      def configure(**options)
+        @lock.synchronize do
+          raise BridgeError, 'the PD4ML bridge runs already: configure before the first use' if @default
+          @options = @options.merge(options)
+        end
+      end
+
+      # The shared bridge, started on first use.
+      def get
+        @lock.synchronize do
+          unless @at_exit
+            @at_exit = true
+            at_exit { shutdown } # Java ends with the Ruby process, before it exits
+          end
+          @default ||= new(**@options)
+        end
+      end
+
+      def started?
+        @lock.synchronize { !@default.nil? }
+      end
+
+      # Stops the shared bridge (it starts again on the next use).
+      def shutdown
+        @lock.synchronize do
+          @default&.close
+          @default = nil
+        end
+      end
+
+      def forget(bridge)
+        @lock.synchronize { @default = nil if @default.equal?(bridge) }
+      end
+
+      # The classpath the bridge starts with: configured, from the environment, or the installed build.
+      def classpath(options = @options)
+        entries = options[:classpath]
+        entries ||= ENV['PD4ML_CLASSPATH'].split(File::PATH_SEPARATOR) if ENV['PD4ML_CLASSPATH'].to_s != ''
+        entries ||= File.read(ENV['PD4ML_CLASSPATH_FILE']).split(/\r?\n/) if ENV['PD4ML_CLASSPATH_FILE'].to_s != ''
+        unless entries
+          entries = Installer.installed_classpath
+          if entries.empty? && Installer.auto_install?
+            warn 'pd4ml: no PD4ML build installed yet: downloading the most recent release ' \
+                 "(once; 'pd4ml install' updates it, PD4ML_AUTO_INSTALL=0 turns this off)"
+            Installer.install
+            entries = Installer.installed_classpath
+          end
+        end
+        entries.map(&:strip).reject(&:empty?).flat_map do |e|
+          if e.end_with?('/*', '\\*')
+            Dir.glob(File.join(e[0..-3].tr('\\', '/'), '*.jar')).sort
+          else
+            [e]
+          end
+        end
+      end
+
+      # The java executable: PD4ML_JAVA, JAVA_HOME/bin/java, else `java`.
+      def java(options = @options)
+        return options[:java] if options[:java]
+        return ENV['PD4ML_JAVA'] if ENV['PD4ML_JAVA'].to_s != ''
+
+        home = ENV['JAVA_HOME'].to_s
+        unless home.empty?
+          exe = File.join(home, 'bin', Gem.win_platform? ? 'java.exe' : 'java')
+          return exe if File.exist?(exe)
+        end
+        'java'
+      end
+
+      # The command line that runs the bridge (with a port: a bridge server).
+      def command(options = @options, port: nil)
+        cp = classpath(options)
+        if cp.empty?
+          raise BridgeError, "PD4ML not found: install a build with 'pd4ml install' (or Pd4ml.install), or point at " \
+                             'one with Pd4ml.configure(classpath: [...]), PD4ML_CLASSPATH or PD4ML_CLASSPATH_FILE'
+        end
+        args = [java(options), '-Djava.awt.headless=true', *Array(options[:jvm_options])]
+        args.concat(ENV['PD4ML_JVM_OPTIONS'].split) if ENV['PD4ML_JVM_OPTIONS'].to_s != ''
+        args.push('-cp', [BRIDGE_JAR, *cp].join(File::PATH_SEPARATOR), 'com.pd4ml.bridge.Bridge')
+        args.push('--port', port.to_s) if port
+        args
+      end
+    end
+
+    def initialize(**options)
+      @lock = Monitor.new
+      @next_id = 1
+      @next_callback = 1
+      @callbacks = {}
+      @pending = {}
+      @released = Queue.new
+      @callback_error = nil
+      @closed = false
+      server = options[:server] || ENV['PD4ML_BRIDGE']
+      if server.to_s != ''
+        uri = URI(server)
+        begin
+          @socket = TCPSocket.new(uri.host, uri.port)
+        rescue SystemCallError => e
+          raise BridgeError, "cannot connect to the PD4ML bridge at #{server}: #{e.message}"
+        end
+        @in = @out = @socket
+      else
+        cmd = self.class.command(options)
+        begin
+          @in, @out, err, @thread = Open3.popen3(*cmd)
+        rescue SystemCallError => e
+          raise BridgeError, "cannot start java (#{cmd.first}): #{e.message}"
+        end
+        log = options[:log_file] || ENV['PD4ML_BRIDGE_LOG']
+        @stderr_tail = +''
+        # drained either way, so Java never blocks on a full pipe
+        @stderr_reader = Thread.new do
+          File.open(log, 'a') do |f|
+            err.each_line { |l| f.write(l); keep_tail(l) }
+          end if log
+          err.each_line { |l| keep_tail(l) } unless log
+        rescue IOError
+          nil
+        end
+      end
+      @in.binmode
+      @out.binmode
+      @in.sync = true
+      hello = request({ 'op' => 'hello' })
+      raise BridgeError, 'incompatible PD4ML bridge protocol' unless hello.is_a?(Hash) && hello['protocol'] == 1
+    end
+
+    def close
+      @lock.synchronize do
+        return if @closed
+
+        @closed = true
+        begin
+          @in.write("{\"id\":0,\"op\":\"close\"}\n")
+          @in.close unless @socket
+        rescue IOError, SystemCallError
+          nil
+        end
+        @socket&.close
+        # let Java finish (it exits on 'close' or end of input), so it never outlives Ruby
+        if @thread && !@thread.join(5)
+          begin
+            Process.kill(:KILL, @thread.pid)
+          rescue SystemCallError
+            nil
+          end
+          @thread.join(5)
+        end
+        @stderr_reader&.join(1)
+      end
+    end
+
+    # ------------------------------------------------------------------------------- protocol
+
+    # Sends one request and returns its decoded result; callbacks run while it waits. With `outs`
+    # (an Array), the content of Output arguments is stored there (binary Strings).
+    def request(req, outs = nil)
+      response = @lock.synchronize do
+        raise BridgeError, 'the PD4ML bridge is closed' if @closed
+
+        refs = []
+        refs << @released.pop until @released.empty?
+        exchange({ 'op' => 'release', 'refs' => refs }) unless refs.empty?
+        exchange(req)
+      end
+      raise JavaError.from(response['error']) if response['error']
+
+      if outs && response['out'].is_a?(Array)
+        response['out'].each_with_index { |data, i| outs[i] = data&.unpack1('m0') }
+      end
+      if (e = @callback_error)
+        @callback_error = nil
+        begin
+          raise e
+        rescue StandardError
+          raise CallbackError, "a callback failed: #{e.message}"
+        end
+      end
+      decode(response['result'])
+    end
+
+    # ----------------------------------------------------------------------------- operations
+
+    def new_object(cls, args) = request({ 'op' => 'new', 'class' => cls, 'args' => args })
+
+    def call(target, method, args, outs = nil)
+      request({ 'op' => 'call', 'ref' => handle_of(target), 'method' => method, 'args' => args }, outs)
+    end
+
+    def call_static(cls, method, args, outs = nil)
+      request({ 'op' => 'static', 'class' => cls, 'method' => method, 'args' => args }, outs)
+    end
+
+    def get_field(target, field)
+      if target.is_a?(String)
+        request({ 'op' => 'get', 'class' => target, 'field' => field })
+      else
+        request({ 'op' => 'get', 'ref' => handle_of(target), 'field' => field })
+      end
+    end
+
+    def set_field(target, field, value)
+      if target.is_a?(String)
+        request({ 'op' => 'set', 'class' => target, 'field' => field, 'value' => value })
+      else
+        request({ 'op' => 'set', 'ref' => handle_of(target), 'field' => field, 'value' => value })
+      end
+    end
+
+    def describe(cls) = request({ 'op' => 'describe', 'class' => cls })
+
+    def instance_of?(target, cls)
+      request({ 'op' => 'instanceof', 'ref' => handle_of(target), 'class' => cls }) == true
+    end
+
+    # A Java object implementing `iface`; its methods call the block with (method, args).
+    def proxy(iface, &block)
+      id = @lock.synchronize { (@next_callback += 1) - 1 }
+      @callbacks[id] = block
+      request({ 'op' => 'proxy', 'interface' => iface, 'callback' => id })
+    end
+
+    # Called by JavaObject finalizers; released with the next request.
+    def release(handle)
+      @released << handle unless @closed
+    end
+
+    # ------------------------------------------------------------------------------- values
+
+    def encode(v)
+      case v
+      when JavaObject then { '$ref' => v.__handle }
+      when Output then { '$out' => v.index }
+      when PD4ML then { '$ref' => v.java.__handle }
+      when String
+        v.encoding == Encoding::BINARY || !v.valid_encoding? ? { '$bytes' => [v].pack('m0') } : v
+      when Symbol then v.to_s
+      when Pathname, URI::Generic then v.to_s
+      when Hash then v.to_h { |k, x| [k.to_s, encode(x)] }
+      when Array then v.map { |x| encode(x) }
+      when nil, true, false, Integer then v
+      when Float
+        raise ArgumentError, "not a finite number: #{v}" unless v.finite?
+
+        v
+      else
+        if v.respond_to?(:read)
+          data = v.read
+          { '$bytes' => [data.to_s].pack('m0') }
+        elsif v.respond_to?(:to_str)
+          v.to_str
+        else
+          raise ArgumentError, "cannot pass #{v.class} to Java"
+        end
+      end
+    end
+
+    def decode(v)
+      case v
+      when Array then v.map { |x| decode(x) }
+      when Hash
+        if v.key?('$ref')
+          JavaObject.new(self, v['$ref'], v['class'], v['enum'])
+        elsif v.key?('$bytes')
+          v['$bytes'].unpack1('m0')
+        else
+          v.transform_values { |x| decode(x) }
+        end
+      else
+        v
+      end
+    end
+
+    private
+
+    def keep_tail(line)
+      @stderr_tail = (@stderr_tail + line)[-4000..] || (@stderr_tail + line)
+    end
+
+    def handle_of(target)
+      case target
+      when JavaObject then target.__handle
+      when PD4ML then target.java.__handle
+      else raise ArgumentError, "not a Java object: #{target.inspect}"
+      end
+    end
+
+    def exchange(req)
+      id = @next_id
+      @next_id += 1
+      line = JSON.generate(encode(req.merge('id' => id)))
+      begin
+        @in.write(line, "\n")
+      rescue IOError, SystemCallError => e
+        gone("the PD4ML bridge is gone (#{e.message})")
+      end
+      loop do
+        return @pending.delete(id) if @pending.key?(id)
+
+        raw = @out.gets
+        gone('the PD4ML bridge closed the connection') if raw.nil?
+        next if raw.strip.empty?
+
+        msg = JSON.parse(raw.force_encoding(Encoding::UTF_8))
+        if msg.key?('callback')
+          dispatch(msg)
+        elsif msg['id'] == id
+          return msg
+        else
+          @pending[msg['id']] = msg # an outer request's response, during a callback
+        end
+      end
+    end
+
+    def dispatch(msg)
+      callback = @callbacks[msg['callback']]
+      return if callback.nil? || @callback_error
+
+      begin
+        callback.call(msg['method'], Array(msg['args']).map { |a| decode(a) })
+      rescue StandardError => e
+        @callback_error = e # raised by the request that caused the callback
+      end
+    end
+
+    def gone(why)
+      @closed = true
+      self.class.forget(self)
+      detail = @stderr_tail.to_s.strip
+      raise BridgeError, why + (detail.empty? ? '' : "\n#{detail}") +
+                         (ENV['PD4ML_BRIDGE_LOG'] ? '' : ' (PD4ML_BRIDGE_LOG=file keeps its output)')
+    end
+  end
+end

data/lib/pd4ml/errors.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pd4ml
+  # The bridge to Java cannot start or broke down (no Java, no PD4ML build, process gone).
+  class BridgeError < StandardError; end
+
+  # A PD4ML build could not be found, downloaded or verified.
+  class InstallError < StandardError; end
+
+  # A Ruby block (a progress listener...) raised while PD4ML ran; the error is #cause.
+  class CallbackError < StandardError; end
+
+  # A Java exception thrown by PD4ML (or any Java code called): its Java class and superclasses,
+  # message, causes and stack trace.
+  #
+  #   begin
+  #     pd.read_html('missing.html')
+  #   rescue Pd4ml::JavaError => e
+  #     raise unless e.instance_of_java?('java.io.IOException')
+  #   end
+  class JavaError < StandardError
+    attr_reader :java_class, :hierarchy, :java_message, :causes, :java_trace
+
+    def initialize(java_message, java_class, hierarchy = [], causes = [], java_trace = '')
+      super("#{java_class}: #{java_message}")
+      @java_message = java_message
+      @java_class = java_class
+      @hierarchy = hierarchy
+      @causes = causes
+      @java_trace = java_trace
+    end
+
+    # Whether the Java exception is of the class or a subclass ('java.io.IOException').
+    def instance_of_java?(name)
+      @java_class == name || @hierarchy.include?(name)
+    end
+
+    def self.from(e)
+      new(e['message'].to_s, e['class'] || 'java.lang.Throwable', e['hierarchy'] || [], e['causes'] || [], e['trace'].to_s)
+    end
+  end
+end