asciidoctor 1.5.8 → 2.0.17

data/lib/asciidoctor/converter.rb

@@ -1,232 +1,417 @@
-# encoding: UTF-8
+# frozen_string_literal: true
 module Asciidoctor
-  # A base module for defining converters that can be used to convert {AbstractNode}
-  # objects in a parsed AsciiDoc document to a backend format such as HTML or
-  # DocBook.
+# A module for defining converters that are used to convert {AbstractNode} objects in a parsed AsciiDoc document to an
+# output (aka backend) format such as HTML or DocBook.
+#
+# A {Converter} is typically instantiated each time an AsciiDoc document is processed (i.e., parsed and converted).
+# Implementing a custom converter entails:
+#
+# * Including the {Converter} module in a converter class and implementing the {Converter#convert} method or extending
+#   the {Converter::Base Base} class and implementing the dispatch methods that map to each node.
+# * Optionally registering the converter with one or more backend names statically using the +register_for+ DSL method
+#   contributed by the {Converter::Config Config} module.
+#
+# Examples
+#
+#   class TextConverter
+#     include Asciidoctor::Converter
+#     register_for 'text'
+#     def initialize *args
+#       super
+#       outfilesuffix '.txt'
+#     end
+#     def convert node, transform = node.node_name, opts = nil
+#       case transform
+#       when 'document', 'section'
+#         [node.title, node.content].join %(\n\n)
+#       when 'paragraph'
+#         (node.content.tr ?\n, ' ') << ?\n
+#       else
+#         (transform.start_with? 'inline_') ? node.text : node.content
+#       end
+#     end
+#   end
+#   puts Asciidoctor.convert_file 'sample.adoc', backend: :text, safe: :safe
+#
+#   class Html5Converter < (Asciidoctor::Converter.for 'html5')
+#     register_for 'html5'
+#     def convert_paragraph node
+#       %(<p>#{node.content}</p>)
+#     end
+#   end
+#   puts Asciidoctor.convert_file 'sample.adoc', safe: :safe
+module Converter
+  autoload :CompositeConverter, %(#{__dir__}/converter/composite)
+  autoload :TemplateConverter, %(#{__dir__}/converter/template) unless RUBY_ENGINE == 'opal'
+
+  # Public: The String backend name that this converter is handling.
+  attr_reader :backend
+
+  # Public: Creates a new instance of this {Converter}.
+  #
+  # backend - The String backend name (aka format) to which this converter converts.
+  # opts    - An options Hash (optional, default: {})
+  #
+  # Returns a new [Converter] instance.
+  def initialize backend, opts = {}
+    @backend = backend
+  end
+
+  # Public: Converts an {AbstractNode} using the given transform.
+  #
+  # This method must be implemented by a concrete converter class.
+  #
+  # node      - The concrete instance of AbstractNode to convert.
+  # transform - An optional String transform that hints at which transformation should be applied to this node. If a
+  #             transform is not given, the transform is often derived from the value of the {AbstractNode#node_name}
+  #             property. (optional, default: nil)
+  # opts      - An optional Hash of options hints about how to convert the node. (optional, default: nil)
+  #
+  # Returns the [String] result.
+  def convert node, transform = nil, opts = nil
+    raise ::NotImplementedError, %(#{self.class} (backend: #{@backend}) must implement the ##{__method__} method)
+  end
+
+  # Public: Reports whether the current converter is able to convert this node (by its transform name). Used by the
+  # {CompositeConverter} to select which converter to use to handle a given node. Returns true by default.
+  #
+  # transform - the String name of the node transformation (typically the node name).
+  #
+  # Returns a [Boolean] indicating whether this converter can handle the specified transform.
+  def handles? transform
+    true
+  end
+
+  # Public: Derive backend traits (basebackend, filetype, outfilesuffix, htmlsyntax) from the given backend.
+  #
+  # backend - the String backend from which to derive the traits
+  # basebackend - the String basebackend to use in favor of deriving one from the backend (optional, default: nil)
+  #
+  # Returns the backend traits for the given backend as a [Hash].
+  def self.derive_backend_traits backend, basebackend = nil
+    return {} unless backend
+    if (outfilesuffix = DEFAULT_EXTENSIONS[(basebackend ||= backend.sub TrailingDigitsRx, '')])
+      filetype = outfilesuffix.slice 1, outfilesuffix.length
+    else
+      outfilesuffix = %(.#{filetype = basebackend})
+    end
+    filetype == 'html' ?
+      { basebackend: basebackend, filetype: filetype, htmlsyntax: 'html', outfilesuffix: outfilesuffix } :
+      { basebackend: basebackend, filetype: filetype, outfilesuffix: outfilesuffix }
+  end
+
+  module BackendTraits
+    def basebackend value = nil
+      value ? ((backend_traits value)[:basebackend] = value) : backend_traits[:basebackend]
+    end
+
+    def filetype value = nil
+      value ? (backend_traits[:filetype] = value) : backend_traits[:filetype]
+    end
+
+    def htmlsyntax value = nil
+      value ? (backend_traits[:htmlsyntax] = value) : backend_traits[:htmlsyntax]
+    end
+
+    def outfilesuffix value = nil
+      value ? (backend_traits[:outfilesuffix] = value) : backend_traits[:outfilesuffix]
+    end
+
+    def supports_templates value = true
+      backend_traits[:supports_templates] = value
+    end
+
+    def supports_templates?
+      backend_traits[:supports_templates]
+    end
+
+    def init_backend_traits value = nil
+      @backend_traits = value || {}
+    end
+
+    def backend_traits basebackend = nil
+      @backend_traits ||= Converter.derive_backend_traits @backend, basebackend
+    end
+
+    alias backend_info backend_traits
+
+    # Deprecated: Use {Converter.derive_backend_traits} instead.
+    def self.derive_backend_traits backend, basebackend = nil
+      Converter.derive_backend_traits backend, basebackend
+    end
+  end
+
+  # A module that contributes the +register_for+ method for registering a converter with the default registry.
+  module Config
+    # Public: Registers this {Converter} class with the default registry to handle the specified backend name(s).
+    #
+    # backends - One or more String backend names with which to associate this {Converter} class.
+    #
+    # Returns nothing.
+    def register_for *backends
+      Converter.register self, *(backends.map {|backend| backend.to_s })
+    end
+  end
+
+  # A reusable module for registering and instantiating {Converter Converter} classes used to convert an {AbstractNode}
+  # to an output (aka backend) format such as HTML or DocBook.
   #
-  # Implementing a converter involves:
+  # {Converter Converter} objects are instantiated by passing a String backend name and, optionally, an options Hash to
+  # the {Factory#create} method. The backend can be thought of as an intent to convert a document to a specified format.
   #
-  # * including this module in a {Converter} implementation class
-  # * overriding the {Converter#convert} method
-  # * optionally associating the converter with one or more backends using
-  #   the {#register_for} DSL method imported by the {Config Converter::Config} module
+  # Applications interact with the factory either through the global, static registry mixed into the {Converter
+  # Converter} module or a concrete class that includes this module such as {CustomFactory}. For example:
   #
   # Examples
   #
-  #   class TextConverter
-  #     include Asciidoctor::Converter
-  #     register_for 'text'
-  #     def initialize backend, opts
-  #       super
-  #       outfilesuffix '.txt'
-  #     end
-  #     def convert node, transform = nil, opts = {}
-  #       case (transform ||= node.node_name)
-  #       when 'document'
-  #         node.content
-  #       when 'section'
-  #         [node.title, node.content].join "\n\n"
-  #       when 'paragraph'
-  #         node.content.tr("\n", ' ') << "\n"
-  #       else
-  #         if transform.start_with? 'inline_'
-  #           node.text
-  #         else
-  #           %(<#{transform}>\n)
-  #         end
-  #       end
-  #     end
-  #   end
-  #
-  #   puts Asciidoctor.convert_file 'sample.adoc', backend: :text
-  module Converter
-    # A module that provides the {#register_for} method for statically
-    # registering a converter with the default {Factory Converter::Factory} instance.
-    module Config
-      # Public: Statically registers the current {Converter} class with the default
-      # {Factory Converter::Factory} to handle conversion to the specified backends.
-      #
-      # This method also defines the converts? method on the class which returns whether
-      # the class is registered to convert a specified backend.
-      #
-      # backends - A String Array of backends with which to associate this {Converter} class.
-      #
-      # Returns nothing
-      def register_for *backends
-        Factory.register self, backends
-        metaclass = class << self; self; end
-        if backends == ['*']
-          metaclass.send :define_method, :converts? do |name|
-            true
-          end
+  #   converter = Asciidoctor::Converter.create 'html5', htmlsyntax: 'xml'
+  module Factory
+    # Public: Create an instance of DefaultProxyFactory or CustomFactory, depending on whether the proxy_default keyword
+    # arg is set (true by default), and optionally seed it with the specified converters map. If proxy_default is set,
+    # entries in the proxy registry are preferred over matching entries from the default registry.
+    #
+    # converters    - An optional Hash of converters to use in place of ones in the default registry. The keys are
+    #                 backend names and the values are converter classes or instances.
+    # proxy_default - A Boolean keyword arg indicating whether to proxy the default registry (optional, default: true).
+    #
+    # Returns a Factory instance (DefaultFactoryProxy or CustomFactory) seeded with the optional converters map.
+    def self.new converters = nil, proxy_default: true
+      proxy_default ? (DefaultFactoryProxy.new converters) : (CustomFactory.new converters)
+    end
+
+    # Deprecated: Maps the old default factory instance holder to the Converter module.
+    def self.default *args
+      Converter
+    end
+
+    # Deprecated: Maps the create method on the old default factory instance holder to the Converter module.
+    def self.create backend, opts = {}
+      default.create backend, opts
+    end
+
+    # Public: Register a custom converter with this factory to handle conversion for the specified backends. If the
+    # backend is an asterisk (i.e., +*+), the converter will handle any backend for which a converter is not registered.
+    #
+    # converter - The Converter class to register.
+    # backends  - One or more String backend names that this converter should be registered to handle.
+    #
+    # Returns nothing
+    def register converter, *backends
+      backends.each {|backend| backend == '*' ? (registry.default = converter) : (registry[backend] = converter) }
+    end
+
+    # Public: Lookup the custom converter registered with this factory to handle the specified backend.
+    #
+    # backend - The String backend name.
+    #
+    # Returns the [Converter] class registered to convert the specified backend or nil if no match is found.
+    def for backend
+      registry[backend]
+    end
+
+    # Public: Create a new Converter object that can be used to convert {AbstractNode}s to the format associated with
+    # the backend. This method accepts an optional Hash of options that are passed to the converter's constructor.
+    #
+    # If a custom Converter is found to convert the specified backend, it's instantiated (if necessary) and returned
+    # immediately. If a custom Converter is not found, an attempt is made to find a built-in converter. If the
+    # +:template_dirs+ key is found in the Hash passed as the second argument, a {CompositeConverter} is created that
+    # delegates to a {TemplateConverter} and, if found, the built-in converter. If the +:template_dirs+ key is not
+    # found, the built-in converter is returned or nil if no converter is found.
+    #
+    # backend - the String backend name.
+    # opts    - a Hash of options to customize creation; also passed to the converter's constructor:
+    #           :template_dirs - a String Array of directories used to instantiate a {TemplateConverter} (optional).
+    #           :delegate_backend - a backend String of the last converter in the {CompositeConverter} chain (optional).
+    #
+    # Returns the [Converter] instance.
+    def create backend, opts = {}
+      if (converter = self.for backend)
+        converter = converter.new backend, opts if ::Class === converter
+        if (template_dirs = opts[:template_dirs]) && BackendTraits === converter && converter.supports_templates?
+          CompositeConverter.new backend, (TemplateConverter.new backend, template_dirs, opts), converter, backend_traits_source: converter
+        else
+          converter
+        end
+      elsif (template_dirs = opts[:template_dirs])
+        if (delegate_backend = opts[:delegate_backend]) && (converter = self.for delegate_backend)
+          converter = converter.new delegate_backend, opts if ::Class === converter
+          CompositeConverter.new backend, (TemplateConverter.new backend, template_dirs, opts), converter, backend_traits_source: converter
         else
-          metaclass.send :define_method, :converts? do |name|
-            backends.include? name
-          end
+          TemplateConverter.new backend, template_dirs, opts
         end
-        nil
       end
     end
 
-    module BackendInfo
-      def backend_info
-        @backend_info ||= setup_backend_info
-      end
+    # Public: Get the Hash of Converter classes keyed by backend name. Intended for testing only.
+    def converters
+      registry.merge
+    end
 
-      def setup_backend_info
-        raise ::ArgumentError, %(Cannot determine backend for converter: #{self.class}) unless @backend
-        base = @backend.sub TrailingDigitsRx, ''
-        if (ext = DEFAULT_EXTENSIONS[base])
-          type = ext.slice 1, ext.length
-        else
-          # QUESTION should we be forcing the basebackend to html if unknown?
-          base = 'html'
-          ext = '.html'
-          type = 'html'
-          syntax = 'html'
-        end
-        {
-          :basebackend => base,
-          :outfilesuffix => ext,
-          :filetype => type,
-          :htmlsyntax => syntax
-        }
+    private
+
+    def registry
+      raise ::NotImplementedError, %(#{Factory} subclass #{self.class} must implement the ##{__method__} method)
+    end
+  end
+
+  class CustomFactory
+    include Factory
+
+    def initialize seed_registry = nil
+      if seed_registry
+        seed_registry.default = seed_registry.delete '*'
+        @registry = seed_registry
+      else
+        @registry = {}
       end
+    end
+
+    # Public: Unregister all Converter classes that are registered with this factory. Intended for testing only.
+    #
+    # Returns nothing.
+    def unregister_all
+      registry.clear.default = nil
+    end
+
+    private
+
+    attr_reader :registry
+  end
+
+  # Mixed into the {Converter} module to provide the global registry of converters that are registered statically.
+  #
+  # This registry includes built-in converters for {Html5Converter HTML 5}, {DocBook5Converter DocBook 5} and
+  # {ManPageConverter man(ual) page}, as well as any custom converters that have been discovered or explicitly
+  # registered. Converter registration is synchronized (where applicable) and is thus guaranteed to be thread safe.
+  module DefaultFactory
+    include Factory
+
+    private
+
+    @@registry = {}
 
-      def filetype value = nil
-        if value
-          backend_info[:filetype] = value
+    def registry
+      @@registry
+    end
+
+    unless RUBY_ENGINE == 'opal' # the following block adds support for synchronization and lazy registration
+      public
+
+      def register converter, *backends
+        if @@mutex.owned?
+          backends.each {|backend| backend == '*' ? (@@catch_all = converter) : (@@registry = @@registry.merge backend => converter) }
         else
-          backend_info[:filetype]
+          @@mutex.synchronize { register converter, *backends }
         end
       end
 
-      def basebackend value = nil
-        if value
-          backend_info[:basebackend] = value
-        else
-          backend_info[:basebackend]
+      def unregister_all
+        @@mutex.synchronize do
+          @@registry = @@registry.select {|backend| PROVIDED[backend] }
+          @@catch_all = nil
         end
       end
 
-      def outfilesuffix value = nil
-        if value
-          backend_info[:outfilesuffix] = value
-        else
-          backend_info[:outfilesuffix]
+      def for backend
+        @@registry.fetch backend do
+          PROVIDED[backend] ? (@@mutex.synchronize do
+            # require is thread-safe, so no reason to refetch
+            require PROVIDED[backend]
+            @@registry[backend]
+          end) : catch_all
         end
       end
 
-      def htmlsyntax value = nil
-        if value
-          backend_info[:htmlsyntax] = value
-        else
-          backend_info[:htmlsyntax]
-        end
+      PROVIDED = {
+        'docbook5' => %(#{__dir__}/converter/docbook5),
+        'html5' => %(#{__dir__}/converter/html5),
+        'manpage' => %(#{__dir__}/converter/manpage),
+      }
+
+      private
+
+      def catch_all
+        @@catch_all
       end
 
-      def supports_templates
-        backend_info[:supports_templates] = true
+      @@catch_all = nil
+      @@mutex = ::Mutex.new
+    end
+  end
+
+  class DefaultFactoryProxy < CustomFactory
+    include DefaultFactory # inserts module into ancestors immediately after superclass
+
+    unless RUBY_ENGINE == 'opal'
+      def unregister_all
+        super
+        @registry.clear.default = nil
       end
 
-      def supports_templates?
-        backend_info[:supports_templates]
+      def for backend
+        @registry.fetch(backend) { super }
       end
-    end
 
-    class << self
-      # Mixes the {Config Converter::Config} module into any class that includes the {Converter} module.
-      #
-      # converter - The Class that includes the {Converter} module
-      #
-      # Returns nothing
-      def included converter
-        converter.extend Config
+      private
+
+      def catch_all
+        @registry.default || super
       end
     end
+  end
 
-    include Config
-    include BackendInfo
+  # Internal: Mixes the {Config} module into any class that includes the {Converter} module. Additionally, mixes the
+  # {BackendTraits} method into instances of this class.
+  #
+  # into - The Class into which the {Converter} module is being included.
+  #
+  # Returns nothing.
+  def self.included into
+    into.send :include, BackendTraits
+    into.extend Config
+  end
+  private_class_method :included # use separate declaration for Ruby 2.0.x
+
+  # An abstract base class for defining converters that can be used to convert {AbstractNode} objects in a parsed
+  # AsciiDoc document to a backend format such as HTML or DocBook.
+  class Base
+    include Logging
+    include Converter
 
-    # Public: Creates a new instance of Converter
+    # Public: Converts an {AbstractNode} by delegating to a method that matches the transform value.
     #
-    # backend - The String backend format to which this converter converts.
-    # opts    - An options Hash (optional, default: {})
+    # This method looks for a method whose name matches the transform prefixed with "convert_" to dispatch to. If the
+    # +opts+ argument is non-nil, this method assumes the dispatch method accepts two arguments, the node and an options
+    # Hash. The options Hash may be used by converters to delegate back to the top-level converter. Currently, this
+    # feature is used for the outline transform. If the +opts+ argument is nil, this method assumes the dispatch method
+    # accepts the node as its only argument.
     #
-    # Returns a new instance of [Converter]
-    def initialize backend, opts = {}
-      @backend = backend
-      setup_backend_info
+    # See {Converter#convert} for details about the arguments and return value.
+    def convert node, transform = node.node_name, opts = nil
+      opts ? (send 'convert_' + transform, node, opts) : (send 'convert_' + transform, node)
+    rescue
+      raise unless ::NoMethodError === (ex = $!) && ex.receiver == self && ex.name.to_s == transform
+      logger.warn %(missing convert handler for #{ex.name} node in #{@backend} backend (#{self.class}))
+      nil
     end
 
-=begin
-    # Public: Invoked when this converter is added to the chain of converters in a {CompositeConverter}.
-    #
-    # owner - The CompositeConverter instance
-    #
-    # Returns nothing
-    def composed owner
+    def handles? transform
+      respond_to? %(convert_#{transform})
     end
-=end
 
-    # Public: Converts an {AbstractNode} using the specified transform along
-    # with additional options. If a transform is not specified, implementations
-    # typically derive one from the {AbstractNode#node_name} property.
+    # Public: Converts the {AbstractNode} using only its converted content.
     #
-    # Implementations are free to decide how to carry out the conversion. In
-    # the case of the built-in converters, the tranform value is used to
-    # dispatch to a handler method. The {TemplateConverter} uses the value of
-    # the transform to select a template to render.
-    #
-    # node      - The concrete instance of AbstractNode to convert
-    # transform - An optional String transform that hints at which transformation
-    #             should be applied to this node. If a transform is not specified,
-    #             the transform is typically derived from the value of the
-    #             node's node_name property. (optional, default: nil)
-    # opts      - An optional Hash of options that provide additional hints about
-    #             how to convert the node. (optional, default: {})
-    #
-    # Returns the [String] result
-    def convert node, transform = nil, opts = {}
-      raise ::NotImplementedError
+    # Returns the converted [String] content.
+    def content_only node
+      node.content
     end
 
-    alias handles? respond_to?
-
-    # Alias for backward compatibility.
-    alias convert_with_options convert
-  end
-
-  # A module that can be used to mix the {#write} method into a {Converter}
-  # implementation to allow the converter to control how the output is written
-  # to disk.
-  module Writer
-    # Public: Writes the output to the specified target file name or stream.
-    #
-    # output - The output String to write
-    # target - The String file name or stream object to which the output should
-    #          be written.
+    # Public: Skips conversion of the {AbstractNode}.
     #
-    # Returns nothing
-    def write output, target
-      if target.respond_to? :write
-        target.write output.chomp
-        # ensure there's a trailing endline to be nice to terminals
-        target.write LF
-      else
-        ::IO.write target, output
-      end
-      nil
-    end
+    # Returns nothing.
+    def skip node; end
   end
 
-  module VoidWriter
-    include Writer
-    # Public: Does not write output
-    def write output, target
-    end
-  end
+  extend DefaultFactory # exports static methods
+end
 end
-
-require 'asciidoctor/converter/base'
-require 'asciidoctor/converter/factory'

data/lib/asciidoctor/core_ext/float/truncate.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# NOTE remove once minimum required Ruby version is at least 2.4
+# NOTE use `send :prepend` to be nice to Ruby 2.0
+Float.send :prepend, (Module.new do
+  def truncate *args
+    if args.length == 1
+      if (precision = Integer args.shift) == 0
+        super
+      elsif precision > 0
+        precision_factor = 10.0 ** precision
+        (self * precision_factor).to_i / precision_factor
+      else
+        precision_factor = 10 ** precision.abs
+        (self / precision_factor).to_i * precision_factor
+      end
+    else
+      super
+    end
+  end
+end) if (Float.instance_method :truncate).arity == 0

data/lib/asciidoctor/core_ext/hash/merge.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+# NOTE remove once minimum required Ruby version is at least 2.6
+# NOTE use `send :prepend` to be nice to Ruby 2.0
+Hash.send :prepend, (Module.new do
+  def merge *args
+    (len = args.length) < 1 ? dup : (len > 1 ? args.inject(self) {|acc, arg| acc.merge arg } : (super args[0]))
+  end
+end) if (Hash.instance_method :merge).arity == 1

data/lib/asciidoctor/core_ext/match_data/names.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# NOTE remove once implemented in Opal; see https://github.com/opal/opal/issues/1964
+class MatchData
+  def names
+    []
+  end
+end unless MatchData.method_defined? :names

data/lib/asciidoctor/core_ext/nil_or_empty.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # A core library extension that defines the method nil_or_empty? as an alias to
 # optimize checks for nil? or empty? on common object types such as NilClass,
 # String, Array, Hash, and Numeric.

data/lib/asciidoctor/core_ext/regexp/is_match.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+# NOTE remove once minimum required Ruby version is at least 2.4
 class Regexp
-  alias match? === unless method_defined? :match?
-end
+  alias match? ===
+end unless Regexp.method_defined? :match?