add Parser::filter_map (#925)

* add `Parser::filter_map`

The code is mostly just the implementation of `Parser::filter`, but
taking an `Option<U>` from the condition.

* Implement `Filter::go` by using `FilterMap`, add `FilterMap` to parsers guide

* format changes using `cargo fmt`

---------

Co-authored-by: zeichenreihe <zeichenreihe@noreply.codeberg.org>

Author: zeichenreihe

guide/meet_the_parsers.md

@@ -95,11 +95,12 @@ Combinators that manipulate or emit errors, along with fallibly validating parse
 |---------------------------------|---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | [`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::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_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::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

@@ -260,6 +260,48 @@ where
         debug::NodeInfo::Filter(Box::new(self.parser.node_info(scope)))
     }
 
+    #[inline(always)]
+    fn go<M: Mode>(&self, inp: &mut InputRef<'src, '_, I, E>) -> PResult<M, O> {
+        (&self.parser)
+            .filter_map(|out| if (self.filter)(&out) { Some(out) } else { None })
+            .go::<M>(inp)
+    }
+
+    go_extra!(O);
+}
+
+/// See [`Parser::filter_map`].
+pub struct FilterMap<A, OA, F> {
+    pub(crate) parser: A,
+    pub(crate) filter_mapper: F,
+    #[allow(dead_code)]
+    pub(crate) phantom: EmptyPhantom<OA>,
+}
+
+impl<A: Copy, OA, F: Copy> Copy for FilterMap<A, OA, F> {}
+impl<A: Clone, OA, F: Clone> Clone for FilterMap<A, OA, F> {
+    fn clone(&self) -> Self {
+        Self {
+            parser: self.parser.clone(),
+            filter_mapper: self.filter_mapper.clone(),
+            phantom: EmptyPhantom::new(),
+        }
+    }
+}
+
+impl<'src, I, O, E, A, OA, F> Parser<'src, I, O, E> for FilterMap<A, OA, F>
+where
+    I: Input<'src>,
+    E: ParserExtra<'src, I>,
+    A: Parser<'src, I, OA, E>,
+    F: Fn(OA) -> Option<O>,
+{
+    #[doc(hidden)]
+    #[cfg(feature = "debug")]
+    fn node_info(&self, scope: &mut debug::NodeScope) -> debug::NodeInfo {
+        debug::NodeInfo::Filter(Box::new(self.parser.node_info(scope)))
+    }
+
     #[inline(always)]
     fn go<M: Mode>(&self, inp: &mut InputRef<'src, '_, I, E>) -> PResult<M, O> {
         let found = inp.peek_maybe();
@@ -274,19 +316,22 @@ where
         inp.errors.alt = old_alt;
         match res {
             Ok(out) => {
-                if (self.filter)(&out) {
-                    // If successful, reinsert the original alt and then apply the new alt on top of it, since both are valid
-                    if let Some(new_alt) = new_alt {
-                        inp.add_alt_err(&new_alt.pos, new_alt.err);
+                match (self.filter_mapper)(out) {
+                    Some(mapped) => {
+                        // If successful, reinsert the original alt and then apply the new alt on top of it, since both are valid
+                        if let Some(new_alt) = new_alt {
+                            inp.add_alt_err(&new_alt.pos, new_alt.err);
+                        }
+                        Ok(M::bind(|| mapped))
+                    }
+                    None => {
+                        // If unsuccessful, reinsert the original alt but replace the new alt with the "something else" error (since it overrides it)
+                        let expected = [DefaultExpected::SomethingElse];
+                        // TODO: Use something more detailed than the next token as the found
+                        let err = E::Error::expected_found(expected, found, span);
+                        inp.add_alt_err(&before.inner, err);
+                        Err(())
                     }
-                    Ok(M::bind(|| out))
-                } else {
-                    // If unsuccessful, reinsert the original alt but replace the new alt with the "something else" error (since it overrides it)
-                    let expected = [DefaultExpected::SomethingElse];
-                    // TODO: Use something more detailed than the next token as the found
-                    let err = E::Error::expected_found(expected, found, span);
-                    inp.add_alt_err(&before.inner, err);
-                    Err(())
                 }
             }
 

src/lib.rs

@@ -520,6 +520,44 @@ pub trait Parser<'src, I: Input<'src>, O, E: ParserExtra<'src, I> = extra::Defau
         }
     }
 
+    /// Filter and map the output of this parser, accepting only inputs that get mapped to `Some`.
+    ///
+    /// The output type of this parser is `U`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use chumsky::{prelude::*, error::Simple};
+    /// #[derive(Debug, PartialEq)]
+    /// enum Token {
+    ///     Digit(char), // invariant: .is_ascii_digit()
+    ///     Alpha(char), // invariant: .is_alphabetic()
+    /// }
+    ///
+    /// let token = any::<_, extra::Err<Simple<char>>>()
+    ///     .filter_map(|c: char| if c.is_ascii_digit() {
+    ///         Some(Token::Digit(c))
+    ///     } else if c.is_alphabetic() {
+    ///         Some(Token::Alpha(c))
+    ///     } else {
+    ///         None
+    ///     });
+    ///
+    /// assert_eq!(token.parse("x").into_result(), Ok(Token::Alpha('x')));
+    /// assert_eq!(token.parse("5").into_result(), Ok(Token::Digit('5')));
+    /// assert!(token.parse("!").has_errors());
+    /// ```
+    fn filter_map<U, F: Fn(O) -> Option<U>>(self, f: F) -> FilterMap<Self, O, F>
+    where
+        Self: Sized,
+    {
+        FilterMap {
+            parser: self,
+            filter_mapper: f,
+            phantom: EmptyPhantom::new(),
+        }
+    }
+
     /// Map the output of this parser to another value.
     ///
     /// The output type of this parser is `U`, the same as the function's output.