Struct Parser 

pub struct Parser { /* 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.

Implementations

impl Parser

pub fn new() -> Self

Creates a new Parser with the default configuration.

This is equivalent to Parser::default() and is provided for discoverability. Configure the parser by chaining the with_* builder methods, then call parse().

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() after this call returns.

Reusing a Parser across documents

A single Parser may be reused to parse many documents (in a loop, for example). Each parse begins from the Parser’s configured baseline – the attributes established through the builder API (e.g. with_intrinsic_attribute()) – with the document attributes discovered while parsing the previous document cleared. Header/body assignments (:foo: bar) therefore do not leak from one document into the next, so output does not depend on parse order. (Attributes discovered by a parse remain inspectable per the paragraph above only until the next parse, which clears them back to the baseline.) Reconfiguring the Parser with a builder method between parses updates that baseline for all subsequent parses.

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 parse_deferred(&mut self, source: &str) -> Document<'static>

Parse a UTF-8 string as an AsciiDoc document, leaving cross-references unresolved.

This behaves like parse(), except it does not resolve cross-references (<<id>>, xref:id[…]). The returned Document carries its references in a deferred state; resolve them later with Document::resolve_references.

This is the entry point for multi-document workflows (e.g. Antora-style site generation): parse every document with this method, build a combined index from each document’s catalog(), then resolve each document against that index. This crate does not merge catalogs itself.

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_silent<N: AsRef<str>, V: AsRef<str>>( self, name: N, value: V, modification_context: ModificationContext, ) -> Self

Sets the value of an intrinsic attribute, rejecting any disallowed subsequent write silently.

This behaves exactly like with_intrinsic_attribute() except that a document header or body assignment that the modification_context does not permit is dropped with no AttributeValueIsLocked warning, instead of recording one. The rejected write is otherwise handled identically (the value is left unchanged).

This reproduces Asciidoctor’s silent safe-mode attribute restrictions: under SERVER/SECURE, a document assignment of a restricted conversion attribute (backend, doctype, docinfo, source-highlighter) is simply dropped, with no diagnostic. Seed such an attribute as an ApiOnly silent intrinsic to lock it against document assignment without warning.

Subsequent calls to this function or the other with_intrinsic_attribute variants are always permitted. The last such call for any given attribute name takes precedence.

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_intrinsic_attribute_bool_silent<N: AsRef<str>>( self, name: N, value: bool, modification_context: ModificationContext, ) -> Self

Sets the value of an intrinsic attribute from a boolean flag, rejecting any disallowed subsequent write silently.

This behaves exactly like with_intrinsic_attribute_bool() except that a document header or body assignment that the modification_context does not permit is dropped with no AttributeValueIsLocked warning, instead of recording one. See with_intrinsic_attribute_silent() for the motivating use case (Asciidoctor’s silent safe-mode attribute restrictions).

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

Subsequent calls to this function or the other with_intrinsic_attribute variants are always permitted. The last such call for any given attribute name takes precedence.

pub fn with_reference_time(self, reference_time: ReferenceTime) -> Self

Pins the reference time (the value of “now”) used to compute the time-dependent document attributes, for reproducible output.

AsciiDoc derives localdate, localtime, localdatetime, and localyear from the current wall-clock time, and docdate, doctime, docdatetime, and docyear from the source file’s modification time (falling back to “now” when no modification time is known). Because those values change from run to run, any output that embeds them is not reproducible. Supplying a ReferenceTime pins “now” to a fixed instant so the computed attributes are stable.

This is the API counterpart of the SOURCE_DATE_EPOCH environment variable; a value set here takes precedence over that variable. To pin only the source-modification time that drives the doc* attributes (leaving local* on the real clock), use with_input_mtime instead; an with_input_mtime value takes precedence over this one for the doc* attributes.

A value set via the document header or body (e.g. an explicit :docdate:) still wins over the computed default.

pub fn with_input_mtime(self, input_mtime: ReferenceTime) -> Self

Pins the modification time of the source document, which drives the docdate, doctime, docdatetime, and docyear attributes.

This mirrors Asciidoctor’s input_mtime option: the local* attributes continue to reflect “now” (the real clock, a with_reference_time value, or SOURCE_DATE_EPOCH), while the doc* attributes reflect the supplied source modification time. A value set here takes precedence over a with_reference_time value for the doc* attributes.

A value set via the document header or body (e.g. an explicit :docdate:) still wins over the computed default.

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.

pub fn with_docinfo_file_handler<DFH: DocinfoFileHandler + 'static>( self, handler: DFH, ) -> Self

Sets the DocinfoFileHandler for this parser.

The docinfo file handler is responsible for providing the content of docinfo files requested while resolving a document’s docinfo (see the docinfo attribute). If no handler is provided, no docinfo content is resolved and Document::docinfo returns an empty string for every location.

pub fn with_svg_file_handler<SFH: SvgFileHandler + 'static>( self, handler: SFH, ) -> Self

Sets the SvgFileHandler for this parser.

The SVG file handler is responsible for providing the raw contents of an SVG file requested by an inline image with the inline option (e.g. image:diagram.svg[opts=inline]). If no handler is provided, inline SVG images fall back to rendering their alt text.

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

Sets the ImageFileHandler for this parser.

The image file handler is responsible for providing the raw bytes of an image that must be embedded as a data: URI – i.e. when the data-uri document attribute is set and the safe mode is below SafeMode::Secure. If no handler is provided (or it cannot find the file), such images fall back to an ordinary web path, exactly as if data-uri were not set.

pub fn with_path_resolver<PR: PathResolver + 'static>( self, path_resolver: PR, ) -> Self

Sets the PathResolver for this parser.

The path resolver turns an asset target (an image src, a stylesheet href, and so on) into the clean, resolved path that appears in the rendered output. The default is DefaultPathResolver, which mirrors Ruby Asciidoctor. A host that needs custom path or URL rewriting – a virtual filesystem, a content root, URL slugs – can supply its own implementation here.

pub fn with_catalog_assets(self, catalog_assets: bool) -> Self

Enables or disables cataloging of referenced image assets.

When enabled (Asciidoctor’s catalog_assets API option), each image referenced by an image:/image:: macro is recorded in the document catalog and can be retrieved afterward via Catalog::images. The default is disabled, in which case no image references are recorded.

pub fn with_safe_mode(self, safe: SafeMode) -> Self

Sets the SafeMode under which the document is parsed and rendered.

The default is SafeMode::Secure, the most conservative setting. Relaxing the safe mode enables security-sensitive rendering behavior, such as rendering an interactive SVG image as an <object> element.

pub fn safe_mode(&self) -> SafeMode

Returns the SafeMode under which this parser operates.

pub fn image_file_handler(&self) -> Option<&dyn ImageFileHandler>

Returns the ImageFileHandler registered on this parser, if any.

A custom InlineSubstitutionRenderer that resolves image URIs itself (rather than inheriting image_uri’s default data-uri embedding) can use this to read an image’s bytes through the same handler the built-in HTML renderer uses. Returns None when no handler was registered via with_image_file_handler, in which case there is no way to embed images and a web path should be used instead.

pub fn svg_file_handler(&self) -> Option<&dyn SvgFileHandler>

Returns the SvgFileHandler registered on this parser, if any.

A custom InlineSubstitutionRenderer that renders inline SVG images itself (rather than inheriting render_image’s opts=inline handling) can use this to read an SVG’s contents through the same handler the built-in HTML renderer uses. Returns None when no handler was registered via with_svg_file_handler, in which case inline SVG contents are unavailable and the alt text should be used instead.

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.