Crate winnow

source ·

Expand description

winnow, making parsing a breeze

winnow is a parser combinator library

Quick links:

List of combinators
[Tutorial][_tutorial::chapter_0]
[Special Topics][_topic]
Discussions

Aspirations

winnow aims to be your “do everything” parser, much like people treat regular expressions.

In roughly priority order:

Support writing parser declaratively while not getting in the way of imperative-style parsing when needed, working as an open-ended toolbox rather than a close-ended framework.
Flexible enough to be used for any application, including parsing binary data, strings, or separate lexing and parsing phases
Zero-cost abstractions, making it easy to write high performance parsers
Easy to use, making it trivial for one-off uses

In addition:

Resilient maintainership, including
- Willing to break compatibility rather than batching up breaking changes in large releases
- Leverage feature flags to keep one active branch
We will support the last 6 months of rust releases (MSRV, currently 1.60)

See also [Special Topic: Why winnow?][crate::_topic::why]

Example

Run

$ cargo add winnow

Then use it to parse:

use winnow::bytes::take_while_m_n;
use winnow::prelude::*;

#[derive(Debug, Eq, PartialEq)]
pub struct Color {
    pub red: u8,
    pub green: u8,
    pub blue: u8,
}

impl std::str::FromStr for Color {
    // The error must be owned
    type Err = winnow::error::Error<String>;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        hex_color.parse(s).map_err(winnow::error::Error::into_owned)
    }
}

pub fn hex_color(input: &str) -> IResult<&str, Color> {
    let (input, _) = "#".parse_next(input)?;
    let (input, (red, green, blue)) = (hex_primary, hex_primary, hex_primary).parse_next(input)?;

    Ok((input, Color { red, green, blue }))
}

fn hex_primary(input: &str) -> IResult<&str, u8> {
    take_while_m_n(2, 2, |c: char| c.is_ascii_hexdigit())
        .map_res(|input| u8::from_str_radix(input, 16))
        .parse_next(input)
}