Crate winnow

Available on crate feature dep_winnow only.

winnow A byte-oriented, zero-copy, parser combinators library.

---

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 binary data, strings, or separate lexing and parsing phases
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]

Modules

ascii

Character specific parsers and combinators

binary

Parsers recognizing numbers

combinator

List of parsers and combinators

error

Error management

prelude

Core concepts available for glob import

stream

Stream capability for combinators to parse

token

Parsers extracting tokens from the stream

Structs

BStr

Improved Debug experience for &[u8] UTF-8-ish streams

Bytes

Improved Debug experience for &[u8] byte streams

LocatingSlice

Allow collecting the span of a parsed token within a slice

Partial

Mark the input as a partial buffer for streaming input.

Stateful

Thread global state through your parsers

Traits

ModalParser

Trait alias for Parser to be used with ModalResult

Parser

Core trait for parsing

Type Aliases

ModalResult

Modal error reporting for Parser::parse_next

Result

By default, the error type (E) is ContextError.

Str

UTF-8 Stream