Module combinator

List of parsers and combinators

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

Links present in this document will nearly always point to complete version of the parser. Most of the parsers also have a streaming version.

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	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_while	take_while(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_till	take_till(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_while: take_till(f) is equivalent to take_while(|c| !f(c))
take_until	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

Choice combinators

combinator	usage	input	output	comment
alt	alt((tag("ab"), tag("cd")))	"cdef"	Ok(("ef", "cd"))	Try a list of parsers and return the result of the first successful one
permutation	permutation(tag("ab"), tag("cd"), tag("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
delimited	delimited(char('('), take(2), char(')'))	"(ab)cd"	Ok(("cd", "ab"))
preceded	preceded(tag("ab"), tag("XY"))	"abXYZ"	Ok(("Z", "XY"))
terminated	terminated(tag("ab"), tag("XY"))	"abXYZ"	Ok(("Z", "ab"))
pair	pair(tag("ab"), tag("XY"))	"abXYZ"	Ok(("Z", ("ab", "XY")))
separated_pair	separated_pair(tag("hello"), char(','), tag("world"))	"hello,world!"	Ok(("!", ("hello", "world")))
(...) (tuples)	(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

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(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
many_m_n	many_m_n(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	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_list0	separated_list0(tag(","), tag("ab"))	"ab,ab,ab."	Ok((".", vec!["ab", "ab", "ab"]))	separated_list1 works like separated_list0 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, 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.

The following parsers could be found on [docs.rs number section][number/complete/index].

• configurable endianness: i16, i32, i64, u16, u32, u64 are combinators that take as argument a [nom8::number::Endianness][number/enum.Endianness], like this: i16(endianness). If the parameter is nom8::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

Streaming related

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

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::map_opt: 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
• not: Returns a result only if the embedded parser returns Error 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

• Parser::context: Add context to the error if the parser fails
• Parser::dbg_err: Prints a message and the input if the parser fails

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, 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

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][crate::bits/::bytes]: Transforms its bits stream input back into a byte slice for the underlying 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

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]

Alternatively there are ready to use functions:

• 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
• any: Matches one token
• crlf: Recognizes the string \r\n
• digit0: Recognizes zero or more numerical characters: [0-9]. digit1 does the same but returns at least one character
• f64: Recognizes floating point number in a byte string and returns a f64
• f32: Recognizes floating point number in a byte string and returns a f32
• hex_digit0: Recognizes zero or more hexadecimal numerical characters: [0-9A-Fa-f]. hex_digit1 does the same but returns at least one character
• hex_u32: Recognizes a hex-encoded integer
• line_ending: Recognizes an end of line (both \n and \r\n)
• multispace0: Recognizes zero or more spaces, tabs, carriage returns and line feeds. multispace1 does the same but returns at least one character
• newline: Matches a newline character \n
• not_line_ending: Recognizes a string of any char except \r or \n
• oct_digit0: Recognizes zero or more octal characters: [0-7]. oct_digit1 does the same but returns at least one character
• rest: Return the remaining input
• space0: Recognizes zero or more spaces and tabs. space1 does the same but returns at least one character
• tab: Matches a tab character \t

Structs

And

Implementation of Parser::and

AndThen

Implementation of Parser::and_then

ByRef

Implementation of Parser::by_ref

Complete

Implementation of Parser::complete

ErrInto

Implementation of Parser::err_into

FlatMap

Implementation of Parser::flat_map

Map

Implementation of Parser::map

MapOpt

Implementation of Parser::map_opt

MapRes

Implementation of Parser::map_res

Or

Implementation of Parser::or

OutputInto

Implementation of Parser::output_into

ParserIterator

Main structure associated to the iterator function.

Recognize

Implementation of Parser::recognize

Span

Implementation of Parser::span

Value

Implementation of Parser::value

Verify

Implementation of Parser::verify

WithRecognized

Implementation of Parser::with_recognized

WithSpan

Implementation of Parser::with_span

Functions

all_consuming

Succeeds if all the input has been consumed by its child parser.

completeDeprecated

Transforms Incomplete into Error.

cond

Calls the parser if the condition is met.

consumedDeprecated

if the child parser was successful, return the consumed input with the output as a tuple. Functions similarly to recognize except it returns the parser output as well.

cut

Transforms an Err::Error (recoverable) to Err::Failure (unrecoverable)

eof

returns its input if it is at the end of input data

fail

A parser which always fails.

flat_mapDeprecated

Creates a new parser from the output of the first parser, then apply that parser over the rest of the input.

intoDeprecated

automatically converts the child parser’s result to another type

iterator

Creates an iterator from input data and a parser.

mapDeprecated

Maps a function on the result of a parser.

map_optDeprecated

Applies a function returning an Option over the result of a parser.

map_parserDeprecated

Applies a parser over the result of another one.

map_resDeprecated

Applies a function returning a Result over the result of a parser.

not

Succeeds if the child parser returns an error.

opt

Optional parser, will return None on Err::Error.

peek

Tries to apply its parser without consuming the input.

recognizeDeprecated

If the child parser was successful, return the consumed input as produced value.

rest

Return the remaining input.

rest_len

Return the length of the remaining input.

success

a parser which always succeeds with given value without consuming any input.

valueDeprecated

Returns the provided value if the child parser succeeds.

verifyDeprecated

Returns the result of the child parser if it satisfies a verification function.