winnow

In winnow, parsers typically return a ModalResult<O, E> rather than a standard Result<O, E>. This allows the parser to communicate not just that an error occurred, but how the caller should respond to it via the ErrMode<E> enum.

ErrMode<E> has three variants:

• Backtrack(E): A recoverable error. The parser failed, but the caller (like an alt combinator) should try other branches.
• Cut(E): An unrecoverable error. The parser has committed to a specific branch, and any further error should be reported directly to the user instead of backtracking.
• Incomplete(Needed): Not enough data is available to complete the parse. This is used with partial streams to signal that more data should be buffered before retrying.

You can manipulate these modes using .cut() to prevent backtracking or .backtrack() to re-enable it.

/// Ok(O) is the parsed value
/// Err(ErrMode<E>) is the error along with how to respond to it
pub type ModalResult<O, E = ContextError> = Result<O, ErrMode<E>>;

The Stateful<I, S> wrapper allows you to attach user-provided state S to an input stream I. This is useful for tracking information across multiple parser calls, such as:

• Recursion checks: Tracking depth to prevent infinite loops.
• Error recovery: Storing context for better error reporting or recovery strategies.
• Debugging: Maintaining counters or logs during the parsing process.

Stateful implements Deref to the inner input I, so you can call most stream methods directly on the Stateful instance. When creating a Checkpoint for a Stateful stream, the checkpoint will also include the state, allowing you to restore both the input position and the user state simultaneously.

Example

# #[cfg(feature = "ascii")] {
# use std::cell::Cell;
# use winnow::prelude::*;
# use winnow::stream::Stateful;
# use winnow::ascii::alpha1;
# type Error = ();
#
# #[derive(Debug)]
# struct State<'s>(&'s mut u32);
#
# impl<'s> State<'s> {
#     fn count(&mut self) {
#         *self.0 += 1;
#     }
# }
#
# type Stream<'is> = Stateful<&'is str, State<'is>>;
#
# fn word<'s>(i: &mut Stream<'s>) -> ModalResult<&'s str> {
#   i.state.count();
#   alpha1.parse_next(i)
# }
#
# let data = "Hello";
# let mut state = 0;
# let input = Stream { input: data, state: State(&mut state) };
# let output = word.parse(input).unwrap();
# assert_eq!(state, 1);
# }

The Partial<I> wrapper is used to mark an input as a partial buffer, which is essential for streaming scenarios (e.g., network protocols or large files) where the entire input might not be available at once.

When using Partial, parsers that require a specific amount of data will return ErrMode::Incomplete(Needed) instead of a standard error if the input is insufficient. This allows the caller to wait for more data and retry.

Key behaviors:

• ErrMode::Incomplete: Reports how much more data is needed.
• Parser::complete_err: Can be used to transform Incomplete errors into Backtrack errors if preferred.
• Ambiguity: For parsers with no clear limit (like alpha0 which matches 0 or more characters), the Partial version will return Incomplete if the end of the buffer is reached, because it cannot know if more valid characters are coming. A 'complete' parser (non-wrapped) would instead return a successful match of the current buffer.

# #[cfg(feature = "ascii")] {
# use winnow::{Result, error::ErrMode, error::Needed, error::ContextError, token, ascii, stream::Partial};
# use winnow::prelude::*;

// A parser using a partial stream
fn take_partial<'s>(i: &mut Partial<&'s [u8]>) -> ModalResult<&'s [u8], ContextError> {
  token::take(4u8).parse_next(i)
}

// A parser using a complete stream
fn take_complete<'s>(i: &mut &'s [u8]) -> ModalResult<&'s [u8], ContextError> {
  token::take(4u8).parse_next(i)
}

// If input is 4+ bytes, both succeed
assert_eq!(take_partial.parse_peek(Partial::new(&b"abcde"[..])), Ok((Partial::new(&b"e"[..]), &b"abcd"[..])));
assert_eq!(take_complete.parse_peek(&b"abcde"[..]), Ok((&b"e"[..], &b"abcd"[..])));

// If input is < 4 bytes, partial returns Incomplete, complete returns an error
assert_eq!(take_partial.parse_peek(Partial::new(&b"abc"[..])), Err(ErrMode::Incomplete(Needed::new(1))));
assert!(take_complete.parse_peek(&b"abc"[..]).is_err());
# }

The Parser trait is the core abstraction in winnow. You can implement it in two primary ways:

1. Using a function: The simplest way is to define a function that takes a mutable reference to a Stream and returns a Result. Any function with the signature FnMut(&mut I) -> Result<O, E> automatically implements Parser.

2. Using stateful objects: You can return a function that captures state, allowing for more complex parsing logic.

Basic types like u8, char, &[u8], and &str also implement Parser for literal matching.

use winnow::prelude::*;

// 1. Function-based parser
fn empty(input: &mut &str) -> ModalResult<()> {
    let output = ();
    Ok(output)
}

// 2. Stateful parser
fn empty_stateful<O: Clone>(output: O) -> impl FnMut(&mut &str) -> ModalResult<O> {
    move |input: &mut &str| {
        let output = output.clone();
        Ok(output)
    }
}

let (input, output) = empty.parse_peek("Hello").unwrap();

Winnow uses error modes to distinguish between recoverable (Backtrack) and unrecoverable (Cut) errors. This is critical when using combinators like alt.

• cut_err: Converts a Backtrack error into a Cut error. This 'commits' the parser, preventing alt from trying other branches. Use this when you have matched a prefix that guarantees a specific syntax, and a subsequent failure should be treated as a hard error rather than a reason to try something else.
• backtrack_err: Converts a Cut error back into a Backtrack error, allowing alt to continue trying other branches.

# // Example of cut_err committing a branch
# use winnow::{error::ErrMode, error::ContextError};
# use winnow::prelude::*;
# use winnow::token::one_of;
# use winnow::ascii::digit1;
# use winnow::combinator::alt;
# use winnow::combinator::preceded;
# use winnow::combinator::cut_err;

fn parser<'i>(input: &mut &'i str) -> ModalResult<&'i str> {
  alt((
    preceded(one_of(['+', '-']), cut_err(digit1)),
    rest
  )).parse_next(input)
}

// If input is "+", it fails at digit1. 
// Because of cut_err, it returns Err(ErrMode::Cut) instead of backtracking to 'rest'.
assert_eq!(parser.parse_peek("+",), Err(ErrMode::Cut(ContextError::new())));