nom-tracable

Extension of nom to trace parser.

Feature

• Tracing parser by colored format
• Forward/backward call count
• Folding the specific parsers
• Histogram/cumulative histogram of parser call count
• Zero-overhead when trace is disabled

Requirement

nom must be 5.0.0 or later. nom-tracable can be applied to function-style parser only.

The input type of nom parser must implement Tracable trait. Therefore &str and &[u8] can't be used. You can define a wrapper type of &str or &[u8] and implement Tracable.

nom-tracable is integrated with nom_locate. You can use nom_locate::LocatedSpan<T, TracableInfo> as input type. This implements Tracable in this crate.

Note: T in nom_locate::LocatedSpan<T, TracableInfo> must implement FragmentDisplay. &str and &[u8] implement it in this crate. If you want to use another type as T, you should implement FragmentDisplay for it.

Usage

```Cargo.toml [features] default = [] trace = ["nom-tracable/trace"]

[dependencies] nom-tracable = "0.9.0" ```

nom-tracable provides trace feature, and the crate using nom-tracable must provide the feature too. When trace is enabled, trace dump is enabled. If not, there is no additional cost.

Example

You can try examples by the following command.

$ cargo run --manifest-path=nom-tracable/Cargo.toml --example str_parser --features trace $ cargo run --manifest-path=nom-tracable/Cargo.toml --example u8_parser --features trace

str_parser is below:

```rust use nom::branch::; use nom::character::complete::; use nom::IResult; use nomlocate::LocatedSpan; use nomtracable::{cumulativehistogram, histogram, tracableparser, TracableInfo};

// Input type must implement trait Tracable // nom_locate::LocatedSpan implements it. type Span<'a> = LocatedSpan<&'a str, TracableInfo>;

// Apply tracable_parser by custom attribute

[tracable_parser]

pub fn expr(s: Span) -> IResult { alt((exprplus, exprminus, term))(s) }

[tracable_parser]

pub fn expr_plus(s: Span) -> IResult { let (s, x) = term(s)?; let (s, y) = char('+')(s)?; let (s, z) = expr(s)?; let ret = format!("{}{}{}", x, y, z); Ok((s, ret)) }

[tracable_parser]

pub fn expr_minus(s: Span) -> IResult { let (s, x) = term(s)?; let (s, y) = char('-')(s)?; let (s, z) = expr(s)?; let ret = format!("{}{}{}", x, y, z); Ok((s, ret)) }

[tracable_parser]

pub fn term(s: Span) -> IResult { let (s, x) = term_internal(s)?; Ok((s, x)) }

[tracable_parser]

pub fn terminternal(s: Span) -> IResult { let (s, x) = char('1')(s)?; Ok((s, x.tostring())) }

fn main() { // Configure trace setting let info = TracableInfo::new().parserwidth(64).fold("term"); let ret = expr(LocatedSpan::newextra("1-1+1+1-1", info));

// Show histogram
histogram();
cumulative_histogram();

} ```

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.