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;