Add map_err_with() (#951)

* Add `map_err_with()`

* Add warning about relying on `.slice()` and `.span()`

Author: tmke8

guide/meet_the_parsers.md

@@ -94,13 +94,14 @@ Combinators that manipulate or emit errors, along with fallibly validating parse
 | Name                            | Example                               | Description                                                                                                                                                                             |
 |---------------------------------|---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | [`Parser::map_err`]             | `a.map_err(...)`                      | Parse a pattern. On failure, map the parser error to another value. Often used to customise error messages or add extra information to them.                                            |
-| [`Parser::map_err_with_state`]  | `a.lazy()`                            | Like [`Parser::map_err`], but provides access to the parser state (see [`Parser::parse_with_state`] for more information).                                                              |
+| [`Parser::map_err_with`]        | `a.map_err_with(...)`                 | Like [`Parser::map_err`], but provides access to metadata associated with the output.                                                                                                   |
+| [`Parser::map_err_with_state`]  | `a.map_err_with_state(...)`           | Like [`Parser::map_err`], but provides access to the parser state (see [`Parser::parse_with_state`] for more information).                                                              |
 | [`Parser::try_foldl`]           | `a.try_foldl(...)`                    | Left-fold the output of the parser into a single value, possibly failing during the reduction. If the function produces an error, the parser fails with that error.                     |
 | [`Parser::try_map`]             | `a.try_map(...)`                      | Map the output of a parser using the given fallible mapping function. If the function produces an error, the parser fails with that error.                                              |
 | [`Parser::try_map_with`]        | `a.try_map_with(...)`                 | Map the output of a parser using the given fallible mapping function, with access to output metadata. If the function produces an error, the parser fails with that error.              |
 | [`Parser::validate`]            | `a.validate(...)`                     | Parse a pattern. On success, map the output to another value with the opportunity to emit extra secondary errors. Commonly used to check the validity of patterns in the parser.        |
 | [`Parser::filter`]              | `any().filter(char::is_lowercase)`    | Parse a pattern and apply the given filtering function to the output. If the filter function returns [`false`], the parser fails.                                                       |
-| [`Parser::filter_map`]          | `any().filter_map(...)                | Parse a pattern and apply the given filter-map function to the output. If the filter-map function returns [`None`], the parser fails.                                                   |
+| [`Parser::filter_map`]          | `any().filter_map(...)`               | Parse a pattern and apply the given filter-map function to the output. If the filter-map function returns [`None`], the parser fails.                                                   |
 | [`Parser::labelled`]            | `a.labelled("a")`                     | Parse a pattern, labelling it. What exactly this does depends on the error type, but it is generally used to give a pattern a more general name (for example, "expression").            |
 
 ### Text-oriented parsing

src/combinator.rs

@@ -3149,7 +3149,7 @@ where
         Self: Sized,
     {
         (&self.parser)
-            .map_err_with_state(|e, _, _| (self.mapper)(e))
+            .map_err_with(|e, _| (self.mapper)(e))
             .go::<M>(inp)
     }
 
@@ -3191,7 +3191,6 @@ where
 //     go_extra!(O);
 // }
 
-// TODO: Remove combinator, replace with map_err_with
 /// See [`Parser::map_err_with_state`].
 #[derive(Copy, Clone)]
 pub struct MapErrWithState<A, F> {
@@ -3237,6 +3236,50 @@ where
     go_extra!(O);
 }
 
+/// See [`Parser::map_err_with`].
+#[derive(Copy, Clone)]
+pub struct MapErrWith<A, F> {
+    pub(crate) parser: A,
+    pub(crate) mapper: F,
+}
+
+impl<'src, I, O, E, A, F> Parser<'src, I, O, E> for MapErrWith<A, F>
+where
+    I: Input<'src>,
+    E: ParserExtra<'src, I>,
+    A: Parser<'src, I, O, E>,
+    F: Fn(E::Error, &mut MapExtra<'src, '_, I, E>) -> E::Error,
+{
+    #[inline(always)]
+    fn go<M: Mode>(&self, inp: &mut InputRef<'src, '_, I, E>) -> PResult<M, O>
+    where
+        Self: Sized,
+    {
+        let start = inp.cursor();
+        let old_alt = inp.take_alt();
+        let res = self.parser.go::<M>(inp);
+        let new_alt = inp.take_alt();
+
+        if res.is_ok() {
+            inp.errors.alt = old_alt;
+            if let Some(new_alt) = new_alt {
+                inp.add_alt_err(&new_alt.pos, new_alt.err);
+            }
+        } else {
+            // Can't fail!
+            let mut new_alt = new_alt.unwrap();
+            new_alt.err = (self.mapper)(new_alt.err, &mut MapExtra::new(&start, inp));
+
+            inp.errors.alt = old_alt;
+            inp.add_alt_err(&new_alt.pos, new_alt.err);
+        }
+
+        res
+    }
+
+    go_extra!(O);
+}
+
 /// See [`Parser::validate`]
 pub struct Validate<A, OA, F> {
     pub(crate) parser: A,

src/lib.rs

@@ -1997,6 +1997,29 @@ pub trait Parser<'src, I: Input<'src>, O, E: ParserExtra<'src, I> = extra::Defau
         }
     }
 
+    /// Map the primary error of this parser to another value, making use of the parser state and
+    /// context.
+    ///
+    /// This function is useful for augmenting errors to allow them to include context in non context-free
+    /// languages, or provide contextual notes on possible causes.
+    ///
+    /// The output type of this parser is `O`, the same as the original parser.
+    ///
+    /// Note: Chumsky permits parsers to leave the input in an unspecified state after an error
+    /// occurs and backtracking begins. As such, the output of [`MapExtra::span`] and
+    /// [`MapExtra::slice`] is unspecified within this function.
+    ///
+    fn map_err_with<F>(self, f: F) -> MapErrWith<Self, F>
+    where
+        Self: Sized,
+        F: Fn(E::Error, &mut MapExtra<'src, '_, I, E>) -> E::Error,
+    {
+        MapErrWith {
+            parser: self,
+            mapper: f,
+        }
+    }
+
     /// Validate an output, producing non-terminal errors if it does not fulfill certain criteria.
     /// The errors will not immediately halt parsing on this path, but instead it will continue,
     /// potentially emitting one or more other errors, only failing after the pattern has otherwise
@@ -4018,6 +4041,36 @@ mod tests {
         );
     }
 
+    #[test]
+    fn map_err_with() {
+        use crate::LabelError;
+
+        let parser = just::<char, &str, extra::Err<_>>('#')
+            .repeated()
+            .count()
+            .ignore_with_ctx(just('"').map_err_with(move |e: Rich<char>, extras| {
+                println!("Found = {:?}", e.found());
+                println!("Expected = {:?}", e.expected().collect::<Vec<_>>());
+                println!("Span = {:?}", e.span());
+                println!("Context = {:?}", extras.ctx());
+                LabelError::<&str, String>::expected_found(
+                    [format!("after {} hashes", extras.ctx())],
+                    e.found().copied().map(Into::into),
+                    *e.span(),
+                )
+            }));
+
+        let mut err: Rich<_> =
+            LabelError::<&str, char>::expected_found(['#'], Some('H'.into()), (3..4).into());
+        err = LabelError::<&str, String>::merge_expected_found(
+            err,
+            ["after 3 hashes".into()],
+            Some('H'.into()),
+            (3..4).into(),
+        );
+        assert_eq!(parser.parse("###H").into_result(), Err(vec![err]));
+    }
+
     #[test]
     fn try_map() {
         use crate::{DefaultExpected, LabelError};