Module: Asciidoctor::Converter::Factory

Included in:
CustomFactory, DefaultFactory
Defined in:
lib/asciidoctor/converter.rb

Overview

A reusable module for registering and instantiating Converter classes used to convert an AbstractNode to an output (aka backend) format such as HTML or DocBook.

Converter objects are instantiated by passing a String backend name and, optionally, an options Hash to the #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 module or a concrete class that includes this module such as CustomFactory. For example:

Examples:

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

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.create(backend, opts = {}) ⇒ Object

Deprecated.

Do not use this in new code, and replace it when updating old code.

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



187
188
189
 
# File 'lib/asciidoctor/converter.rb', line 187

def self.create backend, opts = {}
  default.create backend, opts
end

.default(*args) ⇒ Object

Deprecated.

Do not use this in new code, and replace it when updating old code.

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



182
183
184
 
# File 'lib/asciidoctor/converter.rb', line 182

def self.default *args
  Converter
end

.new(converters = nil, proxy_default: true) ⇒ Object

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.

Parameters:

  • converters (defaults to: nil) —

    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 (defaults to: true) —

    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.



177
178
179
 
# File 'lib/asciidoctor/converter.rb', line 177

def self.new converters = nil, proxy_default: true
  proxy_default ? (DefaultFactoryProxy.new converters) : (CustomFactory.new converters)
end

Instance Method Details

#converters ⇒ Object

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



245
246
247
 
# File 'lib/asciidoctor/converter.rb', line 245

def converters
  registry.merge
end

#create(backend, opts = {}) ⇒ Converter

Create a new Converter object that can be used to convert AbstractNodes 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.

Parameters:

  • backend —

    the String backend name.

  • opts (defaults to: {}) —

    a Hash of options to customize creation; also passed to the converter’s constructor:

Options Hash (opts):

  • :template_dirs (Object) —

    a String Array of directories used to instantiate a TemplateConverter (optional).

  • :delegate_backend (Object) —

    a backend String of the last converter in the CompositeConverter chain (optional).

Returns:

  • (Converter) —

    Returns the Converter instance.



226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/asciidoctor/converter.rb', line 226

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) ⇒ Converter

Lookup the custom converter registered with this factory to handle the specified backend.

Parameters:

  • backend —

    The String backend name.

Returns:

  • (Converter) —

    Returns the Converter class registered to convert the specified backend or nil if no match is found.



207
208
209
 
# File 'lib/asciidoctor/converter.rb', line 207

def for backend
  registry[backend]
end

#register(converter, *backends) ⇒ void

This method returns an undefined value.

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.

Parameters:

  • converter —

    The Converter class to register.

  • backends —

    One or more String backend names that this converter should be registered to handle.



198
199
200
 
# File 'lib/asciidoctor/converter.rb', line 198

def register converter, *backends
  backends.each {|backend| backend == '*' ? (registry.default = converter) : (registry[backend] = converter) }
end