chumsky_branch/lib.rs
1#![allow(clippy::tabs_in_doc_comments)]
2#![warn(rust_2018_idioms, unreachable_pub)]
3#![forbid(elided_lifetimes_in_paths, unsafe_code)]
4
5//! This crate defines three parsing combinators for the [chumsky parsing library](chumsky):
6//!
7//! - [`not_starting_with`]: This combinator takes a list of patterns, and
8//! matches the shortest string from the input that diverges from all
9//! patterns.
10//! - [`not_containing`]: This combinator takes a list of patterns, and
11//! any string that does not contain any of the patterns.
12//! - [`branch`]: This combinator allows branching into a parser. Each
13//! branch defines two parsers. When the first parser matches, it
14//! chooses that branch and that branch only, even if the second parser
15//! fails. The second parser is then used to produce the output type.
16//! You can combine as many branches as you want (similar to `if else`).
17//! Then, you have to define an else branch which just takes a `String`
18//! and needs to produce output from that. Useful if you want to parse
19//! verbatim input plus some syntax.
20//!
21//! # Example
22//!
23//! ```rust
24//! use chumsky::prelude::*;
25//! use chumsky_branch::prelude::*;
26//!
27//! #[derive(Debug, Eq, PartialEq)]
28//! enum Token {
29//! Placeholder(String),
30//! Comment(String),
31//! Verbatim(String)
32//! }
33//!
34//! impl Token {
35//! fn lexer() -> impl Parser<char, Self, Error = Simple<char>> {
36//! branch(
37//! "{{",
38//! text::ident().then_ignore(just("}}")).map(Self::Placeholder)
39//! )
40//! .or_branch(
41//! "/*",
42//! not_containing(["*/"])
43//! .then_ignore(just("*/"))
44//! .map(Self::Comment)
45//! )
46//! .or_else(Self::Verbatim)
47//! }
48//! }
49//!
50//! fn lexer() -> impl Parser<char, Vec<Token>, Error = Simple<char>> {
51//! Token::lexer().repeated().then_ignore(end())
52//! }
53//!
54//! let input = "/* Greet the user */Hello {{name}}!";
55//! assert_eq!(&lexer().parse(input).unwrap(), &[
56//! Token::Comment(" Greet the user ".to_owned()),
57//! Token::Verbatim("Hello ".to_owned()),
58//! Token::Placeholder("name".to_owned()),
59//! Token::Verbatim("!".to_owned())
60//! ]);
61//! ```
62
63#[cfg(test)]
64macro_rules! assert_matches {
65 ($expr:expr, $pat:pat) => {
66 let expr = $expr;
67 assert!(
68 matches!(expr, $pat),
69 "Assertion failed: expected {} to match {}, but found {:?}",
70 stringify!($expr),
71 stringify!($pat),
72 expr
73 );
74 };
75}
76
77mod branch;
78mod not_containing;
79mod not_starting_with;
80
81pub use branch::{branch, Branch};
82pub use not_containing::not_containing;
83pub use not_starting_with::not_starting_with;
84
85pub mod prelude {
86 pub use crate::{
87 branch::branch, not_containing::not_containing,
88 not_starting_with::not_starting_with
89 };
90}