Struct Parser 

pub struct Parser {
    pub path_resolver: PathResolver,
    /* private fields */
}

The Parser struct and its related structs allow a caller to configure how AsciiDoc parsing occurs and then to initiate the parsing process.

Fields

path_resolver: PathResolver

Specifies how to generate clean and secure paths relative to the parsing context.

Implementations

impl Parser

pub fn parse(&mut self, source: &str) -> Document<'static>

Parse a UTF-8 string as an AsciiDoc document.

The Document data structure returned by this call has a ’static lifetime; this is an implementation detail. It retains a copy of the source string that was passed in, but it is not tied to the lifetime of that string.

Nearly all of the data structures contained within the Document structure are tied to the lifetime of the document and have a 'src lifetime to signal their dependency on the source document.

IMPORTANT: The AsciiDoc language documentation states that UTF-16 encoding is allowed if a byte-order-mark (BOM) is present at the start of a file. This format is not directly supported by the asciidoc-parser crate. Any UTF-16 content must be re-encoded as UTF-8 prior to parsing.

The Parser struct will be updated with document attribute values discovered during parsing. These values may be inspected using attribute_value().

Warnings, not errors

Any UTF-8 string is a valid AsciiDoc document, so this function does not return an Option or Result data type. There may be any number of character sequences that have ambiguous or potentially unintended meanings. For that reason, a caller is advised to review the warnings provided via the warnings() iterator.

pub fn attribute_value<N: AsRef<str>>(&self, name: N) -> InterpretedValue

Retrieves the current interpreted value of a document attribute.

Each document holds a set of name-value pairs called document attributes. These attributes provide a means of configuring the AsciiDoc processor, declaring document metadata, and defining reusable content. This page introduces document attributes and answers some questions about the terminology used when referring to them.

What are document attributes?

Document attributes are effectively document-scoped variables for the AsciiDoc language. The AsciiDoc language defines a set of built-in attributes, and also allows the author (or extensions) to define additional document attributes, which may replace built-in attributes when permitted.

Built-in attributes either provide access to read-only information about the document and its environment or allow the author to configure behavior of the AsciiDoc processor for a whole document or select regions. Built-in attributes are effectively unordered. User-defined attribute serve as a powerful text replacement tool. User-defined attributes are stored in the order in which they are defined.

pub fn has_attribute<N: AsRef<str>>(&self, name: N) -> bool

Returns true if the parser has a document attribute by this name.

pub fn is_attribute_set<N: AsRef<str>>(&self, name: N) -> bool

Returns true if the parser has a document attribute by this name which has been set (i.e. is present and not unset).

pub fn with_intrinsic_attribute<N: AsRef<str>, V: AsRef<str>>( self, name: N, value: V, modification_context: ModificationContext, ) -> Self

Sets the value of an intrinsic attribute.

Intrinsic attributes are set automatically by the processor. These attributes provide information about the document being processed (e.g., docfile), the security mode under which the processor is running (e.g., safe-mode-name), and information about the user’s environment (e.g., user-home).

The modification_context establishes whether the value can be subsequently modified by the document header and/or in the document body.

Subsequent calls to this function or with_intrinsic_attribute_bool() are always permitted. The last such call for any given attribute name takes precendence.

pub fn with_intrinsic_attribute_bool<N: AsRef<str>>( self, name: N, value: bool, modification_context: ModificationContext, ) -> Self

Sets the value of an intrinsic attribute from a boolean flag.

A boolean true is interpreted as “set.” A boolean false is interpreted as “unset.”

Intrinsic attributes are set automatically by the processor. These attributes provide information about the document being processed (e.g., docfile), the security mode under which the processor is running (e.g., safe-mode-name), and information about the user’s environment (e.g., user-home).

The modification_context establishes whether the value can be subsequently modified by the document header and/or in the document body.

Subsequent calls to this function or with_intrinsic_attribute() are always permitted. The last such call for any given attribute name takes precendence.

pub fn with_inline_substitution_renderer<ISR: InlineSubstitutionRenderer + 'static>( self, renderer: ISR, ) -> Self

Replace the default InlineSubstitutionRenderer for this parser.

The default implementation of InlineSubstitutionRenderer that is provided is suitable for HTML5 rendering. If you are targeting a different back-end rendering, you will need to provide your own implementation and set it using this call before parsing.

pub fn with_primary_file_name<S: AsRef<str>>(self, name: S) -> Self

Sets the name of the primary file to be parsed when parse() is called.

This name will be used for any error messages detected in this file and also will be passed to IncludeFileHandler::resolve_target() as the source argument for any include:: file resolution requests from this file.

pub fn with_include_file_handler<IFH: IncludeFileHandler + 'static>( self, handler: IFH, ) -> Self

Sets the IncludeFileHandler for this parser.

The include file handler is responsible for resolving include:: directives encountered during preprocessing. If no handler is provided, include directives will be ignored.

Trait Implementations

impl Clone for Parser

fn clone(&self) -> Parser

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Parser

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Parser

fn default() -> Self

Returns the “default value” for a type.