utils/parser/
macros.rs

1/// Macro to define a parser which consumes a single byte and maps it using a lookup table.
2///
3/// This macro is a wrapper around [`parser::byte_lut`](crate::parser::byte_lut) to allow defining
4/// the lookup table using a match-like syntax. Each expression must be const and evaluate to a
5/// value of the same copy type.
6///
7/// # Examples
8/// ```
9/// # use utils::parser::{Parser, self};
10/// let parser = parser::byte_map!(
11///     b'#' => true,
12///     b'.' | b'S' => false,
13/// );
14/// assert_eq!(parser.parse(b"#.S##"), Ok((true, &b".S##"[..])));
15/// assert_eq!(parser.parse(b".S##"), Ok((false, &b"S##"[..])));
16/// assert_eq!(parser.parse(b"S##"), Ok((false, &b"##"[..])));
17///
18/// let (err, remaining) = parser.parse(b"abc").unwrap_err();
19/// assert_eq!(err.to_string(), "expected one of '#', '.', 'S'");
20/// assert_eq!(remaining, &b"abc"[..]);
21/// ```
22#[macro_export]
23macro_rules! parser_byte_map {
24    (
25        $($($l:literal)|+ => $e:expr),+$(,)?
26    ) => {{
27        $crate::parser::byte_lut(&const {
28            // Don't use a const item for the lut to avoid naming the value type
29            let mut lut = [None; 256];
30            $($(
31                assert!(lut[$l as usize].is_none(), "duplicate literal");
32                lut[$l as usize] = Some($e);
33            )+)+
34            lut
35        }, {
36            let mut set = 0u128;
37            $($(
38                let v: u8 = $l;
39                assert!(v < 128, "invalid ASCII");
40                set |= 1u128 << v;
41            )+)+
42            $crate::parser::ParseError::ExpectedOneOf($crate::ascii::AsciiSet::new(set))
43        })
44    }};
45}
46
47/// Macro to define a parser for one or more string literals, mapping the results.
48///
49/// This is a replacement for
50/// [`parser::one_of`](crate::parser::one_of())`(("a".map(|_| Enum::A), "b".map(|_| Enum::b)))`
51/// which produces more optimized assembly and is easier to read and write.
52///
53/// The string patterns are matched in the order provided, so strings should be ordered by length.
54///
55/// Using this makes [2017 day 11](../../year2017/struct.Day11.html), which parses a sequence of
56/// literals separated by commas, over 2x faster.
57///
58/// See also [`parser::parsable_enum!`](crate::parser::parsable_enum), which provides a macro to
59/// define an enum and literal parser together.
60///
61/// # Examples
62/// ```
63/// # use utils::parser::{Parser, self};
64/// #[derive(Debug, PartialEq)]
65/// enum Example {
66///     A,
67///     B,
68///     C,
69/// }
70///
71/// let parser = parser::literal_map!(
72///     "A" | "a" => Example::A,
73///     "B" => Example::B,
74///     "C" => Example::C,
75/// );
76/// assert_eq!(parser.parse(b"A"), Ok((Example::A, &b""[..])));
77/// assert_eq!(parser.parse(b"a"), Ok((Example::A, &b""[..])));
78/// assert_eq!(parser.parse(b"B"), Ok((Example::B, &b""[..])));
79/// assert_eq!(parser.parse(b"C"), Ok((Example::C, &b""[..])));
80/// assert!(parser.parse(b"D").is_err());
81/// ```
82#[macro_export]
83macro_rules! parser_literal_map {
84    (
85        $($($l:literal)|+ => $e:expr),+$(,)?
86    ) => {{
87        const fn coerce_to_parser<F: Fn(&[u8]) -> $crate::parser::ParseResult<'_, O>, O>(f: F) -> F { f }
88
89        coerce_to_parser(|input| {
90            $($(
91                if input.len() >= const { $l.len() } && const { $l.as_bytes() } == &input[..const { $l.len() }] {
92                    return Ok((($e), &input[const { $l.len() }..]));
93                }
94            )+)*
95
96            Err(($crate::parser_literal_map!(@error $($($l)+)+), input))
97        })
98    }};
99    (@error $first:literal $($l:literal)+) => {
100        $crate::parser::ParseError::Custom(concat!("expected one of '", $first, "'", $(", '", $l, "'",)+))
101    };
102    (@error $first:literal) => {
103        $crate::parser::ParseError::ExpectedLiteral($first)
104    };
105}
106
107/// Macro to define an enumerable enum that implements [`Parseable`](crate::parser::Parseable).
108///
109/// The parser is implemented using [`parser::literal_map!`](crate::parser::literal_map) and
110/// [`enumerable_enum!`](crate::enumerable_enum!).
111///
112/// # Examples
113/// ```
114/// # use utils::parser::{Parser, Parseable, self};
115/// parser::parsable_enum! {
116///     #[derive(Debug, PartialEq, Default)]
117///     enum Direction {
118///         #[default]
119///         "north" | "n" => North,
120///         "south" | "s" => South,
121///         "east" | "e" => East,
122///         "west" | "w" => West,
123///     }
124/// }
125///
126/// assert_eq!(Direction::PARSER.parse(b"north"), Ok((Direction::North, &b""[..])));
127/// assert_eq!(Direction::PARSER.parse(b"s"), Ok((Direction::South, &b""[..])));
128/// assert!(Direction::PARSER.parse(b"a").is_err());
129///
130/// assert_eq!(Direction::COUNT, 4);
131/// ```
132///
133/// With discriminant helpers (requires an explicit `#[repr(...)]` attribute first):
134/// ```
135/// # use utils::parser::{Parser, Parseable, self};
136/// parser::parsable_enum! {
137///     #[repr(u8)]
138///     #[derive(Debug, PartialEq)]
139///     enum Operation {
140///         "add" => Add,
141///         "mul" => Mul,
142///         "div" => Div,
143///         "mod" => Mod,
144///         "eql" => Eql,
145///     }
146/// }
147///
148/// assert_eq!(Operation::PARSER.parse(b"add5"), Ok((Operation::Add, &b"5"[..])));
149/// assert_eq!(Operation::PARSER.parse(b"eql"), Ok((Operation::Eql, &b""[..])));
150///
151/// assert_eq!(Operation::COUNT, 5);
152/// assert_eq!(Operation::checked_from_discriminant(2), Some(Operation::Div));
153/// ```
154#[macro_export]
155macro_rules! parser_parsable_enum {
156    (
157        $(#[$($enum_meta:tt)+])*
158        enum $name:ident {$(
159            $(#[$meta:meta])*
160            $($l:literal)|+ => $variant:ident $(= $value:expr)?,
161        )+}
162    ) => {
163        // Use tt for enum_meta to avoid the attributes being captured as opaque fragments, which
164        // is required for the correct enumerable_enum arm to be selected for repr enums.
165        $crate::enumerable_enum! {
166            $(#[$($enum_meta)+])*
167            enum $name {$(
168                $(#[$meta])*
169                $variant $(= $value)?,
170            )+}
171        }
172
173        impl $crate::parser::Parseable for $name {
174            type Parser = for<'a> fn(&'a [u8]) -> $crate::parser::ParseResult<'a, Self>;
175            const PARSER: Self::Parser = $crate::parser_literal_map!($(
176                $($l)|+ => Self::$variant,
177            )+);
178        }
179    };
180}
181
182/// Macro to define a custom parser using a `match` inspired parse tree syntax.
183///
184/// Each rule is made up of a list of chained parsers enclosed in brackets on the left-hand side.
185/// Parsers can be prefixed with an identifier followed by `@` to store the result of that parser in
186/// the supplied variable, similar to normal match patterns.
187///
188/// After the list of parsers, there is an arrow determining the functionality of the rule when the
189/// parsers match:
190/// - **Expression (`=>`)**: The expression on the right-hand is evaluated and returned.
191/// - **Fallible (`=?>`)**: Similar to Expression, but the right-hand side evaluates a result. If
192///   the expression evaluates to [`Ok`], the value contained inside is returned. Otherwise, the
193///   string contained inside the [`Err`] is handled as a custom [`ParseError`](super::ParseError),
194///   and parsing will continue with the following rule.
195/// - **Subtree (`=>>`)**: The right-hand side is a nested set of rules enclosed in braces.
196///
197/// If none of the rules match successfully, the error from the rule which parsed furthest into
198/// the input is returned.
199///
200/// # Examples
201/// ```
202/// # use utils::parser::{self, Parser};
203/// #
204/// #[derive(Debug, PartialEq)]
205/// enum Register {
206///     A, B, C
207/// }
208///
209/// #[derive(Debug, PartialEq)]
210/// enum Instruction {
211///     Add(Register, Register),
212///     AddConstant(Register, i32),
213///     Copy(Register, Register),
214///     Noop,
215/// }
216///
217/// let register = parser::literal_map!(
218///     "A" => Register::A, "B" => Register::B, "C" => Register::C,
219/// );
220///
221/// let instruction = parser::parse_tree!(
222///     ("add ", r @ register, ", ") =>> {
223///         (r2 @ register) => Instruction::Add(r, r2),
224///         (v @ parser::i32()) => Instruction::AddConstant(r, v),
225///     },
226///     ("copy ", r @ register, ", ", r2 @ register) =?> {
227///         if r == r2 {
228///             Err("cannot copy register to itself")
229///         } else {
230///             Ok(Instruction::Copy(r, r2))
231///         }
232///     },
233///     ("noop") => Instruction::Noop,
234/// );
235///
236/// assert_eq!(
237///     instruction.parse_complete("add A, B").unwrap(),
238///     Instruction::Add(Register::A, Register::B)
239/// );
240/// assert_eq!(
241///     instruction.parse_complete("add C, 100").unwrap(),
242///     Instruction::AddConstant(Register::C, 100)
243/// );
244/// assert_eq!(
245///     instruction.parse_complete("copy A, B").unwrap(),
246///     Instruction::Copy(Register::A, Register::B)
247/// );
248/// assert!(instruction
249///     .parse_complete("copy A, A")
250///     .is_err_and(|err| err.to_string().contains("cannot copy register to itself")));
251/// ```
252#[macro_export]
253macro_rules! parser_parse_tree {
254    (@rule $input:ident $furthest_err:ident $furthest_remaining:ident [$(,)?] @expr $rhs:expr) => {
255        return Ok(($rhs, $input));
256    };
257    (@rule $input:ident $furthest_err:ident $furthest_remaining:ident [$(,)?] @expr_res $rhs:expr) => {
258        match $rhs {
259            Ok(v) => return Ok((v, $input)),
260            Err(e) => {
261                if $input.len() < $furthest_remaining {
262                    $furthest_err = $crate::parser::ParseError::Custom(e);
263                    $furthest_remaining = $input.len();
264                }
265            }
266        };
267    };
268    (@rule $input:ident $furthest_err:ident $furthest_remaining:ident [$(,)?] @subtree $($rhs:tt)+) => {
269        $crate::parser_parse_tree!(@toplevel $input $furthest_err $furthest_remaining $($rhs)+);
270    };
271
272    (@rule $input:ident $furthest_err:ident $furthest_remaining:ident
273        [$n:ident @ $lhs:expr $(,$($tail:tt)*)?] $($rhs:tt)+
274    ) => {
275        match $crate::parser::Parser::parse(&($lhs), $input) {
276            Ok(($n, $input)) => {
277                $crate::parser_parse_tree!(@rule $input $furthest_err $furthest_remaining
278                    [$($($tail)*)?] $($rhs)+
279                );
280            },
281            Err((err, remaining)) => {
282                if remaining.len() < $furthest_remaining {
283                    $furthest_err = err;
284                    $furthest_remaining = remaining.len();
285                }
286            }
287        };
288    };
289    (@rule $input:ident $furthest_err:ident $furthest_remaining:ident
290        [$lhs:expr $(,$($tail:tt)*)?] $($rhs:tt)+
291    ) => {
292        match $crate::parser::Parser::parse(&($lhs), $input) {
293            Ok((_, $input)) => {
294                $crate::parser_parse_tree!(@rule $input $furthest_err $furthest_remaining
295                    [$($($tail)*)?] $($rhs)+
296                );
297            },
298            Err((err, remaining)) => {
299                if remaining.len() < $furthest_remaining {
300                    $furthest_err = err;
301                    $furthest_remaining = remaining.len();
302                }
303            }
304        };
305    };
306
307    (@toplevel $input:ident $furthest_err:ident $furthest_remaining:ident
308        ($($lhs:tt)+) => $rhs:expr $(, $($tail:tt)*)?
309    ) => {
310        $crate::parser_parse_tree!(@rule $input $furthest_err $furthest_remaining [$($lhs)+] @expr $rhs);
311        $($crate::parser_parse_tree!(@toplevel $input $furthest_err $furthest_remaining $($tail)*);)?
312    };
313    (@toplevel $input:ident $furthest_err:ident $furthest_remaining:ident
314        ($($lhs:tt)+) =?> $rhs:expr $(, $($tail:tt)*)?
315    ) => {
316        $crate::parser_parse_tree!(@rule $input $furthest_err $furthest_remaining [$($lhs)+] @expr_res $rhs);
317        $($crate::parser_parse_tree!(@toplevel $input $furthest_err $furthest_remaining $($tail)*);)?
318    };
319    (@toplevel $input:ident $furthest_err:ident $furthest_remaining:ident
320        ($($lhs:tt)+) =>> {$($rhs:tt)+} $(, $($tail:tt)*)?
321    ) => {
322        $crate::parser_parse_tree!(@rule $input $furthest_err $furthest_remaining [$($lhs)+] @subtree $($rhs)+);
323        $($crate::parser_parse_tree!(@toplevel $input $furthest_err $furthest_remaining $($tail)*);)?
324    };
325    (@toplevel $input:ident $furthest_err:ident $furthest_remaining:ident $(,)?) => {};
326
327    // Ensures this branch only matches inputs starting with (, giving each rule set a unique prefix
328    (($($first:tt)+) $($tail:tt)+) => {{
329        const fn coerce_to_parser<F: Fn(&[u8]) -> $crate::parser::ParseResult<'_, O>, O>(f: F) -> F { f }
330
331        coerce_to_parser(|input| {
332            let mut furthest_err = $crate::parser::ParseError::Custom("unreachable");
333            let mut furthest_remaining = usize::MAX;
334
335            $crate::parser_parse_tree!(@toplevel input furthest_err furthest_remaining ($($first)+) $($tail)+);
336
337            Err((furthest_err, &input[input.len() - furthest_remaining..]))
338        })
339    }};
340}
utils/parser/macros.rs

utils/parser/
macros.rs
