| `one_of!("abc")` | `"abc"` | `Ok(("bc", 'a'))`|matches one of the provided characters (works with non ASCII characters too)|
| `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!("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!(4)` | `"hello"` | `Ok( ("o", "hell") )`|takes a specific number of bytes or characters|
| `take_while!(is_alphabetic)` | `"abc123"` | `Ok( ("123", "abc") )`| returns the longest list of bytes for which the provided function returns true. `take_while1` does the same, but must return at least one character|
| `take_till!(is_alphabetic)` | `"123abc"` | `Ok( ("abc", "123) )`|returns the longest list of bytes or characters until the provided function returns true. `take_till1` does the same, but must return at least one character. This is the reverse behaviour from `take_while`: `take_till!(f)` is equivalent to `take_while!(|c| !f(c))`|
| `take_until!("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|
| `take_until_and_consume!("world")` | `"Hello world!"` | `Ok( ("!", "Hello ") )`| same as `take_until` but consumes the tag. `take_until_and_consume1` does the same, but must return at least one character|
| `take_until_either!` | `` | ``|DEPRECATED? returns the longest list of bytes until any of the provided characters are found|
| `take_until_either_and_consume` | `` | ``|DEPRECATED? same as take_until_either!, but consumes the terminating character|
| `value!(42, tag!("abcd"))` |`"abcdef"` | `Ok( ("ef", 42) )`|replaces the result of the clid parser with the provided value. Can also be used without a child parser. `value!(42)` would return the `42` value without consuming the input|
| `alt!(tag!("ab") \| tag!("cd"))` | `"cdef"` | `Ok( ("ef", "cd") )`|try a list of parsers and return the result of the first successful one|
| `switch!(take!(2), "ab" => tag!("XYZ") \| "cd" => tag!("123"))` | `"cd1234"` | `Ok(("4", "123"))`|choose the next parser depending on the result of the first one, if successful, and returns the result of the second parser|
| `permutation!(tag!("ab"), tag!("cd"), tag!("12"))` | `"cd12abc"` | `Ok( ("c", ("ab", "cd", "12") )`|succeeds when all its child parser have succeeded, whatever the order|
| `tuple!(tag!("ab"), tag!("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|
| `do_parse!(tag: take!(2) >> length: be_u8 >> data: take!(length) >> (Buffer { tag: tag, data: data}) )` | `&[0, 0, 3, 1, 2, 3][..]` | `Buffer { tag: &[0, 0][..], data: &[1, 2, 3][..] }`|`do_parse` applies sub parsers in a sequence. it can store intermediary results and make them available for later parsers|
## Applying a parser multiple times
| usage | input | output | comment |
|---|---|---|---|
| `count!(take!(2), 3)` | `"abcdefgh"` | `Ok( ("gh", vec!("ab", "cd", "ef")) )`|applies the child parser a specified number of times|
| `count!(&[u8], take!(2), 3)` | `"abcdefgh"` | `Ok( ("gh", ["ab", "cd", "ef"]))`|applies the child parser a fixed number of times and returns a fixed size array. The type must be specified and it must be `Copy`|
| `many0!(tag!("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|
| `many0!(1, 3, tag!("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_till!( 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.|
| `separated_list!(tag!(","), tag!("ab"))` | `"ab,ab,ab."` | `Ok( (".", vec!("ab", "ab", "ab")) )`|`separated_nonempty_list` works like `separated_list` but must returns at least one element|
| `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!(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!(number, tag!("ab"))` | `"2ababab"` | `Ok( ("ab", vec!("ab", "ab")) )`|gets a number from the first parser, then applies the second parser that many times|
## 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 nom::Endianness, like this: i16!(endianness). If the parameter is nom::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, le_f32, le_f64**: recognize floating point numbers
- **be_i8, be_i16, be_i32, be_i24, be_i32, be_i64**: big endian signed integers
eof!: eof!() returns its input if it is at the end of input data
complete!: replaces a Incomplete returned by the child parser with an Error
alt_complete!: is equivalent to the alt! combinator, except that it will not returns Incomplete when one of the constituting parsers returns Incomplete. Instead, it will try the next alternative in the chain.
separated_list_complete!: This is equivalent to the separated_list! combinator, except that it will return Error when either the separator or element subparser returns Incomplete.
separated_nonempty_list_complete!: This is equivalent to the separated_nonempty_list! combinator, except that it will return Error when either the separator or element subparser returns Incomplete.
## Modifiers
| usage | input | output | comment |
|---|---|---|---|
| `` | `` | ``||
| `` | `` | ``||
| `` | `` | ``||
| `` | `` | ``||
| `` | `` | ``||
cond!: conditional combinator
cond_reduce!: Conditional combinator with error
cond_with_error!: Conditional combinator
expr_opt!: evaluates an expression that returns a Option and returns a Ok((I,T)) if Some
expr_res!: evaluates an expression that returns a Result and returns a Ok((I,T)) if Ok
flat_map!:
map!: maps a function on the result of a parser
map_opt!: maps a function returning an Option on the output of a parser
map_res!: maps a function returning a Result on the output of a parser
not!: returns a result only if the embedded parser returns Error or Incomplete does not consume the input
opt!: make the underlying parser optional
opt_res!: make the underlying parser optional
parse_to!: uses the parse method from std::str::FromStr to convert the current input to the specified type
peek!: returns a result without consuming the input
recognize!: if the child parser was successful, return the consumed input as produced value
return_error!: prevents backtracking if the child parser fails
tap!: allows access to the parser's result without affecting it
verify!: returns the result of the child parser if it satisfies a verification function
Error management and debugging
add_return_error!: Add an error if the child parser fails
dbg!: Prints a message if the parser fails
dbg_dmp!: Prints a message and the input if the parser fails
error_code!: creates a parse error from a nom::ErrorKind
error_node!: creates a parse error from a nom::ErrorKind and the next error in the parsing tree. if "verbose-errors" is not activated, it default to only the error code
error_node_position!: creates a parse error from a nom::ErrorKind, the position in the input and the next error in the parsing tree. if "verbose-errors" is not activated, it default to only the error code
error_position!: creates a parse error from a nom::ErrorKind and the position in the input if "verbose-errors" is not activated, it default to only the error code
fix_error!: translate parser result from IResult to IResult with a custom type
## Text parsing
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
## Binary format parsing
length_data!: gets a number from the first parser, than takes a subslice of the input of that size, and returns that subslice
length_bytes!: alias for length_data
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
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 parsers.
tag_bits!: matches an integer pattern to a bitstream. The number of bits of the input to compare must be specified
take_bits!: generates a parser consuming the specified number of bits
Whitespace delimited formats parsing
eat_separator!: helper macros to build a separator parser
sep!: sep is the parser rewriting macro for whitespace separated formats
apply_m!: emulate function currying for method calls on structs apply_m!(self.my_function, arg1, arg2, ...) becomes self.my_function(input, arg1, arg2, ...)
call!: Used to wrap common expressions and function as macros
call_m!: Used to called methods then move self back into self
closure!: Wraps a parser in a closure
method!: Makes a method from a parser combination
named!: Makes a function from a parser combination
named_args!: Makes a function from a parser combination with arguments.
named_attr!: Makes a function from a parser combination, with attributes
try_parse!: A bit like std::try!, this macro will return the remaining input and parsed value if the child parser returned Ok, and will do an early return for Error and Incomplete this can provide more flexibility than do_parse! if needed
## Character test functions
use those functions with a combinator like take_while!:
