Module winnow::combinator

Expand description

List of parsers and combinators

Note: this list is meant to provide a nicer way to find a parser than reading through the documentation on docs.rs. Function combinators are organized in module so they are a bit easier to find.

Basic elements

Those are used to recognize the lowest level elements of your grammar, like, “here is a dot”, or “here is an big endian integer”.

combinator	usage	input	output	comment
`one_of`	`one_of("abc")`	`"abc"`	`Ok(("bc", 'a'))`	Matches one of the provided characters (works with non ASCII characters too)
`none_of`	`none_of("abc")`	`"xyab"`	`Ok(("yab", 'x'))`	Matches anything but the provided characters
`tag`	`"hello"`	`"hello world"`	`Ok((" world", "hello"))`	Recognizes a specific suite of characters or bytes
`tag_no_case`	`tag_no_case("hello")`	`"HeLLo World"`	`Ok((" World", "HeLLo"))`	Case insensitive comparison. Note that case insensitive comparison is not well defined for unicode, and that you might have bad surprises
`take`	`take(4)`	`"hello"`	`Ok(("o", "hell"))`	Takes a specific number of bytes or characters
`take_while0`	`take_while0(is_alphabetic)`	`"abc123"`	`Ok(("123", "abc"))`	Returns the longest list of bytes for which the provided pattern matches. `take_while1` does the same, but must return at least one character
`take_till0`	`take_till0(is_alphabetic)`	`"123abc"`	`Ok(("abc", "123"))`	Returns the longest list of bytes or characters until the provided pattern matches. `take_till1` does the same, but must return at least one character. This is the reverse behaviour from `take_while0`: `take_till(f)` is equivalent to `take_while0(\\|c\\| !f(c))`
`take_until0`	`take_until0("world")`	`"Hello world"`	`Ok(("world", "Hello "))`	Returns the longest list of bytes or characters until the provided tag is found. `take_until1` does the same, but must return at least one character

Choice combinators

combinator	usage	input	output	comment
`alt`	`alt(("ab", "cd"))`	`"cdef"`	`Ok(("ef", "cd"))`	Try a list of parsers and return the result of the first successful one
`dispatch`	-	-	-	`match` for parsers
`permutation`	`permutation(("ab", "cd", "12"))`	`"cd12abc"`	`Ok(("c", ("ab", "cd", "12"))`	Succeeds when all its child parser have succeeded, whatever the order

Sequence combinators

combinator	usage	input	output	comment
`(...)` (tuples)	`("ab", "XY", take(1))`	`"abXYZ!"`	`Ok(("!", ("ab", "XY", "Z")))`	Chains parsers and assemble the sub results in a tuple. You can use as many child parsers as you can put elements in a tuple
`delimited`	`delimited(char('('), take(2), char(')'))`	`"(ab)cd"`	`Ok(("cd", "ab"))`
`preceded`	`preceded("ab", "XY")`	`"abXYZ"`	`Ok(("Z", "XY"))`
`terminated`	`terminated("ab", "XY")`	`"abXYZ"`	`Ok(("Z", "ab"))`
`separated_pair`	`separated_pair("hello", char(','), "world")`	`"hello,world!"`	`Ok(("!", ("hello", "world")))`

Applying a parser multiple times

combinator	usage	input	output	comment
`count`	`count(take(2), 3)`	`"abcdefgh"`	`Ok(("gh", vec!["ab", "cd", "ef"]))`	Applies the child parser a specified number of times
`many0`	`many0("ab")`	`"abababc"`	`Ok(("c", vec!["ab", "ab", "ab"]))`	Applies the parser 0 or more times and returns the list of results in a Vec. `many1` does the same operation but must return at least one element
`many_m_n`	`many_m_n(1, 3, "ab")`	`"ababc"`	`Ok(("c", vec!["ab", "ab"]))`	Applies the parser between m and n times (n included) and returns the list of results in a Vec
`many_till0`	`many_till0(tag( "ab" ), tag( "ef" ))`	`"ababefg"`	`Ok(("g", (vec!["ab", "ab"], "ef")))`	Applies the first parser until the second applies. Returns a tuple containing the list of results from the first in a Vec and the result of the second
`separated0`	`separated0("ab", ",")`	`"ab,ab,ab."`	`Ok((".", vec!["ab", "ab", "ab"]))`	`separated1` works like `separated0` but must returns at least one element
`fold_many0`	`fold_many0(be_u8, \\|\\| 0, \\|acc, item\\| acc + item)`	`[1, 2, 3]`	`Ok(([], 6))`	Applies the parser 0 or more times and folds the list of return values. The `fold_many1` version must apply the child parser at least one time
`fold_many_m_n`	`fold_many_m_n(1, 2, be_u8, \\|\\| 0, \\|acc, item\\| acc + item)`	`[1, 2, 3]`	`Ok(([3], 3))`	Applies the parser between m and n times (n included) and folds the list of return value
`length_count`	`length_count(number, "ab")`	`"2ababab"`	`Ok(("ab", vec!["ab", "ab"]))`	Gets a number from the first parser, then applies the second parser that many times

eof: Returns its input if it is at the end of input data
Parser::complete_err: Replaces an Incomplete returned by the child parser with an Backtrack

Modifiers

cond: Conditional combinator. Wraps another parser and calls it if the condition is met
Parser::flat_map: method to map a new parser from the output of the first parser, then apply that parser over the rest of the input
Parser::value: method to replace the result of a parser
Parser::map: method to map a function on the result of a parser
Parser::and_then: Applies a second parser over the output of the first one
Parser::verify_map: Maps a function returning an Option on the output of a parser
Parser::map_res: Maps a function returning a Result on the output of a parser
Parser::parse_to: Apply std::str::FromStr to the output of the parser
not: Returns a result only if the embedded parser returns Backtrack or Incomplete. Does not consume the input
opt: Make the underlying parser optional
peek: Returns a result without consuming the input
Parser::recognize: If the child parser was successful, return the consumed input as the produced value
Parser::with_recognized: If the child parser was successful, return a tuple of the consumed input and the produced output.
Parser::span: If the child parser was successful, return the location of the consumed input as the produced value
Parser::with_span: If the child parser was successful, return a tuple of the location of the consumed input and the produced output.
Parser::verify: Returns the result of the child parser if it satisfies a verification function

Error management and debugging

cut_err: Commit the parse result, disallowing alternative parsers from being attempted
backtrack_err: Attemmpts a parse, allowing alternative parsers to be attempted despite use of cut_err
Parser::context: Add context to the error if the parser fails
trace: Print the parse state with the debug feature flag
todo(): Placeholder parser

Remaining combinators

success: Returns a value without consuming any input, always succeeds
fail: Inversion of success. Always fails.
Parser::by_ref: Allow moving &mut impl Parser into other parsers

Text parsing

any: Matches one token
tab: Matches a tab character \t
crlf: Recognizes the string \r\n
line_ending: Recognizes an end of line (both \n and \r\n)
newline: Matches a newline character \n
not_line_ending: Recognizes a string of any char except \r or \n
rest: Return the remaining input
alpha0: Recognizes zero or more lowercase and uppercase alphabetic characters: [a-zA-Z]. alpha1 does the same but returns at least one character
alphanumeric0: Recognizes zero or more numerical and alphabetic characters: [0-9a-zA-Z]. alphanumeric1 does the same but returns at least one character
space0: Recognizes zero or more spaces and tabs. space1 does the same but returns at least one character
multispace0: Recognizes zero or more spaces, tabs, carriage returns and line feeds. multispace1 does the same but returns at least one character
digit0: Recognizes zero or more numerical characters: [0-9]. digit1 does the same but returns at least one character
hex_digit0: Recognizes zero or more hexadecimal numerical characters: [0-9A-Fa-f]. hex_digit1 does the same but returns at least one character
oct_digit0: Recognizes zero or more octal characters: [0-7]. oct_digit1 does the same but returns at least one character
float: Parse a floating point number in a byte string
dec_int: Decode a variable-width, decimal signed integer
dec_uint: Decode a variable-width, decimal unsigned integer
hex_uint: Decode a variable-width, hexadecimal integer
escaped: Matches a byte string with escaped characters
escaped_transform: Matches a byte string with escaped characters, and returns a new string with the escaped characters replaced

Character test functions

Use these functions with a combinator like take_while0:

AsChar::is_alpha: Tests if byte is ASCII alphabetic: [A-Za-z]
AsChar::is_alphanum: Tests if byte is ASCII alphanumeric: [A-Za-z0-9]
AsChar::is_dec_digit: Tests if byte is ASCII digit: [0-9]
AsChar::is_hex_digit: Tests if byte is ASCII hex digit: [0-9A-Fa-f]
AsChar::is_oct_digit: Tests if byte is ASCII octal digit: [0-7]
AsChar::is_space: Tests if byte is ASCII space or tab: [ \t]
AsChar::is_newline: Tests if byte is ASCII newline: [\n]

Binary format parsing

length_data: Gets a number from the first parser, then takes a subslice of the input of that size, and returns that subslice
length_value: Gets a number from the first parser, takes a subslice of the input of that size, then applies the second parser on that subslice. If the second parser returns Incomplete, length_value will return an error

Integers

Parsing integers from binary formats can be done in two ways: With parser functions, or combinators with configurable endianness.

configurable endianness: i16, i32, i64, u16, u32, u64 are combinators that take as argument a winnow::number::Endianness, like this: i16(endianness). If the parameter is winnow::number::Endianness::Big, parse a big endian i16 integer, otherwise a little endian i16 integer.
fixed endianness: The functions are prefixed by be_ for big endian numbers, and by le_ for little endian numbers, and the suffix is the type they parse to. As an example, be_u32 parses a big endian unsigned integer stored in 32 bits.
- be_f32, be_f64: Big endian floating point numbers
- le_f32, le_f64: Little endian floating point numbers
- be_i8, be_i16, be_i24, be_i32, be_i64, be_i128: Big endian signed integers
- be_u8, be_u16, be_u24, be_u32, be_u64, be_u128: Big endian unsigned integers
- le_i8, le_i16, le_i24, le_i32, le_i64, le_i128: Little endian signed integers
- le_u8, le_u16, le_u24, le_u32, le_u64, le_u128: Little endian unsigned integers

Bit stream parsing

bits: Transforms the current input type (byte slice &[u8]) to a bit stream on which bit specific parsers and more general combinators can be applied
bytes: Transforms its bits stream input back into a byte slice for the underlying parser
take: Take a set number of its
tag: Check if a set number of bis matches a pattern
bool: Match any one bit