https://github.com/dalance/nom-tracable
Extension of nom to trace parser
https://github.com/dalance/nom-tracable
Last synced: 8 months ago
JSON representation
Extension of nom to trace parser
- Host: GitHub
- URL: https://github.com/dalance/nom-tracable
- Owner: dalance
- License: apache-2.0
- Created: 2019-07-26T11:32:35.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2025-02-03T20:28:21.000Z (over 1 year ago)
- Last Synced: 2025-09-01T18:53:21.401Z (10 months ago)
- Language: Rust
- Size: 78.1 KB
- Stars: 49
- Watchers: 3
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# nom-tracable
Extension of [nom](https://github.com/Geal/nom) to trace parser.
[](https://github.com/dalance/nom-tracable/actions)
[](https://crates.io/crates/nom-tracable)
[](https://docs.rs/nom-tracable)
## 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](https://github.com/fflorent/nom_locate).
You can use `nom_locate::LocatedSpan` as input type.
This implements `Tracable` in this crate.
Note: `T` in `nom_locate::LocatedSpan` 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.1"
```
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 nom_locate::LocatedSpan;
use nom_tracable::{cumulative_histogram, histogram, tracable_parser, 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((expr_plus, expr_minus, 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 term_internal(s: Span) -> IResult {
let (s, x) = char('1')(s)?;
Ok((s, x.to_string()))
}
fn main() {
// Configure trace setting
let info = TracableInfo::new().parser_width(64).fold("term");
let ret = expr(LocatedSpan::new_extra("1-1+1+1-1", info));
// Show histogram
histogram();
cumulative_histogram();
}
```
## License
Licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](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.