Crate nom [−] [src]
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
#[macro_use] extern crate nom; #[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 { let c = c as u8; (c >= 0x30 && c <= 0x39) || (c >= 0x41 && c <= 0x46) || (c >= 0x61 && c <= 0x66) } named!(hex_primary<&str, u8>, map_res!(take_while_m_n!(2, 2, is_hex_digit), from_hex) ); named!(hex_color<&str, Color>, do_parse!( tag!("#") >> red: hex_primary >> green: hex_primary >> blue: hex_primary >> (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, 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 2.0, please read the migration document.
If you are upgrading to nom 4.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 file and generating the corresponding code, you use very small functions with 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 has 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:
#[macro_use] extern crate nom; named!(parens, delimited!(char!('('), is_not!(")"), char!(')')));
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 macros 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 macros to help in developing parsers.
With macros, you would write it like this:
#[macro_use] extern crate nom; named!(take4, take!(4));
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, Context}; type IResult<I, O, E = u32> = Result<(I, O), Err<I, E>>; enum Err<I, E = u32> { Incomplete(Needed), Error(Context<I, E>), Failure(Context<I, 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 enum that contians an error code with its position in the input, and optionally a chain of accumulated errors; - 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 [documentation][doc] for an exhaustive list of parsers. See also the "choose a combinator" guide**.
Making new parsers with macros
Macros are the main way to make new parsers by combining other ones. Those macros accept other macros or function names as arguments. You then need to make a function out of that combinator with named!
, or a closure with closure!
. Here is how you would do, with the tag!
and take!
combinators:
named!(abcd_parser, tag!("abcd")); // will consume bytes if the input begins with "abcd" named!(take_10, take!(10)); // will consume and return 10 bytes of input
The named!
macro can take three different syntaxes:
named!(my_function( &[u8] ) -> &[u8], tag!("abcd")); named!(my_function<&[u8], &[u8]>, tag!("abcd")); named!(my_function, tag!("abcd")); // when you know the parser takes &[u8] as input, and returns &[u8] as output
IMPORTANT NOTE: Rust's macros can be very sensitive to the syntax, so you may encounter an error compiling parsers like this one:
named!(my_function<&[u8], Vec<&[u8]>>, many0!(tag!("abcd")));
You will get the following error: error: expected an item keyword
. This
happens because >>
is seen as an operator, so the macro parser does not
recognize what we want. There is a way to avoid it, by inserting a space:
named!(my_function<&[u8], Vec<&[u8]> >, many0!(tag!("abcd")));
This will compile correctly. I am very sorry for this inconvenience.
Combining parsers
There are more high 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:
named!(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(error_position!(&b"ijklxxx"[..], nom::ErrorKind::Alt))));
The pipe |
character is used as separator.
The opt!
combinator makes a parser optional. If the child parser returns an error, opt!
will succeed and return None:
named!( abcd_opt< &[u8], Option<&[u8]> >, opt!( tag!("abcd") ) ); 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 std::str; named!(multi< Vec<&str> >, many0!( map_res!(tag!( "abcd" ), str::from_utf8) ) ); let a = b"abcdef"; let b = b"abcdabcdef"; let c = b"azerty"; assert_eq!(multi(a), Ok((&b"ef"[..], vec!["abcd"]))); assert_eq!(multi(b), Ok((&b"ef"[..], vec!["abcd", "abcd"]))); assert_eq!(multi(c), Ok((&b"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 do_parse!
and tuple!
, which are used to apply a series of parsers then assemble their results.
Example with tuple!
:
use nom::{ErrorKind, Needed,be_u16}; named!(tpl<&[u8], (u16, &[u8], &[u8]) >, tuple!( be_u16 , take!(3), 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(error_position!(&input[5..], ErrorKind::Tag))));
Example with do_parse!
:
use nom::IResult; #[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)) } named!(f<&[u8],A>, do_parse!( // the parser takes a byte array as input, and returns an A struct tag!("abcd") >> // begins with "abcd" opt!(tag!("abcd")) >> // this is an optional parser aa: ret_int1 >> // the return value of ret_int1, if it does not fail, will be stored in aa tag!("efgh") >> bb: ret_int2 >> tag!("efgh") >> (A{a: aa, b: bb}) // the final tuple will be able to use the variable defined previously ) ); let r = f(b"abcdabcdefghefghX"); assert_eq!(r, Ok((&b"X"[..], A{a: 1, b: 2}))); let r2 = f(b"abcdefghefghX"); assert_eq!(r2, Ok((&b"X"[..], A{a: 1, b: 2})));
The double right arrow >>
is used as separator between every parser in the sequence, and the last closure can see the variables storing the result of parsers. Unless the specified return type is already a tuple, the final line should be that type wrapped in a tuple.
More examples of do_parse!
and tuple!
usage can be found in the INI file parser example.
Going further: read the guides!
Reexports
pub use self::simple_errors::*; |
pub use self::methods::*; |
pub use self::bits::*; |
pub use self::whitespace::*; |
Modules
bits |
Bit level parsers and combinators |
methods |
Method macro combinators |
simple_errors |
Error management |
types |
Custom input types |
whitespace |
Support for whitespace delimited formats |
Macros
add_return_error |
Add an error if the child parser fails |
alt |
Try a list of parsers and return the result of the first successful one |
alt_complete |
Is equivalent to the |
apply |
emulate function currying: |
apply_m |
emulate function currying for method calls on structs
|
bits |
Transforms its byte slice input into a bit stream for the underlying parser. This allows the given bit stream parser to work on a byte slice input. |
bytes |
Counterpart to bits, bytes! transforms its bit stream input into a byte slice for the underlying parser, allowing byte-slice parsers to work on bit streams. |
call |
Used to wrap common expressions and function as macros |
call_m |
Used to called methods then move self back into self |
char |
matches one character: `char!(char) => &[u8] -> IResult<&[u8], char> |
closure |
Wraps a parser in a closure |
complete |
replaces a |
cond |
|
cond_reduce |
|
cond_with_error |
|
count |
|
count_fixed |
|
dbg |
Prints a message if the parser fails |
dbg_dmp |
Prints a message and the input if the parser fails |
delimited |
|
do_parse |
|
eat_separator |
helper macros to build a separator parser |
eof |
|
error_node_position |
creates a parse error from a |
error_position |
creates a parse error from a |
escaped |
|
escaped_transform |
|
exact |
|
expr_opt |
|
expr_res |
|
fix_error |
translate parser result from IResult to IResult with a custom type |
flat_map |
|
fold_many0 |
|
fold_many1 |
|
fold_many_m_n |
|
i16 |
if the parameter is nom::Endianness::Big, parse a big endian i16 integer, otherwise a little endian i16 integer |
i32 |
if the parameter is nom::Endianness::Big, parse a big endian i32 integer, otherwise a little endian i32 integer |
i64 |
if the parameter is nom::Endianness::Big, parse a big endian i64 integer, otherwise a little endian i64 integer |
is_a |
|
is_a_s |
|
is_not |
|
is_not_s |
|
length_bytes |
|
length_count |
|
length_data |
|
length_value |
|
many0 |
|
many1 |
|
many_m_n |
|
many_till |
|
map |
|
map_opt |
|
map_res |
|
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 |
none_of |
matches anything but the provided characters |
not |
|
one_of |
matches one of the provided characters |
opt |
|
opt_res |
|
pair |
|
parse_to |
|
peek |
|
permutation |
|
preceded |
|
recognize |
|
return_error |
Prevents backtracking if the child parser fails |
sep |
sep is the parser rewriting macro for whitespace separated formats |
separated_list |
|
separated_list_complete |
|
separated_nonempty_list |
|
separated_nonempty_list_complete |
|
separated_pair |
|
switch |
|
tag |
|
tag_bits |
Matches the given bit pattern. |
tag_no_case |
|
tag_no_case_s |
|
tag_s |
|
take |
|
take_bits |
Consumes the specified number of bits and returns them as the specified type. |
take_s |
|
take_str |
|
take_till |
|
take_till1 |
|
take_till1_s |
|
take_till_s |
|
take_until |
|
take_until1 |
|
take_until_and_consume |
|
take_until_and_consume1 |
|
take_until_and_consume_s |
|
take_until_either |
|
take_until_either1 |
|
take_until_either_and_consume |
|
take_until_either_and_consume1 |
|
take_until_s |
|
take_while |
|
take_while1 |
|
take_while1_s |
|
take_while_m_n |
|
take_while_s |
|
tap |
|
terminated |
|
try_parse |
A bit like |
tuple |
|
u16 |
if the parameter is nom::Endianness::Big, parse a big endian u16 integer, otherwise a little endian u16 integer |
u32 |
if the parameter is nom::Endianness::Big, parse a big endian u32 integer, otherwise a little endian u32 integer |
u64 |
if the parameter is nom::Endianness::Big, parse a big endian u64 integer, otherwise a little endian u64 integer |
value |
|
verify |
|
wrap_sep | |
ws |
|
Enums
CompareResult |
indicates wether a comparison was successful, an error, or if more data was needed |
Endianness |
Configurable endianness |
Err |
The |
ErrorKind |
indicates which parser returned an error |
Needed |
Contains information on needed data if a parser returned |
Traits
AsBytes |
casts the input type to a byte slice |
AsChar |
transforms common types to a char for basic token parsing |
AtEof |
indicates whether more data can come later in input |
Compare |
abstracts comparison operations |
Convert | |
ExtendInto |
abtracts something which can extend an |
FindSubstring |
look for a substring in self |
FindToken |
look for self in the given input stream |
HexDisplay | |
InputIter |
abstracts common iteration operations on the input type |
InputLength |
abstract method to calculate the input length |
InputTake |
abstracts slicing operations |
Offset |
useful functions to calculate the offset between slices and show a hexdump of a slice |
ParseTo |
used to integrate str's parse() method |
Slice |
slicing operations using ranges |
Functions
alpha |
Recognizes one or more lowercase and uppercase alphabetic characters: a-zA-Z |
alpha0 |
Recognizes zero or more lowercase and uppercase alphabetic characters: a-zA-Z |
alpha1 |
Recognizes one or more lowercase and uppercase alphabetic characters: a-zA-Z |
alphanumeric |
Recognizes one or more numerical and alphabetic characters: 0-9a-zA-Z |
alphanumeric0 |
Recognizes zero or more numerical and alphabetic characters: 0-9a-zA-Z |
alphanumeric1 |
Recognizes one or more numerical and alphabetic characters: 0-9a-zA-Z |
anychar |
matches one byte as a character. Note that the input type will
accept a |
be_f32 |
Recognizes big endian 4 bytes floating point number |
be_f64 |
Recognizes big endian 8 bytes floating point number |
be_i8 |
Recognizes a signed 1 byte integer (equivalent to take!(1) |
be_i16 |
Recognizes big endian signed 2 bytes integer |
be_i24 |
Recognizes big endian signed 3 bytes integer |
be_i32 |
Recognizes big endian signed 4 bytes integer |
be_i64 |
Recognizes big endian signed 8 bytes integer |
be_u8 |
Recognizes an unsigned 1 byte integer (equivalent to take!(1) |
be_u16 |
Recognizes big endian unsigned 2 bytes integer |
be_u24 |
Recognizes big endian unsigned 3 byte integer |
be_u32 |
Recognizes big endian unsigned 4 bytes integer |
be_u64 |
Recognizes big endian unsigned 8 bytes integer |
begin | |
code_from_offset | |
crlf | |
digit |
Recognizes one or more numerical characters: 0-9 |
digit0 |
Recognizes zero or more numerical characters: 0-9 |
digit1 |
Recognizes one or more numerical characters: 0-9 |
double |
Recognizes floating point number in a byte string and returns a f64 |
double_s |
Recognizes floating point number in a string and returns a f64 |
eol | |
error_to_u32 | |
float |
Recognizes floating point number in a byte string and returns a f32 |
float_s |
Recognizes floating point number in a string and returns a f32 |
hex_digit |
Recognizes one or more hexadecimal numerical characters: 0-9, A-F, a-f |
hex_digit0 |
Recognizes zero or more hexadecimal numerical characters: 0-9, A-F, a-f |
hex_digit1 |
Recognizes one or more hexadecimal numerical characters: 0-9, A-F, a-f |
hex_u32 |
Recognizes a hex-encoded integer |
is_alphabetic |
Tests if byte is ASCII alphabetic: A-Z, a-z |
is_alphanumeric |
Tests if byte is ASCII alphanumeric: A-Z, a-z, 0-9 |
is_digit |
Tests if byte is ASCII digit: 0-9 |
is_hex_digit |
Tests if byte is ASCII hex digit: 0-9, A-F, a-f |
is_oct_digit |
Tests if byte is ASCII octal digit: 0-7 |
is_space |
Tests if byte is ASCII space or tab |
le_f32 |
Recognizes little endian 4 bytes floating point number |
le_f64 |
Recognizes little endian 8 bytes floating point number |
le_i8 |
Recognizes a signed 1 byte integer (equivalent to take!(1) |
le_i16 |
Recognizes little endian signed 2 bytes integer |
le_i24 |
Recognizes little endian signed 3 bytes integer |
le_i32 |
Recognizes little endian signed 4 bytes integer |
le_i64 |
Recognizes little endian signed 8 bytes integer |
le_u8 |
Recognizes an unsigned 1 byte integer (equivalent to take!(1) |
le_u16 |
Recognizes little endian unsigned 2 bytes integer |
le_u24 |
Recognizes little endian unsigned 3 byte integer |
le_u32 |
Recognizes little endian unsigned 4 bytes integer |
le_u64 |
Recognizes little endian unsigned 8 bytes integer |
line_ending |
Recognizes an end of line (both '\n' and '\r\n') |
multispace |
Recognizes one or more spaces, tabs, carriage returns and line feeds |
multispace0 |
Recognizes zero or more spaces, tabs, carriage returns and line feeds |
multispace1 |
Recognizes one or more spaces, tabs, carriage returns and line feeds |
need_more | |
need_more_err | |
newline |
Matches a newline character '\n' |
non_empty |
Recognizes non empty buffers |
not_line_ending | |
oct_digit |
Recognizes one or more octal characters: 0-7 |
oct_digit0 |
Recognizes zero or more octal characters: 0-7 |
oct_digit1 |
Recognizes one or more octal characters: 0-7 |
print_codes | |
recognize_float | |
reset_color | |
rest |
Return the remaining input. |
rest_s |
Return the remaining input, for strings. |
sized_buffer | |
slice_to_offsets | |
space |
Recognizes one or more spaces and tabs |
space0 |
Recognizes zero or more spaces and tabs |
space1 |
Recognizes one or more spaces and tabs |
tab |
Matches a tab character '\t' |
tag_cl | |
write_color |
Type Definitions
IResult |
Holds the result of parsing functions |