winnow/macros/
dispatch.rs

1/// `match` for parsers
2///
3/// While `match` works by accepting a value and returning values:
4/// ```rust,ignore
5/// let result_value = match scrutinee_value {
6///     ArmPattern => arm_value,
7/// };
8/// ```
9/// `dispatch!` composes parsers:
10/// ```rust,ignore
11/// let result_parser = dispatch!{scrutinee_parser;
12///     ArmPattern => arm_parser,
13/// };
14/// ```
15///
16/// This is useful when parsers have unique prefixes to test for.
17/// This offers better performance over
18/// [`alt`][crate::combinator::alt] though it might be at the cost of duplicating parts of your grammar
19/// if you needed to [`peek(input_parser)`][crate::combinator::peek] the scrutinee.
20///
21/// For tight control over the error in a catch-all case, use [`fail`][crate::combinator::fail].
22///
23/// # Example
24///
25/// ```rust
26/// # #[cfg(feature = "parser")] {
27/// use winnow::prelude::*;
28/// use winnow::combinator::dispatch;
29/// # use winnow::token::take;
30/// # use winnow::token::take_while;
31/// # use winnow::combinator::fail;
32///
33/// fn integer(input: &mut &str) -> ModalResult<u64> {
34///     dispatch! {take(2usize);
35///         "0b" => take_while(1.., '0'..='1').try_map(|s| u64::from_str_radix(s, 2)),
36///         "0o" => take_while(1.., '0'..='7').try_map(|s| u64::from_str_radix(s, 8)),
37///         "0d" => take_while(1.., '0'..='9').try_map(|s| u64::from_str_radix(s, 10)),
38///         "0x" => take_while(1.., ('0'..='9', 'a'..='f', 'A'..='F')).try_map(|s| u64::from_str_radix(s, 16)),
39///         _ => fail::<_, u64, _>,
40///     }
41///     .parse_next(input)
42/// }
43///
44/// assert_eq!(integer.parse_peek("0x100 Hello"), Ok((" Hello", 0x100)));
45/// # }
46/// ```
47///
48/// ```rust
49/// # #[cfg(feature = "parser")] {
50/// use winnow::prelude::*;
51/// use winnow::combinator::dispatch;
52/// # use winnow::token::any;
53/// # use winnow::combinator::preceded;
54/// # use winnow::combinator::empty;
55/// # use winnow::combinator::fail;
56///
57/// fn escaped(input: &mut &str) -> ModalResult<char> {
58///     preceded('\\', escape_seq_char).parse_next(input)
59/// }
60///
61/// fn escape_seq_char(input: &mut &str) -> ModalResult<char> {
62///     dispatch! {any;
63///         'b' => empty.value('\u{8}'),
64///         'f' => empty.value('\u{c}'),
65///         'n' => empty.value('\n'),
66///         'r' => empty.value('\r'),
67///         't' => empty.value('\t'),
68///         '\\' => empty.value('\\'),
69///         '"' => empty.value('"'),
70///         _ => fail::<_, char, _>,
71///     }
72///     .parse_next(input)
73/// }
74///
75/// assert_eq!(escaped.parse_peek("\\nHello"), Ok(("Hello", '\n')));
76/// # }
77/// ```
78#[macro_export]
79#[doc(hidden)] // forced to be visible in intended location
80macro_rules! dispatch {
81    (
82        $scrutinee_parser:expr;
83        $( $arm_pat:pat $(if $arm_pred:expr)? => $arm_parser: expr ),+ $(,)?
84    ) => {
85        $crate::combinator::trace("dispatch", move |i: &mut _|
86        {
87            use $crate::Parser;
88            let initial = $scrutinee_parser.parse_next(i)?;
89            match initial {
90                $(
91                    $arm_pat $(if $arm_pred)? => $arm_parser.parse_next(i),
92                )*
93            }
94        })
95    }
96}
winnow/macros/dispatch.rs

winnow/macros/
dispatch.rs
