winnow/macros/
dispatch.rs

Help
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/// use winnow::prelude::*;
27/// use winnow::combinator::dispatch;
28/// # use winnow::token::take;
29/// # use winnow::token::take_while;
30/// # use winnow::combinator::fail;
31///
32/// fn integer(input: &mut &str) -> ModalResult<u64> {
33///     dispatch! {take(2usize);
34///         "0b" => take_while(1.., '0'..='1').try_map(|s| u64::from_str_radix(s, 2)),
35///         "0o" => take_while(1.., '0'..='7').try_map(|s| u64::from_str_radix(s, 8)),
36///         "0d" => take_while(1.., '0'..='9').try_map(|s| u64::from_str_radix(s, 10)),
37///         "0x" => take_while(1.., ('0'..='9', 'a'..='f', 'A'..='F')).try_map(|s| u64::from_str_radix(s, 16)),
38///         _ => fail::<_, u64, _>,
39///     }
40///     .parse_next(input)
41/// }
42///
43/// assert_eq!(integer.parse_peek("0x100 Hello"), Ok((" Hello", 0x100)));
44/// ```
45///
46/// ```rust
47/// use winnow::prelude::*;
48/// use winnow::combinator::dispatch;
49/// # use winnow::token::any;
50/// # use winnow::combinator::preceded;
51/// # use winnow::combinator::empty;
52/// # use winnow::combinator::fail;
53///
54/// fn escaped(input: &mut &str) -> ModalResult<char> {
55///     preceded('\\', escape_seq_char).parse_next(input)
56/// }
57///
58/// fn escape_seq_char(input: &mut &str) -> ModalResult<char> {
59///     dispatch! {any;
60///         'b' => empty.value('\u{8}'),
61///         'f' => empty.value('\u{c}'),
62///         'n' => empty.value('\n'),
63///         'r' => empty.value('\r'),
64///         't' => empty.value('\t'),
65///         '\\' => empty.value('\\'),
66///         '"' => empty.value('"'),
67///         _ => fail::<_, char, _>,
68///     }
69///     .parse_next(input)
70/// }
71///
72/// assert_eq!(escaped.parse_peek("\\nHello"), Ok(("Hello", '\n')));
73/// ```
74#[macro_export]
75#[doc(hidden)] // forced to be visible in intended location
76macro_rules! dispatch {
77    (
78        $scrutinee_parser:expr;
79        $( $arm_pat:pat $(if $arm_pred:expr)? => $arm_parser: expr ),+ $(,)?
80    ) => {
81        $crate::combinator::trace("dispatch", move |i: &mut _|
82        {
83            use $crate::Parser;
84            let initial = $scrutinee_parser.parse_next(i)?;
85            match initial {
86                $(
87                    $arm_pat $(if $arm_pred)? => $arm_parser.parse_next(i),
88                )*
89            }
90        })
91    }
92}
winnow/macros/dispatch.rs

winnow/macros/
dispatch.rs
