pub struct Parser<'p> { /* private fields */ }
Expand description
The Parser
struct and its related structs allow a caller to configure
how AsciiDoc parsing occurs and then to initiate the parsing process.
Implementations§
Source§impl<'p> Parser<'p>
impl<'p> Parser<'p>
Sourcepub fn parse<'src>(&self, source: &'src str) -> Document<'src>
pub fn parse<'src>(&self, source: &'src str) -> Document<'src>
Parse a UTF-8 string as an AsciiDoc document.
Note that the document references the underlying source string and necessarily has the same lifetime as the source.
The Document
data structure returned by this call and nearly all
data structures contained within it are gated by the lifetime of the
source
text passed in to this function. For that reason all of
those data structures are given the lifetime 'src
.
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.
§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.
Sourcepub fn attribute_value<N: AsRef<str>>(&self, name: N) -> InterpretedValue<'p>
pub fn attribute_value<N: AsRef<str>>(&self, name: N) -> InterpretedValue<'p>
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.
Sourcepub fn with_intrinsic_attribute<N: AsRef<str>, V: AsRef<str>>(
self,
name: N,
value: V,
modification_context: ModificationContext,
) -> Self
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.
Sourcepub fn with_intrinsic_attribute_bool<N: AsRef<str>>(
self,
name: N,
value: bool,
modification_context: ModificationContext,
) -> Self
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.