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
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
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
filter!	`filter!(&[T] -> bool) => &[T] -> IResult<&[T], &[T]>` returns the longest list of bytes until the provided function fails.
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_not!	`is_not!(&[T:AsBytes]) => &[T] -> IResult<&[T], &[T]>` returns the longest list of bytes that do not appear in the provided array
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
one_of!	matches one of the provided characters
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
pusher!	Prepares a parser function for a push pipeline
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!
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_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_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
FileProducer	Can produce data from a file
MemProducer	Can parse data from an already in memory byte array
ReadProducer	Can produce data from a struct implementing Read
Stepper	Wraps a producer. The `step` method applies a parser and returns its result

Enums

ConsumerState	Holds the current state of the consumer
Err	Contains the error that a parser can return
ErrorCode	indicates which parser returned an error
IResult	Holds the result of parsing functions
Needed	Contains information on needed data if a parser returned `Incomplete`
ProducerState	Holds the data producer's current state
StepperState	Holds the Stepper's current state

Traits

AsBytes
Consumer	Implement the consume method, taking a byte array as input and returning a consumer state
GetInput
GetOutput
HexDisplay	useful functions to calculate the offset between slices and show a hexdump of a slice
Producer	A producer implements the produce method, currently working with u8 arrays

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
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.
sized_buffer
slice_to_offsets
space	Recognizes spaces and tabs
tab
tag_cl
write_color