Class Asciidoctor::Document
In: lib/asciidoctor/document.rb
Parent: AbstractBlock

Public: Methods for parsing and converting AsciiDoc documents.

There are several strategies for getting the title of the document:

doctitle - value of title attribute, if assigned and non-empty,

           otherwise title of first section in document, if present
           otherwise nil

name - an alias of doctitle title - value of the title attribute, or nil if not present first_section.title - title of first section in document, if present header.title - title of section level 0

Keep in mind that you‘ll want to honor these document settings:

notitle - The h1 heading should not be shown noheader - The header block (h1 heading, author, revision info) should not be shown nofooter - the footer block should not be shown

Methods

Classes and Modules

Class Asciidoctor::Document::AttributeEntry
Class Asciidoctor::Document::Title

Constants

Footnote = ::Struct.new :index, :id, :text

External Aliases

catalog -> references
  Public: Alias catalog property as references for backwards compatiblity

Attributes

backend  [R]  Public: Get the cached value of the backend attribute for this document
base_dir  [R]  Public: Get the String base directory for converting this document.

Defaults to directory of the source file. If the source is a string, defaults to the current directory.

callouts  [R]  Public: Get the Hash of callouts
catalog  [R]  Public: Get the document catalog Hash
compat_mode  [R]  Public: Get the Boolean AsciiDoc compatibility mode

enabling this attribute activates the following syntax changes:

  * single quotes as constrained emphasis formatting marks
  * single backticks parsed as inline literal, formatted as monospace
  * single plus parsed as constrained, monospaced inline formatting
  * double plus parsed as constrained, monospaced inline formatting
converter  [R]  Public: Get the Converter associated with this document
counters  [R]  Public: Get the Hash of document counters
doctype  [R]  Public: Get the cached value of the doctype attribute for this document
extensions  [R]  Public: Get the activated Extensions::Registry associated with this document.
header  [R]  Public: Get the level-0 Section
options  [R]  Public: Get the Hash of resolved options used to initialize this Document
outfilesuffix  [R]  Public: Get the outfilesuffix defined at the end of the header.
parent_document  [R]  Public: Get a reference to the parent Document of this nested document.
reader  [R]  Public: Get the Reader associated with this document
safe  [R]  Public A read-only integer value indicating the level of security that should be enforced while processing this document. The value must be set in the Document constructor using the :safe option.

A value of 0 (UNSAFE) disables any of the security features enforced by Asciidoctor (Ruby is still subject to its own restrictions).

A value of 1 (SAFE) closely parallels safe mode in AsciiDoc. In particular, it prevents access to files which reside outside of the parent directory of the source file and disables any macro other than the include directive.

A value of 10 (SERVER) disallows the document from setting attributes that would affect the conversion of the document, in addition to all the security features of SafeMode::SAFE. For instance, this value disallows changing the backend or the source-highlighter using an attribute defined in the source document. This is the most fundamental level of security for server-side deployments (hence the name).

A value of 20 (SECURE) disallows the document from attempting to read files from the file system and including the contents of them into the document, in addition to all the security features of SafeMode::SECURE. In particular, it disallows use of the include::[] directive and the embedding of binary content (data uri), stylesheets and JavaScripts referenced by the document. (Asciidoctor and trusted extensions may still be allowed to embed trusted content into the document).

Since Asciidoctor is aiming for wide adoption, 20 (SECURE) is the default value and is recommended for server-side deployments.

A value of 100 (PARANOID) is planned to disallow the use of passthrough macros and prevents the document from setting any known attributes in addition to all the security features of SafeMode::SECURE. Please note that this level is not currently implemented (and therefore not enforced)!

sourcemap  [RW]  Public: Get or set the Boolean flag that indicates whether source map information should be tracked by the parser

Public Class methods

Public: Initialize a {Document} object.

data - The AsciiDoc source data as a String or String Array. (default: nil) options - A Hash of options to control processing (e.g., safe mode value (:safe), backend (:backend),

          header/footer toggle (:header_footer), custom attributes (:attributes)). (default: {})

Duplication of the options Hash is handled in the enclosing API.

Examples

  data = File.read filename
  doc = Asciidoctor::Document.new data
  puts doc.convert

Public Instance methods

Public: Append a content Block to this Document.

If the child block is a Section, assign an index to it.

block - The child Block to append to this parent Block

Returns The parent Block

Internal: Apply substitutions to the attribute value

If the value is an inline passthrough macro (e.g., pass:<subs>[value]), apply the substitutions defined in <subs> to the value, or leave the value unmodified if no substitutions are specified. If the value is not an inline passthrough macro, apply header substitutions to the value.

value - The String attribute value on which to perform substitutions

Returns The String value with substitutions performed

Public: Determine if the attribute has been locked by being assigned in document options

key - The attribute key to check

Returns true if the attribute is locked, false otherwise

Public: Convenience method to retrieve the document attribute ‘author

returns the full name of the author as a String

Internal: Delete any attributes stored for playback

Public: Convert the AsciiDoc document using the templates loaded by the Converter. If a :template_dir is not specified, or a template is missing, the converter will fall back to using the appropriate built-in template.

Public: Get the named counter and take the next number in the sequence.

name - the String name of the counter seed - the initial value as a String or Integer

returns the next number in the sequence for the specified counter

counter_increment(counter_name, block)

TODO document me

Public: Delete the specified attribute from the document if the name is not locked

If the attribute is locked, false is returned. Otherwise, the attribute is deleted.

name - the String attribute name

returns true if the attribute was deleted, false if it was not because it‘s locked

Public: Read the docinfo file(s) for inclusion in the document template

If the docinfo1 attribute is set, read the docinfo.ext file. If the docinfo attribute is set, read the doc-name.docinfo.ext file. If the docinfo2 attribute is set, read both files in that order.

location - The Symbol location of the docinfo (e.g., :head, :footer, etc). (default: :head) suffix - The suffix of the docinfo file(s). If not set, the extension

           will be set to the outfilesuffix. (default: nil)

returns The contents of the docinfo file(s) or empty string if no files are found or the safe mode is secure or greater.

Public: Resolves the primary title for the document

Searches the locations to find the first non-empty value:

 * document-level attribute named title
 * header title (known as the document title)
 * title of the first section
 * document-level attribute named untitled-label (if :use_fallback option is set)

If no value can be resolved, nil is returned.

If the :partition attribute is specified, the value is parsed into an Document::Title object. If the :sanitize attribute is specified, XML elements are removed from the value.

TODO separate sanitization by type (:cdata for HTML/XML, :plain_text for non-SGML, false for none)

Returns the resolved title as a [Title] if the :partition option is passed or a [String] if not or nil if no value can be resolved.

Internal: called after the header has been parsed and before the content will be parsed.

header?()

Alias for has_header?

Public: Increment the specified counter and store it in the block‘s attributes

counter_name - the String name of the counter attribute block - the Block on which to save the counter

returns the next number in the sequence for the specified counter

name(opts = {})

Alias for doctitle

Internal: Get the next value in the sequence.

Handles both integer and character sequences.

current - the value to increment as a String or Integer

returns the next value in the sequence according to the current value‘s type

Public: Parse the AsciiDoc source stored in the {Reader} into an abstract syntax tree.

If the data parameter is not nil, create a new {PreprocessorReader} and assigned it to the reader property of this object. Otherwise, continue with the reader that was created in {initialize}. Pass the reader to {Parser.parse} to parse the source data into an abstract syntax tree.

If parsing has already been performed, this method returns without performing any processing.

data - The optional replacement AsciiDoc source data as a String or String Array. (default: nil)

Returns this [Document]

Internal: Replay attribute assignments at the block level

render(opts = {})

Alias for convert

Internal: Resolve the list of comma-delimited subs to apply to docinfo files.

Resolve the list of substitutions from the value of the docinfosubs document attribute, if specified. Otherwise, return an Array containing the Symbol :attributes.

Returns an [Array] of substitution [Symbol]s

Internal: Restore the attributes to the previously saved state (attributes in header)

Public: Convenience method to retrieve the document attribute ‘revdate

returns the date of last revision for the document as a String

Internal: Branch the attributes so that the original state can be restored at a future time.

Public: Set the specified attribute on the document if the name is not locked

If the attribute is locked, false is returned. Otherwise, the value is assigned to the attribute name after first performing attribute substitutions on the value. If the attribute name is ‘backend’ or ‘doctype’, then the value of backend-related attributes are updated.

name - the String attribute name value - the String attribute value; must not be nil (default: ’’)

Returns the resolved value if the attribute was set or false if it was not because it‘s locked.

Make the raw source for the Document available.

Make the raw source lines for the Document available.

The title explicitly defined in the document attributes

Public: Update the backend attributes to reflect a change in the active backend.

This method also handles updating the related doctype attributes if the doctype attribute is assigned at the time this method is called.

Returns the resolved String backend if updated, nothing otherwise.

TODO document me

Returns the String doctype if updated, nothing otherwise.

Public: Write the output to the specified file

If the converter responds to :write, delegate the work of writing the file to that method. Otherwise, write the output the specified file.

[Validate]