granit_parser/
lib.rs

1// Copyright 2015, Yuheng Chen.
2// Copyright 2023, Ethiraric.
3// See the LICENSE file at the top-level directory of this distribution.
4
5//! YAML 1.2 parser implementation in pure Rust.
6//!
7//! `granit-parser` is a low-level event parser. It reads YAML input and yields a stream of
8//! [`Event`] values paired with their source [`Span`].
9//! Comments are emitted as [`Event::Comment`]. They are presentation metadata, not YAML data
10//! nodes, so consumers building YAML value trees should ignore them.
11//!
12//! Add it to your project:
13//!
14//! ```sh
15//! cargo add granit-parser
16//! ```
17//!
18//! # Usage
19//!
20//! ```rust
21//! use granit_parser::{Event, Parser, Placement};
22//!
23//! # fn main() -> Result<(), granit_parser::ScanError> {
24//! let yaml = r#"# header
25//! items: # inline
26//!   - milk
27//!   - bread
28//! "#;
29//! let mut comments = Vec::new();
30//!
31//! for next in Parser::new_from_str(yaml) {
32//!     let (event, span) = next?;
33//!     if let Event::Comment(text, placement) = event {
34//!         comments.push((
35//!             text.into_owned(),
36//!             placement,
37//!             span.slice(yaml).unwrap().to_owned(),
38//!         ));
39//!     }
40//! }
41//!
42//! assert_eq!(
43//!     comments,
44//!     [
45//!         (" header".to_owned(), Placement::Above, "# header".to_owned()),
46//!         (" inline".to_owned(), Placement::Right, "# inline".to_owned()),
47//!     ]
48//! );
49//! # Ok(())
50//! # }
51//! ```
52//!
53//! For comment events, the companion [`Span`] covers the whole source comment, including `#` and
54//! excluding the line break. With [`Parser::new_from_str`], [`Span::slice`] returns that source
55//! comment text.
56//!
57//! # Limits
58//!
59//! [`Options`] controls comment emission and limits on buffered comments, simple-key lookahead,
60//! and flow-collection nesting. Comment tokens and events are emitted by default; setting
61//! [`Options::emit_comments`] to `false` recognizes and validates comments without capturing their
62//! text or emitting them. The defaults allow 96 buffered comment events, 1024 characters of
63//! simple-key lookahead, and 255 nested flow collections. Existing constructors use these
64//! defaults. [`Parser::new_from_str_with_options`], [`Parser::new_from_iter_with_options`],
65//! [`Parser::new_from_fallible_iter_with_options`], [`Parser::with_options`],
66//! [`Scanner::with_options`], and [`ParserStack::with_options`] accept customized options created
67//! with [`options!`].
68//!
69//! # Features
70//! **Note:** This crate's MSRV is `1.81.0`.
71//!
72//! #### `error_messages` (enabled by default)
73//! Provides human-readable text through [`ErrorKind`]'s `Display` implementation and
74//! [`ScanError::info`]. Disabling this feature makes both render an empty string while retaining
75//! machine-readable error kinds and source markers.
76//!
77//! #### `std`
78//! Retains the original `std::io::Error` inside [`InputIoError`] when constructed through
79//! `InputIoError::from_io` or its `From<std::io::Error>` implementation. Without this feature,
80//! [`InputIoError::from_message`] remains available for portable `no_std` error reporting.
81//!
82//! #### `debug_prints`
83//! Enables the `debug` module and usage of debug prints in the scanner and the parser. Do not
84//! enable if you are consuming the crate rather than working on it as this can significantly
85//! decrease performance. Output remains opt-in behind a local compile-time toggle in
86//! `src/debug.rs`.
87//!
88//! This feature does not raise the MSRV further.
89//!
90//! This feature enables `std` and is _not_ `no_std` compatible.
91
92#![forbid(unsafe_code)]
93#![warn(missing_docs, clippy::pedantic)]
94#![no_std]
95
96extern crate alloc;
97
98#[cfg(feature = "std")]
99extern crate std;
100
101mod char_traits;
102#[macro_use]
103mod debug;
104mod error;
105pub mod input;
106mod macros;
107mod options;
108mod parser;
109mod parser_stack;
110mod scanner;
111
112pub use crate::error::{ErrorKind, InputIoError, ScanError};
113pub use crate::input::{str::StrInput, BorrowedInput, BufferedInput, FallibleBufferedInput, Input};
114pub use crate::options::Options;
115pub use crate::parser::{
116    Event, EventReceiver, ParseResult, Parser, ParserTrait, SpannedEventReceiver, StructureStyle,
117    Tag, TryEventReceiver, TryLoadError, TrySpannedEventReceiver, YamlVersion,
118};
119pub use crate::parser_stack::{ParserStack, ReplayParser};
120pub use crate::scanner::{
121    Comment, Marker, Placement, ScalarStyle, Scanner, Span, Token, TokenType,
122};
granit_parser/lib.rs

granit_parser/
lib.rs
