class Asciidoctor::Extensions::Registry
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.
Attributes
Public: Returns the {Asciidoctor::Document} on which the extensions in this registry are being used.
Public: Returns the Array
of {Group} classes, instances and/or Procs that have been registered.
Public Class Methods
# File lib/asciidoctor/extensions.rb, line 649 def initialize groups = {} @groups = groups @preprocessor_extensions = @tree_processor_extensions = @postprocessor_extensions = @include_processor_extensions = @docinfo_processor_extensions = nil @block_extensions = @block_macro_extensions = @inline_macro_extensions = nil @document = nil end
Public Instance Methods
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].
# File lib/asciidoctor/extensions.rb, line 662 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 group.activate self end end self end
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 aBlockProcessor
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 block :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
.
# File lib/asciidoctor/extensions.rb, line 1024 def block *args, &block add_syntax_processor :block, args, &block end
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 aBlockMacroProcessor
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 |parent, target, attrs| ... end end # as a method block with an explicit macro name block_macro :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
.
# File lib/asciidoctor/extensions.rb, line 1113 def block_macro *args, &block add_syntax_processor :block_macro, args, &block end
Public: Checks whether any {BlockMacroProcessor} extensions have been registered.
Returns a [Boolean] indicating whether any BlockMacroProcessor
extensions are registered.
# File lib/asciidoctor/extensions.rb, line 1120 def block_macros? !!@block_macro_extensions end
Public: Checks whether any {BlockProcessor} extensions have been registered.
Returns a [Boolean] indicating whether any BlockProcessor
extensions are registered.
# File lib/asciidoctor/extensions.rb, line 1031 def blocks? !!@block_extensions end
Public: Registers an {DocinfoProcessor} with the extension registry to add additionnal 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 aDocinfoProcessor
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 |doc| at_location :footer 'footer content' end end
Returns the [Extension] stored in the registry that proxies the instance of this DocinfoProcessor
.
# File lib/asciidoctor/extensions.rb, line 929 def docinfo_processor *args, &block add_document_processor :docinfo_processor, args, &block end
Public: Retrieves the {Extension} proxy objects for all the DocinfoProcessor
instances stored in this registry.
location - A Symbol
for selecting docinfo extensions at a given location (:head or :footer) (default: nil)
Returns an [Array] of Extension
proxy objects.
# File lib/asciidoctor/extensions.rb, line 956 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 else nil end end
Public: Checks whether any {DocinfoProcessor} extensions have been registered.
location - A Symbol
for selecting docinfo extensions at a given location (:head or :footer) (default: nil)
Returns a [Boolean] indicating whether any DocinfoProcessor
extensions are registered.
# File lib/asciidoctor/extensions.rb, line 938 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
Public: Retrieves the {Extension} proxy object for the BlockProcessor
registered to handle block content with the name.
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.
# File lib/asciidoctor/extensions.rb, line 1055 def find_block_extension name @block_extensions[name.to_sym] 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.
# File lib/asciidoctor/extensions.rb, line 1144 def find_block_macro_extension name @block_macro_extensions[name.to_sym] end
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.
# File lib/asciidoctor/extensions.rb, line 1231 def find_inline_macro_extension name @inline_macro_extensions[name.to_sym] 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 aIncludeProcessor
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
.
# File lib/asciidoctor/extensions.rb, line 876 def include_processor *args, &block add_document_processor :include_processor, args, &block end
Public: Retrieves the {Extension} proxy objects for all the IncludeProcessor
instances stored in this registry.
Returns an [Array] of Extension
proxy objects.
# File lib/asciidoctor/extensions.rb, line 891 def include_processors @include_processor_extensions end
Public: Checks whether any {IncludeProcessor} extensions have been registered.
Returns a [Boolean] indicating whether any IncludeProcessor
extensions are registered.
# File lib/asciidoctor/extensions.rb, line 883 def include_processors? !!@include_processor_extensions 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 anInlineMacroProcessor
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 ChromeInineMacro, :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 '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 inline_macro :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
.
# File lib/asciidoctor/extensions.rb, line 1202 def inline_macro *args, &block add_syntax_processor :inline_macro, args, &block end
Public: Retrieves the {Extension} proxy objects for all InlineMacroProcessor
instances in this registry.
Returns an [Array] of Extension
proxy objects.
# File lib/asciidoctor/extensions.rb, line 1239 def inline_macros @inline_macro_extensions.values end
Public: Checks whether any {InlineMacroProcessor} extensions have been registered.
Returns a [Boolean] indicating whether any IncludeMacroProcessor extensions are registered.
# File lib/asciidoctor/extensions.rb, line 1209 def inline_macros? !!@inline_macro_extensions end
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 aPostprocessor
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
.
# File lib/asciidoctor/extensions.rb, line 824 def postprocessor *args, &block add_document_processor :postprocessor, args, &block end
Public: Retrieves the {Extension} proxy objects for all Postprocessor
instances in this registry.
Returns an [Array] of Extension
proxy objects.
# File lib/asciidoctor/extensions.rb, line 839 def postprocessors @postprocessor_extensions end
Public: Checks whether any {Postprocessor} extensions have been registered.
Returns a [Boolean] indicating whether any Postprocessor
extensions are registered.
# File lib/asciidoctor/extensions.rb, line 831 def postprocessors? !!@postprocessor_extensions end
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 aPreprocessor
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 |doc, reader| ... end end
Returns the [Extension] stored in the registry that proxies the instance of this Preprocessor
.
# File lib/asciidoctor/extensions.rb, line 715 def preprocessor *args, &block add_document_processor :preprocessor, args, &block end
Public: Retrieves the {Extension} proxy objects for all Preprocessor
instances in this registry.
Returns an [Array] of Extension
proxy objects.
# File lib/asciidoctor/extensions.rb, line 730 def preprocessors @preprocessor_extensions end
Public: Checks whether any {Preprocessor} extensions have been registered.
Returns a [Boolean] indicating whether any Preprocessor
extensions are registered.
# File lib/asciidoctor/extensions.rb, line 722 def preprocessors? !!@preprocessor_extensions end
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.
# File lib/asciidoctor/extensions.rb, line 1040 def registered_for_block? name, context if (ext = @block_extensions[name.to_sym]) (ext.config[:contexts].include? context) ? ext : false else false end end
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.
# File lib/asciidoctor/extensions.rb, line 1133 def registered_for_block_macro? name (ext = @block_macro_extensions[name.to_sym]) ? ext : false end
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.
# File lib/asciidoctor/extensions.rb, line 1220 def registered_for_inline_macro? name (ext = @inline_macro_extensions[name.to_sym]) ? ext : false end
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 aTreeProcessor
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 |document| ... end end
Returns the [Extension] stored in the registry that proxies the instance of this TreeProcessor
.
# File lib/asciidoctor/extensions.rb, line 767 def tree_processor *args, &block add_document_processor :tree_processor, args, &block end
Public: Retrieves the {Extension} proxy objects for all TreeProcessor
instances in this registry.
Returns an [Array] of Extension
proxy objects.
# File lib/asciidoctor/extensions.rb, line 782 def tree_processors @tree_processor_extensions end
Public: Checks whether any {TreeProcessor} extensions have been registered.
Returns a [Boolean] indicating whether any TreeProcessor
extensions are registered.
# File lib/asciidoctor/extensions.rb, line 774 def tree_processors? !!@tree_processor_extensions end
Alias deprecated methods for backwards compatibility
Private Instance Methods
# File lib/asciidoctor/extensions.rb, line 1245 def add_document_processor kind, args, &block kind_name = kind.to_s.tr '_', ' ' kind_class_symbol = kind_name.split.map {|it| it.capitalize }.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 # NOTE class << processor idiom doesn't work in Opal #class << processor # include_dsl #end # NOTE kind_class.contants(false) doesn't exist in Ruby 1.8.7 processor.extend kind_class.const_get :DSL if kind_class.constants.grep :DSL processor.instance_exec(&block) processor.freeze unless processor.process_block_given? raise ::ArgumentError, %(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 String class name if (processor_class = Extensions.resolve_class processor) unless processor_class < kind_class || (kind_java_class && processor_class < kind_java_class) raise ::ArgumentError, %(Invalid type for #{kind_name} extension: #{processor}) end processor_instance = processor_class.new config processor_instance.freeze ProcessorExtension.new kind, processor_instance # style 3: specified as instance elsif kind_class === processor || (kind_java_class && kind_java_class === processor) processor.update_config config processor.freeze ProcessorExtension.new kind, processor else raise ::ArgumentError, %(Invalid arguments specified for registering #{kind_name} extension: #{args}) end end if extension.config[:position] == :>> kind_store.unshift extension else kind_store << extension end end
# File lib/asciidoctor/extensions.rb, line 1295 def add_syntax_processor kind, args, &block kind_name = kind.to_s.tr '_', ' ' kind_class_symbol = (kind_name.split.map {|it| it.capitalize }.push 'Processor').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 if block_given? name, config = resolve_args args, 2 processor = kind_class.new as_symbol(name), config # NOTE class << processor idiom doesn't work in Opal #class << processor # include_dsl #end # NOTE kind_class.contants(false) doesn't exist in Ruby 1.8.7 processor.extend kind_class.const_get :DSL if kind_class.constants.grep :DSL if block.arity == 1 yield processor else processor.instance_exec(&block) end unless (name = as_symbol processor.name) raise ::ArgumentError, %(No name specified for #{kind_name} extension at #{block.source_location}) end unless processor.process_block_given? raise ::NoMethodError, %(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 String class name if (processor_class = Extensions.resolve_class processor) unless processor_class < kind_class || (kind_java_class && processor_class < kind_java_class) raise ::ArgumentError, %(Class specified for #{kind_name} extension does not inherit from #{kind_class}: #{processor}) end processor_instance = processor_class.new as_symbol(name), config unless (name = as_symbol processor_instance.name) raise ::ArgumentError, %(No name specified for #{kind_name} extension: #{processor}) end processor_instance.freeze kind_store[name] = ProcessorExtension.new kind, processor_instance # style 3: specified as instance elsif kind_class === processor || (kind_java_class && kind_java_class === processor) 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, %(No name specified for #{kind_name} extension: #{processor}) end processor.freeze kind_store[name] = ProcessorExtension.new kind, processor else raise ::ArgumentError, %(Invalid arguments specified for registering #{kind_name} extension: #{args}) end end end
# File lib/asciidoctor/extensions.rb, line 1364 def as_symbol name name ? name.to_sym : nil end
# File lib/asciidoctor/extensions.rb, line 1352 def resolve_args args, expect opts = ::Hash === args[-1] ? args.pop : {} return opts if expect == 1 if (missing = expect - 1 - args.size) > 0 args += (::Array.new missing) elsif missing < 0 args.pop(-missing) end args << opts args end