utils/parser/
base.rs

1use crate::input::InputError;
2use crate::parser::combinator::{
3    Commit, Map, MapResult, Optional, Or, RepeatArrayVec, RepeatN, RepeatVec, WithConsumed,
4    WithPrefix, WithSuffix,
5};
6use crate::parser::error::{ParseError, WithErrorMsg};
7use crate::parser::iterator::{ParserIterator, ParserMatchesIterator};
8use crate::parser::simple::{Constant, Eol};
9use crate::parser::then::{Then, Then2, Unimplemented};
10
11/// [`Result`] type returned by [`Parser::parse_ctx`].
12pub type ParserResult<'i, T> = Result<(T, &'i [u8]), ErrToken>;
13
14/// Trait implemented by all parsers.
15///
16/// Unlike [`Leaf`](super::Leaf) parsers, parsers implementing this trait may handle branching and
17/// error recovery, including backtracking and commit.
18///
19/// Every [`Leaf`](super::Leaf) parser is also a [`Parser`] via a blanket implementation.
20#[must_use]
21pub trait Parser<'i>: Sized {
22    /// Type of the value produced by [`parse`](Self::parse_ctx) when successful.
23    type Output;
24
25    /// Type of the chained parser returned by [`then`](Self::then).
26    ///
27    /// This is used to allow multiple [`then`](Self::then) calls to extend one tuple, instead of
28    /// nesting tuples inside each other.
29    type Then<T: Parser<'i>>: Then<'i, Self, T>;
30
31    /// Parse the provided bytes.
32    ///
33    /// Returns a tuple of the successfully parsed [`Output`](Self::Output) value and the
34    /// remaining bytes, or an [`ErrToken`] representing that an error was pushed into the provided
35    /// [`ParseState`].
36    fn parse_ctx(
37        &self,
38        input: &'i [u8],
39        state: &mut ParseState<'i>,
40        commit: &mut bool,
41        tail: bool,
42    ) -> ParserResult<'i, Self::Output>;
43
44    // Provided methods
45
46    /// Sequence another parser after this one.
47    ///
48    /// # Examples
49    /// ```
50    /// # use utils::parser::{self, ParseState, Parser};
51    /// assert!(matches!(
52    ///     parser::i32()
53    ///         .then(parser::i32())
54    ///         .parse_complete("123-123"),
55    ///     Ok((123, -123)),
56    /// ));
57    /// ```
58    #[inline]
59    fn then<T: Parser<'i>>(self, next: T) -> Self::Then<T> {
60        Then::then(self, next)
61    }
62
63    /// Attempt to parse using this parser, followed by the provided parser.
64    ///
65    /// The second parser will not be tried if the first parser commits.
66    ///
67    /// See also [`parser::one_of`](super::one_of()).
68    ///
69    /// # Examples
70    /// ```
71    /// # use utils::parser::{self, ParseError, Parser};
72    /// let parser = parser::u8()
73    ///     .map(|x| u32::from(x) * 1001001)
74    ///     .or(parser::u32());
75    /// assert!(matches!(
76    ///     parser.parse_complete("123"),
77    ///     Ok(123123123)
78    /// ));
79    /// assert!(matches!(
80    ///     parser.parse_complete("1000"),
81    ///     Ok(1000)
82    /// ));
83    /// ```
84    #[inline]
85    fn or<T: Parser<'i, Output = Self::Output>>(self, alternative: T) -> Or<Self, T> {
86        Or {
87            first: self,
88            second: alternative,
89        }
90    }
91
92    /// Prevent backtracking past this parser if it succeeds and consumes input.
93    ///
94    /// After committing, any later errors within the current alternative are treated as fatal,
95    /// preventing the current innermost alternative parser from trying other branches.
96    ///
97    /// This can be used to help ensure error messages are clear in cases where returning the
98    /// furthest error from another branch would be misleading.
99    /// It can also improve performance in error cases.
100    ///
101    /// If this parser is not inside an alternative, this has no effect.
102    ///
103    /// The following alternative parsers honor commit to prevent backtracking:
104    /// - [`Parser::optional`]
105    /// - [`Parser::or`]
106    /// - [`Parser::repeat_arrayvec`]
107    /// - [`Parser::repeat`]
108    /// - [`parser::one_of`](super::one_of())
109    /// - [`parser::parse_tree`](super::parse_tree)
110    #[inline]
111    fn commit(self) -> Commit<Self> {
112        Commit { parser: self }
113    }
114
115    /// Map the output of this parser using the supplied function.
116    ///
117    /// # Examples
118    /// ```
119    /// # use utils::parser::{self, Parser};
120    /// assert!(matches!(
121    ///     parser::u32()
122    ///         .map(|x| x * 2)
123    ///         .parse_complete("123"),
124    ///     Ok(246)
125    /// ));
126    /// ```
127    ///
128    /// Closure that returns a value borrowing from both its input and an outer variable:
129    /// ```
130    /// # use utils::parser::{self, Parser};
131    /// let my_string = String::from("123");
132    /// let my_vec = vec![4, 5, 6];
133    /// assert!(matches!(
134    ///     parser::take_while(u8::is_ascii_digit)
135    ///         .map(|x| (x, my_vec.as_slice()))
136    ///         .parse_complete(&my_string),
137    ///     Ok((&[b'1', b'2', b'3'], &[4, 5, 6]))
138    /// ));
139    /// ```
140    #[inline]
141    fn map<O, F: Fn(Self::Output) -> O>(self, f: F) -> Map<Self, F> {
142        Map {
143            parser: self,
144            map_fn: f,
145        }
146    }
147
148    /// Map the output of this parser using the supplied fallible function.
149    ///
150    /// Errors must be `&'static str`, which will be mapped to [`ParseError::Custom`].
151    ///
152    /// # Examples
153    /// ```
154    /// # use utils::parser::{self, ParseError, Parser};
155    /// let parser = parser::u8()
156    ///     .map_res(|x| x.checked_mul(2).ok_or("input too large"));
157    /// assert!(matches!(
158    ///     parser.parse_complete("123"),
159    ///     Ok(246)
160    /// ));
161    /// assert_eq!(
162    ///     parser.parse_complete("200").unwrap_err().into_source(),
163    ///     ParseError::Custom("input too large"),
164    /// );
165    /// ```
166    ///
167    /// Closure that returns a value borrowing from both its input and an outer variable:
168    /// ```
169    /// # use utils::parser::{self, Parser};
170    /// let my_string = String::from("123");
171    /// let my_vec = vec![4, 5, 6];
172    /// assert!(matches!(
173    ///     parser::take_while(u8::is_ascii_digit)
174    ///         .map_res(|x| {
175    ///             if x.len() < 10 {
176    ///                 Ok((x, my_vec.as_slice()))
177    ///             } else {
178    ///                 Err("expected fewer than 10 digits")
179    ///             }
180    ///         })
181    ///         .parse_complete(&my_string),
182    ///     Ok((&[b'1', b'2', b'3'], &[4, 5, 6]))
183    /// ));
184    /// ```
185    #[inline]
186    fn map_res<O, F: Fn(Self::Output) -> Result<O, &'static str>>(
187        self,
188        f: F,
189    ) -> MapResult<Self, F> {
190        MapResult {
191            parser: self,
192            map_fn: f,
193        }
194    }
195
196    /// Wrap [`Output`](Self::Output) in [`Option`], returning [`None`] on error unless the parser
197    /// commits.
198    ///
199    /// # Examples
200    /// ```
201    /// # use utils::parser::{self, ParseError, Parser};
202    /// let parser = parser::u32()
203    ///     .optional();
204    /// assert!(matches!(
205    ///     parser.parse_first("123"),
206    ///     Ok((Some(123), &[]))
207    /// ));
208    /// assert!(matches!(
209    ///     parser.parse_first("abc"),
210    ///     Ok((None, &[b'a', b'b', b'c']))
211    /// ));
212    /// ```
213    #[inline]
214    fn optional(self) -> Optional<Self> {
215        Optional { parser: self }
216    }
217
218    /// Repeat this parser `N` times, returning an [`array`].
219    ///
220    /// If the number of items is variable use [`repeat_arrayvec`](Self::repeat_arrayvec) or
221    /// [`repeat`](Self::repeat).
222    ///
223    /// # Examples
224    /// ```
225    /// # use utils::parser::{self, Parser};
226    /// assert!(matches!(
227    ///     parser::u32()
228    ///         .repeat_n(",") // N = 3 is inferred
229    ///         .parse_complete("12,34,56"),
230    ///     Ok([12, 34, 56])
231    /// ));
232    /// ```
233    #[inline]
234    fn repeat_n<const N: usize, S: Parser<'i>>(self, separator: S) -> RepeatN<N, Self, S>
235    where
236        Self::Output: Copy + Default,
237    {
238        RepeatN {
239            parser: self,
240            separator,
241        }
242    }
243
244    /// Repeat this parser while it matches, returning a [`ArrayVec`](crate::array::ArrayVec).
245    ///
246    /// This parser can parse up to `N` items. If more items match, it will return an error.
247    ///
248    /// Returns error if the item parser commits and fails, or if the separator commits and then
249    /// either it or the next item fails.
250    ///
251    /// See [`repeat`](Self::repeat) if the upper bound is large or not known, and
252    /// [`repeat_n`](Self::repeat_n) if the number of items is consistent.
253    ///
254    /// # Examples
255    /// ```
256    /// # use utils::array::ArrayVec;
257    /// use utils::parser::{self, Parser};
258    /// let parser = parser::u32()
259    ///     .repeat_arrayvec::<5, _>(",", 3);
260    /// assert_eq!(
261    ///     parser.parse_first("12,34,56,78").unwrap(),
262    ///     (ArrayVec::from_slice(&[12, 34, 56, 78]).unwrap(), &b""[..])
263    /// );
264    /// assert_eq!(
265    ///     parser.parse_first("12,34,56,abc").unwrap(),
266    ///     (ArrayVec::from_slice(&[12, 34, 56]).unwrap(), &b",abc"[..])
267    /// );
268    /// assert!(parser.parse_first("12,34").is_err());
269    /// ```
270    #[inline]
271    fn repeat_arrayvec<const N: usize, S: Parser<'i>>(
272        self,
273        separator: S,
274        min_elements: usize,
275    ) -> RepeatArrayVec<N, Self, S>
276    where
277        Self::Output: Copy + Default,
278    {
279        RepeatArrayVec {
280            parser: self,
281            separator,
282            min_elements,
283        }
284    }
285
286    /// Repeat this parser while it matches, returning a [`Vec`].
287    ///
288    /// Returns error if the item parser commits and fails, or if the separator commits and then
289    /// either it or the next item fails.
290    ///
291    /// To avoid allocating, prefer [`repeat_n`](Self::repeat_n) if the number of items is
292    /// consistent and known in advance, or [`repeat_arrayvec`](Self::repeat_arrayvec) if the number
293    /// of items is variable but has a known upper bound.
294    ///
295    /// # Examples
296    /// ```
297    /// # use utils::parser::{self, Parser};
298    /// let parser = parser::u32()
299    ///     .repeat(",", 3);
300    /// assert_eq!(parser.parse_first("12,34,56,78").unwrap(), (vec![12, 34, 56, 78], &b""[..]));
301    /// assert_eq!(parser.parse_first("12,34,56,abc").unwrap(), (vec![12, 34, 56], &b",abc"[..]));
302    /// assert!(parser.parse_first("12,34").is_err());
303    /// ```
304    #[inline]
305    fn repeat<S: Parser<'i>>(self, separator: S, min_elements: usize) -> RepeatVec<Self, S> {
306        RepeatVec {
307            parser: self,
308            separator,
309            min_elements,
310        }
311    }
312
313    /// Return the output of this parser as well as the bytes consumed.
314    ///
315    /// This can be used to map any errors that occur while processing the parsed input back to the
316    /// problematic item's position in the input.
317    ///
318    /// # Examples
319    /// ```
320    /// # use utils::parser::{self, Parser};
321    /// assert_eq!(
322    ///     parser::u32().with_consumed().parse_first("012,345,678").unwrap(),
323    ///     ((12, &b"012"[..]), &b",345,678"[..])
324    /// );
325    /// ```
326    #[inline]
327    fn with_consumed(self) -> WithConsumed<Self> {
328        WithConsumed { parser: self }
329    }
330
331    /// Parse a prefix (normally a string literal) before this parser.
332    ///
333    /// The result of the prefix parser is discarded.
334    ///
335    /// # Examples
336    /// ```
337    /// # use utils::parser::{self, Parser};
338    /// assert_eq!(
339    ///     parser::u32()
340    ///         .with_prefix("abc")
341    ///         .parse_complete("abc123")
342    ///         .unwrap(),
343    ///     123,
344    /// );
345    /// ```
346    #[inline]
347    fn with_prefix<T: Parser<'i>>(self, prefix: T) -> WithPrefix<Self, T> {
348        WithPrefix {
349            parser: self,
350            prefix,
351        }
352    }
353
354    /// Parse a suffix (normally a string literal) after this parser.
355    ///
356    /// The result of the suffix parser is discarded.
357    ///
358    /// # Examples
359    /// ```
360    /// # use utils::parser::{self, Parser};
361    /// assert_eq!(
362    ///     parser::u32()
363    ///         .with_suffix("abc")
364    ///         .parse_complete("123abc")
365    ///         .unwrap(),
366    ///     123,
367    /// );
368    /// ```
369    #[inline]
370    fn with_suffix<T: Parser<'i>>(self, suffix: T) -> WithSuffix<Self, T> {
371        WithSuffix {
372            parser: self,
373            suffix,
374        }
375    }
376
377    /// Parse a end of line (or end of string) after this parser.
378    ///
379    /// Equivalent to [`parser.with_suffix`](Parser::with_suffix)`(`[`parser::eol()`](super::eol)`)`.
380    ///
381    /// # Examples
382    /// ```
383    /// # use utils::parser::{self, Parser};
384    /// assert_eq!(
385    ///     parser::u32()
386    ///         .with_eol()
387    ///         .parse_first("123\nabc")
388    ///         .unwrap(),
389    ///     (123, &b"abc"[..]),
390    /// );
391    /// ```
392    #[inline]
393    fn with_eol(self) -> WithSuffix<Self, Eol> {
394        WithSuffix {
395            parser: self,
396            suffix: Eol(),
397        }
398    }
399
400    /// Replace this parser's error message with the provided string.
401    ///
402    /// # Examples
403    /// ```
404    /// # use utils::parser::{self, ParseError, Parser};
405    /// let parser = parser::u8()
406    ///     .error_msg("expected power level");
407    /// assert_eq!(
408    ///     parser.parse_complete("123").unwrap(),
409    ///     123,
410    /// );
411    /// assert_eq!(
412    ///     parser.parse_complete("abc").unwrap_err().into_source(),
413    ///     ParseError::Custom("expected power level"),
414    /// );
415    /// ```
416    #[inline]
417    fn error_msg(self, message: &'static str) -> WithErrorMsg<Self> {
418        WithErrorMsg {
419            parser: self,
420            message,
421        }
422    }
423
424    /// Apply this parser once, returning the parsed value and the remaining input or error.
425    ///
426    /// This method should only be used to parse the first match and should not be called repeatedly
427    /// to parse the remainder of the input, as the reported error positions will be incorrect.
428    ///
429    /// # Examples
430    /// ```
431    /// # use utils::parser::{self, Parser};
432    /// assert_eq!(parser::u32().parse_first("1234").unwrap(), (1234, &b""[..]));
433    /// assert_eq!(parser::u32().parse_first("123abc").unwrap(), (123, &b"abc"[..]));
434    /// assert!(parser::u32().parse_first("abc123").is_err());
435    /// ```
436    #[inline]
437    fn parse_first(&self, input: &'i str) -> Result<(Self::Output, &'i [u8]), InputError> {
438        let mut state = ParseState::default();
439        self.parse_ctx(input.as_bytes(), &mut state, &mut false, false)
440            .map_err(|_| state.into_input_error(input))
441    }
442
443    /// Apply this parser once, checking the provided input is fully consumed.
444    ///
445    /// # Examples
446    /// ```
447    /// # use utils::parser::{self, Parser};
448    /// assert_eq!(parser::u32().parse_complete("1234").unwrap(), 1234);
449    /// assert!(parser::u32().parse_complete("1234abc").is_err());
450    /// ```
451    #[inline]
452    fn parse_complete(&self, input: &'i str) -> Result<Self::Output, InputError> {
453        let mut state = ParseState::default();
454        match self.parse_ctx(input.as_bytes(), &mut state, &mut false, true) {
455            Ok((v, [])) => return Ok(v),
456            Ok((_, remaining)) => {
457                // Ensure there is an error reported. This may not be the error returned below, as
458                // one may have already been reported further into the input.
459                let _ = state.error(ParseError::ExpectedEof(), remaining);
460            }
461            Err(_) => {}
462        }
463        Err(state.into_input_error(input))
464    }
465
466    /// Apply this parser repeatedly until the provided input is fully consumed.
467    ///
468    /// Equivalent to `parser.repeat(parser::noop(), 0).parse_complete(input)`.
469    ///
470    /// # Examples
471    /// ```
472    /// # use utils::parser::{self, Parser};
473    /// assert_eq!(
474    ///     parser::u32()
475    ///         .then(parser::u32().with_prefix("x"))
476    ///         .with_suffix(",".or(parser::eof()))
477    ///         .parse_all("1x2,3x4,1234x5678")
478    ///         .unwrap(),
479    ///     vec![
480    ///         (1, 2),
481    ///         (3, 4),
482    ///         (1234, 5678),
483    ///     ]
484    /// );
485    /// ```
486    #[inline]
487    fn parse_all(&self, input: &'i str) -> Result<Vec<Self::Output>, InputError> {
488        ParserRef(self)
489            .repeat(Constant(()), 1)
490            .parse_complete(input)
491    }
492
493    /// Similar to [`parse_all`](Self::parse_all) but expects a newline between each item.
494    ///
495    /// # Examples
496    /// ```
497    /// # use utils::parser::{self, Parser};
498    /// assert_eq!(
499    ///     parser::u32()
500    ///         .then(parser::u32().with_prefix("x"))
501    ///         .parse_lines("1x2\n3x4\n1234x5678")
502    ///         .unwrap(),
503    ///     vec![
504    ///         (1, 2),
505    ///         (3, 4),
506    ///         (1234, 5678),
507    ///     ]
508    /// );
509    /// ```
510    #[inline]
511    fn parse_lines(&self, input: &'i str) -> Result<Vec<Self::Output>, InputError> {
512        ParserRef(self).repeat(Eol(), 1).parse_complete(input)
513    }
514
515    /// Create an iterator which applies this parser repeatedly until the provided input is fully
516    /// consumed.
517    ///
518    /// The returned iterator will lazily parse the provided input string, producing a sequence of
519    /// [`Result`] values. Once the end of input is reached, or an error is returned, the parser
520    /// will always return [`None`].
521    ///
522    /// # Examples
523    /// ```
524    /// # use utils::input::InputError;
525    /// # use utils::parser::{self, Parser};
526    /// let iterator = parser::u32()
527    ///     .with_eol()
528    ///     .parse_iterator("12\n34\n56\n78");
529    /// for item in iterator {
530    ///     println!("{}", item?);
531    /// }
532    /// # Ok::<(), InputError>(())
533    /// ```
534    ///
535    /// ```
536    /// # use utils::parser::{self, Parser};
537    /// let mut iterator = parser::u32()
538    ///     .with_eol()
539    ///     .parse_iterator("12\n34\nnot a integer");
540    /// assert_eq!(iterator.next().unwrap().unwrap(), 12);
541    /// assert_eq!(iterator.next().unwrap().unwrap(), 34);
542    /// assert!(iterator.next().unwrap().is_err());
543    /// assert!(iterator.next().is_none());
544    /// ```
545    ///
546    /// ```
547    /// # use utils::input::InputError;
548    /// # use utils::parser::{self, Parser};
549    /// let filtered = parser::u32()
550    ///     .with_eol()
551    ///     .parse_iterator("11\n22\n33\n44\n55")
552    ///     .filter(|r| r.is_err() || r.as_ref().is_ok_and(|v| v % 2 == 0))
553    ///     .collect::<Result<Vec<u32>, InputError>>()?;
554    /// assert_eq!(filtered, vec![22, 44]);
555    /// # Ok::<(), InputError>(())
556    /// ```
557    #[inline]
558    fn parse_iterator(self, input: &str) -> ParserIterator<'_, Self> {
559        ParserIterator {
560            input,
561            remaining: input.as_bytes(),
562            parser: self,
563        }
564    }
565
566    /// Create an iterator which returns matches only and skips over errors.
567    ///
568    /// This is intended for cases that require extracting matches out of the input.
569    /// Otherwise, [`parse_iterator`](Self::parse_iterator) should be used with a parser that can
570    /// match the entire input structure.
571    ///
572    /// # Examples
573    /// ```
574    /// # use utils::parser::{self, Parser};
575    /// assert_eq!(
576    ///     parser::u32()
577    ///         .matches_iterator("abc123d456efg7hi8jk9lmnop")
578    ///         .collect::<Vec<_>>(),
579    ///     vec![123, 456, 7, 8, 9]
580    /// );
581    /// ```
582    #[inline]
583    fn matches_iterator(self, input: &str) -> ParserMatchesIterator<'_, Self> {
584        ParserMatchesIterator {
585            remaining: input.as_bytes(),
586            parser: self,
587        }
588    }
589}
590
591// Workaround to allow using methods which consume a parser in methods which take references.
592struct ParserRef<'a, P>(&'a P);
593impl<'i, P: Parser<'i>> Parser<'i> for ParserRef<'_, P> {
594    type Output = P::Output;
595    type Then<T: Parser<'i>> = Unimplemented;
596
597    #[inline]
598    fn parse_ctx(
599        &self,
600        input: &'i [u8],
601        state: &mut ParseState<'i>,
602        commit: &mut bool,
603        tail: bool,
604    ) -> ParserResult<'i, Self::Output> {
605        self.0.parse_ctx(input, state, commit, tail)
606    }
607}
608
609struct FromFn<F>(F);
610impl<'i, F: Fn(&'i [u8], &mut ParseState<'i>, &mut bool, bool) -> ParserResult<'i, O>, O> Parser<'i>
611    for FromFn<F>
612{
613    type Output = O;
614    type Then<T: Parser<'i>> = Then2<Self, T>;
615
616    #[inline]
617    fn parse_ctx(
618        &self,
619        input: &'i [u8],
620        state: &mut ParseState<'i>,
621        commit: &mut bool,
622        tail: bool,
623    ) -> ParserResult<'i, Self::Output> {
624        self.0(input, state, commit, tail)
625    }
626}
627
628/// [`Parser`] which delegates to the provided function/closure.
629///
630/// This wrapper exists to avoid conflicting implementations of the [`Parser`] trait, which would
631/// occur if both [`Leaf`](super::Leaf) and [`Parser`] were implemented for the [`Fn`] trait family.
632#[inline]
633pub fn from_parser_fn<'i, O>(
634    f: impl Fn(&'i [u8], &mut ParseState<'i>, &mut bool, bool) -> ParserResult<'i, O>,
635) -> impl Parser<'i, Output = O> {
636    FromFn(f)
637}
638
639/// Per-parse shared state.
640///
641/// Tracks the furthest encountered error, allowing combinators like [`Parser::optional`] to return
642/// [`Ok`] while still reporting the furthest seen error for better user-facing error messages.
643#[must_use]
644#[derive(Default)]
645pub struct ParseState<'i> {
646    pub(super) error: Option<(ParseError, &'i [u8])>,
647}
648
649impl<'i> ParseState<'i> {
650    /// Record an error.
651    ///
652    /// The error will be discarded if a further error is already stored.
653    ///
654    /// Returns an [`ErrToken`] which can be used to return [`Err`] from [`Parser::parse_ctx`].
655    #[inline]
656    pub fn error(&mut self, error: ParseError, remaining: &'i [u8]) -> ErrToken {
657        if self.error.is_none() || matches!(self.error, Some((_, r)) if r.len() > remaining.len()) {
658            self.error = Some((error, remaining));
659        }
660        ErrToken::new()
661    }
662
663    /// Build an [`InputError`] from the furthest error seen.
664    #[cold]
665    pub fn into_input_error(self, input: &str) -> InputError {
666        let (error, remaining) = self.error.expect("error not set");
667        InputError::new(input, remaining, error)
668    }
669}
670
671mod token {
672    use std::fmt::{Debug, Formatter};
673
674    // Must not be public
675    #[derive(PartialEq, Eq)]
676    struct Private;
677
678    /// ZST used to ensure that [`Parser`](super::Parser) implementations push errors to
679    /// [`ParseState`](super::ParseState).
680    ///
681    /// Parser implementation must acquire an `ErrToken` to return
682    /// [`ParserResult::Err`](super::ParserResult), which can only be done by calling
683    /// [`ParseState::error`](super::ParseState::error) or by propagating an `ErrToken` returned by
684    /// a child parser.
685    #[must_use]
686    #[derive(PartialEq, Eq)] // Must not implement Clone or Default
687    pub struct ErrToken(Private);
688
689    impl ErrToken {
690        pub(super) fn new() -> Self {
691            Self(Private)
692        }
693    }
694
695    impl Debug for ErrToken {
696        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
697            write!(f, "ErrToken")
698        }
699    }
700}
701pub use token::ErrToken;