asciidoctor 0.1.4 → 1.5.0

data/lib/asciidoctor/extensions.rb

@@ -1,443 +1,1235 @@
 module Asciidoctor
+# 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.
 module Extensions
-  class Extension
+
+  # Public: An abstract base class for document and syntax processors.
+  #
+  # This class provides access to a class-level Hash for holding default
+  # configuration options defined using the {Processor.option} method. This
+  # style of default configuration is specific to the native Ruby environment
+  # and is only consulted inside the initializer. An overriding configuration
+  # Hash can be passed to the initializer. Once the processor is initialized,
+  # the configuration is accessed using the {Processor#config} instance variable.
+  #
+  # Instances of the Processor class provide convenience methods for creating
+  # AST nodes, such as Block and Inline, and for parsing child content.
+  class Processor
     class << self
-      def register
-        ::Asciidoctor::Extensions.register self
+      # Public: Get the static configuration for this processor class.
+      # 
+      # Returns a configuration [Hash]
+      def config
+        @config ||= {}
+      end
+
+      # Public: Assigns a default value for the specified option that gets
+      # applied to all instances of this processor.
+      #
+      # Examples
+      #
+      #   option :contexts, [:open, :paragraph]
+      #
+      # Returns nothing
+      def option key, default_value
+        config[key] = default_value
       end
 
-      def activate registry, document
+      # Include the DSL class for this processor into this processor class or instance.
+      #
+      # This method automatically detects whether to use the include or extend keyword
+      # based on what is appropriate.
+      #
+      # Returns nothing
+      def use_dsl
+        if self.name.nil_or_empty?
+          # NOTE contants(false) doesn't exist in Ruby 1.8.7
+          #include const_get :DSL if constants(false).grep :DSL
+          include const_get :DSL if constants.grep :DSL
+        else
+          # NOTE contants(false) doesn't exist in Ruby 1.8.7
+          #extend const_get :DSL if constants(false).grep :DSL
+          extend const_get :DSL if constants.grep :DSL
+        end
       end
+      alias :extend_dsl :use_dsl
+      alias :include_dsl :use_dsl
     end
-  end
 
-  class << self
-    def registered?
-      !@registered.nil?
+    # Public: Get the configuration Hash for this processor instance.
+    attr_reader :config
+
+    def initialize config = {}
+      @config = self.class.config.merge config
     end
 
-    def registered
-      @registered ||= []
+    def update_config config
+      @config.update config
     end
 
-    # QUESTION should we require extensions to have names?
-    # how about autogenerate name for class, assume extension
-    # is name of block if block is given
-    # having a name makes it easier to unregister an extension
-    def register extension = nil, &block
-      if block_given?
-        registered << block
-      elsif extension
-        registered << resolve_class(extension)
-      end 
+    def process *args
+      raise ::NotImplementedError
     end
 
-    def resolve_class(object)
-      object.is_a?(Class) ? object : class_for_name(object.to_s)
+    def create_block parent, context, source, attrs, opts = {}
+      Block.new parent, context, { :source => source, :attributes => attrs }.merge(opts)
     end
 
-    def class_for_name(qualified_name)
-      qualified_name.split('::').inject(Object) do |module_, name|
-        if name.empty?
-          module_
-        elsif module_.const_defined? name
-          module_.const_get(name)
-        else
-          raise "Could not resolve class for name: #{qualified_name}"
-        end
+    def create_image_block parent, attrs, opts = {}
+      create_block parent, :image, nil, attrs, opts
+    end
+
+    def create_inline parent, context, text, opts = {}
+      Inline.new parent, context, text, opts
+    end
+
+    # Public: Parses blocks in the content and attaches the block to the parent.
+    #
+    # Returns nothing
+    #--
+    # QUESTION is parse_content the right method name? should we wrap in open block automatically?
+    def parse_content parent, content, attributes = {}
+      reader = (content.is_a? Reader) ? reader : (Reader.new content)
+      while reader.has_more_lines?
+        block = Parser.next_block(reader, parent, attributes)
+        parent << block if block
       end
+      nil
     end
 
-    def unregister_all
-      @registered = []
+    # TODO fill out remaining methods
+    [
+      [:create_paragraph,     :create_block,  :paragraph],
+      [:create_open_block,    :create_block,  :open],
+      [:create_example_block, :create_block,  :example],
+      [:create_pass_block,    :create_block,  :pass],
+      [:create_listing_block, :create_block,  :listing],
+      [:create_literal_block, :create_block,  :literal],
+      [:create_anchor,        :create_inline, :anchor]
+    ].each do |method_name, delegate_method_name, context|
+      define_method method_name do |*args|
+        send delegate_method_name, *args.dup.insert(1, context)
+      end
     end
   end
 
-  class Registry
-    attr_accessor :preprocessors
-    attr_accessor :treeprocessors
-    attr_accessor :postprocessors
-    attr_accessor :include_processors
-    attr_accessor :blocks
-    attr_accessor :block_macros
-    attr_accessor :inline_macros
-
-    def initialize document = nil
-      @preprocessors = []
-      @treeprocessors = []
-      @postprocessors = []
-      @include_processors = []
-      @include_processor_cache = {}
-      @block_delimiters = {}
-      @blocks = {}
-      @block_processor_cache = {}
-      @block_macros = {}
-      @block_macro_processor_cache = {}
-      @inline_macros = {}
-      @inline_macro_processor_cache = {}
-
-      Extensions.registered.each do |extension|
-        if extension.is_a? Proc
-          register document, &extension
-        else
-          extension.activate self, document
-        end
-      end
-    end 
-
-    def preprocessor processor, position = :<<
-      processor = resolve_processor_class processor
-      if position == :<< || @preprocessors.empty?
-        @preprocessors.push processor
-      elsif position == :>>
-        @preprocessors.unshift processor
+  # Internal: Overlays a builder DSL for configuring the Processor instance.
+  # Includes a method to define configuration options and another to define the
+  # {Processor#process} method.
+  module ProcessorDsl
+    def option key, value
+      config[key] = value
+    end
+
+    def process *args, &block
+      # need to check for both block/proc and lambda
+      # TODO need test for this!
+      #if block_given? || (args.size == 1 && ((block = args[0]).is_a? ::Proc))
+      if block_given?
+        @process_block = block
+      elsif @process_block
+        # NOTE Proc automatically expands a single array argument
+        # ...but lambda doesn't (and we want to accept lambdas too)
+        # TODO need a test for this!
+        @process_block.call(*args)
       else
-        @preprocessors.push processor
+        raise ::NotImplementedError
       end
     end
+    #alias :process_with :process
 
-    def preprocessors?
-      !@preprocessors.empty?
+    def process_block_given?
+      defined? @process_block
     end
+  end
 
-    def load_preprocessors *args
-      @preprocessors.map do |processor|
-        processor.new(*args)
-      end
+  # Public: Preprocessors are run after the source text is split into lines and
+  # normalized, but before parsing begins.
+  #
+  # Prior to invoking the preprocessor, Asciidoctor splits the source text into
+  # lines and normalizes them. The normalize process strips trailing whitespace
+  # from each line and leaves behind a line-feed character (i.e., "\n").
+  #
+  # Asciidoctor passes a reference to the Reader and a copy of the lines Array
+  # to the {Processor#process} method of an instance of each registered
+  # Preprocessor. The Preprocessor modifies the Array as necessary and either
+  # returns a reference to the same Reader or a reference to a new Reader.
+  #
+  # Preprocessor implementations must extend the Preprocessor class.
+  class Preprocessor < Processor
+    def process document, reader
+      raise ::NotImplementedError
     end
+  end
+  Preprocessor::DSL = ProcessorDsl
 
-    def treeprocessor processor, position = :<<
-      processor = resolve_processor_class processor
-      if position == :<< || @treeprocessors.empty?
-        @treeprocessors.push processor
-      elsif position == :>>
-        @treeprocessors.unshift processor
+  # 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.
+  #--
+  # QUESTION should the treeprocessor get invoked after parse header too?
+  class Treeprocessor < Processor
+    def process document
+      raise ::NotImplementedError
+    end
+  end
+  Treeprocessor::DSL = ProcessorDsl
+
+  # Public: Postprocessors are run after the document is converted, but before
+  # it is written to the output stream.
+  #
+  # Asciidoctor passes a reference to the converted String to the {Processor#process}
+  # method of each registered Postprocessor. The Preprocessor modifies the
+  # String as necessary and returns the String replacement.
+  #
+  # The markup format in the String is determined by the backend used to convert
+  # the Document. The backend and be looked up using the backend method on the
+  # Document object, as well as various backend-related document attributes.
+  #
+  # TIP: Postprocessors can also be used to relocate assets needed by the published
+  # document.
+  #
+  # Postprocessor implementations must Postprocessor.
+  class Postprocessor < Processor
+    def process document, output
+      raise ::NotImplementedError
+    end
+  end
+  Postprocessor::DSL = ProcessorDsl
+
+  # Public: IncludeProcessors are used to process `include::<target>[]`
+  # directives in the source document.
+  #
+  # When Asciidoctor comes across a `include::<target>[]` directive in the
+  # source document, it iterates through the IncludeProcessors and delegates
+  # the work of reading the content to the first processor that identifies
+  # itself as capable of handling that target.
+  #
+  # IncludeProcessor implementations must extend IncludeProcessor.
+  #--
+  # TODO add file extension or regexp to shortcut handles?
+  class IncludeProcessor < Processor
+    def process document, reader, target, attributes
+      raise ::NotImplementedError
+    end
+
+    def handles? target
+      true
+    end
+  end
+  IncludeProcessor::DSL = ProcessorDsl
+
+  # Public: BlockProcessors are used to handle delimited blocks and paragraphs
+  # that have a custom name.
+  #
+  # When Asciidoctor encounters a delimited block or paragraph with an
+  # unrecognized name while parsing the document, it looks for a BlockProcessor
+  # registered to handle this name and, if found, invokes its {Processor#process}
+  # method to build a cooresponding node in the document tree.
+  #
+  # AsciiDoc example:
+  #
+  #   [shout]
+  #   Get a move on.
+  #
+  # Recognized options:
+  #
+  # * :named - The name of the block (required: true)
+  # * :contexts - The blocks contexts on which this style can be used (default: [:paragraph, :open]
+  # * :content_model - The structure of the content supported in this block (default: :compound)
+  # * :positional_attributes - A list of attribute names used to map positional attributes (default: nil)
+  # * ...
+  #
+  # BlockProcessor implementations must extend BlockProcessor.
+  class BlockProcessor < Processor
+    attr_accessor :name
+
+    def initialize name = nil, config = {}
+      super config
+      @name = name || @config[:name]
+      # assign fallbacks
+      case @config[:contexts]
+      when ::NilClass
+        @config[:contexts] ||= [:open, :paragraph].to_set
+      when ::Symbol
+        @config[:contexts] = [@config[:contexts]].to_set
       else
-        @treeprocessors.push processor
+        @config[:contexts] = @config[:contexts].to_set
       end
+      # QUESTION should the default content model be raw??
+      @config[:content_model] ||= :compound
     end
 
-    def treeprocessors?
-      !@treeprocessors.empty?
+    def process parent, reader, attributes
+      raise ::NotImplementedError
     end
+  end
+
+  module BlockProcessorDsl
+    include ProcessorDsl
 
-    def load_treeprocessors *args
-      @treeprocessors.map do |processor|
-        processor.new(*args)
+    # FIXME this isn't the prettiest thing
+    def named value
+      if self.is_a? Processor
+        @name = value
+      else
+        option :name, value
       end
     end
+    alias :match_name :named
+    alias :bind_to :named
 
-    def postprocessor processor, position = :<<
-      processor = resolve_processor_class processor
-      if position == :<< || @postprocessors.empty?
-        @postprocessors.push processor
-      elsif position == :>>
-        @postprocessors.unshift processor
+    def contexts *value
+      option :contexts, value.flatten
+    end
+    alias :on_contexts :contexts
+    alias :on_context :contexts
+
+    def content_model value
+      option :content_model, value
+    end
+    alias :parse_content_as :content_model
+
+    def positional_attributes *value
+      option :pos_attrs, value.flatten
+    end
+    alias :pos_attrs :positional_attributes
+    alias :name_attributes :positional_attributes
+    alias :name_positional_attributes :positional_attributes
+
+    def default_attrs value
+      option :default_attrs, value
+    end
+    alias :seed_attributes_with :default_attrs
+  end
+  BlockProcessor::DSL = BlockProcessorDsl
+
+  class MacroProcessor < Processor
+    attr_accessor :name
+
+    def initialize name = nil, config = {}
+      super config
+      @name = name || @config[:name]
+      @config[:content_model] ||= :attributes
+    end
+
+    def process parent, target, attributes
+      raise ::NotImplementedError
+    end
+  end
+
+  module MacroProcessorDsl
+    include ProcessorDsl
+    # QUESTION perhaps include a SyntaxDsl?
+
+    def named value
+      if self.is_a? Processor
+        @name = value
       else
-        @postprocessors.push processor
+        option :name, value
       end
     end
+    alias :match_name :named
+    alias :bind_to :named
 
-    def postprocessors?
-      !@postprocessors.empty?
+    def content_model value
+      option :content_model, value
     end
+    alias :parse_content_as :content_model
 
-    def load_postprocessors *args
-      @postprocessors.map do |processor|
-        processor.new(*args)
-      end
+    def positional_attributes *value
+      option :pos_attrs, value.flatten
+    end
+    alias :pos_attrs :positional_attributes
+    alias :name_attributes :positional_attributes
+    alias :name_positional_attributes :positional_attributes
+
+    def default_attrs value
+      option :default_attrs, value
     end
+    alias :seed_attributes_with :default_attrs
+  end
+
+  # Public: BlockMacroProcessors are used to handle block macros that have a
+  # custom name.
+  #
+  # BlockMacroProcessor implementations must extend BlockMacroProcessor.
+  class BlockMacroProcessor < MacroProcessor
+  end
+  BlockMacroProcessor::DSL = MacroProcessorDsl
 
-    def include_processor processor, position = :<<
-      processor = resolve_processor_class processor
-      if position == :<< || @include_processors.empty?
-        @include_processors.push processor
-      elsif position == :>>
-        @include_processors.unshift processor
+  # Public: InlineMacroProcessors are used to handle block macros that have a
+  # custom name.
+  #
+  # InlineMacroProcessor implementations must extend InlineMacroProcessor.
+  #--
+  # TODO break this out into different pattern types
+  # for example, FormalInlineMacro, ShortInlineMacro (no target) and other patterns
+  # FIXME for inline passthrough, we need to have some way to specify the text as a passthrough
+  class InlineMacroProcessor < MacroProcessor
+    def initialize name, config = {}
+      super
+      @config[:regexp] ||= (resolve_regexp @name, @config[:format])
+    end
+
+    def resolve_regexp name, format
+      # TODO memoize these regular expressions!
+      if format == :short
+        %r(\\?#{name}:\[((?:\\\]|[^\]])*?)\])
       else
-        @include_processors.push processor
+        %r(\\?#{name}:(\S+?)\[((?:\\\]|[^\]])*?)\])
       end
     end
+  end
 
-    def include_processors?
-      !@include_processors.empty?
+  module InlineMacroProcessorDsl
+    include MacroProcessorDsl
+
+    def using_format value
+      option :format, value
     end
 
-    def load_include_processors *args
-      @include_processors.map do |processor|
-        processor.new(*args)
-      end
-      # QUESTION do we need/want the cache?
-      #@include_processors.map do |processor|
-      #  @include_processor_cache[processor] ||= processor.new(*args)
-      #end
+    def match value
+      option :regexp, value
     end
+  end
+  InlineMacroProcessor::DSL = InlineMacroProcessorDsl
 
-    # TODO allow contexts to be specified here, perhaps as [:upper, [:paragraph, :sidebar]]
-    def block name, processor, delimiter = nil, &block
-      processor = resolve_processor_class processor
-      @blocks[name] = processor
-      if block_given?
-        @block_delimiters[block] = name
-      elsif delimiter && delimiter.is_a?(Regexp)
-        @block_delimiters[delimiter] = name
+  # Public: Extension is a proxy object for an extension implementation such as
+  # a processor. It allows the preparation of the extension instance to be
+  # separated from its usage to provide consistency between different
+  # interfaces and avoid tight coupling with the extension type.
+  #
+  # The proxy encapsulates the extension kind (e.g., :block), its config Hash
+  # and the extension instance. This Proxy is what gets stored in the extension
+  # registry when activated.
+  #--
+  # QUESTION call this ExtensionInfo?
+  class Extension
+    attr :kind
+    attr :config
+    attr :instance
+
+    def initialize kind, instance, config
+      @kind = kind
+      @instance = instance
+      @config = config
+    end
+  end
+
+  # Public: A specialization of the Extension proxy that additionally stores a
+  # reference to the {Processor#process} method. By storing this reference, its
+  # possible to accomodate both concrete extension implementations and Procs.
+  class ProcessorExtension < Extension
+    attr :process_method
+
+    def initialize kind, instance, process_method = nil
+      super kind, instance, instance.config
+      @process_method = process_method || instance.method(:process)
+    end
+  end
+
+  # Public: A Group is used to register one or more extensions with the Registry.
+  #
+  # The Group should be subclassed and registered with the Registry either by
+  # invoking the {Group.register} method or passing the subclass to the
+  # {Extensions.register} method. Extensions are registered with the Registry
+  # inside the {Group#activate} method.
+  class Group
+    class << self
+      def register name = nil
+        Extensions.register name, self
       end
     end
 
-    def blocks?
-      !@blocks.empty?
+    def activate registry
+      raise ::NotImplementedError
     end
+  end
+
+  # Public: The primary entry point into the extension system.
+  #
+  # Registry holds the extensions which have been registered and activated, has
+  # methods for registering or defining a processor and looks up extensions
+  # stored in the registry during parsing.
+  class Registry
+    # Public: Returns the {Asciidoctor::Document} on which the extensions in this registry are being used.
+    attr_reader :document
+
+    # Public: Returns the Array of {Group} classes, instances and/or Procs that have been registered.
+    attr_reader :groups
 
-    def block_delimiters?
-      !@block_delimiters.empty?
+    def initialize groups = {}
+      @groups = groups
+      @preprocessor_extensions = @treeprocessor_extensions = @postprocessor_extensions = @include_processor_extensions = nil
+      @block_extensions = @block_macro_extensions = @inline_macro_extensions = nil
+      @document = nil
     end
 
-    # NOTE block delimiters not yet implemented
-    def at_block_delimiter? line
-      @block_delimiters.each do |delimiter, name|
-        if delimiter.is_a? Proc
-          if delimiter.call(line)
-            return name
+    # Public: Activates all the global extension {Group}s and the extension {Group}s
+    # associated with this registry.
+    #
+    # document - the {Asciidoctor::Document} on which the extensions are to be used.
+    #
+    # Returns the instance of this [Registry].
+    def activate document
+      @document = document
+      (Extensions.groups.values + @groups.values).each do |group|
+        case group
+        when ::Proc
+          case group.arity
+          when 0, -1
+            instance_exec(&group)
+          when 1
+            group.call self
           end
+        when ::Class
+          group.new.activate self
         else
-          if line.match(delimiter)
-            return name
-          end
+          group.activate self
         end
       end
-      false
+      self
     end
 
-    def load_block_processor name, *args
-      @block_processor_cache[name] ||= @blocks[name].new(name.to_sym, *args)
+    # Public: Registers a {Preprocessor} with the extension registry to process
+    # the AsciiDoc source before parsing begins.
+    #
+    # The Preprocessor may be one of four types:
+    #
+    # * A Preprocessor subclass
+    # * An instance of a Preprocessor subclass
+    # * The String name of a Preprocessor subclass
+    # * A method block (i.e., Proc) that conforms to the Preprocessor contract
+    #
+    # Unless the Preprocessor is passed as the method block, it must be the
+    # first argument to this method.
+    #
+    # Examples
+    #
+    #   # as a Preprocessor subclass
+    #   preprocessor FrontMatterPreprocessor
+    #
+    #   # as an instance of a Preprocessor subclass
+    #   preprocessor FrontMatterPreprocessor.new
+    #
+    #   # as a name of a Preprocessor subclass
+    #   preprocessor 'FrontMatterPreprocessor'
+    #
+    #   # as a method block
+    #   preprocessor do
+    #     process |reader, lines|
+    #       ...
+    #     end
+    #   end
+    #
+    # Returns the [Extension] stored in the registry that proxies the
+    # instance of this Preprocessor.
+    def preprocessor *args, &block
+      add_document_processor :preprocessor, args, &block
     end
 
-    def processor_registered_for_block? name, context
-      if @blocks.has_key? name.to_sym
-        (@blocks[name.to_sym].config.fetch(:contexts, nil) || []).include?(context)
-      else
-        false
-      end
+    # Public: Checks whether any {Preprocessor} extensions have been registered.
+    #
+    # Returns a [Boolean] indicating whether any Preprocessor extensions are registered.
+    def preprocessors?
+      !!@preprocessor_extensions
     end
 
-    def block_macro name, processor
-      processor = resolve_processor_class processor
-      @block_macros[name.to_s] = processor
+    # Public: Retrieves the {Extension} proxy objects for all
+    # Preprocessor instances in this registry.
+    #
+    # Returns an [Array] of Extension proxy objects.
+    def preprocessors
+      @preprocessor_extensions
     end
 
-    def block_macros?
-      !@block_macros.empty?
+    # Public: Registers a {Treeprocessor} with the extension registry to process
+    # the AsciiDoc source after parsing is complete.
+    #
+    # The Treeprocessor may be one of four types:
+    #
+    # * A Treeprocessor subclass
+    # * An instance of a Treeprocessor subclass
+    # * The String name of a Treeprocessor subclass
+    # * A method block (i.e., Proc) that conforms to the Treeprocessor contract
+    #
+    # Unless the Treeprocessor is passed as the method block, it must be the
+    # first argument to this method.
+    #
+    # Examples
+    #
+    #   # as a Treeprocessor subclass
+    #   treeprocessor ShellTreeprocessor
+    #
+    #   # as an instance of a Treeprocessor subclass
+    #   treeprocessor ShellTreeprocessor.new
+    #
+    #   # as a name of a Treeprocessor subclass
+    #   treeprocessor 'ShellTreeprocessor'
+    #
+    #   # as a method block
+    #   treeprocessor do
+    #     process |document|
+    #       ...
+    #     end
+    #   end
+    #
+    # Returns the [Extension] stored in the registry that proxies the
+    # instance of this Treeprocessor.
+    def treeprocessor *args, &block
+      add_document_processor :treeprocessor, args, &block
     end
 
-    def load_block_macro_processor name, *args
-      @block_macro_processor_cache[name] ||= @block_macros[name].new(name, *args)
+    # Public: Checks whether any {Treeprocessor} extensions have been registered.
+    #
+    # Returns a [Boolean] indicating whether any Treeprocessor extensions are registered.
+    def treeprocessors?
+      !!@treeprocessor_extensions
     end
 
-    def processor_registered_for_block_macro? name
-      @block_macros.has_key? name
+    # Public: Retrieves the {Extension} proxy objects for all
+    # Treeprocessor instances in this registry.
+    #
+    # Returns an [Array] of Extension proxy objects.
+    def treeprocessors
+      @treeprocessor_extensions
     end
 
-    # TODO probably need ordering control before/after other inline macros
-    def inline_macro name, processor
-      processor = resolve_processor_class processor
-      @inline_macros[name.to_s] = processor
+    # Public: Registers a {Postprocessor} with the extension registry to process
+    # the output after conversion is complete.
+    #
+    # The Postprocessor may be one of four types:
+    #
+    # * A Postprocessor subclass
+    # * An instance of a Postprocessor subclass
+    # * The String name of a Postprocessor subclass
+    # * A method block (i.e., Proc) that conforms to the Postprocessor contract
+    #
+    # Unless the Postprocessor is passed as the method block, it must be the
+    # first argument to this method.
+    #
+    # Examples
+    #
+    #   # as a Postprocessor subclass
+    #   postprocessor AnalyticsPostprocessor
+    #
+    #   # as an instance of a Postprocessor subclass
+    #   postprocessor AnalyticsPostprocessor.new
+    #
+    #   # as a name of a Postprocessor subclass
+    #   postprocessor 'AnalyticsPostprocessor'
+    #
+    #   # as a method block
+    #   postprocessor do
+    #     process |document, output|
+    #       ...
+    #     end
+    #   end
+    #
+    # Returns the [Extension] stored in the registry that proxies the
+    # instance of this Postprocessor.
+    def postprocessor *args, &block
+      add_document_processor :postprocessor, args, &block
     end
 
-    def inline_macros?
-      !@inline_macros.empty?
+    # Public: Checks whether any {Postprocessor} extensions have been registered.
+    #
+    # Returns a [Boolean] indicating whether any Postprocessor extensions are registered.
+    def postprocessors?
+      !!@postprocessor_extensions
     end
 
-    def load_inline_macro_processor name, *args
-      @inline_macro_processor_cache[name] ||= @inline_macros[name].new(name, *args)
+    # Public: Retrieves the {Extension} proxy objects for all
+    # Postprocessor instances in this registry.
+    #
+    # Returns an [Array] of Extension proxy objects.
+    def postprocessors
+      @postprocessor_extensions
     end
 
-    def load_inline_macro_processors *args
-      @inline_macros.map do |name, processor|
-        load_inline_macro_processor name, *args
-      end
+    # Public: Registers an {IncludeProcessor} with the extension registry to have
+    # a shot at handling the include directive.
+    #
+    # The IncludeProcessor may be one of four types:
+    #
+    # * A IncludeProcessor subclass
+    # * An instance of a IncludeProcessor subclass
+    # * The String name of a IncludeProcessor subclass
+    # * A method block (i.e., Proc) that conforms to the IncludeProcessor contract
+    #
+    # Unless the IncludeProcessor is passed as the method block, it must be the
+    # first argument to this method.
+    #
+    # Examples
+    #
+    #   # as an IncludeProcessor subclass
+    #   include_processor GitIncludeProcessor
+    #
+    #   # as an instance of a Postprocessor subclass
+    #   include_processor GitIncludeProcessor.new
+    #
+    #   # as a name of a Postprocessor subclass
+    #   include_processor 'GitIncludeProcessor'
+    #
+    #   # as a method block
+    #   include_processor do
+    #     process |document, output|
+    #       ...
+    #     end
+    #   end
+    #
+    # Returns the [Extension] stored in the registry that proxies the
+    # instance of this IncludeProcessor.
+    def include_processor *args, &block
+      add_document_processor :include_processor, args, &block
     end
 
-    def processor_registered_for_inline_macro? name
-      @inline_macros.has_key? name
+    # Public: Checks whether any {IncludeProcessor} extensions have been registered.
+    #
+    # Returns a [Boolean] indicating whether any IncludeProcessor extensions are registered.
+    def include_processors?
+      !!@include_processor_extensions
     end
 
-    def register document, &block
-      instance_exec document, &block
+    # Public: Retrieves the {Extension} proxy objects for all the
+    # IncludeProcessor instances stored in this registry.
+    #
+    # Returns an [Array] of Extension proxy objects.
+    def include_processors
+      @include_processor_extensions
     end
 
-    def resolve_processor_class object
-      ::Asciidoctor::Extensions.resolve_class object
+    # Public: Registers a {BlockProcessor} with the extension registry to
+    # process the block content (i.e., delimited block or paragraph) in the
+    # AsciiDoc source annotated with the specified block name (i.e., style).
+    #
+    # The BlockProcessor may be one of four types:
+    #
+    # * A BlockProcessor subclass
+    # * An instance of a BlockProcessor subclass
+    # * The String name of a BlockProcessor subclass
+    # * A method block (i.e., Proc) that conforms to the BlockProcessor contract
+    #
+    # Unless the BlockProcessor is passed as the method block, it must be the
+    # first argument to this method. The second argument is the name (coersed
+    # to a Symbol) of the AsciiDoc block content (i.e., delimited block or
+    # paragraph) that this processor is registered to handle. If a block name
+    # is not passed as an argument, it gets read from the name property of the
+    # BlockProcessor instance. If a name still cannot be determined, an error
+    # is raised.
+    # 
+    # Examples
+    #
+    #   # as a BlockProcessor subclass
+    #   block ShoutBlock
+    #
+    #   # as a BlockProcessor subclass with an explicit block name
+    #   block ShoutBlock, :shout
+    #
+    #   # as an instance of a BlockProcessor subclass
+    #   block ShoutBlock.new
+    #
+    #   # as an instance of a BlockProcessor subclass with an explicit block name
+    #   block ShoutBlock.new, :shout
+    #
+    #   # as a name of a BlockProcessor subclass
+    #   block 'ShoutBlock'
+    #
+    #   # as a name of a BlockProcessor subclass with an explicit block name
+    #   block 'ShoutBlock', :shout
+    #
+    #   # as a method block
+    #   block do
+    #     named :shout 
+    #     process |parent, reader, attrs|
+    #       ...
+    #     end
+    #   end
+    #
+    #   # as a method block with an explicit block name
+    #   register :shout do
+    #     process |parent, reader, attrs|
+    #       ...
+    #     end
+    #   end
+    #
+    # Returns an instance of the [Extension] proxy object that is stored in the
+    # registry and manages the instance of this BlockProcessor.
+    def block *args, &block
+      add_syntax_processor :block, args, &block
     end
 
-    def reset
-      @block_processor_cache = {}
-      @block_macro_processor_cache = {}
-      @inline_macro_processor_cache = {}
+    # Public: Checks whether any {BlockProcessor} extensions have been registered.
+    #
+    # Returns a [Boolean] indicating whether any BlockProcessor extensions are registered.
+    def blocks?
+      !!@block_extensions
     end
-  end
 
-  class Processor
-    def initialize(document)
-      @document = document
+    # Public: Checks whether any {BlockProcessor} extensions are registered to
+    # handle the specified block name appearing on the specified context.
+    #
+    # Returns the [Extension] proxy object for the BlockProcessor that matches
+    # the block name and context or false if no match is found.
+    def registered_for_block? name, context
+      if (ext = @block_extensions[name.to_sym])
+        (ext.config[:contexts].include? context) ? ext : false
+      else
+        false
+      end
     end
-  end
 
-  # Public: Preprocessors are run after the source text is split into lines and
-  # before parsing begins.
-  #
-  # Prior to invoking the preprocessor, Asciidoctor splits the source text into
-  # lines and normalizes them. The normalize process strips trailing whitespace
-  # from each line and leaves behind a line-feed character (i.e., "\n").
-  #
-  # Asciidoctor passes a reference to the Reader and a copy of the lines Array
-  # to the process method of an instance of each registered Preprocessor. The
-  # Preprocessor modifies the Array as necessary and either returns a reference
-  # to the same Reader or a reference to a new one.
-  #
-  # Preprocessors must extend Asciidoctor::Extensions::Preprocessor.
-  class Preprocessor < Processor
-    # Public: Accepts the Reader and an Array of lines, modifies them as
-    # needed, then returns the Reader or a reference to a new one.
+    # Public: Retrieves the {Extension} proxy object for the BlockProcessor registered
+    # to handle block content with the name.
     #
-    # Each subclass of Preprocessor should override this method.
-    def process reader, lines
-      reader
+    # name - the String or Symbol (coersed to a Symbol) macro name
+    #
+    # Returns the [Extension] object stored in the registry that proxies the
+    # corresponding BlockProcessor or nil if a match is not found.
+    def find_block_extension name
+      @block_extensions[name.to_sym]
     end
-  end
 
-  # Public: Treeprocessors are run on the Document after the source has been
-  # parsed into an abstract syntax tree, as represented by the Document object
-  # and its child Node objects.
-  #
-  # Asciidoctor invokes the process method on an instance of each registered
-  # Treeprocessor.
-  #
-  # QUESTION should the treeprocessor get invoked after parse header too?
-  #
-  # Treeprocessors must extend Asciidoctor::Extensions::Treeprocessor.
-  class Treeprocessor < Processor
-    def process
+    # Public: Registers a {BlockMacroProcessor} with the extension registry to
+    # process a block macro with the specified name.
+    #
+    # The BlockMacroProcessor may be one of four types:
+    #
+    # * A BlockMacroProcessor subclass
+    # * An instance of a BlockMacroProcessor subclass
+    # * The String name of a BlockMacroProcessor subclass
+    # * A method block (i.e., Proc) that conforms to the BlockMacroProcessor contract
+    #
+    # Unless the BlockMacroProcessor is passed as the method block, it must be
+    # the first argument to this method. The second argument is the name
+    # (coersed to a Symbol) of the AsciiDoc block macro that this processor is
+    # registered to handle. If a block macro name is not passed as an argument,
+    # it gets read from the name property of the BlockMacroProcessor instance.
+    # If a name still cannot be determined, an error is raised.
+    # 
+    # Examples
+    #
+    #   # as a BlockMacroProcessor subclass
+    #   block GistBlockMacro
+    #
+    #   # as a BlockMacroProcessor subclass with an explicit macro name
+    #   block GistBlockMacro, :gist
+    #
+    #   # as an instance of a BlockMacroProcessor subclass
+    #   block GistBlockMacro.new
+    #
+    #   # as an instance of a BlockMacroProcessor subclass with an explicit macro name
+    #   block GistBlockMacro.new, :gist
+    #
+    #   # as a name of a BlockMacroProcessor subclass
+    #   block 'GistBlockMacro'
+    #
+    #   # as a name of a BlockMacroProcessor subclass with an explicit macro name
+    #   block 'GistBlockMacro', :gist
+    #
+    #   # as a method block
+    #   block_macro do
+    #     named :gist
+    #     process |parent, target, attrs|
+    #       ...
+    #     end
+    #   end
+    #
+    #   # as a method block with an explicit macro name
+    #   register :gist do
+    #     process |parent, target, attrs|
+    #       ...
+    #     end
+    #   end
+    #
+    # Returns an instance of the [Extension] proxy object that is stored in the
+    # registry and manages the instance of this BlockMacroProcessor.
+    def block_macro *args, &block
+      add_syntax_processor :block_macro, args, &block
     end
-  end
 
-  # Public: Postprocessors are run after the document is rendered and before
-  # it's written to the output stream.
-  #
-  # Asciidoctor passes a reference to the output String to the process method
-  # of each registered Postprocessor. The Preprocessor modifies the String as
-  # necessary and returns the String replacement.
-  #
-  # The markup format in the String is determined from the backend used to
-  # render the Document. The backend and be looked up using the backend method
-  # on the Document object, as well as various backend-related document
-  # attributes.
-  #
-  # Postprocessors can also be used to relocate assets needed by the published
-  # document.
-  #
-  # Postprocessors must extend Asciidoctor::Extensions::Postprocessor.
-  class Postprocessor < Processor
-    def process output
-      output
+    # Public: Checks whether any {BlockMacroProcessor} extensions have been registered.
+    #
+    # Returns a [Boolean] indicating whether any BlockMacroProcessor extensions are registered.
+    def block_macros?
+      !!@block_macro_extensions
     end
-  end
 
-  # Public: IncludeProcessors are used to process include::[] macros in the
-  # source document.
-  #
-  # When Asciidoctor discovers an include::[] macro in the source document, it
-  # iterates through the IncludeProcessors and delegates the work of reading
-  # the content to the first processor that identifies itself as capable of
-  # handling that target.
-  #
-  # IncludeProcessors must extend Asciidoctor::Extensions::IncludeProcessor.
-  class IncludeProcessor < Processor
-    def process target, attributes
-      output
+    # Public: Checks whether any {BlockMacroProcessor} extensions are registered to
+    # handle the block macro with the specified name.
+    #
+    # name - the String or Symbol (coersed to a Symbol) macro name
+    #
+    # Returns the [Extension] proxy object for the BlockMacroProcessor that matches
+    # the macro name or false if no match is found.
+    #--
+    # TODO only allow blank target if format is :short
+    def registered_for_block_macro? name
+      (ext = @block_macro_extensions[name.to_sym]) ? ext : false
     end
-  end
 
-  # Supported options:
-  # * :contexts - The blocks contexts (types) on which this style can be used (default: [:paragraph, :open]
-  # * :content_model - The structure of the content supported in this block (default: :compound)
-  # * :pos_attrs - A list of attribute names used to map positional attributes (default: nil)
-  # * :default_attrs - Set default values for attributes (default: nil)
-  # * ...
-  class BlockProcessor < Processor
-    class << self
-      def config
-        @config ||= {:contexts => [:paragraph, :open]}
-      end
+    # Public: Retrieves the {Extension} proxy object for the BlockMacroProcessor registered
+    # to handle a block macro with the specified name.
+    #
+    # name - the String or Symbol (coersed to a Symbol) macro name
+    #
+    # Returns the [Extension] object stored in the registry that proxies the
+    # cooresponding BlockMacroProcessor or nil if a match is not found.
+    def find_block_macro_extension name
+      @block_macro_extensions[name.to_sym]
+    end
 
-      def option(key, default_value)
-        config[key] = default_value
-      end
+    # Public: Registers a {InlineMacroProcessor} with the extension registry to
+    # process an inline macro with the specified name.
+    #
+    # The InlineMacroProcessor may be one of four types:
+    #
+    # * An InlineMacroProcessor subclass
+    # * An instance of an InlineMacroProcessor subclass
+    # * The String name of an InlineMacroProcessor subclass
+    # * A method block (i.e., Proc) that conforms to the InlineMacroProcessor contract
+    #
+    # Unless the InlineMacroProcessor is passed as the method block, it must be
+    # the first argument to this method. The second argument is the name
+    # (coersed to a Symbol) of the AsciiDoc block macro that this processor is
+    # registered to handle. If a block macro name is not passed as an argument,
+    # it gets read from the name property of the InlineMacroProcessor instance.
+    # If a name still cannot be determined, an error is raised.
+    # 
+    # Examples
+    #
+    #   # as an InlineMacroProcessor subclass
+    #   block ChromeInlineMacro
+    #
+    #   # as an InlineMacroProcessor subclass with an explicit macro name
+    #   block ChromeInineMacro, :chrome
+    #
+    #   # as an instance of an InlineMacroProcessor subclass
+    #   block ChromeInlineMacro.new
+    #
+    #   # as an instance of an InlineMacroProcessor subclass with an explicit macro name
+    #   block ChromeInlineMacro.new, :chrome
+    #
+    #   # as a name of an InlineMacroProcessor subclass
+    #   block 'ChromeInlineMacro'
+    #
+    #   # as a name of an InlineMacroProcessor subclass with an explicit macro name
+    #   block 'ChromeInineMacro', :chrome
+    #
+    #   # as a method block
+    #   inline_macro do
+    #     named :chrome
+    #     process |parent, target, attrs|
+    #       ...
+    #     end
+    #   end
+    #
+    #   # as a method block with an explicit macro name
+    #   register :chrome do
+    #     process |parent, target, attrs|
+    #       ...
+    #     end
+    #   end
+    #
+    # Returns an instance of the [Extension] proxy object that is stored in the
+    # registry and manages the instance of this InlineMacroProcessor.
+    def inline_macro *args, &block
+      add_syntax_processor :inline_macro, args, &block
     end
 
-    attr_reader :document
-    attr_reader :context
-    attr_reader :options
+    # Public: Checks whether any {InlineMacroProcessor} extensions have been registered.
+    #
+    # Returns a [Boolean] indicating whether any IncludeMacroProcessor extensions are registered.
+    def inline_macros?
+      !!@inline_macro_extensions
+    end
 
-    def initialize(context, document, opts = {})
-      super(document)
-      @context = context
-      @options = self.class.config.dup
-      opts.delete(:contexts) # contexts can't be overridden
-      @options.update(opts)
-      #@options[:contexts] ||= [:paragraph, :open]
-      @options[:content_model] ||= :compound
+    # Public: Checks whether any {InlineMacroProcessor} extensions are registered to
+    # handle the inline macro with the specified name.
+    #
+    # name - the String or Symbol (coersed to a Symbol) macro name
+    #
+    # Returns the [Extension] proxy object for the InlineMacroProcessor that matches
+    # the macro name or false if no match is found.
+    def registered_for_inline_macro? name
+      (ext = @inline_macro_extensions[name.to_sym]) ? ext : false
     end
 
-    def process parent, reader, attributes
-      nil
+    # Public: Retrieves the {Extension} proxy object for the InlineMacroProcessor registered
+    # to handle an inline macro with the specified name.
+    #
+    # name - the String or Symbol (coersed to a Symbol) macro name
+    #
+    # Returns the [Extension] object stored in the registry that proxies the
+    # cooresponding InlineMacroProcessor or nil if a match is not found.
+    def find_inline_macro_extension name
+      @inline_macro_extensions[name.to_sym]
     end
-  end
 
-  class MacroProcessor < Processor
-    class << self
-      def config
-        @config ||= {}
+    # Public: Retrieves the {Extension} proxy objects for all
+    # InlineMacroProcessor instances in this registry.
+    #
+    # Returns an [Array] of Extension proxy objects.
+    def inline_macros
+      @inline_macro_extensions.values
+    end
+
+    private
+
+    def add_document_processor kind, args, &block
+      kind_name = kind.to_s.tr '_', ' '
+      kind_class_symbol = kind_name.split(' ').map {|word| %(#{word.chr.upcase}#{word[1..-1]}) }.join.to_sym
+      kind_class = Extensions.const_get kind_class_symbol
+      kind_java_class = (defined? ::AsciidoctorJ) ? (::AsciidoctorJ::Extensions.const_get kind_class_symbol) : nil
+      kind_store = instance_variable_get(%(@#{kind}_extensions).to_sym) || instance_variable_set(%(@#{kind}_extensions).to_sym, [])
+      # style 1: specified as block
+      extension = if block_given?
+        config = resolve_args args, 1
+        # TODO if block arity is 0, assume block is process method
+        processor = kind_class.new config
+        class << processor
+          include_dsl
+        end
+        processor.instance_exec(&block)
+        processor.freeze
+        unless processor.process_block_given?
+          raise ::ArgumentError.new %(No block specified to process #{kind_name} extension at #{block.source_location})
+        end
+        ProcessorExtension.new kind, processor
+      else
+        processor, config = resolve_args args, 2
+        # style 2: specified as class or class name
+        if (processor.is_a? ::Class) || ((processor.is_a? ::String) && (processor = Extensions.class_for_name processor))
+          unless processor < kind_class || (kind_java_class && processor < kind_java_class)
+            raise ::ArgumentError.new %(Invalid type for #{kind_name} extension: #{processor})
+          end
+          processor_instance = processor.new config
+          processor_instance.freeze
+          ProcessorExtension.new kind, processor_instance
+        # style 3: specified as instance
+        elsif (processor.is_a? kind_class) || (kind_java_class && (processor.is_a? kind_java_class))
+          processor.update_config config
+          processor.freeze
+          ProcessorExtension.new kind, processor
+        else
+          raise ::ArgumentError.new %(Invalid arguments specified for registering #{kind_name} extension: #{args})
+        end
       end
 
-      def option(key, default_value)
-        config[key] = default_value
+      if extension.config[:position] == :>>
+        kind_store.unshift extension
+      else
+        kind_store << extension
       end
     end
 
-    attr_reader :document
-    attr_reader :name
-    attr_reader :options
+    def add_syntax_processor kind, args, &block
+      kind_name = kind.to_s.tr '_', ' '
+      kind_class_basename = kind_name.split(' ').map {|word| %(#{word.chr.upcase}#{word[1..-1]}) }.join
+      kind_class_symbol = %(#{kind_class_basename}Processor).to_sym
+      kind_class = Extensions.const_get kind_class_symbol
+      kind_java_class = (defined? ::AsciidoctorJ) ? (::AsciidoctorJ::Extensions.const_get kind_class_symbol) : nil
+      kind_store = instance_variable_get(%(@#{kind}_extensions).to_sym) || instance_variable_set(%(@#{kind}_extensions).to_sym, {})
+      # style 1: specified as block
+      if block_given?
+        name, config = resolve_args args, 2
+        processor = kind_class.new as_symbol(name), config
+        class << processor
+          include_dsl
+        end
+        if block.arity == 1
+          yield processor
+        else
+          processor.instance_exec(&block)
+        end
+        unless (name = as_symbol processor.name)
+          raise ::ArgumentError.new %(No name specified for #{kind_name} extension at #{block.source_location})
+        end
+        unless processor.process_block_given?
+          raise ::NoMethodError.new %(No block specified to process #{kind_name} extension at #{block.source_location})
+        end
+        processor.freeze
+        kind_store[name] = ProcessorExtension.new kind, processor
+      else
+        processor, name, config = resolve_args args, 3
+        # style 2: specified as class or class name
+        if (processor.is_a? ::Class) || ((processor.is_a? ::String) && (processor = Extensions.class_for_name processor))
+          unless processor < kind_class || (kind_java_class && processor < kind_java_class)
+            raise ::ArgumentError.new %(Class specified for #{kind_name} extension does not inherit from #{kind_class}: #{processor})
+          end
+          processor_instance = processor.new as_symbol(name), config
+          unless (name = as_symbol processor_instance.name)
+            raise ::ArgumentError.new %(No name specified for #{kind_name} extension: #{processor})
+          end
+          processor.freeze
+          kind_store[name] = ProcessorExtension.new kind, processor_instance
+        # style 3: specified as instance
+        elsif (processor.is_a? kind_class) || (kind_java_class && (processor.is_a? kind_java_class))
+          processor.update_config config
+          # TODO need a test for this override!
+          unless (name = name ? (processor.name = as_symbol name) : (as_symbol processor.name))
+            raise ::ArgumentError.new %(No name specified for #{kind_name} extension: #{processor})
+          end
+          processor.freeze
+          kind_store[name] = ProcessorExtension.new kind, processor
+        else
+          raise ::ArgumentError.new %(Invalid arguments specified for registering #{kind_name} extension: #{args})
+        end
+      end
+    end
 
-    def initialize(name, document, opts = {})
-      super(document)
-      @name = name
-      @options = self.class.config.dup
-      @options.update(opts)
+    def resolve_args args, expect
+      opts = (args[-1].is_a? ::Hash) ? args.pop : {}
+      return opts if expect == 1
+      num_args = args.size
+      if (missing = expect - 1 - num_args) > 0
+        args.fill nil, num_args, missing
+      elsif missing < 0
+        args.pop(-missing)
+      end
+      args << opts
+      args
     end
 
-    def process parent, target, attributes, source = nil
-      nil
+    def as_symbol name
+      name ? ((name.is_a? ::Symbol) ? name : name.to_sym) : nil
     end
   end
 
-  class BlockMacroProcessor < MacroProcessor
-  end
+  class << self
+    def generate_name
+      %(extgrp#{next_auto_id})
+    end
 
-  # TODO break this out into different pattern types
-  # for example, FormalInlineMacro, ShortInlineMacro (no target) and other patterns
-  class InlineMacroProcessor < MacroProcessor
-    def initialize(name, document, opts = {})
-      super
-      @regexp = nil
+    def next_auto_id
+      @auto_id ||= -1
+      @auto_id += 1
+    end
+
+    def groups
+      @groups ||= {}
     end
 
-    def regexp
-      if @options[:short_form]
-        @regexp ||= %r(\\?#{@name}:\[((?:\\\]|[^\]])*?)\])
+    def build_registry name = nil, &block
+      if block_given?
+        name ||= generate_name
+        Registry.new({ name => block })
       else
-        @regexp ||= %r(\\?#{@name}:(\S+?)\[((?:\\\]|[^\]])*?)\])
+        Registry.new
       end
     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.
+    def register *args, &block
+      argc = args.length
+      resolved_group = if block_given?
+        block
+      elsif !(group = args.pop)
+        raise ::ArgumentError.new %(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 %(Wrong number of arguments (#{argc} for 1..2))
+      end
+      groups[name] = resolved_group
+    end
+
+    def unregister_all
+      @groups = {}
+    end
+
+    # unused atm, but tested
+    def resolve_class object
+      (object.is_a? ::Class) ? object : (class_for_name object.to_s)
+    end
+
+    # Public: Resolves the Class object for the qualified name.
+    #
+    # Returns Class
+    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 %(Could not resolve class for name: #{qualified_name})
+        end
+      end
+      resolved_class
+    end
   end
+
 end
 end