module Asciidoctor::Extensions

Extensions provide a way to participate in the parsing and converting phases of the AsciiDoc processor or extend the AsciiDoc syntax.

The various extensions participate in AsciiDoc processing as follows:

  1. After the source lines are normalized, {Preprocessor}s modify or replace the source lines before parsing begins. {IncludeProcessor}s are used to process include directives for targets which they claim to handle.

  2. The Parser parses the block-level content into an abstract syntax tree. Custom blocks and block macros are processed by associated {BlockProcessor}s and {BlockMacroProcessor}s, respectively.

  3. {Treeprocessor}s are run on the abstract syntax tree.

  4. Conversion of the document begins, at which point inline markup is processed and converted. Custom inline macros are processed by associated {InlineMacroProcessor}s.

  5. {Postprocessor}s modify or replace the converted document.

  6. The output is written to the output stream.

Extensions may be registered globally using the {Extensions.register} method or added to a custom {Registry} instance and passed as an option to a single Asciidoctor processor.

Public Class Methods

build_registry(name = nil, &block) click to toggle source
# File lib/asciidoctor/extensions.rb, line 1249
def build_registry name = nil, &block
  if block_given?
    name ||= generate_name
    Registry.new({ name => block })
  else
    Registry.new
  end
end
class_for_name(qualified_name) click to toggle source

Public: Resolves the Class object for the qualified name.

Returns Class

# File lib/asciidoctor/extensions.rb, line 1331
def class_for_name qualified_name
  resolved_class = ::Object
  qualified_name.split('::').each do |name|
    if name.empty?
      # do nothing
    elsif resolved_class.const_defined? name
      resolved_class = resolved_class.const_get name
    else
      raise %Q(Could not resolve class for name: #{qualified_name})
    end
  end
  resolved_class
end
generate_name() click to toggle source
# File lib/asciidoctor/extensions.rb, line 1236
def generate_name
  %Q(extgrp#{next_auto_id})
end
groups() click to toggle source
# File lib/asciidoctor/extensions.rb, line 1245
def groups
  @groups ||= {}
end
next_auto_id() click to toggle source
# File lib/asciidoctor/extensions.rb, line 1240
def next_auto_id
  @auto_id ||= -1
  @auto_id += 1
end
register(*args, &block) click to toggle source

Public: Registers an extension Group that subsequently registers a collection of extensions.

Registers the extension Group specified under the given name. If a name is not given, one is calculated by appending the next value in a 0-based index to the string “extgrp”. For instance, the first unnamed extension group to be registered is assigned the name “extgrp0” if a name is not specified.

The names are not yet used, but are intended for selectively activating extensions in the future.

If the extension group argument is a String or a Symbol, it gets resolved to a Class before being registered.

name - The name under which this extension group is registered (optional, default: nil) group - A block (Proc), a Class, a String or Symbol name of a Class or

an Object instance of a Class.

Examples

Asciidoctor::Extensions.register UmlExtensions

Asciidoctor::Extensions.register :uml, UmlExtensions

Asciidoctor::Extensions.register do
  block_processor :plantuml, PlantUmlBlock
end

Asciidoctor::Extensions.register :uml do
  block_processor :plantuml, PlantUmlBlock
end

Returns the [Proc, Class or Object] instance, matching the type passed to this method.

# File lib/asciidoctor/extensions.rb, line 1292
def register *args, &block
  argc = args.length
  resolved_group = if block_given?
    block
  elsif !(group = args.pop)
    raise ::ArgumentError.new %Q(Extension group to register not specified)
  else
    # QUESTION should we instantiate the group class here or defer until
    # activation??
    case group
    when ::Class
      group
    when ::String
      class_for_name group
    when ::Symbol
      class_for_name group.to_s
    else
      group
    end
  end
  name = args.pop || generate_name
  unless args.empty?
    raise ::ArgumentError.new %Q(Wrong number of arguments (#{argc} for 1..2))
  end
  groups[name] = resolved_group
end
resolve_class(object) click to toggle source

unused atm, but tested

# File lib/asciidoctor/extensions.rb, line 1324
def resolve_class object
  ::Class === object ? object : (class_for_name object.to_s)
end
unregister_all() click to toggle source
# File lib/asciidoctor/extensions.rb, line 1319
def unregister_all
  @groups = {}
end