Skip to main content

utils/parser/
base.rs

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