Module winnow::combinator
source · 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 | new input | output | comment |
---|---|---|---|---|---|
one_of | one_of(['a', 'b', 'c']) | "abc" | "bc" | Ok('a') | Matches one of the provided set of tokens (works with non ASCII characters too) |
none_of | none_of(['a', 'b', 'c']) | "xyab" | "yab" | Ok('x') | Matches anything but one of the provided set of tokens |
literal | "hello" | "hello world" | " world" | Ok("hello") | Recognizes a specific suite of characters or bytes (see also Caseless ) |
take | take(4) | "hello" | "o" | Ok("hell") | Takes a specific number of bytes or characters |
take_while | take_while(0.., is_alphabetic) | "abc123" | "123" | Ok("abc") | Returns the longest slice of bytes or characters for which the provided set of tokens matches. |
take_till | take_till(0.., is_alphabetic) | "123abc" | "abc" | Ok("123") | Returns a slice of bytes or characters until the provided set of tokens matches. This is the reverse behaviour from take_while : take_till(f) is equivalent to take_while(0.., \|c\| !f(c)) |
take_until | take_until(0.., "world") | "Hello world" | "world" | Ok("Hello ") | Returns a slice of bytes or characters until the provided literal is found. |
§Choice combinators
combinator | usage | input | new input | output | comment |
---|---|---|---|---|---|
alt | alt(("ab", "cd")) | "cdef" | "ef" | Ok("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" | "c" | Ok(("ab", "cd", "12")) | Succeeds when all its child parser have succeeded, whatever the order |
§Sequence combinators
combinator | usage | input | new 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 |
seq! | seq!(_: '(', take(2), _: ')') | "(ab)cd" | "cd" | Ok("ab") | |
delimited | delimited('(', take(2), ')') | "(ab)cd" | "cd" | Ok("ab") | |
preceded | preceded("ab", "XY") | "abXYZ" | "Z" | Ok("XY") | |
terminated | terminated("ab", "XY") | "abXYZ" | "Z" | Ok("ab") | |
separated_pair | separated_pair("hello", ',', "world") | "hello,world!" | "!" | Ok(("hello", "world")) |
§Applying a parser multiple times
combinator | usage | input | new input | output | comment |
---|---|---|---|---|---|
repeat | repeat(1..=3, "ab") | "ababc" | "c" | Ok(vec!["ab", "ab"]) | Applies the parser between m and n times (n included) and returns the list of results in a Vec |
repeat_till | repeat_till(0.., "ab", "ef") | "ababefg" | "g" | Ok((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 |
separated | separated(1..=3, "ab", ",") | "ab,ab,ab." | "." | Ok(vec!["ab", "ab", "ab"]) | Applies the parser and separator between m and n times (n included) and returns the list of results in a Vec |
Repeat::fold | `repeat(1..=2, be_u8).fold( | 0, | acc, item | acc + item)` |
§Partial related
eof
: Returns its input if it is at the end of input dataParser::complete_err
: Replaces anIncomplete
returned by the child parser with anBacktrack
§Modifiers
cond
: Conditional combinator. Wraps another parser and calls it if the condition is metParser::flat_map
: method to map a new parser from the output of the first parser, then apply that parser over the rest of the inputParser::value
: method to replace the result of a parserParser::default_value
: method to replace the result of a parserParser::void
: method to discard the result of a parserParser::map
: method to map a function on the result of a parserParser::and_then
: Applies a second parser over the output of the first oneParser::verify_map
: Maps a function returning anOption
on the output of a parserParser::try_map
: Maps a function returning aResult
on the output of a parserParser::parse_to
: Applystd::str::FromStr
to the output of the parsernot
: Returns a result only if the embedded parser returnsBacktrack
orIncomplete
. Does not consume the inputopt
: Make the underlying parser optionalpeek
: Returns a result without consuming the inputParser::recognize
: If the child parser was successful, return the consumed input as the produced valueParser::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 valueParser::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 attemptedbacktrack_err
: Attempts a parse, allowing alternative parsers to be attempted despite use ofcut_err
Parser::context
: Add context to the error if the parser failstrace
: Print the parse state with thedebug
feature flagtodo()
: Placeholder parser
§Remaining combinators
empty
: Returns a value without consuming any input, always succeedsfail
: Inversion ofempty
. 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
-
till_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 -
take_escaped
: Recognize the input slice with escaped characters -
escaped_transform
: Parse escaped characters, unescaping them
§Character test functions
Use these functions with a combinator like take_while
:
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_repeat
Gets a number from the first parser, then applies the second parser that many timeslength_take
: Gets a number from the first parser, then takes a subslice of the input of that size, and returns that subslicelength_and_then
: 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 returnsIncomplete
,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 awinnow::binary::Endianness
, like this:i16(endianness)
. If the parameter iswinnow::binary::Endianness::Big
, parse a big endiani16
integer, otherwise a little endiani16
integer. - fixed endianness: The functions are prefixed by
be_
for big endian numbers, and byle_
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 numbersle_f32
,le_f64
: Little endian floating point numbersbe_i8
,be_i16
,be_i24
,be_i32
,be_i64
,be_i128
: Big endian signed integersbe_u8
,be_u16
,be_u24
,be_u32
,be_u64
,be_u128
: Big endian unsigned integersle_i8
,le_i16
,le_i24
,le_i32
,le_i64
,le_i128
: Little endian signed integersle_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 appliedbytes
: Transforms its bits stream input back into a byte slice for the underlying parsertake
: Take a set number of bitspattern
: Check if a set number of bits matches a patternbool
: Match any one bit
Macros§
match
for parsers- Initialize a struct or tuple out of a sequences of parsers
Structs§
- Implementation of
Parser::and_then
- Implementation of
Parser::by_ref
- Implementation of
Parser::complete_err
- Implementation of
Parser::context
- Implementation of
Parser::default_value
- Implementation of
Parser::err_into
- Implementation of
Parser::flat_map
- Implementation of
Parser::map
- Implementation of
Parser::output_into
- Implementation of
Parser::parse_to
- Main structure associated to
iterator
. - Implementation of
Parser::recognize
- Implementation of
repeat
- Implementation of
Parser::span
- Implementation of
Parser::try_map
- Implementation of
Parser::value
- Implementation of
Parser::verify
- Implementation of
Parser::verify_map
- Implementation of
Parser::void
- Implementation of
Parser::with_recognized
- Implementation of
Parser::with_span
Traits§
- Helper trait for the alt() combinator.
- Helper trait for the permutation() combinator.
Functions§
- Pick the first successful parser
- Transforms an
ErrMode::Cut
(unrecoverable) toErrMode::Backtrack
(recoverable) - Calls the parser if the condition is met.
- Transforms an
ErrMode::Backtrack
(recoverable) toErrMode::Cut
(unrecoverable) - Sequence three parsers, only returning the output of the second.
- Succeed, consuming no input
- Match the end of the
Stream
- A parser which always fails.
- Repeats the embedded parser, filling the given slice with results.
- Repeats the embedded parser, lazily returning the results
- Succeeds if the child parser returns an error.
- Tries to apply its parser without consuming the input.
- Applies a list of parsers in any order.
- Sequence two parsers, only returning the output from the second.
Accumulate
the output of a parser into a container, likeVec
- Return the remaining input.
- Return the length of the remaining input.
Accumulate
the output of a parser, interleaved withsep
- Alternates between two parsers, merging the results (left associative)
- Alternates between two parsers, merging the results (right associative)
- Sequence three parsers, only returning the values of the first and third.
- Sequence two parsers, only returning the output of the first.
- A placeholder for a not-yet-implemented
Parser
- Trace the execution of the parser