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.
Constants
- Treeprocessor
Public: TreeProcessors are run on the Document after the source has been parsed into an abstract syntax tree (AST), as represented by the Document object and its child Node objects (e.g., Section, Block, List, ListItem).
Asciidoctor invokes the {Processor#process} method on an instance of each registered TreeProcessor.
TreeProcessor implementations must extend TreeProcessor.
Public Class Methods
Deprecated: Use create instead of ::build_registry
Public: Resolves the Class object for the qualified name.
Returns Class
# File lib/asciidoctor/extensions.rb, line 1466 def class_for_name qualified_name resolved = ::Object (qualified_name.split '::').each do |name| unless name.empty? || ((resolved.const_defined? name) && ::Module === (resolved = resolved.const_get name)) raise ::NameError, %(Could not resolve class for name: #{qualified_name}) end end raise ::NameError, %(Could not resolve class for name: #{qualified_name}) unless ::Class === resolved resolved end
# File lib/asciidoctor/extensions.rb, line 1369 def create name = nil, &block if block_given? Registry.new({ (name || generate_name) => block }) else Registry.new end end
# File lib/asciidoctor/extensions.rb, line 1356 def generate_name %(extgrp#{next_auto_id}) end
# File lib/asciidoctor/extensions.rb, line 1365 def groups @groups ||= {} end
# File lib/asciidoctor/extensions.rb, line 1360 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 1413 def register *args, &block argc = args.size if block_given? resolved_group = block elsif (group = args.pop) # QUESTION should we instantiate the group class here or defer until activation?? resolved_group = (resolve_class group) || group else raise ::ArgumentError, %(Extension group to register not specified) end name = args.pop || generate_name unless args.empty? raise ::ArgumentError, %(Wrong number of arguments (#{argc} for 1..2)) end groups[name.to_sym] = resolved_group end
Internal: Resolve the specified object as a Class
object - The object to resolve as a Class
Returns a Class if the specified object is a Class (but not a Module) or a String that resolves to a Class; otherwise, nil
# File lib/asciidoctor/extensions.rb, line 1454 def resolve_class object case object when ::Class object when ::String class_for_name object end end
Public: Unregister all statically-registered extension groups.
Returns nothing
# File lib/asciidoctor/extensions.rb, line 1433 def unregister_all @groups = {} nil end