feat(token): Add 'peek_any'

examples/arithmetic/parser_lexer.rs

@@ -10,11 +10,10 @@ use winnow::{
     combinator::alt,
     combinator::dispatch,
     combinator::fail,
-    combinator::peek,
     combinator::repeat,
     combinator::{delimited, preceded, terminated},
-    token::any,
     token::one_of,
+    token::peek_any,
 };
 
 #[derive(Debug, Clone)]
@@ -109,7 +108,7 @@ pub(crate) fn lex(i: &mut &str) -> Result<Vec<Token>> {
 }
 
 fn token(i: &mut &str) -> Result<Token> {
-    dispatch! {peek(any);
+    dispatch! {peek_any;
         '0'..='9' => digits.try_map(FromStr::from_str).map(Token::Value),
         '(' => '('.value(Token::OpenParen),
         ')' => ')'.value(Token::CloseParen),

examples/json/parser_dispatch.rs

@@ -7,11 +7,11 @@ use winnow::{
     ascii::float,
     combinator::empty,
     combinator::fail,
-    combinator::peek,
     combinator::{alt, dispatch},
     combinator::{delimited, preceded, separated_pair, terminated},
     combinator::{repeat, separated},
     error::{AddContext, ParserError, StrContext},
+    token::peek_any,
     token::{any, none_of, take, take_while},
 };
 
@@ -43,7 +43,7 @@ fn json_value<'i, E: ParserError<Stream<'i>> + AddContext<Stream<'i>, StrContext
 ) -> Result<JsonValue, E> {
     // `dispatch` gives you `match`-like behavior compared to `alt` successively trying different
     // implementations.
-    dispatch!(peek(any);
+    dispatch!(peek_any;
         'n' => null.value(JsonValue::Null),
         't' => true_.map(JsonValue::Boolean),
         'f' => false_.map(JsonValue::Boolean),

src/ascii/mod.rs

@@ -12,7 +12,6 @@ use crate::combinator::dispatch;
 use crate::combinator::empty;
 use crate::combinator::fail;
 use crate::combinator::opt;
-use crate::combinator::peek;
 use crate::combinator::trace;
 use crate::error::Needed;
 use crate::error::ParserError;
@@ -21,6 +20,7 @@ use crate::stream::{AsBStr, AsChar, ParseSlice, Stream, StreamIsPartial};
 use crate::stream::{Compare, CompareResult};
 use crate::token::any;
 use crate::token::one_of;
+use crate::token::peek_any;
 use crate::token::take_until;
 use crate::token::take_while;
 use crate::Parser;
@@ -1489,7 +1489,7 @@ where
     <I as Stream>::IterOffsets: Clone,
     I: AsBStr,
 {
-    dispatch! {opt(peek(any).map(AsChar::as_char));
+    dispatch! {opt(peek_any.map(AsChar::as_char));
         Some('N') | Some('n') => Caseless("nan").void(),
         Some('+') | Some('-') => (any, take_unsigned_float_or_exceptions).void(),
         _ => take_unsigned_float_or_exceptions,
@@ -1509,7 +1509,7 @@ where
     <I as Stream>::IterOffsets: Clone,
     I: AsBStr,
 {
-    dispatch! {opt(peek(any).map(AsChar::as_char));
+    dispatch! {opt(peek_any.map(AsChar::as_char));
         Some('I') | Some('i') => (Caseless("inf"), opt(Caseless("inity"))).void(),
         Some('.') => ('.', digit1, take_exp).void(),
         _ => (digit1, opt(('.', opt(digit1))), take_exp).void(),
@@ -1527,7 +1527,7 @@ where
     <I as Stream>::IterOffsets: Clone,
     I: AsBStr,
 {
-    dispatch! {opt(peek(any).map(AsChar::as_char));
+    dispatch! {opt(peek_any.map(AsChar::as_char));
         Some('E') | Some('e') => (one_of(['e', 'E']), opt(one_of(['+', '-'])), digit1).void(),
         _ => empty,
     }

src/combinator/core.rs

@@ -88,6 +88,8 @@ where
 ///
 /// To lookahead and only advance on success, see [`opt`].
 ///
+/// To peek just a token (i.e. `peek(any)`), see [`peek_token`][crate::token::peek_token].
+///
 /// # Example
 ///
 /// ```rust

src/token/mod.rs

@@ -82,6 +82,61 @@ where
     })
 }
 
+/// Get the next token, if present, without advancing the input
+///
+/// To peek with a [`Parser`], see [`peek`][crate::combiantor::peek].
+///
+/// # Effective Signature
+///
+/// Assuming you are parsing a `&str` [Stream]:
+/// ```rust
+/// # use winnow::prelude::*;;
+/// pub fn peek_any(input: &mut &str) -> ModalResult<char>
+/// # {
+/// #     winnow::token::peek_any.parse_next(input)
+/// # }
+/// ```
+///
+/// # Example
+///
+/// ```rust
+/// # use winnow::prelude::*;
+/// # use winnow::combinator::dispatch;
+/// # use winnow::combinator::fail;
+/// use winnow::token::peek_any;
+///
+/// fn bool<'i>(input: &mut &'i str) -> ModalResult<&'i str> {
+///     dispatch!(peek_any;
+///         't' => "true",
+///         'f' => "false",
+///         _ => fail,
+///     )
+///     .parse_next(input)
+/// }
+///
+/// assert_eq!(bool.parse_peek("true;"), Ok((";", "true")));
+/// assert!(bool.parse_peek("123;").is_err());
+/// ```
+#[doc(alias = "look_ahead")]
+#[doc(alias = "rewind")]
+#[doc(alias = "peek_token")]
+pub fn peek_any<Input, Error>(input: &mut Input) -> Result<<Input as Stream>::Token, Error>
+where
+    Input: StreamIsPartial + Stream,
+    Error: ParserError<Input>,
+{
+    trace("peek_any", move |input: &mut Input| {
+        input.peek_token().ok_or_else(|| {
+            if <Input as StreamIsPartial>::is_partial_supported() && input.is_partial() {
+                ParserError::incomplete(input, Needed::new(1))
+            } else {
+                ParserError::from_input(input)
+            }
+        })
+    })
+    .parse_next(input)
+}
+
 /// Recognizes a literal
 ///
 /// The input data will be compared to the literal combinator's argument and will return the part of