feat: Unstable support for error recovery

The main things this leave out include:
- A happy path for error reporting
- Examples

First step towards #96

Cargo.toml

@@ -51,8 +51,9 @@ alloc = []
 std = ["alloc", "memchr?/std"]
 simd = ["dep:memchr"]
 debug = ["dep:anstream", "dep:anstyle", "dep:is-terminal", "dep:terminal_size"]
+unstable-recover = []
 
-unstable-doc = ["alloc", "std", "simd"]
+unstable-doc = ["alloc", "std", "simd", "unstable-recover"]
 
 [dependencies]
 anstream = { version = "0.3.2", optional = true }

src/combinator/parser.rs

@@ -1,8 +1,12 @@
 use crate::combinator::trace;
 use crate::combinator::trace_result;
+#[cfg(feature = "unstable-recover")]
+use crate::error::FromRecoverableError;
 use crate::error::{AddContext, ErrMode, ErrorKind, FromExternalError, ParserError};
 use crate::lib::std::borrow::Borrow;
 use crate::lib::std::ops::Range;
+#[cfg(feature = "unstable-recover")]
+use crate::stream::Recover;
 use crate::stream::StreamIsPartial;
 use crate::stream::{Location, Stream};
 use crate::*;
@@ -903,3 +907,203 @@ where
         .parse_next(i)
     }
 }
+
+/// Implementation of [`Parser::retry_after`]
+#[cfg_attr(nightly, warn(rustdoc::missing_doc_code_examples))]
+#[cfg(feature = "unstable-recover")]
+pub struct RetryAfter<P, R, I, O, E, ER>
+where
+    P: Parser<I, O, E>,
+    R: Parser<I, (), E>,
+    I: Stream,
+    I: Recover<E>,
+    E: FromRecoverableError<I, E>,
+    ER: FromRecoverableError<I, E>,
+{
+    parser: P,
+    recover: R,
+    i: core::marker::PhantomData<I>,
+    o: core::marker::PhantomData<O>,
+    e: core::marker::PhantomData<E>,
+    er: core::marker::PhantomData<ER>,
+}
+
+#[cfg(feature = "unstable-recover")]
+impl<P, R, I, O, E, ER> RetryAfter<P, R, I, O, E, ER>
+where
+    P: Parser<I, O, E>,
+    R: Parser<I, (), E>,
+    I: Stream,
+    I: Recover<E>,
+    E: FromRecoverableError<I, E>,
+    ER: FromRecoverableError<I, E>,
+{
+    #[inline(always)]
+    pub(crate) fn new(parser: P, recover: R) -> Self {
+        Self {
+            parser,
+            recover,
+            i: Default::default(),
+            o: Default::default(),
+            e: Default::default(),
+            er: Default::default(),
+        }
+    }
+}
+
+#[cfg(feature = "unstable-recover")]
+impl<P, R, I, O, E, ER> Parser<I, O, E> for RetryAfter<P, R, I, O, E, ER>
+where
+    P: Parser<I, O, E>,
+    R: Parser<I, (), E>,
+    I: Stream,
+    I: Recover<E>,
+    E: FromRecoverableError<I, E>,
+    ER: FromRecoverableError<I, E>,
+{
+    #[inline(always)]
+    fn parse_next(&mut self, i: &mut I) -> PResult<O, E> {
+        if I::is_recovery_supported() {
+            retry_after_inner::<P, R, I, O, E, ER>(&mut self.parser, &mut self.recover, i)
+        } else {
+            self.parser.parse_next(i)
+        }
+    }
+}
+
+#[cfg(feature = "unstable-recover")]
+fn retry_after_inner<P, R, I, O, E, ER>(parser: &mut P, recover: &mut R, i: &mut I) -> PResult<O, E>
+where
+    P: Parser<I, O, E>,
+    R: Parser<I, (), E>,
+    I: Stream,
+    I: Recover<E>,
+    E: FromRecoverableError<I, E>,
+    ER: FromRecoverableError<I, E>,
+{
+    loop {
+        let token_start = i.checkpoint();
+        let mut err = match parser.parse_next(i) {
+            Ok(o) => {
+                return Ok(o);
+            }
+            Err(ErrMode::Incomplete(e)) => return Err(ErrMode::Incomplete(e)),
+            Err(err) => err,
+        };
+        let err_start = i.checkpoint();
+        let err_start_eof_offset = i.eof_offset();
+        if recover.parse_next(i).is_ok() {
+            let i_eof_offset = i.eof_offset();
+            if err_start_eof_offset == i_eof_offset {
+                // Didn't advance so bubble the error up
+            } else if let Err(err_) = i.record_err(&token_start, &err_start, err) {
+                err = err_;
+            } else {
+                continue;
+            }
+        }
+
+        i.reset(err_start.clone());
+        err = err.map(|err| E::from_recoverable_error(&token_start, &err_start, i, err));
+        return Err(err);
+    }
+}
+
+/// Implementation of [`Parser::resume_after`]
+#[cfg(feature = "unstable-recover")]
+#[cfg_attr(nightly, warn(rustdoc::missing_doc_code_examples))]
+pub struct ResumeAfter<P, R, I, O, E, ER>
+where
+    P: Parser<I, O, E>,
+    R: Parser<I, (), E>,
+    I: Stream,
+    I: Recover<E>,
+    E: FromRecoverableError<I, E>,
+    ER: FromRecoverableError<I, E>,
+{
+    parser: P,
+    recover: R,
+    i: core::marker::PhantomData<I>,
+    o: core::marker::PhantomData<O>,
+    e: core::marker::PhantomData<E>,
+    er: core::marker::PhantomData<ER>,
+}
+
+#[cfg(feature = "unstable-recover")]
+impl<P, R, I, O, E, ER> ResumeAfter<P, R, I, O, E, ER>
+where
+    P: Parser<I, O, E>,
+    R: Parser<I, (), E>,
+    I: Stream,
+    I: Recover<E>,
+    E: FromRecoverableError<I, E>,
+    ER: FromRecoverableError<I, E>,
+{
+    #[inline(always)]
+    pub(crate) fn new(parser: P, recover: R) -> Self {
+        Self {
+            parser,
+            recover,
+            i: Default::default(),
+            o: Default::default(),
+            e: Default::default(),
+            er: Default::default(),
+        }
+    }
+}
+
+#[cfg(feature = "unstable-recover")]
+impl<P, R, I, O, E, ER> Parser<I, Option<O>, E> for ResumeAfter<P, R, I, O, E, ER>
+where
+    P: Parser<I, O, E>,
+    R: Parser<I, (), E>,
+    I: Stream,
+    I: Recover<E>,
+    E: FromRecoverableError<I, E>,
+    ER: FromRecoverableError<I, E>,
+{
+    #[inline(always)]
+    fn parse_next(&mut self, i: &mut I) -> PResult<Option<O>, E> {
+        if I::is_recovery_supported() {
+            resume_after_inner::<P, R, I, O, E, ER>(&mut self.parser, &mut self.recover, i)
+        } else {
+            self.parser.parse_next(i).map(Some)
+        }
+    }
+}
+
+#[cfg(feature = "unstable-recover")]
+fn resume_after_inner<P, R, I, O, E, ER>(
+    parser: &mut P,
+    recover: &mut R,
+    i: &mut I,
+) -> PResult<Option<O>, E>
+where
+    P: Parser<I, O, E>,
+    R: Parser<I, (), E>,
+    I: Stream,
+    I: Recover<E>,
+    E: FromRecoverableError<I, E>,
+    ER: FromRecoverableError<I, E>,
+{
+    let token_start = i.checkpoint();
+    let mut err = match parser.parse_next(i) {
+        Ok(o) => {
+            return Ok(Some(o));
+        }
+        Err(ErrMode::Incomplete(e)) => return Err(ErrMode::Incomplete(e)),
+        Err(err) => err,
+    };
+    let err_start = i.checkpoint();
+    if recover.parse_next(i).is_ok() {
+        if let Err(err_) = i.record_err(&token_start, &err_start, err) {
+            err = err_;
+        } else {
+            return Ok(None);
+        }
+    }
+
+    i.reset(err_start.clone());
+    err = err.map(|err| E::from_recoverable_error(&token_start, &err_start, i, err));
+    Err(err)
+}

src/error.rs

@@ -313,6 +313,17 @@ pub trait AddContext<I, C = &'static str>: Sized {
     }
 }
 
+/// Capture context from when an error was recovered
+pub trait FromRecoverableError<I: Stream, E> {
+    /// Capture context from when an error was recovered
+    fn from_recoverable_error(
+        token_start: &<I as Stream>::Checkpoint,
+        err_start: &<I as Stream>::Checkpoint,
+        input: &I,
+        e: E,
+    ) -> Self;
+}
+
 /// Create a new error with an external error, from [`std::str::FromStr`]
 ///
 /// This trait is required by the [`Parser::try_map`] combinator.
@@ -387,6 +398,18 @@ impl<I: Clone> ParserError<I> for InputError<I> {
 
 impl<I: Clone, C> AddContext<I, C> for InputError<I> {}
 
+impl<I: Clone + Stream> FromRecoverableError<I, Self> for InputError<I> {
+    #[inline]
+    fn from_recoverable_error(
+        _token_start: &<I as Stream>::Checkpoint,
+        _err_start: &<I as Stream>::Checkpoint,
+        _input: &I,
+        e: Self,
+    ) -> Self {
+        e
+    }
+}
+
 impl<I: Clone, E> FromExternalError<I, E> for InputError<I> {
     /// Create a new error from an input position and an external error
     #[inline]
@@ -446,6 +469,18 @@ impl<I> ParserError<I> for () {
 
 impl<I, C> AddContext<I, C> for () {}
 
+impl<I: Stream> FromRecoverableError<I, Self> for () {
+    #[inline]
+    fn from_recoverable_error(
+        _token_start: &<I as Stream>::Checkpoint,
+        _err_start: &<I as Stream>::Checkpoint,
+        _input: &I,
+        e: Self,
+    ) -> Self {
+        e
+    }
+}
+
 impl<I, E> FromExternalError<I, E> for () {
     #[inline]
     fn from_external_error(_input: &I, _kind: ErrorKind, _e: E) -> Self {}
@@ -536,6 +571,18 @@ impl<C, I> AddContext<I, C> for ContextError<C> {
     }
 }
 
+impl<I: Stream, C> FromRecoverableError<I, Self> for ContextError<C> {
+    #[inline]
+    fn from_recoverable_error(
+        _token_start: &<I as Stream>::Checkpoint,
+        _err_start: &<I as Stream>::Checkpoint,
+        _input: &I,
+        e: Self,
+    ) -> Self {
+        e
+    }
+}
+
 #[cfg(feature = "std")]
 impl<C, I, E: std::error::Error + Send + Sync + 'static> FromExternalError<I, E>
     for ContextError<C>
@@ -863,6 +910,19 @@ where
     }
 }
 
+#[cfg(feature = "std")]
+impl<I: Clone + Stream, C> FromRecoverableError<I, Self> for TreeError<I, C> {
+    #[inline]
+    fn from_recoverable_error(
+        _token_start: &<I as Stream>::Checkpoint,
+        _err_start: &<I as Stream>::Checkpoint,
+        _input: &I,
+        e: Self,
+    ) -> Self {
+        e
+    }
+}
+
 #[cfg(feature = "std")]
 impl<I, C, E: std::error::Error + Send + Sync + 'static> FromExternalError<I, E> for TreeError<I, C>
 where

src/lib.rs

@@ -240,6 +240,8 @@ pub mod prelude {
     pub use crate::IResult;
     pub use crate::PResult;
     pub use crate::Parser;
+    #[cfg(feature = "unstable-recover")]
+    pub use crate::RecoverableParser as _;
 }
 
 pub use error::IResult;