Expand description
nom-trace
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;
//adds a thread local storage object to store the trace
declare_trace!();
pub fn main() {
named!(parser<Vec<&[u8]>>,
//wrap a parser with tr!() to add a trace point
tr!(preceded!(
tr!(tag!("data: ")),
tr!(delimited!(
tag!("("),
separated_list!(
tr!(tag!(",")),
tr!(digit)
),
tr!(tag!(")"))
))
))
);
println!("parsed: {:?}", parser(&b"data: (1,2,3)"[..]));
// prints the last parser trace
print_trace!();
// the list of trace events can be cleared
reset_trace!();
}
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.
Macros
activates tracing (it is activated by default)
deactivates tracing (it is activated by default)
defines the storage point for trace event
print the trace events to stdout
clears the list of events
wrap a nom parser or combinator with this macro to add a trace point
Structs
the main structure hoding trace events. It must be declared and stored
in a thread level storage variable through the
declare_trace!()
macro