shrimple_parser/lib.rs
1//! Zero-dependency library with no-std support for writing parsers in a concise functional style
2//! & with rich error-reporting.
3//!
4//! The library's structure can be represented as the trinity of
5//! - [`Input`]
6//! - [`Pattern`]
7//! All patterns live in the [`pattern`] module
8//! - [`Parser`]
9//! All parsers live in the [`parser`] module
10//!
11//! The basic form of a parser is
12//!
13//! ```rust,ignore
14//! use shrimple_parser::{Input, ParsingResult};
15//!
16//! fn foo<In: Input>(input: In) -> ParsingResult<In, Foo, FooParseError> { ... }
17//! ```
18//!
19//! If the parser is infallible, i.e. never returns an unrecoverable error, it's customary to make
20//! it generic over the reason type, to make combining it easier.
21//!
22//! ```rust,ignore
23//! fn foo<In: Input, Reason>(input: In) -> ParsingResult<In, Foo, Reason> { ... }
24//! ```
25//!
26//! Kinds of errors are distinguished via a user-defined `Reason` type, which signals what did
27//! a parser expect.
28//! A [`ParsingError`] can also have no reason, which will mean that the error is recoverable.
29//!
30//! The distinction between recoverable & fatal errors is important for parsers that need to try
31//! multiple options.
32//!
33//! Error reporting with precise location in the source is facilitated by
34//! constructing a [`FullParsingError`] with methods such as
35//! [`Parser::with_full_error`], [`ParsingError::with_src_loc`]
36
37#![cfg_attr(
38 feature = "nightly",
39 feature(unboxed_closures, fn_traits, tuple_trait, doc_cfg)
40)]
41
42mod error;
43mod input;
44mod loc;
45pub mod parser;
46pub mod pattern;
47pub mod tuple;
48pub mod utils;
49
50pub use {
51 error::{FullParsingError, ParsingError, ParsingResult},
52 input::Input,
53 loc::{FullLocation, Location},
54 parser::{MappingParser, Parser},
55 pattern::Pattern,
56};
57
58#[cfg(feature = "proc-macro2")]
59pub use loc::LineColumnToLocationError;