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. 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.

§Limits

To keep streaming parsing memory bounded, syntactically ambiguous collection-entry positions that require comment lookahead accept at most 32 consecutive comments before the following node is resolved. Longer runs return a ScanError instead of being buffered without bound.

§Features

Note: This crate’s MSRV is 1.81.0.

§`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.

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.
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.