Crate granit_parser

Expand description

YAML 1.2 parser implementation in pure Rust.

granit-parser is a low-level event parser. It reads YAML input and yields a stream of Event values paired with their source Span. With the default comments feature, comments are emitted as Event::Comment. They are presentation metadata, not YAML data nodes, so consumers building YAML value trees should ignore them.

Add it to your project:

cargo add granit-parser

§Usage

use granit_parser::{Event, Parser, Placement};

let yaml = r#"# header
items: # inline
  - milk
  - bread
"#;
let mut comments = Vec::new();

for next in Parser::new_from_str(yaml) {
    let (event, span) = next?;
    if let Event::Comment(text, placement) = event {
        comments.push((
            text.into_owned(),
            placement,
            span.slice(yaml).unwrap().to_owned(),
        ));
    }
}

assert_eq!(
    comments,
    [
        (" header".to_owned(), Placement::Above, "# header".to_owned()),
        (" inline".to_owned(), Placement::Right, "# inline".to_owned()),
    ]
);

For comment events, the companion Span covers the whole source comment, including # and excluding the line break. With Parser::new_from_str, Span::slice returns that source comment text.

§Anchor and tag source metadata

Set Options::emit_anchor_events to receive Event::Anchor with the assigned ID and original name, without &. Its companion span covers the complete &name token. This event immediately follows the anchored scalar or collection start, before any collection children. It is presentation metadata, so Event::is_node returns false. Its source range precedes the node content even though the event follows the node. Emission defaults to false, leaving existing event streams unchanged.

The adjacency guarantee applies within each Parser. With ParserStack, consume pending anchor metadata before pushing another source if relying on adjacency in the combined stream.

Resolved Event::Alias events carry the target ID and a complete *name token span. An unresolved alias can instead be exposed through Options::emit_unresolved_aliases. Explicit tags remain on node events; Span::tag_span preserves their complete raw token, including verbatim notation and percent escapes that normalized tag helpers may not reproduce.

use std::collections::BTreeMap;
use granit_parser::{Event, Parser};

let yaml = "message: &msg !note hello\ncopy: *msg\nexample: \"&msg is just text\"\n";
let options = granit_parser::options! { emit_anchor_events: true };
let mut anchors = BTreeMap::new();
for result in Parser::new_from_str_with_options(yaml, options) {
    let (event, span) = result?;
    if let Some(tag_span) = span.tag_span() {
        assert_eq!(tag_span.slice(yaml), Some("!note"));
    }
    match event {
        Event::Anchor(id, name) => {
            assert_eq!(span.slice(yaml), Some("&msg"));
            anchors.insert(id, (name, span));
        }
        Event::Alias(id) => {
            let (name, definition_span) = &anchors[&id];
            assert_eq!(name, "msg");
            assert_eq!(definition_span.slice(yaml), Some("&msg"));
            assert_eq!(span.slice(yaml), Some("*msg"));
        }
        _ => {}
    }
}
assert_eq!(anchors.len(), 1); // The quoted text does not define an anchor.

§Limits

Options::strict_indentation enables strict YAML indentation for flow collections. It defaults to false for compatibility with PyYAML and ruamel.yaml, accepting under-indented flow entries and delimiters. Options also controls comment emission and limits on buffered comments, simple-key lookahead, directive retention, and flow- and block-collection nesting. With the comments feature, comment tokens and events are emitted by default; setting Options::emit_comments to false recognizes and validates comments without capturing their text or emitting them. The defaults allow 96 buffered comment events, 1024 characters of simple-key lookahead, 1024 bytes of retained directive data, 16 reserved-directive parameters, 255 nested flow collections, and 255 nested block collections. Existing constructors use these defaults. Without the comments feature, comment capture and emission are compiled out of scanners, parsers, and parser stacks. YAML comments are still skipped and validated. Options::emit_comments remains available and defaults to true with the feature enabled and false without it. Setting it to true has no effect without the feature. Parser::new_from_str_with_options, Parser::new_from_iter_with_options, Parser::new_from_fallible_iter_with_options, Parser::with_options, Scanner::with_options, and ParserStack::with_options accept customized options created with options!.

Tooling can set Options::emit_unresolved_aliases to true to receive Event::UnresolvedAlias nodes and continue structural parsing when an anchor is missing. These references remain invalid YAML and must be handled by the consumer. The option defaults to false, preserving the ErrorKind::UnknownAnchor error and termination.

§Features

Note: This crate’s MSRV is 1.81.0.

§`comments` (enabled by default)

Enables scanner comment tokens, parser comment events, and their capture, placement, buffering, and continuation state. Without it, scanners skip comments without retaining their text, and comment-specific state is compiled out. YAML comment syntax and source positions are still validated and tracked.

Comment, Placement, TokenType::Comment, Event::Comment, ErrorKind::TooManyComments, Options::max_buffered_comment_events, and Input::may_contain_comments are available only with this feature.

§`error_messages` (enabled by default)

Provides human-readable text through ErrorKind’s Display implementation and ScanError::info. Disabling this feature makes both render an empty string while retaining machine-readable error kinds and source markers.

§`std`

Retains the original std::io::Error inside InputIoError when constructed through InputIoError::from_io or its From<std::io::Error> implementation. Without this feature, InputIoError::from_message remains available for portable no_std error reporting.

§`debug_prints`

Enables the debug module and usage of debug prints in the scanner and the parser. Do not enable if you are consuming the crate rather than working on it as this can significantly decrease performance. Output remains opt-in behind a local compile-time toggle in src/debug.rs.

This feature does not raise the MSRV further.

This feature enables std and is not no_std compatible.

Re-exports§

pub use crate::input::BorrowedInput;
pub use crate::input::BufferedInput;
pub use crate::input::FallibleBufferedInput;
pub use crate::input::Input;

Modules§

input: Utilities to create a source of input to the parser.

Macros§

options: Construct Options from its defaults and a list of field assignments.

Structs§

Comment: YAML comment metadata captured from the source.
InputIoError: Details of an I/O failure reported by an input adapter.
Marker: A location in a YAML document.
Options: Options controlling parser and scanner behavior and resource usage.
Parser: A YAML parser.
ParserStack: A parser implementation that uses a stack for include-style parsing.
ReplayParser: A lightweight parser that replays a pre-collected event stream.
ScanError: An error that occurred while reading, scanning, or parsing YAML.
Scanner: The YAML scanner.
Span: A range of locations in a YAML document.
StrInput: A parser input backed by a &str.
Tag: A YAML tag.
Token: A scanner token.
YamlVersion: YAML version declared by a %YAML directive.

Enums§

ErrorKind: Machine-readable category for a ScanError.
Event: An event generated by the YAML parser.
Placement: A positional hint for a YAML source comment.
ScalarStyle: The source style used for a YAML scalar.
StructureStyle: The notation style used for a YAML sequence or mapping.
TokenType: The contents of a scanner token.
TryLoadError: Error returned by Parser::try_load and ParserTrait::try_load.

Traits§

EventReceiver: Trait to be implemented in order to use the low-level parsing API.
ParserTrait: Trait extracted from Parser to support mocking and alternative implementations.
SpannedEventReceiver: Trait to be implemented for using the low-level parsing API.
TryEventReceiver: Trait to be implemented for fallible event handling without source spans.
TrySpannedEventReceiver: Trait to be implemented for fallible event handling with source spans.

Type Aliases§

ParseResult: A convenience alias for a parser event result.