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:

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.
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.
{TreeProcessor}s are run on the abstract syntax tree.
Conversion of the document begins, at which point inline markup is processed and converted. Custom inline macros are processed by associated {InlineMacroProcessor}s.
{Postprocessor}s modify or replace the converted document.
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

create(name = nil, &block) click to toggle source

# File lib/asciidoctor/extensions.rb, line 1491
def create name = nil, &block
  if block_given?
    Registry.new (name || generate_name) => block
  else
    Registry.new
  end
end

generate_name() click to toggle source

# File lib/asciidoctor/extensions.rb, line 1478
def generate_name
  %(extgrp#{next_auto_id})
end

groups() click to toggle source

# File lib/asciidoctor/extensions.rb, line 1487
def groups
  @groups ||= {}
end

next_auto_id() click to toggle source

# File lib/asciidoctor/extensions.rb, line 1482
def next_auto_id
  @auto_id ||= -1
  @auto_id += 1
end

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 1533
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 = (Helpers.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

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 1563
def unregister *names
  names.each_with_object(groups) {|group, catalog| catalog.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 1553
def unregister_all
  @groups = {}
  nil
end