3 unstable releases

0.2.1 Jul 14, 2019
0.2.0 Jul 14, 2019
0.1.0 Oct 13, 2018

#248 in Parser tooling

Download history 8/week @ 2024-02-19 32/week @ 2024-02-26 9/week @ 2024-03-04 9/week @ 2024-03-11 10/week @ 2024-03-18 4/week @ 2024-03-25 76/week @ 2024-04-01

101 downloads per month

MIT license

411 lines


This crate provides a way to trace a parser execution, storing positions in the input data, positions in the parser tree and parser results.

As an example, if you run the following code:

#[macro_use] extern crate nom;
#[macro_use] extern crate nom_trace;

pub fn main() {
  named!(parser<&str, Vec<&str>>,
    //wrap a parser with tr!() to add a trace point
      tr!(tag!("data: ")),

  println!("parsed: {:?}", parser("data: (1,2,3)"));

  // prints the last parser trace

  // the list of trace events can be cleared

You would get the following result

parsed: Ok(("", ["1", "2", "3"]))
preceded        "data: (1,2,3)"

        tag     "data: (1,2,3)"

        -> Ok("data: ")
        delimited       "(1,2,3)"

                digit   "1,2,3)"

                -> Ok("1")
                tag     ",2,3)"

                -> Ok(",")
                digit   "2,3)"

                -> Ok("2")
                tag     ",3)"

                -> Ok(",")
                digit   "3)"

                -> Ok("3")
                tag     ")"

                -> Error(Code(")", Tag))
                tag     ")"

                -> Ok(")")
        -> Ok(["1", "2", "3"])
-> Ok(["1", "2", "3"])

Parser level is indicated through indentation. For each trace point, we have:

  • indent level, then parser or combinator name, then input position
  • traces for sub parsers
  • -> followed by the parser's result

You can add intermediate names instead of combinator names for the trace, like this: tr!(PARENS, delimited!( ... )) this would replace the name delimited in the trace print, with PARENS

This tracer works with parsers based on &[u8] and &str input types. For &[u8], input positions will be displayed as a hexdump.

Recording multiple traces

Used directly, macros will record a trace under the "default" tag. But if you want to record multiple traces at the same time, add a static string as first argument.

As an example, in the following code, the root trace will record in "default", while traces inside the separated_list will go in the "in list" trace.

You can then print it by doing print_trace!("in list").

    //wrap a parser with tr!() to add a trace point
      tag!("data: "),
          tr!("in list", tag!(",")),
          tr!("in list", digit)

nom 5 functions support

The tr function supports the same combinator design as introduced in nom 5. Unfortunately, it cannot manipulate its arguments directly from inside the code like macros do, so it must receive explicitely the tag argument, and a name for this trace point (in macros, that name is generated from a stringify call of the argument of tr!).

So using tr directly, you would need to to tr("default", "name", parser1)`. It is recommended to make you own trace parser, as follows:

fn t<I,O,E,F>(name: &'static str, f: F) -> impl Fn(I) -> IResult<I,O,E>
  where Input: From<I>,
        F: Fn(I) -> IResult<I,O,E>,
        I: Clone,
        O: Debug,
        E: Debug {
  tr(name, f)


~15K SLoC