1//! # List of parsers and combinators
2//!
3//! <div class="warning">
4//!
5//! **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.
6//!
7//! </div>
8//!
9//! ## Basic elements
10//!
11//! Those are used to take a series of tokens for the lowest level elements of your grammar, like, "here is a dot", or "here is an big endian integer".
12//!
13//! | combinator | usage | input | new input | output | comment |
14//! |---|---|---|---|---|---|
15//! | [`one_of`][crate::token::one_of] | `one_of(['a', 'b', 'c'])` | `"abc"` | `"bc"` | `Ok('a')` |Matches one of the provided [set of tokens][crate::stream::ContainsToken] (works with non ASCII characters too)|
16//! | [`none_of`][crate::token::none_of] | `none_of(['a', 'b', 'c'])` | `"xyab"` | `"yab"` | `Ok('x')` |Matches anything but one of the provided [set of tokens][crate::stream::ContainsToken]|
17//! | [`literal`][crate::token::literal] | `"hello"` | `"hello world"` | `" world"` | `Ok("hello")` |Recognizes a specific suite of characters or bytes (see also [`Caseless`][crate::ascii::Caseless])|
18//! | [`take`][crate::token::take] | `take(4)` | `"hello"` | `"o"` | `Ok("hell")` |Takes a specific number of bytes or characters|
19//! | [`take_while`][crate::token::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][crate::stream::ContainsToken] matches.|
20//! | [`take_till`][crate::token::take_till] | `take_till(0.., is_alphabetic)` | `"123abc"` | `"abc"` | `Ok("123")` |Returns a slice of bytes or characters until the provided [set of tokens][crate::stream::ContainsToken] matches. This is the reverse behaviour from `take_while`: `take_till(f)` is equivalent to `take_while(0.., \|c\| !f(c))`|
21//! | [`take_until`][crate::token::take_until] | `take_until(0.., "world")` | `"Hello world"` | `"world"` | `Ok("Hello ")` |Returns a slice of bytes or characters until the provided [literal][crate::token::literal] is found.|
22//!
23//! ## Choice combinators
24//!
25//! | combinator | usage | input | new input | output | comment |
26//! |---|---|---|---|---|---|
27//! | [`alt`] | `alt(("ab", "cd"))` | `"cdef"` | `"ef"` | `Ok("cd")` |Try a list of parsers and return the result of the first successful one|
28//! | [`dispatch`] | \- | \- | \- | \- | `match` for parsers |
29//! | [`permutation`] | `permutation(("ab", "cd", "12"))` | `"cd12abc"` | `"c"` | `Ok(("ab", "cd", "12"))` |Succeeds when all its child parser have succeeded, whatever the order|
30//!
31//! ## Sequence combinators
32//!
33//! | combinator | usage | input | new input | output | comment |
34//! |---|---|---|---|---|---|
35//! | [`(...)` (tuples)][crate::Parser] | `("ab", "XY", take(1))` | `"abXYZ!"` | `"!"` | `Ok(("ab", "XY", "Z"))` |Parse a series of values|
36//! | [`seq!`] | `seq!(_: '(', take(2), _: ')')` | `"(ab)cd"` | `"cd"` | `Ok("ab")` |Parse a series of values, discarding those you specify|
37//! | [`delimited`] | `delimited('(', take(2), ')')` | `"(ab)cd"` | `"cd"` | `Ok("ab")` |Parse three values, discarding the first and third value|
38//! | [`preceded`] | `preceded("ab", "XY")` | `"abXYZ"` | `"Z"` | `Ok("XY")` |Parse two values, discarding the first value|
39//! | [`terminated`] | `terminated("ab", "XY")` | `"abXYZ"` | `"Z"` | `Ok("ab")` |Parse two values, discarding the second value|
40//! | [`separated_pair`] | `separated_pair("hello", ',', "world")` | `"hello,world!"` | `"!"` | `Ok(("hello", "world"))` | Parse three values, discarding the middle value|
41//!
42//! ## Applying a parser multiple times
43//!
44//! | combinator | usage | input | new input | output | comment |
45//! |---|---|---|---|---|---|
46//! | [`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|
47//! | [`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|
48//! | [`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|
49//! | [`Repeat::fold`] | <code>repeat(1..=2, `be_u8`).fold(\|\| 0, \|acc, item\| acc + item)</code> | `[1, 2, 3]` | `[3]` | `Ok(3)` |Applies the parser between m and n times (n included) and folds the list of return value|
50//!
51//! ## Partial related
52//!
53//! - [`eof`]: Returns its input if it is at the end of input data
54//! - [`Parser::complete_err`]: Replaces an `Incomplete` returned by the child parser with an `Backtrack`
55//!
56//! ## Modifiers
57//!
58//! - [`cond`]: Conditional combinator. Wraps another parser and calls it if the condition is met
59//! - [`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
60//! - [`Parser::value`]: method to replace the result of a parser
61//! - [`Parser::default_value`]: method to replace the result of a parser
62//! - [`Parser::void`]: method to discard the result of a parser
63//! - [`Parser::map`]: method to map a function on the result of a parser
64//! - [`Parser::and_then`]: Applies a second parser over the output of the first one
65//! - [`Parser::verify_map`]: Maps a function returning an `Option` on the output of a parser
66//! - [`Parser::try_map`]: Maps a function returning a `Result` on the output of a parser
67//! - [`Parser::parse_to`]: Apply [`std::str::FromStr`] to the output of the parser
68//! - [`not`]: Returns a result only if the embedded parser returns `Backtrack` or `Incomplete`. Does not consume the input
69//! - [`opt`]: Make the underlying parser optional
70//! - [`peek`]: Returns a result without consuming the input
71//! - [`Parser::take`]: If the child parser was successful, return the consumed input as the produced value
72//! - [`Parser::with_taken`]: If the child parser was successful, return a tuple of the consumed input and the produced output.
73//! - [`Parser::span`]: If the child parser was successful, return the location of the consumed input as the produced value
74//! - [`Parser::with_span`]: If the child parser was successful, return a tuple of the location of the consumed input and the produced output.
75//! - [`Parser::verify`]: Returns the result of the child parser if it satisfies a verification function
76//!
77//! ## Error management and debugging
78//!
79//! - [`cut_err`]: Commit the parse result, disallowing alternative parsers from being attempted
80//! - [`backtrack_err`]: Attempts a parse, allowing alternative parsers to be attempted despite
81//! use of `cut_err`
82//! - [`Parser::context`]: Add context to the error if the parser fails
83//! - [`trace`]: Print the parse state with the `debug` feature flag
84//! - [`todo()`]: Placeholder parser
85//!
86//! ## Remaining combinators
87//!
88//! - [`empty`]: Succeed, consuming no input
89//! - [`fail`]: Inversion of [`empty`]. Always fails.
90//! - [`Parser::by_ref`]: Allow moving `&mut impl Parser` into other parsers
91//!
92//! ## Text parsing
93//!
94//! - [`any`][crate::token::any]: Matches one token
95//! - [`tab`][crate::ascii::tab]: Matches a tab character `\t`
96//! - [`crlf`][crate::ascii::crlf]: Recognizes the string `\r\n`
97//! - [`line_ending`][crate::ascii::line_ending]: Recognizes an end of line (both `\n` and `\r\n`)
98//! - [`newline`][crate::ascii::newline]: Matches a newline character `\n`
99//! - [`till_line_ending`][crate::ascii::till_line_ending]: Recognizes a string of any char except `\r` or `\n`
100//! - [`rest`][crate::token::rest]: Return the remaining input
101//!
102//! - [`alpha0`][crate::ascii::alpha0]: Recognizes zero or more lowercase and uppercase alphabetic characters: `[a-zA-Z]`. [`alpha1`][crate::ascii::alpha1] does the same but returns at least one character
103//! - [`alphanumeric0`][crate::ascii::alphanumeric0]: Recognizes zero or more numerical and alphabetic characters: `[0-9a-zA-Z]`. [`alphanumeric1`][crate::ascii::alphanumeric1] does the same but returns at least one character
104//! - [`space0`][crate::ascii::space0]: Recognizes zero or more spaces and tabs. [`space1`][crate::ascii::space1] does the same but returns at least one character
105//! - [`multispace0`][crate::ascii::multispace0]: Recognizes zero or more spaces, tabs, carriage returns and line feeds. [`multispace1`][crate::ascii::multispace1] does the same but returns at least one character
106//! - [`digit0`][crate::ascii::digit0]: Recognizes zero or more numerical characters: `[0-9]`. [`digit1`][crate::ascii::digit1] does the same but returns at least one character
107//! - [`hex_digit0`][crate::ascii::hex_digit0]: Recognizes zero or more hexadecimal numerical characters: `[0-9A-Fa-f]`. [`hex_digit1`][crate::ascii::hex_digit1] does the same but returns at least one character
108//! - [`oct_digit0`][crate::ascii::oct_digit0]: Recognizes zero or more octal characters: `[0-7]`. [`oct_digit1`][crate::ascii::oct_digit1] does the same but returns at least one character
109//!
110//! - [`float`][crate::ascii::float]: Parse a floating point number in a byte string
111//! - [`dec_int`][crate::ascii::dec_int]: Decode a variable-width, decimal signed integer
112//! - [`dec_uint`][crate::ascii::dec_uint]: Decode a variable-width, decimal unsigned integer
113//! - [`hex_uint`][crate::ascii::hex_uint]: Decode a variable-width, hexadecimal integer
114//!
115//! - [`take_escaped`][crate::ascii::take_escaped]: Recognize the input slice with escaped characters
116//! - [`escaped_transform`][crate::ascii::escaped_transform]: Parse escaped characters, unescaping them
117//!
118//! ### Character test functions
119//!
120//! Use these functions with a combinator like `take_while`:
121//!
122//! - [`AsChar::is_alpha`][crate::stream::AsChar::is_alpha]: Tests if byte is ASCII alphabetic: `[A-Za-z]`
123//! - [`AsChar::is_alphanum`][crate::stream::AsChar::is_alphanum]: Tests if byte is ASCII alphanumeric: `[A-Za-z0-9]`
124//! - [`AsChar::is_dec_digit`][crate::stream::AsChar::is_dec_digit]: Tests if byte is ASCII digit: `[0-9]`
125//! - [`AsChar::is_hex_digit`][crate::stream::AsChar::is_hex_digit]: Tests if byte is ASCII hex digit: `[0-9A-Fa-f]`
126//! - [`AsChar::is_oct_digit`][crate::stream::AsChar::is_oct_digit]: Tests if byte is ASCII octal digit: `[0-7]`
127//! - [`AsChar::is_space`][crate::stream::AsChar::is_space]: Tests if byte is ASCII space or tab: `[ \t]`
128//! - [`AsChar::is_newline`][crate::stream::AsChar::is_newline]: Tests if byte is ASCII newline: `[\n]`
129//!
130//! ## Binary format parsing
131//!
132//! - [`length_repeat`][crate::binary::length_repeat] Gets a number from the first parser, then applies the second parser that many times
133//! - [`length_take`][crate::binary::length_take]: Gets a number from the first parser, then takes a subslice of the input of that size, and returns that subslice
134//! - [`length_and_then`][crate::binary::length_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 returns `Incomplete`, `length_value` will return an error
135//!
136//! ### Integers
137//!
138//! Parsing integers from binary formats can be done in two ways: With parser functions, or combinators with configurable endianness.
139//!
140//! - **configurable endianness:** [`i16`][crate::binary::i16], [`i32`][crate::binary::i32],
141//! [`i64`][crate::binary::i64], [`u16`][crate::binary::u16], [`u32`][crate::binary::u32],
142//! [`u64`][crate::binary::u64] are combinators that take as argument a
143//! [`winnow::binary::Endianness`][crate::binary::Endianness], like this: `i16(endianness)`. If the
144//! parameter is `winnow::binary::Endianness::Big`, parse a big endian `i16` integer, otherwise a
145//! little endian `i16` integer.
146//! - **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.
147//! - [`be_f32`][crate::binary::be_f32], [`be_f64`][crate::binary::be_f64]: Big endian floating point numbers
148//! - [`le_f32`][crate::binary::le_f32], [`le_f64`][crate::binary::le_f64]: Little endian floating point numbers
149//! - [`be_i8`][crate::binary::be_i8], [`be_i16`][crate::binary::be_i16], [`be_i24`][crate::binary::be_i24], [`be_i32`][crate::binary::be_i32], [`be_i64`][crate::binary::be_i64], [`be_i128`][crate::binary::be_i128]: Big endian signed integers
150//! - [`be_u8`][crate::binary::be_u8], [`be_u16`][crate::binary::be_u16], [`be_u24`][crate::binary::be_u24], [`be_u32`][crate::binary::be_u32], [`be_u64`][crate::binary::be_u64], [`be_u128`][crate::binary::be_u128]: Big endian unsigned integers
151//! - [`le_i8`][crate::binary::le_i8], [`le_i16`][crate::binary::le_i16], [`le_i24`][crate::binary::le_i24], [`le_i32`][crate::binary::le_i32], [`le_i64`][crate::binary::le_i64], [`le_i128`][crate::binary::le_i128]: Little endian signed integers
152//! - [`le_u8`][crate::binary::le_u8], [`le_u16`][crate::binary::le_u16], [`le_u24`][crate::binary::le_u24], [`le_u32`][crate::binary::le_u32], [`le_u64`][crate::binary::le_u64], [`le_u128`][crate::binary::le_u128]: Little endian unsigned integers
153//!
154//! ### Bit stream parsing
155//!
156//! - [`bits`][crate::binary::bits::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
157//! - [`bytes`][crate::binary::bits::bytes]: Transforms its bits stream input back into a byte slice for the underlying parser
158//! - [`take`][crate::binary::bits::take]: Take a set number of bits
159//! - [`pattern`][crate::binary::bits::pattern]: Check if a set number of bits matches a pattern
160//! - [`bool`][crate::binary::bits::bool]: Match any one bit
161
162mod branch;
163mod core;
164mod debug;
165mod multi;
166mod sequence;
167
168#[cfg(test)]
169mod tests;
170
171pub mod impls;
172
173pub use self::branch::*;
174pub use self::core::*;
175pub use self::debug::*;
176pub use self::multi::*;
177pub use self::sequence::*;
178
179#[allow(unused_imports)]
180use crate::Parser;
181