module Asciidoctor::Extensions - asciidoctor-1.5.6.2 Documentation

# 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 1479
    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, %Q(Could not resolve class for name: #{qualified_name})
        end
      end
      raise ::NameError, %Q(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 1382
    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 1369
    def generate_name
      %Q(extgrp#{next_auto_id})
    end

groups() click to toggle source

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

next_auto_id() click to toggle source

    # File lib/asciidoctor/extensions.rb, line 1373
    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 1426
    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, %Q(Extension group to register not specified)
      end
      name = args.pop || generate_name
      unless args.empty?
        raise ::ArgumentError, %Q(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 1467
    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 1456
    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 1446
    def unregister_all
      @groups = {}
      nil
    end