resolves #2330 allow PDF optimizer to be pluggable (PR #2332)

Author: mojavelinux

CHANGELOG.adoc

@@ -19,6 +19,8 @@ Enhancements::
 * rename `kbd-separator` theme key to `kbd-separator-content` to make its consistent with other content keys; remap old key and warn
 * preserve em and rem units on numerator in calc operation in theme (#2314)
 * allow optimizer to be specified using `:pdf_optimizer` API option (#1785)
+* allow custom optimizer to be registered by extending `Asciidoctor::PDF::Optimizer::Base` and calling `register_for` method (#2330)
+* allow custom optimizer to be selected using `pdf-optimizer` attribute (#2330)
 
 Improvements::
 

bin/asciidoctor-pdf-optimize

@@ -1,10 +1,10 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-if File.file? (optimizer = File.join (File.dirname __dir__), 'lib/asciidoctor/pdf/optimizer.rb')
+if File.file? (optimizer = File.join (File.dirname __dir__), 'lib/asciidoctor/pdf/optimizer/rghost.rb')
   require optimizer
 else
-  require 'asciidoctor/pdf/optimizer'
+  require 'asciidoctor/pdf/optimizer/rghost'
 end
 
 args = ARGV.dup
@@ -16,4 +16,4 @@ end
 
 quality = args[0] == '--quality' ? args[1].to_s : ''
 
-(Asciidoctor::PDF::Optimizer.new quality).optimize_file filename
+(Asciidoctor::PDF::Optimizer::RGhost.new quality).optimize_file filename

docs/modules/ROOT/examples/optimizer-hexapdf.rb

@@ -0,0 +1,30 @@
+require 'hexapdf/cli'
+
+class OptimizerHexaPDF < Asciidoctor::PDF::Optimizer::Base
+  register_for 'hexapdf'
+
+  def initialize *_args
+    super
+    app = HexaPDF::CLI::Application.new
+    app.instance_variable_set :@force, true
+    @optimize = app.main_command.commands['optimize']
+    @optimize.singleton_class.attr_reader :out_options
+    options = @optimize.out_options
+    options.compress_pages = true
+    #options.object_streams = :preserve
+    #options.xref_streams = :preserve
+    #options.streams = :preserve # or :uncompress
+  end
+
+  def optimize_file path
+    @optimize.execute path, path
+    nil
+  rescue
+    # retry without page compression, which can sometimes fail
+    @optimize.out_options.compress_pages = false
+    @optimize.execute path, path
+    nil
+  ensure
+    @optimize.out_options.compress_pages = false
+  end
+end

docs/modules/ROOT/pages/optimize-pdf.adoc

@@ -135,52 +135,47 @@ This command does not manipulate the images in any way.
 It merely compresses the objects in the PDF and prunes any unreachable references.
 But given how much waste Prawn leaves behind, this turns out to reduce the file size substantially.
 
-You can hook this command directly into the converter by providing your own implementation of the `Optimizer` class.
-Start by creating a Ruby file named [.path]_optimizer-hexapdf.rb_, then populate it with the following code:
+To see all the options that `hexapdf optimize` offers, run:
+
+ $ hexapdf help optimize
+
+For example, to make the source of the PDF a bit more readable (though less optimized), set the stream-related options to `preserve` (e.g., `--streams preserve` from the CLI or `options.streams = :preserve` from the API).
+You can also disable page compression (e.g., `--no-compress-pages` from the CLI or `options.compress_pages = false` from the API).
+
+hexapdf also allows you to add password protection to your PDF, if that's something you're interested in doing.
+
+=== Define an optimizer
+
+You can hook HexaPDF directly into the conversion process by providing your own implementation of the `Optimizer` class.
+Start by creating a Ruby file named [.path]_optimizer-hexapdf.rb_ where you will define the optimizer.
+Next, populate that file with the following code:
 
 .optimizer-hexapdf.rb
 [source,ruby]
 ----
-require 'hexapdf/cli'
-
-class Asciidoctor::PDF::Optimizer
-  def initialize(*)
-    app = HexaPDF::CLI::Application.new
-    app.instance_variable_set :@force, true
-    @optimize = app.main_command.commands['optimize']
-  end
-
-  def optimize_file path
-    options = @optimize.instance_variable_get :@out_options
-    options.compress_pages = true
-    #options.object_streams = :preserve
-    #options.xref_streams = :preserve
-    #options.streams = :preserve # or :uncompress
-    @optimize.execute path, path
-    nil
-  rescue
-    # retry without page compression, which can sometimes fail
-    options.compress_pages = false
-    @optimize.execute path, path
-    nil
-  end
-end
+include::example$optimizer-hexapdf.rb[]
 ----
 
-To activate your custom optimizer, load this file when invoking the `asciidoctor-pdf` using the `-r` flag and set the `optimize` attribute as well using the `-a` flag.
+To activate your custom optimizer when using the `asciidoctor-pdf` command, load the optimizer code using the `-r` flag, then set both the `optimize` and `pdf-optimizer` attributes using the `-a` flag.
 
- $ asciidoctor-pdf -r ./optimizer-hexapdf.rb -a optimize filename.adoc
+ $ asciidoctor-pdf -r ./optimizer-hexapdf.rb -a optimize -a pdf-optimizer=hexapdf filename.adoc
 
-Now you can convert and optimize all in one go.
+If you're calling Asciidoctor PDF using the API, you can pass in the optimizer class directly with the `:pdf_optimizer` option:
 
-To see more options that `hexapdf optimize` offers, run:
+[,ruby]
+----
+require 'asciidoctor/pdf'
+require_relative 'optimizer-hexapdf'
 
- $ hexapdf help optimize
+Asciidoctor.convert_file 'filename.adoc',
+  safe: :safe,
+  attributes: 'optimize',
+  pdf_optimizer: OptimizerHexaPDF
+----
 
-For example, to make the source of the PDF a bit more readable (though less optimized), set the stream-related options to `preserve` (e.g., `--streams preserve` from the CLI or `options.streams = :preserve` from the API).
-You can also disable page compression (e.g., `--no-compress-pages` from the CLI or `options.compress_pages = false` from the API).
+TIP: When you pass the optimizer class directly to the API, the `register_for` call in the class declaration to self-register the class with a keyword is not required.
 
-hexapdf also allows you to add password protection to your PDF, if that's something you're interested in doing.
+You've now converted the input file to PDF and optimized it all in one go!
 
 == Rasterizing the PDF
 

lib/asciidoctor/pdf/converter.rb

@@ -3,6 +3,7 @@
 require_relative 'formatted_string'
 require_relative 'formatted_text'
 require_relative 'index_catalog'
+require_relative 'optimizer'
 require_relative 'pdfmark'
 require_relative 'roman_numeral'
 require_relative 'section_info_by_page'
@@ -37,7 +38,6 @@ class Converter < ::Prawn::Document
       CodeRayRequirePath = ::File.join __dir__, 'ext/prawn/coderay_encoder'
       RougeRequirePath = ::File.join __dir__, 'ext/rouge'
       PygmentsRequirePath = ::File.join __dir__, 'ext/pygments'
-      OptimizerRequirePath = ::File.join __dir__, 'optimizer'
 
       AdmonitionIcons = {
         caution: { name: 'fas-fire', stroke_color: 'BF3400' },
@@ -420,8 +420,7 @@ def init_pdf doc
         @pdfmark = (doc.attr? 'pdfmark') ? (Pdfmark.new doc) : nil
         # NOTE: defer instantiating optimizer until we know min pdf version
         if (optimize = doc.attr 'optimize') &&
-            (optimizer = doc.options[:pdf_optimizer] || (((defined? ::Asciidoctor::PDF::Optimizer) ||
-            !(Helpers.require_library OptimizerRequirePath, 'rghost', :warn).nil?) && ::Asciidoctor::PDF::Optimizer))
+            (optimizer = doc.options[:pdf_optimizer] || (Optimizer.for (doc.attr 'pdf-optimizer', 'rghost')))
           @optimize = (optimize.include? ',') ?
             ([:quality, :compliance].zip (optimize.split ',', 2)).to_h :
             ((optimize.include? '/') ? { compliance: optimize } : { quality: optimize })

lib/asciidoctor/pdf/optimizer.rb

@@ -1,78 +1,56 @@
 # frozen_string_literal: true
 
-require 'pathname'
-require 'rghost'
-require 'rghost/gs_alone'
-require 'tmpdir'
-
-RGhost::GSAlone.prepend (Module.new do
-  def initialize params, debug
-    (@params = params.dup).push(*(@params.pop.split File::PATH_SEPARATOR))
-    @debug = debug
-  end
-
-  def run
-    RGhost::Config.config_platform unless File.exist? RGhost::Config::GS[:path].to_s
-    (cmd = @params.slice 1, @params.length).unshift RGhost::Config::GS[:path].to_s
-    #puts cmd if @debug
-    system(*cmd)
-  end
-end)
-
-RGhost::Engine.prepend (Module.new do
-  def shellescape str
-    str
-  end
-end)
-
 module Asciidoctor
   module PDF
-    class Optimizer
-      # see https://www.ghostscript.com/doc/current/VectorDevices.htm#PSPDF_IN for details
-      (QUALITY_NAMES = {
-        'default' => :default,
-        'screen' => :screen,
-        'ebook' => :ebook,
-        'printer' => :printer,
-        'prepress' => :prepress,
-      }).default = :default
-
+    module Optimizer
       attr_reader :quality
       attr_reader :compatibility_level
       attr_reader :compliance
 
       def initialize quality = 'default', compatibility_level = '1.4', compliance = 'PDF'
-        @quality = QUALITY_NAMES[quality]
+        @quality = quality
         @compatibility_level = compatibility_level
         @compliance = compliance
-        if (gs_path = ::ENV['GS'])
-          ::RGhost::Config::GS[:path] = gs_path
-        end
       end
 
       def optimize_file target
-        ::Dir::Tmpname.create ['asciidoctor-pdf-', '.pdf'] do |tmpfile|
-          filename_o = ::Pathname.new target
-          filename_tmp = ::Pathname.new tmpfile
-          if (pdfmark = filename_o.sub_ext '.pdfmark').file?
-            inputs = [target, pdfmark.to_s].join ::File::PATH_SEPARATOR
-          else
-            inputs = target
-          end
-          d = { Printed: false, CannotEmbedFontPolicy: '/Warning', CompatibilityLevel: @compatibility_level }
-          case @compliance
-          when 'PDF/A', 'PDF/A-1', 'PDF/A-2', 'PDF/A-3'
-            d[:PDFA] = ((@compliance.split '-', 2)[1] || 1).to_i
-            d[:ShowAnnots] = false
-          when 'PDF/X', 'PDF/X-1', 'PDF/X-3'
-            d[:PDFX] = true
-            d[:ShowAnnots] = false
+        raise ::NotImplementedError, %(#{Optimizer} subclass #{self.class} must implement the ##{__method__} method)
+      end
+
+      private_class_method def self.included into
+        into.extend Config
+      end
+
+      module Config
+        def register_for name
+          Optimizer.register self, name.to_s
+        end
+      end
+
+      module Factory
+        @@registry = {}
+
+        def for name
+          if (optimizer = @@registry[name]).nil? && name == 'rghost'
+            if (::Asciidoctor::Helpers.require_library %(#{__dir__}/optimizer/rghost), 'rghost', :warn).nil?
+              @@registry[name] = false
+            else
+              optimizer = @@registry[name] = Optimizer::RGhost
+            end
           end
-          (::RGhost::Convert.new inputs).to :pdf, filename: filename_tmp.to_s, quality: @quality, d: d
-          filename_o.binwrite filename_tmp.binread
+          optimizer || nil
+        end
+
+        def register optimizer, name
+          optimizer ? (@@registry[name] = optimizer) : (@@registry.delete name)
         end
-        nil
       end
+
+      class Base
+        include Optimizer
+      end
+
+      extend Factory
     end
   end
 end

lib/asciidoctor/pdf/optimizer/rghost.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative '../optimizer' unless defined? ::Asciidoctor::PDF::Optimizer
+require 'pathname'
+require 'rghost'
+require 'rghost/gs_alone'
+require 'tmpdir'
+
+RGhost::GSAlone.prepend (Module.new do
+  def initialize params, debug
+    (@params = params.dup).push(*(@params.pop.split File::PATH_SEPARATOR))
+    @debug = debug
+  end
+
+  def run
+    RGhost::Config.config_platform unless File.exist? RGhost::Config::GS[:path].to_s
+    (cmd = @params.slice 1, @params.length).unshift RGhost::Config::GS[:path].to_s
+    #puts cmd if @debug
+    system(*cmd)
+  end
+end)
+
+RGhost::Engine.prepend (Module.new do
+  def shellescape str
+    str
+  end
+end)
+
+module Asciidoctor
+  module PDF
+    class Optimizer::RGhost < Optimizer::Base
+      # see https://www.ghostscript.com/doc/current/VectorDevices.htm#PSPDF_IN for details
+      (QUALITY_NAMES = {
+        'default' => :default,
+        'screen' => :screen,
+        'ebook' => :ebook,
+        'printer' => :printer,
+        'prepress' => :prepress,
+      }).default = :default
+
+      def initialize *_args
+        super
+        if (gs_path = ::ENV['GS'])
+          ::RGhost::Config::GS[:path] = gs_path
+        end
+      end
+
+      def optimize_file target
+        ::Dir::Tmpname.create ['asciidoctor-pdf-', '.pdf'] do |tmpfile|
+          filename_o = ::Pathname.new target
+          filename_tmp = ::Pathname.new tmpfile
+          if (pdfmark = filename_o.sub_ext '.pdfmark').file?
+            inputs = [target, pdfmark.to_s].join ::File::PATH_SEPARATOR
+          else
+            inputs = target
+          end
+          d = { Printed: false, CannotEmbedFontPolicy: '/Warning', CompatibilityLevel: @compatibility_level }
+          case @compliance
+          when 'PDF/A', 'PDF/A-1', 'PDF/A-2', 'PDF/A-3'
+            d[:PDFA] = ((@compliance.split '-', 2)[1] || 1).to_i
+            d[:ShowAnnots] = false
+          when 'PDF/X', 'PDF/X-1', 'PDF/X-3'
+            d[:PDFX] = true
+            d[:ShowAnnots] = false
+          end
+          (::RGhost::Convert.new inputs).to :pdf, filename: filename_tmp.to_s, quality: QUALITY_NAMES[@quality], d: d
+          filename_o.binwrite filename_tmp.binread
+        end
+        nil
+      end
+    end
+  end
+end

spec/optimizer_spec.rb

@@ -18,10 +18,11 @@
     (expect pdf_info[:Title]).to eql 'Document Title'
     (expect pdf_info[:Author]).to eql 'Doc Writer'
     (expect pdf_info[:Subject]).to eql 'Example'
-    (expect defined? Asciidoctor::PDF::Optimizer).to be_truthy
     # NOTE: assert constructor behavior once we know the class has been loaded
-    optimizer = Asciidoctor::PDF::Optimizer.new
-    (expect optimizer.quality).to eql :default
+    optimizer_class = Asciidoctor::PDF::Optimizer.for 'rghost'
+    (expect optimizer_class).not_to be_nil
+    optimizer = optimizer_class.new
+    (expect optimizer.quality).to eql 'default'
     (expect optimizer.compatibility_level).to eql '1.4'
     (expect optimizer.compliance).to eql 'PDF'
   end
@@ -185,4 +186,46 @@ def self.optimized
     (expect optimized[0][:quality]).to eql 'ebook'
     (expect optimized[0][:path]).to eql to_file
   end
+
+  it 'should allow custom PDF optimizer to be registered and used' do
+    create_class Asciidoctor::PDF::Optimizer::Base do
+      register_for 'custom'
+
+      def optimize_file path
+        self.class.optimized << { quality: @quality, path: path }
+        nil
+      end
+
+      def self.optimized
+        @optimized ||= []
+      end
+    end
+
+    optimizer = Asciidoctor::PDF::Optimizer.for 'custom'
+    (expect optimizer).not_to be_nil
+    input_file = example_file 'basic-example.adoc'
+    to_file = output_file 'optimizer-custom-registered.pdf'
+    Asciidoctor.convert_file input_file, backend: 'pdf', attributes: 'optimize=ebook pdf-optimizer=custom', to_file: to_file, safe: :safe
+    optimized = optimizer.optimized
+    (expect optimized).to have_size 1
+    (expect optimized[0][:quality]).to eql 'ebook'
+    (expect optimized[0][:path]).to eql to_file
+  ensure
+    Asciidoctor::PDF::Optimizer.register 'custom', nil
+  end
+
+  it 'should raise error if registered optimizer does not implement optimize_file method' do
+    create_class Asciidoctor::PDF::Optimizer::Base do
+      register_for 'custom'
+    end
+
+    (expect Asciidoctor::PDF::Optimizer.for 'custom').not_to be_nil
+    input_file = example_file 'basic-example.adoc'
+    to_file = output_file 'optimizer-custom-registered-invalid.pdf'
+    (expect do
+      Asciidoctor.convert_file input_file, backend: 'pdf', attributes: 'optimize=ebook pdf-optimizer=custom', to_file: to_file, safe: :safe
+    end).to raise_exception NotImplementedError, %r/must implement the #optimize_file method/
+  ensure
+    Asciidoctor::PDF::Optimizer.register 'custom', nil
+  end
 end)