module Asciidoctor::Converter

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

Attributes

backend[R]

Public: The String backend name that this converter is handling.

Public Class Methods

derive_backend_traits(backend, basebackend = nil) click to toggle source

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

# File lib/asciidoctor/converter.rb, line 91
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

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

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.

# File lib/asciidoctor/converter.rb, line 56
def initialize backend, opts = {}
  @backend = backend
end

Public Instance Methods

convert(node, transform = nil, opts = nil) click to toggle source

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.

# File lib/asciidoctor/converter.rb, line 71
def convert node, transform = nil, opts = nil
  raise ::NotImplementedError, %(#{self.class} (backend: #{@backend}) must implement the ##{__method__} method)
end

handles?(transform) click to toggle source

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.

# File lib/asciidoctor/converter.rb, line 81
def handles? transform
  true
end