3 unstable releases
0.2.1 | Jul 14, 2019 |
---|---|
0.2.0 | Jul 14, 2019 |
0.1.0 | Oct 13, 2018 |
#244 in Parser tooling
114 downloads per month
21KB
411 lines
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;
pub fn main() {
named!(parser<&str, Vec<&str>>,
//wrap a parser with tr!() to add a trace point
tr!(preceded!(
tr!(tag!("data: ")),
tr!(delimited!(
tag!("("),
separated_list!(
tr!(tag!(",")),
tr!(nom::digit)
),
tr!(tag!(")"))
))
))
);
println!("parsed: {:?}", parser("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.
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")
.
named!(parser<Vec<&[u8]>>,
//wrap a parser with tr!() to add a trace point
tr!(preceded!(
tag!("data: "),
delimited!(
tag!("("),
separated_list!(
tr!("in list", tag!(",")),
tr!("in list", digit)
),
tag!(")")
)
))
);
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)
}
Dependencies
~1MB
~18K SLoC