Crate nom [] [src]

Nom, eating data byte by byte

The goal is to make a parser combinator library that is safe, supports streaming (push and pull), and as much as possible zero copy.

The code is available on Github

Example

#[macro_use]
extern crate nom;

use nom::{IResult,digit,multispace};
use nom::IResult::*;

// Parser definition

use std::str;
use std::str::FromStr;

named!(parens<i64>, delimited!(
    delimited!(opt!(multispace), tag!("("), opt!(multispace)),
    expr,
    delimited!(opt!(multispace), tag!(")"), opt!(multispace))
  )
);

// We transform an integer string into a i64
// we look for a digit suite, and try to convert it.
// if either str::from_utf8 or FromStr::from_str fail,
// the parser will fail
named!(factor<i64>,
  alt!(
    map_res!(
      map_res!(
        delimited!(opt!(multispace), digit, opt!(multispace)),
        str::from_utf8
      ),
      FromStr::from_str
    )
  | parens
  )
);

// we define acc as mutable to update its value whenever a new term is found
named!(term <i64>,
  chain!(
    mut acc: factor  ~
             many0!(
               alt!(
                 tap!(mul: preceded!(tag!("*"), factor) => acc = acc * mul) |
                 tap!(div: preceded!(tag!("/"), factor) => acc = acc / div)
               )
             ),
    || { return acc }
  )
);

named!(expr <i64>,
  chain!(
    mut acc: term  ~
             many0!(
               alt!(
                 tap!(add: preceded!(tag!("+"), term) => acc = acc + add) |
                 tap!(sub: preceded!(tag!("-"), term) => acc = acc - sub)
               )
             ),
    || { return acc }
  )
);

fn main() {
  assert_eq!(expr(&b" 1 +  2 "[..]),             IResult::Done(&b""[..], 3));
  assert_eq!(expr(&b" 12 + 6 - 4+  3"[..]),      IResult::Done(&b""[..], 17));
  assert_eq!(expr(&b" 1 + 2*3 + 4"[..]),         IResult::Done(&b""[..], 11));

  assert_eq!(expr(&b" (  2 )"[..]),              IResult::Done(&b""[..], 2));
  assert_eq!(expr(&b" 2* (  3 + 4 ) "[..]),      IResult::Done(&b""[..], 14));
  assert_eq!(expr(&b"  2*2 / ( 5 - 1) + 3"[..]), IResult::Done(&b""[..], 4));
}

Macros

alt!

alt!(I -> IResult<I,O> | I -> IResult<I,O> | ... | I -> IResult<I,O> ) => I -> IResult<I, O> try a list of parsers, return the result of the first successful one

alt_parser!

Internal parser, do not use directly

apply!

emulate function currying: apply!(my_function, arg1, arg2, ...) becomes my_function(input, arg1, arg2, ...)

bits!

bits!( parser ) => ( &[u8], (&[u8], usize) -> IResult<(&[u8], usize), T> ) -> IResult<&[u8], T> transforms its byte slice input in a bit stream for the underlying parsers

bits_impl!

Internal parser, do not use directly

call!

Used to wrap common expressions and function as macros

chain!

chain!(I->IResult<I,A> ~ I->IResult<I,B> ~ ... I->IResult<I,X> , || { return O } ) => I -> IResult<I, O> chains parsers and assemble the results through a closure

chaining_parser!

Internal parser, do not use directly

char!

matches one character: `char!(char) => &[u8] -> IResult<&[u8], char>

closure!

Wraps a parser in a closure

cond!

cond!(bool, I -> IResult<I,O>) => I -> IResult<I, Option<O>> Conditional combinator

cond_reduce!

cond_reduce!(bool, I -> IResult<I,O>) => I -> IResult<I, O> Conditional combinator with error

consumer_from_parser!
count!

count!(I -> IResult<I,O>, nb) => I -> IResult<I, Vec<O>> Applies the child parser a specified number of times

count_fixed!

count_fixed!(O, I -> IResult<I,O>, nb) => I -> IResult<I, [O; nb]> 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

dbg!

Prints a message if the parser fails

dbg_dmp!

Prints a message and the input if the parser fails

delimited!

delimited!(I -> IResult<I,T>, I -> IResult<I,O>, I -> IResult<I,U>) => I -> IResult<I, O> delimited(opening, X, closing) returns X

delimited1!

Internal parser, do not use directly

delimited2!

Internal parser, do not use directly

error!

Prevents backtracking if the child parser fails

expr_opt!

expr_opt!(Option<O>) => I -> IResult<I, O> evaluate an expression that returns a Option and returns a IResult::Done(I,T) if Ok

expr_res!

expr_res!(Result<E,O>) => I -> IResult<I, O> evaluate an expression that returns a Result and returns a IResult::Done(I,T) if Ok

flat_map!

flat_map!(R -> IResult<R,S>, S -> IResult<S,T>) => R -> IResult<R, T>

i16!

if parameter is true, parse a big endian i16 integer, otherwise a little endian i16 integer

i32!

if parameter is true, parse a big endian i32 integer, otherwise a little endian i32 integer

i64!

if parameter is true, parse a big endian i64 integer, otherwise a little endian i64 integer

is_a!

is_a!(&[T]) => &[T] -> IResult<&[T], &[T]> returns the longest list of bytes that appear in the provided array

is_a_bytes!
is_not!

is_not!(&[T:AsBytes]) => &[T] -> IResult<&[T], &[T]> returns the longest list of bytes that do not appear in the provided array

is_not_bytes!
length_value!

length_value!(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 times

many0!

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

many1!

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 Vec

map!

map!(I -> IResult<I,O>, O -> P) => I -> IResult<I, P> maps a function on the result of a parser

map_impl!

Internal parser, do not use directly

map_opt!

map_res!(I -> IResult<I,O>, O -> Option<P>) => I -> IResult<I, P> maps a function returning an Option on the output of a parser

map_opt_impl!

Internal parser, do not use directly

map_res!

map_res!(I -> IResult<I,O>, O -> Result<P>) => I -> IResult<I, P> maps a function returning a Result on the output of a parser

map_res_impl!

Internal parser, do not use directly

named!

Makes a function from a parser combination

none_of!

matches anything but the provided characters

none_of_bytes!
one_of!

matches one of the provided characters

one_of_bytes!
opt!

opt!(I -> IResult<I,O>) => I -> IResult<I, Option<O>> make the underlying parser optional

opt_res!

opt_res!(I -> IResult<I,O>) => I -> IResult<I, Result<nom::Err,O>> make the underlying parser optional

pair!

pair!(I -> IResult<I,O>, I -> IResult<I,P>) => I -> IResult<I, (O,P)> pair(X,Y), returns (x,y)

peek!

peek!(I -> IResult<I,O>) => I -> IResult<I, O> returns a result without consuming the input

preceded!

preceded!(I -> IResult<I,T>, I -> IResult<I,O>) => I -> IResult<I, O> preceded(opening, X) returns X

separated_list!

separated_list!(I -> IResult<I,T>, I -> IResult<I,O>) => I -> IResult<I, Vec<O>> separated_list(sep, X) returns Vec

separated_nonempty_list!

separated_nonempty_list!(I -> IResult<I,T>, I -> IResult<I,O>) => I -> IResult<I, Vec<O>> separated_nonempty_list(sep, X) returns Vec

separated_pair!

separated_pair!(I -> IResult<I,O>, I -> IResult<I, T>, I -> IResult<I,P>) => I -> IResult<I, (O,P)> separated_pair(X,sep,Y) returns (x,y)

separated_pair1!

Internal parser, do not use directly

separated_pair2!

Internal parser, do not use directly

switch!

switch!(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

tag!

tag!(&[T]: nom::AsBytes) => &[T] -> IResult<&[T], &[T]> declares a byte array as a suite to recognize

tag_bits!
tag_bytes!
take!

take!(nb) => &[T] -> IResult<&[T], &[T]> generates a parser consuming the specified number of bytes

take_bits!

take_bits!(type, nb) => ( (&[T], usize), U, usize) -> IResult<(&[T], usize), U> generates a parser consuming the specified number of bytes

take_str!

take!(nb) => &[T] -> IResult<&[T], &str> same as take! but returning a &str

take_till!

take_till!(&[T] -> bool) => &[T] -> IResult<&[T], &[T]> returns the longest list of bytes until the provided function succeeds

take_until!

take_until!(tag) => &[T] -> IResult<&[T], &[T]> consumes data until it finds the specified tag

take_until_and_consume!

take_until_and_consume!(tag) => &[T] -> IResult<&[T], &[T]> generates a parser consuming bytes until the specified byte sequence is found, and consumes it

take_until_and_consume_bytes!
take_until_bytes!
take_until_either!

take_until_either!(tag) => &[T] -> IResult<&[T], &[T]>

take_until_either_and_consume!

take_until_either_and_consume!(tag) => &[T] -> IResult<&[T], &[T]> consumes data until it finds any of the specified characters, and consume it

take_until_either_and_consume_bytes!
take_until_either_bytes!
take_while!

take_while!(&[T] -> bool) => &[T] -> IResult<&[T], &[T]> returns the longest list of bytes until the provided function fails.

take_while1!

take_while1!(&[T] -> bool) => &[T] -> IResult<&[T], &[T]> returns the longest (non empty) list of bytes until the provided function fails.

tap!

tap!(name: I -> IResult<I,O> => { block }) => I -> IResult<I, O> allows access to the parser's result without affecting it

terminated!

terminated!(I -> IResult<I,O>, I -> IResult<I,T>) => I -> IResult<I, O> terminated(X, closing) returns X

u16!

if parameter is true, parse a big endian u16 integer, otherwise a little endian u16 integer

u32!

if parameter is true, parse a big endian u32 integer, otherwise a little endian u32 integer

u64!

if parameter is true, parse a big endian u64 integer, otherwise a little endian u64 integer

Structs

AccReader
ChainConsumer

ChainConsumer takes a consumer C1 R -> S, and a consumer C2 S -> T, and makes a consumer R -> T by applying C2 on C1's result

FileProducer
MapConsumer

MapConsumer takes a function S -> T and applies it on a consumer producing values of type S

MemProducer

A MemProducer generates values from an in memory byte buffer

ProducerRepeat

ProducerRepeat takes a single value, and generates it at each step

Enums

ConsumerState

Stores a consumer's current computation state

Err

Contains the error that a parser can return

ErrorKind

indicates which parser returned an error

IResult

Holds the result of parsing functions

Input
Move
Needed

Contains information on needed data if a parser returned Incomplete

Traits

AsBytes
Consumer

The Consumer trait wraps a computation and its state

GetInput
GetOutput
HexDisplay

useful functions to calculate the offset between slices and show a hexdump of a slice

Producer

The producer wraps a data source, like file or network, and applies a consumer on it

Functions

add_error_pattern
alpha

Recognizes lowercase and uppercase alphabetic characters: a-zA-Z

alphanumeric

Recognizes numerical and alphabetic characters: 0-9a-zA-Z

anychar
be_f32

Recognizes big endian 4 bytes floating point number

be_f64

Recognizes big endian 8 bytes floating point number

be_i16

Recognizes big endian signed 2 bytes integer

be_i32

Recognizes big endian signed 4 bytes integer

be_i64

Recognizes big endian signed 8 bytes integer

be_i8

Recognizes a signed 1 byte integer (equivalent to take!(1)

be_u16

Recognizes big endian unsigned 2 bytes integer

be_u32

Recognizes big endian unsigned 4 bytes integer

be_u64

Recognizes big endian unsigned 8 bytes integer

be_u8

Recognizes an unsigned 1 byte integer (equivalent to take!(1)

begin
code_from_offset
compare_error_paths
crlf
digit

Recognizes numerical characters: 0-9

eof

Recognizes empty input buffers

eol
error_to_list
error_to_u32
generate_colors
is_alphabetic
is_alphanumeric
is_digit
is_space
le_i16

Recognizes little endian signed 2 bytes integer

le_i32

Recognizes little endian signed 4 bytes integer

le_i64

Recognizes little endian signed 8 bytes integer

le_i8

Recognizes a signed 1 byte integer (equivalent to take!(1)

le_u16

Recognizes little endian unsigned 2 bytes integer

le_u32

Recognizes little endian unsigned 4 bytes integer

le_u64

Recognizes little endian unsigned 8 bytes integer

le_u8

Recognizes an unsigned 1 byte integer (equivalent to take!(1)

length_value
line_ending

Recognizes a line feed

multispace

Recognizes spaces, tabs, carriage returns and line feeds

newline
not_line_ending
prepare_errors
print
print_codes
print_error
print_offsets
reset_color
rest

Return the remaining input.

shift
sized_buffer
slice_to_offsets
space

Recognizes spaces and tabs

tab
tag_cl
write_color