Crate acdc_parser

Expand description

AsciiDoc parser.

Parse strings, files, readers, or inline fragments into an abstract syntax tree with source locations and recoverable warnings.

§Quick start

Use parse, parse_file, parse_from_reader, or parse_inline. Parser provides a builder-style alternative. ParseResult owns the AST and its backing text; keep the result alive while borrowing ParseResult::document.

use acdc_parser::{Options, parse};

let content = r#"= Document Title

This is a paragraph.

== Section Title

This is a subsection."#;

let parsed = parse(content, &Options::default())?;
let document = parsed.document();
assert!(!document.blocks.is_empty());

for warning in parsed.warnings() {
    eprintln!("{warning}");
}

§Cargo features

pre-spec-subs (default): experimental block subs= settings and their AST types. Without it, explicit settings report source recovery and use block defaults.
setext (off by default): legacy underlined headings, enabled through OptionsBuilder::with_setext() when the feature is compiled.
network (off by default): HTTP(S) includes, subject to safe mode and caller permission.

The parser uses the draft AsciiDoc specification and Asciidoctor as references; it does not claim complete conformance. A successful parse may contain recovered content. Check ParseResult::source_recovery when an application requires complete input, and ParseResult::warnings for all collected diagnostics.

§Checklist markers

acdc treats [X] as a checked list marker, alongside [x] and [*]. Asciidoctor leaves [X] in the item text. This is an intentional acdc extension.

§Include loading

Parsing defaults to SafeMode::Secure. Include directives become links without reading their targets. Select a lower mode to enable include reads. Options::include_loader defaults to IncludeLoader::System, the filesystem and optional HTTP(S) loader. Use IncludeLoader::custom to supply sources from an editor or another store. In modes below Secure, IncludeLoader::Disabled preserves literal directives without reading targets. These settings apply to string, reader, and file input; a custom provider does not lower the safe mode or grant URI permission.

§Local include confinement

SafeMode::Safe and SafeMode::Server use the effective include base as their local boundary. Set it through OptionsBuilder::with_base_dir; file input otherwise uses the entry file’s directory, and string or reader input uses the current directory. Given an entry document at /workspace/docs/main.adoc:

../shared.adoc becomes /workspace/docs/shared.adoc and emits a warning;
/tmp/shared.adoc becomes /workspace/docs/tmp/shared.adoc and emits a warning;
a nested include from /workspace/docs/chapters/part.adoc still uses /workspace/docs as its boundary.

The check does not resolve symlinks. If /workspace/docs/linked.adoc points to /private/secret.adoc, including linked.adoc reads /private/secret.adoc. These path transformations match asciidoctor; they are not strict symlink containment.

§Remote includes

HTTP(S) includes need a safe mode below SafeMode::Secure and the caller’s allow-uri-read attribute. A document cannot grant itself this permission. IncludeLoader::System also needs the network feature. A custom IncludeSourceProvider can supply permitted URI content through another transport.

On bare WebAssembly targets such as wasm32-unknown-unknown, network does not provide an HTTP client. If the system loader attempts an HTTP(S) include, the parser reports a warning and leaves the directive unresolved. Fetch content in the host before parsing and supply it through a custom provider.

§Include source size limit

Each include can select up to 10 MiB of normalized UTF-8 text, including newlines. The parser checks this limit before and after indent=. Use lines=, tag=, or tags= to select a small part of a larger source. If the selected text exceeds the limit, parsing fails with Error::IncludeSourceTooLarge. Excess tag metadata causes Error::IncludeSelectionTooComplex.

All includes in one parse share a budget, with a default of 64 MiB. Each include counts its selected UTF-8 text after indent=, plus one byte for a separating newline if the text is not empty. This count precedes nested processing and removal of comments and inactive conditionals. Repeated includes count each time. Nested includes share the budget; their expanded output is not counted again in the parent. Exceeding the budget causes Error::IncludeExpansionTooLarge at the include directive. Set OptionsBuilder::with_max_total_include_bytes to change the budget in bytes. Zero permits only empty selections. Document attributes cannot change it. Safe-mode permissions and the per-include limit still apply.

A finite lines= selection stops at its highest requested line. Errors after that line do not affect the result. The parser removes trailing whitespace from each line independently. Full includes, open-ended ranges, and tag selections read to the end of the source.

The built-in HTTP(S) loader has a separate 10 MiB limit for bytes read after decompression. This includes bytes read ahead of the selection. When a finite line selection is complete, the loader closes the response without reading the rest.

These resource limits differ from asciidoctor. They do not limit scan time. They do not apply to the entry document.

§Include indentation

The indent attribute on an include accepts 0..=4096. Larger values return a located Error::IncludeIndentTooLarge before the target is read. This fixed safety limit is an intentional acdc security policy, not an AsciiDoc language requirement. It prevents one directive from requesting an unbounded indentation prefix and deliberately diverges from asciidoctor, which has no documented or implemented maximum.

§Table limits

Tables accept at most 100 logical columns and 1,000 rows, bounding an accepted table to 100,000 materialized cells. The column bound also applies to cols multipliers, cell duplication counts, and column spans; row spans are bounded by the row limit. Larger requests return a located Error::Parse.

These fixed internal safety limits cannot be changed through Options or document attributes. They intentionally diverge from asciidoctor, which has no equivalent table dimension cap.

Structs§

Admonition: An Admonition represents an admonition in a document.
Anchor: An Anchor represents an anchor in a document.
Attribution: An attribution in a blockquote (the author/source of the quote).
Audio: An Audio represents an audio block in a document.
Author: An Author represents the author of a document.
Autolink: An Autolink represents an inline autolink in a document.
BlockMetadata: A BlockMetadata represents the metadata of a block in a document.
Bold: A Bold represents a bold section of text in a document.
Button: A Button represents an inline button in a document.
CalloutList: A CalloutList represents a callout list in a document.
CalloutListItem: A CalloutListItem represents an item in a callout list.
CalloutRef: A CalloutRef represents a callout reference marker within verbatim content.
CiteTitle: A citation title in a blockquote (the title of the cited work).
ColumnFormat: Column format specification for table formatting
Comment: A comment in a document that produces no output.
CrossReference: A CrossReference represents an inline cross-reference (xref) in a document.
CurvedApostrophe: A CurvedApostrophe represents a curved apostrophe section of text in a document.
CurvedQuotation: A CurvedQuotation represents a curved quotation section of text in a document.
DelimitedBlock: A DelimitedBlock represents a delimited block in a document.
DescriptionList: A DescriptionList represents a description list in a document.
DescriptionListItem: An item in a description list (term + description).
DiscreteHeader: A DiscreteHeader represents a discrete header in a document.
Document: A Document represents the root of an AsciiDoc document.
DocumentAttribute: An accepted document-attribute assignment in the document body.
DocumentAttributeValue: A defined document attribute, including its retained text representation.
DocumentAttributes: Validated document attributes with universal defaults.
ElementAttributes: Element-level attributes (for blocks, sections, etc.).
Footnote: A Footnote represents an inline footnote in a document.
Header: A Header represents the header of a document.
Highlight: A Highlight represents a highlighted section of text in a document.
Icon: An Icon represents an inline icon in a document.
Image: An Image represents an image block in a document.
IncludeSource: An opened include source.
IncludeSourceError: Failure returned by an IncludeSourceProvider.
IndexTerm: An IndexTerm represents an index term in a document.
Italic: An Italic represents an italic section of text in a document.
Keyboard: A Keyboard represents an inline keyboard shortcut in a document.
LineBreak: A LineBreak represents a line break (inline).
Link: A Link represents an inline link in a document.
ListItem: A ListItem represents a list item in a document.
Location: A Location represents a location in a document.
Mailto: An Mailto represents an inline mailto: in a document.
Menu: A Menu represents an inline menu in a document.
Monospace: A Monospace represents a monospace section of text in a document.
Options
OptionsBuilder: Builder for Options that provides an API for configuration.
OrderedList: An OrderedList represents an ordered list in a document.
OwnedSource: Source text with no AST — returned by consumers (e.g. the LSP) when the input is available but parsing failed.
PageBreak: A PageBreak represents a page break in a document.
Paragraph: A Paragraph represents a paragraph in a document.
ParseInlineResult: Successful inline-only parse output: the inline-node slice plus the buffers it borrows from, plus any non-fatal warnings. Counterpart to ParseResult for the inline-only entry point.
ParseResult: Owns a parsed document, its backing text, and non-fatal warnings.
Parser: Type-based parser for AsciiDoc content.
Pass: A Pass represents a passthrough macro in a document.
Plain: Ordinary inline text that inherits processing from its enclosing block.
Position: A Position represents a human-readable position in a document — one ASG locationBoundary. For byte offsets, use Location.absolute_start / Location.absolute_end.
Raw: Inline passthrough text with its own substitution policy.
Reference: Reference metadata for a cross-reference target.
Section: A Section represents a section in a document.
SourceLocation: Source location information combining a file path with a Location span.
SourceUrl: A parsed URL that preserves the author’s original input for display.
StandaloneCurvedApostrophe: A StandaloneCurvedApostrophe represents a standalone curved apostrophe character.
Stem: A Stem represents an inline mathematical expression.
StemContent: Content of a stem block with math notation.
Subscript: A Subscript represents a subscript section of text in a document.
Superscript: A Superscript represents a superscript section of text in a document.
Table: A Table represents a table in a document.
TableColumn: A TableColumn represents a column/cell in a table row.
TableOfContents: A TableOfContents represents a table of contents block.
TablePresentation: Table decoration resolved from the attributes at the table’s source position.
TableRow: A row in a table, containing one or more columns (cells).
ThematicBreak: A ThematicBreak represents a thematic break in a document.
Title: A title in a document (section titles, block titles, document title, etc.).
TocEntry: A TocEntry represents a table of contents entry.
UnorderedList: A UnorderedList represents an unordered list in a document.
Url: An Url represents an inline URL in a document.
Verbatim: Text from a literal, listing, or source context.
Video: A Video represents a video block in a document.
Warning: A non-fatal condition detected during parsing.

Enums§

AdmonitionVariant: The variant/type of an admonition block.
AttributeValue: An AttributeValue represents the value of an attribute in a document.
Block: A Block represents a block in a document.
CalloutRefKind: The kind of callout reference marker (how it was expressed in the source).
Caption: The caption a titled block takes.
CaptionKind: A block category with its own caption attribute and counter.
ColumnStyle: Column content style
ColumnWidth: Column width specification
CommentKind: The syntactic form a Comment originated from.
DelimitedBlockType: The inner content type of a delimited block.
DocumentAttributeAssignment: An accepted set or unset document-attribute assignment.
Error
Form: The form of an inline formatting element (how it was expressed in the source)
HorizontalAlignment: Horizontal alignment for table cells
IncludeLoader: Selects how the parser loads include sources.
IncludeSourceErrorKind: Classification of a source-provider failure.
IncludeSourceTarget: A fully resolved include target presented to an IncludeSourceProvider.
IndexTermKind: The kind of index term, encoding both visibility and structure.
IndexTermRelationship: A relationship from an index entry to another index term.
InlineMacro: An inline macro - a functional element that produces inline content.
InlineNode: An InlineNode represents an inline node in a document.
ListItemCheckedStatus: A ListItemCheckedStatus represents the checked status of a list item.
PassthroughKind
SafeMode: Controls include access and exposure of local paths during parsing.
SectionKind: The structural category of a section.
Source: The source location for media content (images, audio, video).
StemNotation: Notation type for mathematical expressions.
Substitution: An AsciiDoc substitution or named substitution group.
SubstitutionOp: A substitution operation to apply to a default substitution list.
SubstitutionSpec: Specification for substitutions to apply to a block.
TableFrame: The outer border applied to a table.
TableGrid: The rules drawn between table cells.
TableStripes: The body rows that receive a background fill.
VerticalAlignment: Vertical alignment for table cells
WarningKind: Categorised non-fatal conditions.
XrefCaptionLabel: Selects the label used by an automatic cross-reference to a numbered caption.
XrefSignifier: The word that introduces a section number in an automatic cross-reference.
XrefStyle: The display style for an automatic cross-reference.

Constants§

HEADER: Default substitutions for header content.
ICON_SIZES
MAX_SECTION_LEVELS
MAX_TOC_LEVELS
NORMAL: Default substitutions for normal content (paragraphs, etc).
UNNUMBERED_SECTION_STYLES: Section styles that should not receive automatic numbering.
VERBATIM: Default substitutions for verbatim blocks (listing, literal).

Traits§

IncludeSourceProvider: Supplies bytes for include targets resolved by the parser.

Functions§

parse: Parse AsciiDoc content from a string.
parse_file: Parse AsciiDoc content from a file.
parse_from_reader: Parse AsciiDoc content from a reader.
parse_inline: Parse inline AsciiDoc content from a string.
parse_text_for_quotes: Parse text for inline formatting markup (bold, italic, monospace, etc.).
strip_quotes: Strip surrounding single or double quotes from a string.
substitute: Apply a sequence of substitutions to text.
substitute_attributes: Expand known attribute references once, leaving unresolved references unchanged.

Type Aliases§

AttributeName: An AttributeName represents the name of an attribute in a document.
Role
Subtitle