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.

Constants

Treeprocessor

Public: TreeProcessors are run on the Document after the source has been parsed into an abstract syntax tree (AST), as represented by the Document object and its child Node objects (e.g., Section, Block, List, ListItem).

Asciidoctor invokes the {Processor#process} method on an instance of each registered TreeProcessor.

TreeProcessor implementations must extend TreeProcessor.

Public Class Methods

build_registry(name = nil, &block)

Deprecated: Use create instead of ::build_registry

Alias for: create
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 1466
def class_for_name qualified_name
  resolved = ::Object
  (qualified_name.split '::').each do |name|
    unless name.empty? || ((resolved.const_defined? name) && ::Module === (resolved = resolved.const_get name))
      raise ::NameError, %(Could not resolve class for name: #{qualified_name})
    end
  end
  raise ::NameError, %(Could not resolve class for name: #{qualified_name}) unless ::Class === resolved
  resolved
end
create(name = nil, &block) click to toggle source
# File lib/asciidoctor/extensions.rb, line 1369
def create name = nil, &block
  if block_given?
    Registry.new({ (name || generate_name) => block })
  else
    Registry.new
  end
end
Also aliased as: build_registry
generate_name() click to toggle source
# File lib/asciidoctor/extensions.rb, line 1356
def generate_name
  %(extgrp#{next_auto_id})
end
groups() click to toggle source
# File lib/asciidoctor/extensions.rb, line 1365
def groups
  @groups ||= {}
end
next_auto_id() click to toggle source
# File lib/asciidoctor/extensions.rb, line 1360
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 1413
def register *args, &block
  argc = args.size
  if block_given?
    resolved_group = block
  elsif (group = args.pop)
    # QUESTION should we instantiate the group class here or defer until activation??
    resolved_group = (resolve_class group) || group
  else
    raise ::ArgumentError, %(Extension group to register not specified)
  end
  name = args.pop || generate_name
  unless args.empty?
    raise ::ArgumentError, %(Wrong number of arguments (#{argc} for 1..2))
  end
  groups[name.to_sym] = resolved_group
end
resolve_class(object) click to toggle source

Internal: Resolve the specified object as a Class

object - The object to resolve as a Class

Returns a Class if the specified object is a Class (but not a Module) or a String that resolves to a Class; otherwise, nil

# File lib/asciidoctor/extensions.rb, line 1454
def resolve_class object
  case object
  when ::Class
    object
  when ::String
    class_for_name object
  end
end
unregister(*names) click to toggle source

Public: Unregister statically-registered extension groups by name.

names - one or more Symbol or String group names to unregister

Returns nothing

# File lib/asciidoctor/extensions.rb, line 1443
def unregister *names
  names.each {|group| @groups.delete group.to_sym }
  nil
end
unregister_all() click to toggle source

Public: Unregister all statically-registered extension groups.

Returns nothing

# File lib/asciidoctor/extensions.rb, line 1433
def unregister_all
  @groups = {}
  nil
end