Public: Methods for parsing Asciidoc input files and rendering documents using eRuby templates.
Asciidoc documents comprise a header followed by zero or more sections. Sections are composed of blocks of content. For example:
Doc Title ========= SECTION 1 --------- This is a paragraph block in the first section. SECTION 2 This section has a paragraph block and an olist block. 1. Item 1 2. Item 2
Examples:
Use built-in templates:
lines = File.readlines("your_file.asc") doc = Asciidoctor::Document.new(lines) html = doc.render File.open("your_file.html", "w+") do |file| file.puts html end
Use custom (Tilt-supported) templates:
lines = File.readlines("your_file.asc") doc = Asciidoctor::Document.new(lines, :template_dir => 'templates') html = doc.render File.open("your_file.html", "w+") do |file| file.puts html end
ROOT_PATH | = | File.expand_path(File.join(File.dirname(__FILE__), '..')) | The root path of the Asciidoctor gem | |||||
FORCE_ENCODING | = | RUBY_VERSION > '1.9' && Encoding.default_external != Encoding::UTF_8 | Flag to indicate whether encoding of external strings needs to be forced to UTF-8 All input data must be force encoded to UTF-8 if Encoding.default_external is not UTF-8 Address failures performing string operations that are reported as "invalid byte sequence in US-ASCII" Ruby 1.8 doesn‘t seem to experience this problem (perhaps because it isn‘t validating the encodings) | |||||
DEFAULT_DOCTYPE | = | 'article' | The default document type Can influence markup generated by render templates | |||||
DEFAULT_BACKEND | = | 'html5' | The backend determines the format of the rendered output, default to html5 | |||||
DEFAULT_STYLESHEET_KEYS | = | ['', 'DEFAULT'].to_set | ||||||
DEFAULT_STYLESHEET_NAME | = | 'asciidoctor.css' | ||||||
BACKEND_ALIASES | = | { 'html' => 'html5', 'docbook' => 'docbook45' | Pointers to the preferred version for a given backend. | |||||
DEFAULT_PAGE_WIDTHS | = | { 'docbook' => 425 | Default page widths for calculating absolute widths | |||||
DEFAULT_EXTENSIONS | = | { 'html' => '.html', 'docbook' => '.xml', 'asciidoc' => '.ad', 'markdown' => '.md' | Default extensions for the respective base backends | |||||
SECTION_LEVELS | = | { '=' => 0, '-' => 1, '~' => 2, '^' => 3, '+' => 4 | ||||||
ADMONITION_STYLES | = | ['NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION'].to_set | ||||||
PARAGRAPH_STYLES | = | ['comment', 'example', 'literal', 'listing', 'normal', 'pass', 'quote', 'sidebar', 'source', 'verse', 'abstract', 'partintro'].to_set | ||||||
VERBATIM_STYLES | = | ['literal', 'listing', 'source', 'verse'].to_set | ||||||
DELIMITED_BLOCKS | = | { '--' => [:open, ['comment', 'example', 'literal', 'listing', 'pass', 'quote', 'sidebar', 'source', 'verse', 'admonition', 'abstract', 'partintro'].to_set], '----' => [:listing, ['literal', 'source'].to_set], '....' => [:literal, ['listing', 'source'].to_set], '====' => [:example, ['admonition'].to_set], '****' => [:sidebar, Set.new], '____' => [:quote, ['verse'].to_set], '""' => [:quote, ['verse'].to_set], '++++' => [:pass, Set.new], '|===' => [:table, Set.new], ',===' => [:table, Set.new], ':===' => [:table, Set.new], '!===' => [:table, Set.new], '////' => [:comment, Set.new], '```' => [:fenced_code, Set.new], '~~~' => [:fenced_code, Set.new] | ||||||
BREAK_LINES | = | { %q{'''} => :ruler, '<<<' => :page_break | ||||||
LIST_CONTEXTS | = | [:ulist, :olist, :dlist, :colist] | ||||||
NESTABLE_LIST_CONTEXTS | = | [:ulist, :olist, :dlist] | ||||||
ORDERED_LIST_STYLES | = | [:arabic, :loweralpha, :lowerroman, :upperalpha, :upperroman] | ||||||
ORDERED_LIST_MARKER_PATTERNS | = | { :arabic => /\d+[.>]/, :loweralpha => /[a-z]\./, :upperalpha => /[A-Z]\./, :lowerroman => /[ivx]+\)/, :upperroman => /[IVX]+\)/ | ||||||
ORDERED_LIST_KEYWORDS | = | { 'loweralpha' => 'a', 'lowerroman' => 'i', 'upperalpha' => 'A', 'upperroman' => 'I' | ||||||
LIST_CONTINUATION | = | '+' | ||||||
LINE_BREAK | = | ' +' | ||||||
BLANK_LINE_PATTERN | = | /^[[:blank:]]*\n/ | NOTE allows for empty space in line as it could be left by the template engine | |||||
LINE_FEED_ENTITY | = | ' ' | ||||||
COMPLIANCE | = | { # AsciiDoc terminates paragraphs adjacent to # block content (delimiter or block attribute list) # Compliance value: true # TODO what about literal paragraph? :block_terminates_paragraph => true, # AsciiDoc does not treat paragraphs labeled with a # verbatim style (literal, listing, source, verse) # as verbatim; override this behavior # Compliance value: false :strict_verbatim_paragraphs => true, # AsciiDoc allows start and end delimiters around # a block to be different lengths # this option requires that they be the same # Compliance value: false :congruent_block_delimiters => true, # AsciiDoc will recognize commonly-used Markdown syntax # to the degree it does not interfere with existing # AsciiDoc behavior. :markdown_syntax => true | Flags to control compliance with the behavior of AsciiDoc | |||||
REGEXP | = | { # NOTE: this is a inline admonition note :admonition_inline => /^(#{ADMONITION_STYLES.to_a * '|'}):\s/, # [[Foo]] :anchor => /^\[\[([^\s\[\]]+)\]\]$/, # Foowhatevs [[Bar]] :anchor_embedded => /^(.*?)\s*\[\[([^\[\]]+)\]\]$/, # [[ref]] (anywhere inline) :anchor_macro => /\\?\[\[([\w":].*?)\]\]/, # matches any unbounded block delimiter: # listing, literal, example, sidebar, quote, passthrough, table, fenced code # does not include open block or air quotes # TIP position the most common blocks towards the front of the pattern :any_blk => %r{^(?:(?:-|\.|=|\*|_|\+|/){4,}|[\|,;!]={3,}|(?:`|~){3,}.*)$}, # detect a list item of any sort # [[:graph:]] is a non-blank character :any_list => /^(?: <?\d+>[[:blank:]]+[[:graph:]]| [[:blank:]]*(?:(?:-|\*|\.){1,5}|\d+\.|[A-Za-z]\.|[IVXivx]+\))[[:blank:]]+[[:graph:]]| [[:blank:]]*.*?(?::{2,4}|;;)(?:[[:blank:]]+[[:graph:]]|$) )/x, # :foo: bar # :Author: Dan # :numbered!: :attr_entry => /^:(\w.*?):(?:[[:blank:]]+(.*))?$/, # {name?value} :attr_conditional => /^\s*\{([^\?]+)\?\s*([^\}]+)\s*\}/, # + Attribute values treat lines ending with ' +' as a continuation, # not a line-break as elsewhere in the document, where this is # a forced line break. This should be the same regexp as :line_break, # below, but it gets its own entry because readability ftw, even # though repeating regexps ftl. :attr_continue => /^[[:blank:]]*(.*)[[:blank:]]\+[[:blank:]]*$/, # :foo!: :attr_delete => /^:([^:]+)!:$/, # An attribute list above a block element # # Can be strictly positional: # [quote, Adam Smith, Wealth of Nations] # Or can have name/value pairs # [NOTE, caption="Good to know"] # Can be defined by an attribute # [{lead}] :blk_attr_list => /^\[(|[[:blank:]]*[\w\{,.#"'].*)\]$/, # block attribute list or block id (bulk query) :attr_line => /^\[(|[[:blank:]]*[\w\{,.#"'].*|\[[^\[\]]*\])\]$/, # attribute reference # {foo} # {counter:pcount:1} :attr_ref => /(\\)?\{((set|counter2?):.+?|\w+(?:[\-]\w+)*)(\\)?\}/, # The author info line the appears immediately following the document title # John Doe <john@anonymous.com> :author_info => /^(\w[\w\-'.]*)(?: +(\w[\w\-'.]*))?(?: +(\w[\w\-'.]*))?(?: +<([^>]+)>)?$/, # [[[Foo]]] (anywhere inline) :biblio_macro => /\\?\[\[\[([\w:][\w:.-]*?)\]\]\]/, # callout reference inside literal text # <1> # special characters will already be replaced, hence their use in the regex :callout_render => /\\?<(\d+)>/, # ...but not while scanning :callout_scan => /\\?<(\d+)>/, # <1> Foo :colist => /^<?(\d+)>[[:blank:]]+(.*)/, # //// # comment block # //// :comment_blk => %r{^/{4,}$}, # // (and then whatever) :comment => %r{^//(?:[^/]|$)}, # one,two;three;four :ssv_or_csv_delim => /,|;/, # one two three :space_delim => /([^\\])[[:blank:]]+/, # Ctrl + Alt+T # Ctrl,T :kbd_delim => /(?:\+|,)(?=[[:blank:]]*[^\1])/, # one\ two\ three :escaped_space => /\\([[:blank:]])/, # 29 :digits => /^\d+$/, # foo:: || foo::: || foo:::: || foo;; # Should be followed by a definition, on the same line... # foo:: That which precedes 'bar' (see also, <<bar>>) # ...or on a separate line # foo:: # That which precedes 'bar' (see also, <<bar>>) # The term may be an attribute reference # {term_foo}:: {def_foo} # REVIEW leading space has already been stripped, so may not need in regex :dlist => /^[[:blank:]]*(.*?)(:{2,4}|;;)(?:[[:blank:]]+(.*))?$/, :dlist_siblings => { # (?:.*?[^:])? - a non-capturing group which grabs longest sequence of characters that doesn't end w/ colon '::' => /^[[:blank:]]*((?:.*[^:])?)(::)(?:[[:blank:]]+(.*))?$/, ':::' => /^[[:blank:]]*((?:.*[^:])?)(:::)(?:[[:blank:]]+(.*))?$/, '::::' => /^[[:blank:]]*((?:.*[^:])?)(::::)(?:[[:blank:]]+(.*))?$/, ';;' => /^[[:blank:]]*(.*)(;;)(?:[[:blank:]]+(.*))?$/ |
The following pattern, which appears frequently, captures the contents
between square brackets, ignoring escaped closing brackets (closing
brackets prefixed with a backslash ’\’ character)
Pattern: (?:\[((?:\\]|[^\]])*?)\]) Matches:
|
|||||
INTRINSICS | = | Hash.new{|h,k| STDERR.puts "Missing intrinsic: #{k.inspect}"; | ||||||
SPECIAL_CHARS | = | { '<' => '<', '>' => '>', '&' => '&' | ||||||
SPECIAL_CHARS_PATTERN | = | /[#{SPECIAL_CHARS.keys.join}]/ | ||||||
QUOTE_SUBS | = | [ # **strong** [:strong, :unconstrained, /\\?(?:\[([^\]]+?)\])?\*\*(.+?)\*\*/m], # *strong* [:strong, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?\*(\S|\S.*?\S)\*(?=\W|$)/m], # ``double-quoted'' [:double, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?``(\S|\S.*?\S)''(?=\W|$)/m], # 'emphasis' [:emphasis, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?'(\S|\S.*?\S)'(?=\W|$)/m], # `single-quoted' [:single, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?`(\S|\S.*?\S)'(?=\W|$)/m], # ++monospaced++ [:monospaced, :unconstrained, /\\?(?:\[([^\]]+?)\])?\+\+(.+?)\+\+/m], # +monospaced+ [:monospaced, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?\+(\S|\S.*?\S)\+(?=\W|$)/m], # __emphasis__ [:emphasis, :unconstrained, /\\?(?:\[([^\]]+?)\])?\_\_(.+?)\_\_/m], # _emphasis_ [:emphasis, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?_(\S|\S.*?\S)_(?=\W|$)/m], # ##unquoted## [:none, :unconstrained, /\\?(?:\[([^\]]+?)\])?##(.+?)##/m], # #unquoted# [:none, :constrained, /(^|[^\w;:}])(?:\[([^\]]+?)\])?#(\S|\S.*?\S)#(?=\W|$)/m], # ^superscript^ [:superscript, :unconstrained, /\\?(?:\[([^\]]+?)\])?\^(.+?)\^/m], # ~subscript~ [:subscript, :unconstrained, /\\?(?:\[([^\]]+?)\])?\~(.+?)\~/m] |
|
|||||
REPLACEMENTS | = | [ # (C) [/\\?\(C\)/, '©', :none], # (R) [/\\?\(R\)/, '®', :none], # (TM) [/\\?\(TM\)/, '™', :none], # foo -- bar [/(^|\n| |\\)--( |\n|$)/, ' — ', :none], # foo--bar [/(\w)\\?--(?=\w)/, '—', :leading], # ellipsis [/\\?\.\.\./, '…', :leading], # single quotes [/(\w)\\?'(\w)/, '’', :bounding], # right arrow -> [/\\?->/, '→', :none], # right double arrow => [/\\?=>/, '⇒', :none], # left arrow <- [/\\?<-/, '←', :none], # right left arrow <= [/\\?<=/, '⇐', :none], # restore entities [/\\?(&)amp;((?:[[:alpha:]]+|#[[:digit:]]+|#x[[:alnum:]]+);)/, '', :bounding] | NOTE in Ruby 1.8.7, [^\] does not match start of line, so we need to match it explicitly order is significant | |||||
Rows | = | Struct.new(:head, :foot, :body) | ||||||
VERSION | = | '0.1.3' |
Public: Parse the AsciiDoc source input into an Asciidoctor::Document
Accepts input as an IO (or StringIO), String or String Array object. If the input is a File, information about the file is stored in attributes on the Document object.
input - the AsciiDoc source as a IO, String or Array. options - a String, Array or Hash of options to control processing (default: {})
String and Array values are converted into a Hash. See Asciidoctor::Document#initialize for details about options.
block - a callback block for handling include::[] directives
returns the Asciidoctor::Document
Public: Parse the contents of the AsciiDoc source file into an Asciidoctor::Document
Accepts input as an IO, String or String Array object. If the input is a File, information about the file is stored in attributes on the Document.
input - the String AsciiDoc source filename options - a String, Array or Hash of options to control processing (default: {})
String and Array values are converted into a Hash. See Asciidoctor::Document#initialize for details about options.
block - a callback block for handling include::[] directives
returns the Asciidoctor::Document
Public: Parse the AsciiDoc source input into an Asciidoctor::Document and render it to the specified backend format
Accepts input as an IO, String or String Array object. If the input is a File, information about the file is stored in attributes on the Document.
If the :in_place option is true, and the input is a File, the output is written to a file adjacent to the input file, having an extension that corresponds to the backend format. Otherwise, if the :to_file option is specified, the file is written to that file. If :to_file is not an absolute path, it is resolved relative to :to_dir, if given, otherwise the Document#base_dir. If the target directory does not exist, it will not be created unless the :mkdirs option is set to true. If the file cannot be written because the target directory does not exist, or because it falls outside of the Document#base_dir in safe mode, an IOError is raised.
If the output is going to be written to a file, the header and footer are rendered unless specified otherwise (writing to a file implies creating a standalone document). Otherwise, the header and footer are not rendered by default and the rendered output is returned.
input - the String AsciiDoc source filename options - a String, Array or Hash of options to control processing (default: {})
String and Array values are converted into a Hash. See Asciidoctor::Document#initialize for details about options.
block - a callback block for handling include::[] directives
returns the Document object if the rendered result String is written to a file, otherwise the rendered result String
Public: Parse the contents of the AsciiDoc source file into an Asciidoctor::Document and render it to the specified backend format
input - the String AsciiDoc source filename options - a String, Array or Hash of options to control processing (default: {})
String and Array values are converted into a Hash. See Asciidoctor::Document#initialize for details about options.
block - a callback block for handling include::[] directives
returns the Document object if the rendered result String is written to a file, otherwise the rendered result String