Class: Asciidoctor::Extensions::Registry

Inherits:
Object
  • Object
show all
Defined in:
lib/asciidoctor/extensions.rb

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(groups = {}) ⇒ Registry

Returns a new instance of Registry.



722
723
724
725
726
727
 
# File 'lib/asciidoctor/extensions.rb', line 722

def initialize groups = {}
  @groups = groups
  reset
  @preprocessor_extensions = @tree_processor_extensions = @postprocessor_extensions = @include_processor_extensions = @docinfo_processor_extensions = @block_extensions = @block_macro_extensions = @inline_macro_extensions = nil
  @document = nil
end

Instance Attribute Details

#document ⇒ Object (readonly)

Returns the Document on which the extensions in this registry are being used.



717
718
719
 
# File 'lib/asciidoctor/extensions.rb', line 717

def document
  @document
end

#groups ⇒ Object (readonly)

Returns the Hash of Group classes, instances, and/or Procs that have been registered with this registry.



720
721
722
 
# File 'lib/asciidoctor/extensions.rb', line 720

def groups
  @groups
end

Instance Method Details

#activate(document) ⇒ Registry

Activates all the global extension Groups and the extension Groups associated with this registry.

Parameters:

  • document —

    the Document on which the extensions are to be used.

Returns:

  • (Registry) —

    Returns the instance of this Registry.



735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
 
# File 'lib/asciidoctor/extensions.rb', line 735

def activate document
  reset if @document
  @document = document
  unless (ext_groups = Extensions.groups.values + @groups.values).empty?
    ext_groups.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
        group.activate self
      end
    end
  end
  self
end

#block(*args, &block) ⇒ Extension

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 do |parent, reader, attrs|
    ...
  end
end
# as a method block with an explicit block name
block :shout do
  process do |parent, reader, attrs|
    ...
  end
end

Returns:

  • (Extension) —

    Returns an instance of the Extension proxy object that is stored in the registry and manages the instance of this BlockProcessor.



1098
1099
1100
 
# File 'lib/asciidoctor/extensions.rb', line 1098

def block *args, &block
  add_syntax_processor :block, args, &block
end

#block_macro(*args, &block) ⇒ Extension

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_macro GistBlockMacro
# as a BlockMacroProcessor subclass with an explicit macro name
block_macro GistBlockMacro, :gist
# as an instance of a BlockMacroProcessor subclass
block_macro GistBlockMacro.new
# as an instance of a BlockMacroProcessor subclass with an explicit macro name
block_macro GistBlockMacro.new, :gist
# as a name of a BlockMacroProcessor subclass
block_macro 'GistBlockMacro'
# as a name of a BlockMacroProcessor subclass with an explicit macro name
block_macro 'GistBlockMacro', :gist
# as a method block
block_macro do
  named :gist
  process do |parent, target, attrs|
    ...
  end
end
# as a method block with an explicit macro name
block_macro :gist do
  process do |parent, target, attrs|
    ...
  end
end

Returns:

  • (Extension) —

    Returns an instance of the Extension proxy object that is stored in the registry and manages the instance of this BlockMacroProcessor.



1193
1194
1195
 
# File 'lib/asciidoctor/extensions.rb', line 1193

def block_macro *args, &block
  add_syntax_processor :block_macro, args, &block
end

#block_macros? ⇒ Boolean

Checks whether any BlockMacroProcessor extensions have been registered.

Returns:

  • (Boolean) —

    Returns a Boolean indicating whether any BlockMacroProcessor extensions are registered.



1200
1201
1202
 
# File 'lib/asciidoctor/extensions.rb', line 1200

def block_macros?
  !!@block_macro_extensions
end

#blocks? ⇒ Boolean

Checks whether any BlockProcessor extensions have been registered.

Returns:

  • (Boolean) —

    Returns a Boolean indicating whether any BlockProcessor extensions are registered.



1105
1106
1107
 
# File 'lib/asciidoctor/extensions.rb', line 1105

def blocks?
  !!@block_extensions
end

#docinfo_processor(*args, &block) ⇒ Extension

Registers an DocinfoProcessor with the extension registry to add additional docinfo to the document.

The DocinfoProcessor may be one of four types:

  • A DocinfoProcessor subclass

  • An instance of a DocinfoProcessor subclass

  • The String name of a DocinfoProcessor subclass

  • A method block (i.e., Proc) that conforms to the DocinfoProcessor contract

Unless the DocinfoProcessor is passed as the method block, it must be the first argument to this method.

Examples:

# as an DocinfoProcessor subclass
docinfo_processor MetaRobotsDocinfoProcessor
# as an instance of a DocinfoProcessor subclass with an explicit location
docinfo_processor JQueryDocinfoProcessor.new, location: :footer
# as a name of a DocinfoProcessor subclass
docinfo_processor 'MetaRobotsDocinfoProcessor'
# as a method block
docinfo_processor do
  process do |doc|
    at_location :footer
    'footer content'
  end
end

Returns:

  • (Extension) —

    Returns the Extension stored in the registry that proxies the instance of this DocinfoProcessor.



1005
1006
1007
 
# File 'lib/asciidoctor/extensions.rb', line 1005

def docinfo_processor *args, &block
  add_document_processor :docinfo_processor, args, &block
end

#docinfo_processors(location = nil) ⇒ Array

Retrieves the Extension proxy objects for all the DocinfoProcessor instances stored in this registry.

Parameters:

  • location (defaults to: nil) —

    A Symbol for selecting docinfo extensions at a given location (:head or :footer) (default: nil)

Returns:

  • (Array) —

    Returns an Array of Extension proxy objects.



1032
1033
1034
1035
1036
1037
1038
1039
1040
 
# File 'lib/asciidoctor/extensions.rb', line 1032

def docinfo_processors location = nil
  if @docinfo_processor_extensions
    if location
      @docinfo_processor_extensions.select {|ext| ext.config[:location] == location }
    else
      @docinfo_processor_extensions
    end
  end
end

#docinfo_processors?(location = nil) ⇒ Boolean

Checks whether any DocinfoProcessor extensions have been registered.

Parameters:

  • location (defaults to: nil) —

    A Symbol for selecting docinfo extensions at a given location (:head or :footer) (default: nil)

Returns:

  • (Boolean) —

    Returns a Boolean indicating whether any DocinfoProcessor extensions are registered.



1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
 
# File 'lib/asciidoctor/extensions.rb', line 1014

def docinfo_processors? location = nil
  if @docinfo_processor_extensions
    if location
      @docinfo_processor_extensions.any? {|ext| ext.config[:location] == location }
    else
      true
    end
  else
    false
  end
end

#find_block_extension(name) ⇒ Extension

Retrieves the Extension proxy object for the BlockProcessor registered to handle block content with the name.

Parameters:

  • name —

    the String or Symbol (coersed to a Symbol) macro name

  • This —

    method assumes you’ve called blocks? first to check whether any

  • block —

    extensions are registered.

Returns:

  • (Extension) —

    Returns the Extension object stored in the registry that proxies the corresponding BlockProcessor or nil if a match is not found.



1135
1136
1137
 
# File 'lib/asciidoctor/extensions.rb', line 1135

def find_block_extension name
  @block_extensions[name.to_sym]
end

#find_block_macro_extension(name) ⇒ Extension

Retrieves the Extension proxy object for the BlockMacroProcessor registered to handle a block macro with the specified name.

Parameters:

  • name —

    the String or Symbol (coersed to a Symbol) macro name

  • This —

    method assumes you’ve called block_macros? first to check whether any

  • block —

    macro extensions are registered.

Returns:

  • (Extension) —

    Returns the Extension object stored in the registry that proxies the corresponding BlockMacroProcessor or nil if a match is not found.



1230
1231
1232
 
# File 'lib/asciidoctor/extensions.rb', line 1230

def find_block_macro_extension name
  @block_macro_extensions[name.to_sym]
end

#find_inline_macro_extension(name) ⇒ Extension

Retrieves the Extension proxy object for the InlineMacroProcessor registered to handle an inline macro with the specified name.

Parameters:

  • name —

    the String or Symbol (coersed to a Symbol) macro name

  • This —

    method assumes you’ve called inline_macros? first to check whether any

  • inline —

    macro extensions are registered.

Returns:

  • (Extension) —

    Returns the Extension object stored in the registry that proxies the corresponding InlineMacroProcessor or nil if a match is not found.



1323
1324
1325
 
# File 'lib/asciidoctor/extensions.rb', line 1323

def find_inline_macro_extension name
  @inline_macro_extensions[name.to_sym]
end

#include_processor(*args, &block) ⇒ Extension

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 do |document, output|
    ...
  end
end

Returns:

  • (Extension) —

    Returns the Extension stored in the registry that proxies the instance of this IncludeProcessor.



952
953
954
 
# File 'lib/asciidoctor/extensions.rb', line 952

def include_processor *args, &block
  add_document_processor :include_processor, args, &block
end

#include_processors ⇒ Array

Retrieves the Extension proxy objects for all the IncludeProcessor instances stored in this registry.

Returns:

  • (Array) —

    Returns an Array of Extension proxy objects.



967
968
969
 
# File 'lib/asciidoctor/extensions.rb', line 967

def include_processors
  @include_processor_extensions
end

#include_processors? ⇒ Boolean

Checks whether any IncludeProcessor extensions have been registered.

Returns:

  • (Boolean) —

    Returns a Boolean indicating whether any IncludeProcessor extensions are registered.



959
960
961
 
# File 'lib/asciidoctor/extensions.rb', line 959

def include_processors?
  !!@include_processor_extensions
end

#inline_macro(*args, &block) ⇒ Extension

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
inline_macro ChromeInlineMacro
# as an InlineMacroProcessor subclass with an explicit macro name
inline_macro ChromeInlineMacro, :chrome
# as an instance of an InlineMacroProcessor subclass
inline_macro ChromeInlineMacro.new
# as an instance of an InlineMacroProcessor subclass with an explicit macro name
inline_macro ChromeInlineMacro.new, :chrome
# as a name of an InlineMacroProcessor subclass
inline_macro 'ChromeInlineMacro'
# as a name of an InlineMacroProcessor subclass with an explicit macro name
inline_macro 'ChromeInlineMacro', :chrome
# as a method block
inline_macro do
  named :chrome
  process do |parent, target, attrs|
    ...
  end
end
# as a method block with an explicit macro name
inline_macro :chrome do
  process do |parent, target, attrs|
    ...
  end
end

Returns:

  • (Extension) —

    Returns an instance of the Extension proxy object that is stored in the registry and manages the instance of this InlineMacroProcessor.



1288
1289
1290
 
# File 'lib/asciidoctor/extensions.rb', line 1288

def inline_macro *args, &block
  add_syntax_processor :inline_macro, args, &block
end

#inline_macros ⇒ Array

Retrieves the Extension proxy objects for all InlineMacroProcessor instances in this registry.

This method assumes you’ve called inline_macros? first to check whether any inline macro extensions are registered.

Returns:

  • (Array) —

    Returns an Array of Extension proxy objects.



1334
1335
1336
 
# File 'lib/asciidoctor/extensions.rb', line 1334

def inline_macros
  @inline_macro_extensions.values
end

#inline_macros? ⇒ Boolean

Checks whether any InlineMacroProcessor extensions have been registered.

Returns:

  • (Boolean) —

    Returns a Boolean indicating whether any IncludeMacroProcessor extensions are registered.



1295
1296
1297
 
# File 'lib/asciidoctor/extensions.rb', line 1295

def inline_macros?
  !!@inline_macro_extensions
end

#postprocessor(*args, &block) ⇒ Extension

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 do |document, output|
    ...
  end
end

Returns:

  • (Extension) —

    Returns the Extension stored in the registry that proxies the instance of this Postprocessor.



900
901
902
 
# File 'lib/asciidoctor/extensions.rb', line 900

def postprocessor *args, &block
  add_document_processor :postprocessor, args, &block
end

#postprocessors ⇒ Array

Retrieves the Extension proxy objects for all Postprocessor instances in this registry.

Returns:

  • (Array) —

    Returns an Array of Extension proxy objects.



915
916
917
 
# File 'lib/asciidoctor/extensions.rb', line 915

def postprocessors
  @postprocessor_extensions
end

#postprocessors? ⇒ Boolean

Checks whether any Postprocessor extensions have been registered.

Returns:

  • (Boolean) —

    Returns a Boolean indicating whether any Postprocessor extensions are registered.



907
908
909
 
# File 'lib/asciidoctor/extensions.rb', line 907

def postprocessors?
  !!@postprocessor_extensions
end

#prefer(*args, &block) ⇒ Extension

Inserts the document processor Extension instance as the first processor of its kind in the extension registry.

Examples:

prefer :include_processor do
  process do |document, reader, target, attrs|
    ...
  end
end

Returns:

  • (Extension) —

    Returns the Extension stored in the registry that proxies the instance of this processor.



1351
1352
1353
1354
1355
1356
 
# File 'lib/asciidoctor/extensions.rb', line 1351

def prefer *args, &block
  extension = ProcessorExtension === (arg0 = args.shift) ? arg0 : (send arg0, *args, &block)
  extensions_store = instance_variable_get(%(@#{extension.kind}_extensions).to_sym)
  extensions_store.unshift extensions_store.delete extension
  extension
end

#preprocessor(*args, &block) ⇒ Extension

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 do |doc, reader|
    ...
  end
end

Returns:

  • (Extension) —

    Returns the Extension stored in the registry that proxies the instance of this Preprocessor.



791
792
793
 
# File 'lib/asciidoctor/extensions.rb', line 791

def preprocessor *args, &block
  add_document_processor :preprocessor, args, &block
end

#preprocessors ⇒ Array

Retrieves the Extension proxy objects for all Preprocessor instances in this registry.

Returns:

  • (Array) —

    Returns an Array of Extension proxy objects.



806
807
808
 
# File 'lib/asciidoctor/extensions.rb', line 806

def preprocessors
  @preprocessor_extensions
end

#preprocessors? ⇒ Boolean

Checks whether any Preprocessor extensions have been registered.

Returns:

  • (Boolean) —

    Returns a Boolean indicating whether any Preprocessor extensions are registered.



798
799
800
 
# File 'lib/asciidoctor/extensions.rb', line 798

def preprocessors?
  !!@preprocessor_extensions
end

#registered_for_block?(name, context) ⇒ Extension

Checks whether any BlockProcessor extensions are registered to handle the specified block name appearing on the specified context.

This method assumes you’ve called blocks? first to check whether any block extensions are registered.

Returns:

  • (Extension) —

    Returns the Extension proxy object for the BlockProcessor that matches the block name and context or false if no match is found.



1117
1118
1119
1120
1121
1122
1123
 
# File 'lib/asciidoctor/extensions.rb', line 1117

def registered_for_block? name, context
  if (ext = @block_extensions[name.to_sym])
    (ext.config[:contexts].include? context) ? ext : false
  else
    false
  end
end

#registered_for_block_macro?(name) ⇒ Extension

Checks whether any BlockMacroProcessor extensions are registered to handle the block macro with the specified name.

Parameters:

  • name —

    the String or Symbol (coersed to a Symbol) macro name

  • This —

    method assumes you’ve called block_macros? first to check whether any

  • block —

    macro extensions are registered.

Returns:

  • (Extension) —

    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



1216
1217
1218
 
# File 'lib/asciidoctor/extensions.rb', line 1216

def registered_for_block_macro? name
  (ext = @block_macro_extensions[name.to_sym]) ? ext : false
end

#registered_for_inline_macro?(name) ⇒ Extension

Checks whether any InlineMacroProcessor extensions are registered to handle the inline macro with the specified name.

Parameters:

  • name —

    the String or Symbol (coersed to a Symbol) macro name

  • This —

    method assumes you’ve called inline_macros? first to check whether any

  • inline —

    macro extensions are registered.

Returns:

  • (Extension) —

    Returns the Extension proxy object for the InlineMacroProcessor that matches the macro name or false if no match is found.



1309
1310
1311
 
# File 'lib/asciidoctor/extensions.rb', line 1309

def registered_for_inline_macro? name
  (ext = @inline_macro_extensions[name.to_sym]) ? ext : false
end

#tree_processor(*args, &block) ⇒ Extension Also known as: treeprocessor

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
tree_processor ShellTreeProcessor
# as an instance of a TreeProcessor subclass
tree_processor ShellTreeProcessor.new
# as a name of a TreeProcessor subclass
tree_processor 'ShellTreeProcessor'
# as a method block
tree_processor do
  process do |document|
    ...
  end
end

Returns:

  • (Extension) —

    Returns the Extension stored in the registry that proxies the instance of this TreeProcessor.



843
844
845
 
# File 'lib/asciidoctor/extensions.rb', line 843

def tree_processor *args, &block
  add_document_processor :tree_processor, args, &block
end

#tree_processors ⇒ Array Also known as: treeprocessors

Retrieves the Extension proxy objects for all TreeProcessor instances in this registry.

Returns:

  • (Array) —

    Returns an Array of Extension proxy objects.



858
859
860
 
# File 'lib/asciidoctor/extensions.rb', line 858

def tree_processors
  @tree_processor_extensions
end

#tree_processors? ⇒ Boolean Also known as: treeprocessors?

Checks whether any TreeProcessor extensions have been registered.

Returns:

  • (Boolean) —

    Returns a Boolean indicating whether any TreeProcessor extensions are registered.



850
851
852
 
# File 'lib/asciidoctor/extensions.rb', line 850

def tree_processors?
  !!@tree_processor_extensions
end