Expand description
nom, eating data byte by byte
nom is a parser combinator library with a focus on safe parsing, streaming patterns, and as much as possible zero copy.
Example
extern crate nom;
use nom::{
IResult,
bytes::complete::{tag, take_while_m_n},
combinator::map_res,
sequence::tuple};
#[derive(Debug,PartialEq)]
pub struct Color {
pub red: u8,
pub green: u8,
pub blue: u8,
}
fn from_hex(input: &str) -> Result<u8, std::num::ParseIntError> {
u8::from_str_radix(input, 16)
}
fn is_hex_digit(c: char) -> bool {
c.is_digit(16)
}
fn hex_primary(input: &str) -> IResult<&str, u8> {
map_res(
take_while_m_n(2, 2, is_hex_digit),
from_hex
)(input)
}
fn hex_color(input: &str) -> IResult<&str, Color> {
let (input, _) = tag("#")(input)?;
let (input, (red, green, blue)) = tuple((hex_primary, hex_primary, hex_primary))(input)?;
Ok((input, Color { red, green, blue }))
}
fn main() {
assert_eq!(hex_color("#2F14DF"), Ok(("", Color {
red: 47,
green: 20,
blue: 223,
})));
}
The code is available on Github
There are a few guides with more details about the design of nom macros, how to write parsers, or the error management system.
Looking for a specific combinator? Read the “choose a combinator” guide
If you are upgrading to nom 5.0, please read the migration document.
See also the FAQ.
Parser combinators
Parser combinators are an approach to parsers that is very different from software like lex and yacc. Instead of writing the grammar in a separate syntax and generating the corresponding code, you use very small functions with a very specific purpose, like “take 5 bytes”, or “recognize the word ‘HTTP’”, and assemble then in meaningful patterns like “recognize ‘HTTP’, then a space, then a version”. The resulting code is small, and looks like the grammar you would have written with other parser approaches.
This gives us a few advantages:
- the parsers are small and easy to write
- the parsers components are easy to reuse (if they’re general enough, please add them to nom!)
- the parsers components are easy to test separately (unit tests and property-based tests)
- the parser combination code looks close to the grammar you would have written
- you can build partial parsers, specific to the data you need at the moment, and ignore the rest
Here is an example of one such parser, to recognize text between parentheses:
use nom::{
IResult,
sequence::delimited,
// see the "streaming/complete" paragraph lower for an explanation of these submodules
character::complete::char,
bytes::complete::is_not
};
fn parens(input: &str) -> IResult<&str, &str> {
delimited(char('('), is_not(")"), char(')'))(input)
}
It defines a function named parens
which will recognize a sequence of the
character (
, the longest byte array not containing )
, then the character
)
, and will return the byte array in the middle.
Here is another parser, written without using nom’s combinators this time:
#[macro_use]
extern crate nom;
use nom::{IResult, Err, Needed};
fn take4(i: &[u8]) -> IResult<&[u8], &[u8]>{
if i.len() < 4 {
Err(Err::Incomplete(Needed::Size(4)))
} else {
Ok((&i[4..], &i[0..4]))
}
}
This function takes a byte array as input, and tries to consume 4 bytes. Writing all the parsers manually, like this, is dangerous, despite Rust’s safety features. There are still a lot of mistakes one can make. That’s why nom provides a list of function and macros to help in developing parsers.
With functions, you would write it like this:
use nom::{IResult, bytes::streaming::take};
fn take4(input: &str) -> IResult<&str, &str> {
take(4u8)(input)
}
With macros, you would write it like this:
#[macro_use]
extern crate nom;
named!(take4, take!(4));
nom has used macros for combinators from versions 1 to 4, and from version 5, it proposes new combinators as functions, but still allows the macros style (macros have been rewritten to use the functions under the hood). For new parsers, we recommend using the functions instead of macros, since rustc messages will be much easier to understand.
A parser in nom is a function which, for an input type I
, an output type O
and an optional error type E
, will have the following signature:
fn parser(input: I) -> IResult<I, O, E>;
Or like this, if you don’t want to specify a custom error type (it will be u32
by default):
fn parser(input: I) -> IResult<I, O>;
IResult
is an alias for the Result
type:
use nom::{Needed, error::ErrorKind};
type IResult<I, O, E = (I,ErrorKind)> = Result<(I, O), Err<E>>;
enum Err<E> {
Incomplete(Needed),
Error(E),
Failure(E),
}
It can have the following values:
- a correct result
Ok((I,O))
with the first element being the remaining of the input (not parsed yet), and the second the output value; - an error
Err(Err::Error(c))
withc
an error that can be built from the input position and a parser specific error - an error
Err(Err::Incomplete(Needed))
indicating that more input is necessary.Needed
can indicate how much data is needed - an error
Err(Err::Failure(c))
. It works like theError
case, except it indicates an unrecoverable error: we cannot backtrack and test another parser
Please refer to the “choose a combinator” guide for an exhaustive list of parsers. See also the rest of the documentation here. .
Making new parsers with function combinators
nom is based on functions that generate parsers, with a signature like
this: (arguments) -> impl Fn(Input) -> IResult<Input, Output, Error>
.
The arguments of a combinator can be direct values (like take
which uses
a number of bytes or character as argument) or even other parsers (like
delimited
which takes as argument 3 parsers, and returns the result of
the second one if all are successful).
Here are some examples:
use nom::IResult;
use nom::bytes::complete::{tag, take};
fn abcd_parser(i: &str) -> IResult<&str, &str> {
tag("abcd")(i) // will consume bytes if the input begins with "abcd"
}
fn take_10(i: &[u8]) -> IResult<&[u8], &[u8]> {
take(10u8)(i) // will consume and return 10 bytes of input
}
Combining parsers
There are higher level patterns, like the alt
combinator, which
provides a choice between multiple parsers. If one branch fails, it tries
the next, and returns the result of the first parser that succeeds:
use nom::IResult;
use nom::branch::alt;
use nom::bytes::complete::tag;
let alt_tags = alt((tag("abcd"), tag("efgh")));
assert_eq!(alt_tags(&b"abcdxxx"[..]), Ok((&b"xxx"[..], &b"abcd"[..])));
assert_eq!(alt_tags(&b"efghxxx"[..]), Ok((&b"xxx"[..], &b"efgh"[..])));
assert_eq!(alt_tags(&b"ijklxxx"[..]), Err(nom::Err::Error((&b"ijklxxx"[..], nom::error::ErrorKind::Tag))));
The opt
combinator makes a parser optional. If the child parser returns
an error, opt
will still succeed and return None:
use nom::{IResult, combinator::opt, bytes::complete::tag};
fn abcd_opt(i: &[u8]) -> IResult<&[u8], Option<&[u8]>> {
opt(tag("abcd"))(i)
}
assert_eq!(abcd_opt(&b"abcdxxx"[..]), Ok((&b"xxx"[..], Some(&b"abcd"[..]))));
assert_eq!(abcd_opt(&b"efghxxx"[..]), Ok((&b"efghxxx"[..], None)));
many0
applies a parser 0 or more times, and returns a vector of the aggregated results:
use nom::{IResult, multi::many0, bytes::complete::tag};
use std::str;
fn multi(i: &str) -> IResult<&str, Vec<&str>> {
many0(tag("abcd"))(i)
}
let a = "abcdef";
let b = "abcdabcdef";
let c = "azerty";
assert_eq!(multi(a), Ok(("ef", vec!["abcd"])));
assert_eq!(multi(b), Ok(("ef", vec!["abcd", "abcd"])));
assert_eq!(multi(c), Ok(("azerty", Vec::new())));
Here are some basic combining macros available:
opt
: will make the parser optional (if it returns theO
type, the new parser returnsOption<O>
)many0
: will apply the parser 0 or more times (if it returns theO
type, the new parser returnsVec<O>
)many1
: will apply the parser 1 or more times
There are more complex (and more useful) parsers like tuple!
, which is
used to apply a series of parsers then assemble their results.
Example with tuple
:
use nom::{error::ErrorKind, Needed,
number::streaming::be_u16,
bytes::streaming::{tag, take},
sequence::tuple};
let tpl = tuple((be_u16, take(3u8), tag("fg")));
assert_eq!(
tpl(&b"abcdefgh"[..]),
Ok((
&b"h"[..],
(0x6162u16, &b"cde"[..], &b"fg"[..])
))
);
assert_eq!(tpl(&b"abcde"[..]), Err(nom::Err::Incomplete(Needed::Size(2))));
let input = &b"abcdejk"[..];
assert_eq!(tpl(input), Err(nom::Err::Error((&input[5..], ErrorKind::Tag))));
But you can also use a sequence of combinators written in imperative style,
thanks to the ?
operator:
use nom::{IResult, bytes::complete::tag};
#[derive(Debug, PartialEq)]
struct A {
a: u8,
b: u8
}
fn ret_int1(i:&[u8]) -> IResult<&[u8], u8> { Ok((i,1)) }
fn ret_int2(i:&[u8]) -> IResult<&[u8], u8> { Ok((i,2)) }
fn f(i: &[u8]) -> IResult<&[u8], A> {
// if successful, the parser returns `Ok((remaining_input, output_value))` that we can destructure
let (i, _) = tag("abcd")(i)?;
let (i, a) = ret_int1(i)?;
let (i, _) = tag("efgh")(i)?;
let (i, b) = ret_int2(i)?;
Ok((i, A { a, b }))
}
let r = f(b"abcdefghX");
assert_eq!(r, Ok((&b"X"[..], A{a: 1, b: 2})));
Streaming / Complete
Some of nom’s modules have streaming
or complete
submodules. They hold
different variants of the same combinators.
A streaming parser assumes that we might not have all of the input data. This can happen with some network protocol or large file parsers, where the input buffer can be full and need to be resized or refilled.
A complete parser assumes that we already have all of the input data. This will be the common case with small files that can be read intirely to memory.
Here is how it works in practice:
use nom::{IResult, Err, Needed, error::ErrorKind, bytes, character};
fn take_streaming(i: &[u8]) -> IResult<&[u8], &[u8]> {
bytes::streaming::take(4u8)(i)
}
fn take_complete(i: &[u8]) -> IResult<&[u8], &[u8]> {
bytes::complete::take(4u8)(i)
}
// both parsers will take 4 bytes as expected
assert_eq!(take_streaming(&b"abcde"[..]), Ok((&b"e"[..], &b"abcd"[..])));
assert_eq!(take_complete(&b"abcde"[..]), Ok((&b"e"[..], &b"abcd"[..])));
// if the input is smaller than 4 bytes, the streaming parser
// will return `Incomplete` to indicate that we need more data
assert_eq!(take_streaming(&b"abc"[..]), Err(Err::Incomplete(Needed::Size(4))));
// but the complete parser will return an error
assert_eq!(take_complete(&b"abc"[..]), Err(Err::Error((&b"abc"[..], ErrorKind::Eof))));
// the alpha0 function recognizes 0 or more alphabetic characters
fn alpha0_streaming(i: &str) -> IResult<&str, &str> {
character::streaming::alpha0(i)
}
fn alpha0_complete(i: &str) -> IResult<&str, &str> {
character::complete::alpha0(i)
}
// if there's a clear limit to the recognized characters, both parsers work the same way
assert_eq!(alpha0_streaming("abcd;"), Ok((";", "abcd")));
assert_eq!(alpha0_complete("abcd;"), Ok((";", "abcd")));
// but when there's no limit, the streaming version returns `Incomplete`, because it cannot
// know if more input data should be recognized. The whole input could be "abcd;", or
// "abcde;"
assert_eq!(alpha0_streaming("abcd"), Err(Err::Incomplete(Needed::Size(1))));
// while the complete version knows that all of the data is there
assert_eq!(alpha0_complete("abcd"), Ok(("", "abcd")));
Going further: read the guides!
Re-exports
Modules
std
or core
/alloc
. This is how serde
does
it, albeit there it is not public.Macros
Incomplete
returned by the child parser
with an Error
cond!(bool, I -> IResult<I,O>) => I -> IResult<I, Option<O>>
Conditional combinatorcount!(I -> IResult<I,O>, nb) => I -> IResult<I, Vec<O>>
Applies the child parser a specified number of timesdelimited!(I -> IResult<I,T>, I -> IResult<I,O>, I -> IResult<I,U>) => I -> IResult<I, O>
delimited(opening, X, closing) returns Xdo_parse!(I->IResult<I,A> >> I->IResult<I,B> >> ... I->IResult<I,X> , ( O ) ) => I -> IResult<I, O>
do_parse applies sub parsers in a sequence.
it can store intermediary results and make them available
for later parserseof!()
returns its input if it is at the end of input datanom::ErrorKind
,
the position in the input and the next error in
the parsing tree.nom::ErrorKind
and the position in the inputescaped!(T -> IResult<T, T>, U, T -> IResult<T, T>) => T -> IResult<T, T> where T: InputIter, U: AsChar
matches a byte string with escaped characters.escaped_transform!(&[T] -> IResult<&[T], &[T]>, T, &[T] -> IResult<&[T], &[T]>) => &[T] -> IResult<&[T], Vec<T>>
matches a byte string with escaped characters.exact!()
will fail if the child parser does not consume the whole dataflat_map!(R -> IResult<R,S>, S -> IResult<S,T>) => R -> IResult<R, T>
fold_many0!(I -> IResult<I,O>, R, Fn(R, O) -> R) => I -> IResult<I, R>
Applies the parser 0 or more times and folds the list of return valuesfold_many1!(I -> IResult<I,O>, R, Fn(R, O) -> R) => I -> IResult<I, R>
Applies the parser 1 or more times and folds the list of return valuesfold_many_m_n!(usize, usize, I -> IResult<I,O>, R, Fn(R, O) -> R) => I -> IResult<I, R>
Applies the parser between m and n times (n included) and folds the list of return valueis_a!(&[T]) => &[T] -> IResult<&[T], &[T]>
returns the longest list of bytes that appear in the provided arrayis_not!(&[T:AsBytes]) => &[T] -> IResult<&[T], &[T]>
returns the longest list of bytes that do not appear in the provided arraylength_count!(I -> IResult<I, nb>, I -> IResult<I,O>) => I -> IResult<I, Vec<O>>
gets a number from the first parser, then applies the second parser that many timeslength_data!(I -> IResult<I, nb>) => O
length_value!(I -> IResult<I, nb>, I -> IResult<I,O>) => I -> IResult<I, O>
many0!(I -> IResult<I,O>) => I -> IResult<I, Vec<O>>
Applies the parser 0 or more times and returns the list of results in a Vec.many0_count!(I -> IResult<I,O>) => I -> IResult<I, usize>
Applies the parser 0 or more times and returns the number of times the parser was applied.many1!(I -> IResult<I,O>) => I -> IResult<I, Vec<O>>
Applies the parser 1 or more times and returns the list of results in a Vecmany1_count!(I -> IResult<I,O>) => I -> IResult<I, usize>
Applies the parser 1 or more times and returns the number of times the parser was applied.many_m_n!(usize, usize, I -> IResult<I,O>) => I -> IResult<I, Vec<O>>
Applies the parser between m and n times (n included) and returns the list of
results in a Vecmany_till!(I -> IResult<I,O>, I -> IResult<I,P>) => I -> IResult<I, (Vec<O>, P)>
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.map!(I -> IResult<I, O>, O -> P) => I -> IResult<I, P>
map_opt!(I -> IResult<I, O>, O -> Option<P>) => I -> IResult<I, P>
maps a function returning an Option on the output of a parsermap_res!(I -> IResult<I, O>, O -> Result<P>) => I -> IResult<I, P>
maps a function returning a Result on the output of a parsernot!(I -> IResult<I,O>) => I -> IResult<I, ()>
returns a result only if the embedded parser returns Error or Err(Err::Incomplete)
does not consume the inputopt!(I -> IResult<I,O>) => I -> IResult<I, Option<O>>
make the underlying parser optionalopt_res!(I -> IResult<I,O>) => I -> IResult<I, Result<nom::Err,O>>
make the underlying parser optionalpair!(I -> IResult<I,O>, I -> IResult<I,P>) => I -> IResult<I, (O,P)>
pair returns a tuple of the results of its two child parsers of both succeedparse_to!(O) => I -> IResult<I, O>
uses the parse
method from std::str::FromStr
to convert the current
input to the specified typepeek!(I -> IResult<I,O>) => I -> IResult<I, O>
returns a result without consuming the inputpermutation!(I -> IResult<I,A>, I -> IResult<I,B>, ... I -> IResult<I,X> ) => I -> IResult<I, (A,B,...X)>
applies its sub parsers in a sequence, but independent from their order
this parser will only succeed if all of its sub parsers succeedpreceded!(I -> IResult<I,T>, I -> IResult<I,O>) => I -> IResult<I, O>
preceded returns the result of its second parser if both succeedre_bytes_capture!(regexp) => &[T] -> IResult<&[T], Vec<&[T]>>
Returns the first capture groupre_bytes_capture_static!(regexp) => &[T] -> IResult<&[T], Vec<&[T]>>
Returns the first capture group. Regular expression calculated at compile timere_bytes_captures!(regexp) => &[T] -> IResult<&[T], Vec<Vec<&[T]>>>
Returns all the capture groupsre_bytes_captures_static!(regexp) => &[T] -> IResult<&[T], Vec<Vec<&[T]>>>
Returns all the capture groups. Regular expression calculated at compile timere_bytes_find!(regexp) => &[T] -> IResult<&[T], &[T]>
Returns the first matchre_bytes_find!(regexp) => &[T] -> IResult<&[T], &[T]>
Returns the first match. Regular expression calculated at compile timere_bytes_match!(regexp) => &[T] -> IResult<&[T], &[T]>
Returns the whole input if a match is foundre_bytes_match_static!(regexp) => &[T] -> IResult<&[T], &[T]>
Returns the whole input if a match is found. Regular expression calculated at compile timere_bytes_matches!(regexp) => &[T] -> IResult<&[T], Vec<&[T]>>
Returns all the matched partsre_bytes_matches_static!(regexp) => &[T] -> IResult<&[T], Vec<&[T]>>
Returns all the matched parts. Regular expression calculated at compile timere_capture!(regexp) => &[T] -> IResult<&[T], Vec<&[T]>>
Returns the first capture groupre_capture_static!(regexp) => &[T] -> IResult<&[T], Vec<&[T]>>
Returns the first capture group. Regular expression calculated at compile timere_captures!(regexp) => &[T] -> IResult<&[T], Vec<Vec<&[T]>>>
Returns all the capture groupsre_captures_static!(regexp) => &[T] -> IResult<&[T], Vec<Vec<&[T]>>>
Returns all the capture groups. Regular expression calculated at compile timere_find!(regexp) => &[T] -> IResult<&[T], &[T]>
Returns the first matchre_find_static!(regexp) => &[T] -> IResult<&[T], &[T]>
Returns the first match. Regular expression calculated at compile timere_match!(regexp) => &[T] -> IResult<&[T], &[T]>
Returns the whole input if a match is foundre_match_static!(regexp) => &[T] -> IResult<&[T], &[T]>
Returns the whole input if a match is found. Regular expression calculated at compile timere_matches!(regexp) => &[T] -> IResult<&[T], Vec<&[T]>>
Returns all the matched partsre_matches_static!(regexp) => &[T] -> IResult<&[T], Vec<&[T]>>
Returns all the matched parts. Regular expression calculated at compile timerecognize!(I -> IResult<I, O> ) => I -> IResult<I, I>
if the child parser was successful, return the consumed input as produced valueseparated_list!(I -> IResult<I,T>, I -> IResult<I,O>) => I -> IResult<I, Vec<O>>
separated_list(sep, X) returns a Vecseparated_nonempty_list!(I -> IResult<I,T>, I -> IResult<I,O>) => I -> IResult<I, Vec<O>>
separated_nonempty_list(sep, X) returns a Vecseparated_pair!(I -> IResult<I,O>, I -> IResult<I, T>, I -> IResult<I,P>) => I -> IResult<I, (O,P)>
separated_pair(X,sep,Y) returns a tuple of its first and third child parsers
if all 3 succeedswitch!(I -> IResult<I,P>, P => I -> IResult<I,O> | ... | P => I -> IResult<I,O> ) => I -> IResult<I, O>
choose the next parser depending on the result of the first one, if successful,
and returns the result of the second parsertag!(&[T]: nom::AsBytes) => &[T] -> IResult<&[T], &[T]>
declares a byte array as a suite to recognizetag_no_case!(&[T]) => &[T] -> IResult<&[T], &[T]>
declares a case insensitive ascii string as a suite to recognizetake!(nb) => &[T] -> IResult<&[T], &[T]>
generates a parser consuming the specified number of bytestake_str!(nb) => &[T] -> IResult<&[T], &str>
same as take! but returning a &strtake_till!(T -> bool) => &[T] -> IResult<&[T], &[T]>
returns the longest list of bytes until the provided function succeedstake_till1!(T -> bool) => &[T] -> IResult<&[T], &[T]>
returns the longest non empty list of bytes until the provided function succeedstake_until!(tag) => &[T] -> IResult<&[T], &[T]>
consumes data until it finds the specified tag.take_until1!(tag) => &[T] -> IResult<&[T], &[T]>
consumes data (at least one byte) until it finds the specified tagtake_while!(T -> bool) => &[T] -> IResult<&[T], &[T]>
returns the longest list of bytes until the provided function fails.take_while1!(T -> bool) => &[T] -> IResult<&[T], &[T]>
returns the longest (non empty) list of bytes until the provided function fails.take_while_m_n!(m: usize, n: usize, T -> bool) => &[T] -> IResult<&[T], &[T]>
returns a list of bytes or characters for which the provided function returns true.
the returned list’s size will be at least m, and at most ntap!(name: I -> IResult<I,O> => { block }) => I -> IResult<I, O>
allows access to the parser’s result without affecting itterminated!(I -> IResult<I,O>, I -> IResult<I,T>) => I -> IResult<I, O>
terminated returns the result of its first parser if both succeedstd::try!
, this macro will return the remaining input and
parsed value if the child parser returned Ok
, and will do an early
return for the Err
side.tuple!(I->IResult<I,A>, I->IResult<I,B>, ... I->IResult<I,X>) => I -> IResult<I, (A, B, ..., X)>
chains parsers and assemble the sub results in a tuple.value!(T, R -> IResult<R, S> ) => R -> IResult<R, T>
verify!(I -> IResult<I, O>, O -> bool) => I -> IResult<I, O>
returns the result of the child parser if it satisfies a verification functionws!(I -> IResult<I,O>) => I -> IResult<I, O>
Enums
Err
enum indicates the parser was not successfulIncomplete
Traits
Extend
used to build modified input slices in escaped_transform
InputTakeAtPosition
).