module Asciidoctor::Converter::Factory

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.

{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.

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

converter = Asciidoctor::Converter.create 'html5', htmlsyntax: 'xml'

Public Class Methods

create(backend, opts = {}) click to toggle source

Deprecated: Maps the create method on the old default factory instance holder to the Converter module.

# File lib/asciidoctor/converter.rb, line 188
def self.create backend, opts = {}
  default.create backend, opts
end

default(*args) click to toggle source

Deprecated: Maps the old default factory instance holder to the Converter module.

# File lib/asciidoctor/converter.rb, line 183
def self.default *args
  Converter
end

new(converters = nil, proxy_default: true) click to toggle source

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.

# File lib/asciidoctor/converter.rb, line 178
def self.new converters = nil, proxy_default: true
  proxy_default ? (DefaultFactoryProxy.new converters) : (CustomFactory.new converters)
end

Public Instance Methods

converters() click to toggle source

Public: Get the Hash of Converter classes keyed by backend name. Intended for testing only.

# File lib/asciidoctor/converter.rb, line 246
def converters
  registry.merge
end

create(backend, opts = {}) click to toggle source

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.

# File lib/asciidoctor/converter.rb, line 227
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
      TemplateConverter.new backend, template_dirs, opts
    end
  end
end

for(backend) click to toggle source

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.

# File lib/asciidoctor/converter.rb, line 208
def for backend
  registry[backend]
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

# File lib/asciidoctor/converter.rb, line 199
def register converter, *backends
  backends.each {|backend| backend == '*' ? (registry.default = converter) : (registry[backend] = converter) }
end