module Asciidoctor::Extensions
Extensions provide a way to participate in the parsing and converting phases of the AsciiDoc processor or extend the AsciiDoc syntax.
The various extensions participate in AsciiDoc processing as follows:
-
After the source lines are normalized, {Preprocessor}s modify or replace the source lines before parsing begins. {IncludeProcessor}s are used to process include directives for targets which they claim to handle.
-
The Parser parses the block-level content into an abstract syntax tree. Custom blocks and block macros are processed by associated {BlockProcessor}s and {BlockMacroProcessor}s, respectively.
-
{Treeprocessor}s are run on the abstract syntax tree.
-
Conversion of the document begins, at which point inline markup is processed and converted. Custom inline macros are processed by associated {InlineMacroProcessor}s.
-
{Postprocessor}s modify or replace the converted document.
-
The output is written to the output stream.
Extensions may be registered globally using the {Extensions.register} method or added to a custom {Registry} instance and passed as an option to a single Asciidoctor processor.
Public Class Methods
# File lib/asciidoctor/extensions.rb, line 1249 def build_registry name = nil, &block if block_given? name ||= generate_name Registry.new({ name => block }) else Registry.new end end
Public: Resolves the Class object for the qualified name.
Returns Class
# File lib/asciidoctor/extensions.rb, line 1331 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 %Q(Could not resolve class for name: #{qualified_name}) end end resolved_class end
# File lib/asciidoctor/extensions.rb, line 1236 def generate_name %Q(extgrp#{next_auto_id}) end
# File lib/asciidoctor/extensions.rb, line 1245 def groups @groups ||= {} end
# File lib/asciidoctor/extensions.rb, line 1240 def next_auto_id @auto_id ||= -1 @auto_id += 1 end
Public: Registers an extension Group that subsequently registers a collection of extensions.
Registers the extension Group specified under the given name. If a name is not given, one is calculated by appending the next value in a 0-based index to the string “extgrp”. For instance, the first unnamed extension group to be registered is assigned the name “extgrp0” if a name is not specified.
The names are not yet used, but are intended for selectively activating extensions in the future.
If the extension group argument is a String or a Symbol, it gets resolved to a Class before being registered.
name - The name under which this extension group is registered (optional, default: nil) group - A block (Proc), a Class, a String or Symbol name of a Class or
an Object instance of a Class.
Examples
Asciidoctor::Extensions.register UmlExtensions Asciidoctor::Extensions.register :uml, UmlExtensions Asciidoctor::Extensions.register do block_processor :plantuml, PlantUmlBlock end Asciidoctor::Extensions.register :uml do block_processor :plantuml, PlantUmlBlock end
Returns the [Proc, Class or Object] instance, matching the type passed to this method.
# File lib/asciidoctor/extensions.rb, line 1292 def register *args, &block argc = args.length resolved_group = if block_given? block elsif !(group = args.pop) raise ::ArgumentError.new %Q(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 %Q(Wrong number of arguments (#{argc} for 1..2)) end groups[name] = resolved_group end
unused atm, but tested
# File lib/asciidoctor/extensions.rb, line 1324 def resolve_class object ::Class === object ? object : (class_for_name object.to_s) end
# File lib/asciidoctor/extensions.rb, line 1319 def unregister_all @groups = {} end