Crate winnow

winnow, making parsing a breeze

winnow is a parser combinator library

Quick links:

• List of combinators
• [Tutorial][_tutorial::chapter_0]
• [Special Topics][_topic]
• Discussions
• CHANGELOG (includes major version migration guides)

Aspirations

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

In roughly priority order:

1. 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.
2. Flexible enough to be used for any application, including parsing strings, binary data, or separate [lexing and parsing phases][_topic::lexing]
3. Zero-cost abstractions, making it easy to write high performance parsers
4. 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.64.0)

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

Example

Run

$ cargo add winnow

Then use it to parse:

use winnow::combinator::seq;
use winnow::prelude::*;
use winnow::token::take_while;
use winnow::Result;

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

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

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        hex_color.parse(s).map_err(|e| e.to_string())
    }
}

pub(crate) fn hex_color(input: &mut &str) -> Result<Color> {
    seq!(Color {
        _: '#',
        red: hex_primary,
        green: hex_primary,
        blue: hex_primary
    })
    .parse_next(input)
}

fn hex_primary(input: &mut &str) -> Result<u8> {
    take_while(2, |c: char| c.is_ascii_hexdigit())
        .try_map(|input| u8::from_str_radix(input, 16))
        .parse_next(input)
}

See also the [Tutorial][_tutorial::chapter_0] and [Special Topics][_topic]

Re-exports

pub use error::ModalResult;

pub use error::Result;

pub use stream::BStr;

pub use stream::Bytes;

pub use stream::LocatingSlice;

pub use stream::Partial;

pub use stream::Stateful;

pub use stream::Str;

Modules

ascii

Character specific parsers and combinators

binary

Parsers recognizing numbers

combinator

List of parsers and combinators

error

Error management

macros 🔒

parser 🔒

Basic types to build the parsers

prelude

Core concepts available for glob import

stream

Stream capability for combinators to parse

token

Parsers extracting tokens from the stream

util 🔒

Traits

ModalParser

Trait alias for Parser to be used with ModalResult

Parser

Core trait for parsing