{"id":28547585,"url":"https://github.com/rust-bakery/nom-trace","last_synced_at":"2025-12-12T12:47:34.811Z","repository":{"id":57645548,"uuid":"152865580","full_name":"rust-bakery/nom-trace","owner":"rust-bakery","description":null,"archived":false,"fork":false,"pushed_at":"2019-07-14T14:49:26.000Z","size":20,"stargazers_count":19,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-27T00:22:12.145Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rust-bakery.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-13T11:31:15.000Z","updated_at":"2025-06-10T14:44:07.000Z","dependencies_parsed_at":"2022-09-08T15:11:46.314Z","dependency_job_id":null,"html_url":"https://github.com/rust-bakery/nom-trace","commit_stats":null,"previous_names":["geal/nom-trace"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/rust-bakery/nom-trace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-bakery%2Fnom-trace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-bakery%2Fnom-trace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-bakery%2Fnom-trace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-bakery%2Fnom-trace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rust-bakery","download_url":"https://codeload.github.com/rust-bakery/nom-trace/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-bakery%2Fnom-trace/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264119262,"owners_count":23560351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-10T00:37:24.249Z","updated_at":"2025-10-19T07:22:28.977Z","avatar_url":"https://github.com/rust-bakery.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nom-trace\n\nThis crate provides a way to trace a parser execution,\nstoring positions in the input data, positions in the parser\ntree and parser results.\n\nAs an example, if you run the following code:\n\n```rust\n#[macro_use] extern crate nom;\n#[macro_use] extern crate nom_trace;\n\npub fn main() {\n  named!(parser\u003c\u0026str, Vec\u003c\u0026str\u003e\u003e,\n    //wrap a parser with tr!() to add a trace point\n    tr!(preceded!(\n      tr!(tag!(\"data: \")),\n      tr!(delimited!(\n        tag!(\"(\"),\n        separated_list!(\n          tr!(tag!(\",\")),\n          tr!(nom::digit)\n        ),\n        tr!(tag!(\")\"))\n      ))\n    ))\n  );\n\n  println!(\"parsed: {:?}\", parser(\"data: (1,2,3)\"));\n\n  // prints the last parser trace\n  print_trace!();\n\n  // the list of trace events can be cleared\n  reset_trace!();\n}\n```\n\nYou would get the following result\n```\nparsed: Ok((\"\", [\"1\", \"2\", \"3\"]))\npreceded        \"data: (1,2,3)\"\n\n        tag     \"data: (1,2,3)\"\n\n        -\u003e Ok(\"data: \")\n        delimited       \"(1,2,3)\"\n\n                digit   \"1,2,3)\"\n\n                -\u003e Ok(\"1\")\n                tag     \",2,3)\"\n\n                -\u003e Ok(\",\")\n                digit   \"2,3)\"\n\n                -\u003e Ok(\"2\")\n                tag     \",3)\"\n\n                -\u003e Ok(\",\")\n                digit   \"3)\"\n\n                -\u003e Ok(\"3\")\n                tag     \")\"\n\n                -\u003e Error(Code(\")\", Tag))\n                tag     \")\"\n\n                -\u003e Ok(\")\")\n        -\u003e Ok([\"1\", \"2\", \"3\"])\n-\u003e Ok([\"1\", \"2\", \"3\"])\n```\n\nParser level is indicated through indentation. For each trace point, we have:\n\n- indent level, then parser or combinator name, then input position\n- traces for sub parsers\n- `-\u003e` followed by the parser's result\n\nYou can add intermediate names instead of combinator names for the trace,\nlike this: `tr!(PARENS, delimited!( ... ))`\nthis would replace the name `delimited` in the trace print, with `PARENS`\n\nThis tracer works with parsers based on `\u0026[u8]` and `\u0026str` input types.\nFor `\u0026[u8]`, input positions will be displayed as a hexdump.\n\n\n# Recording multiple traces\n\nUsed directly, macros will record a trace under the \"default\" tag. But\nif you want to record multiple traces at the same time, add a static string\nas first argument.\n\nAs an example, in the following code, the root trace will record in \"default\",\nwhile traces inside the `separated_list` will go in the \"in list\" trace.\n\nYou can then print it by doing `print_trace!(\"in list\")`.\n\n```rust,ignore\n  named!(parser\u003cVec\u003c\u0026[u8]\u003e\u003e,\n    //wrap a parser with tr!() to add a trace point\n    tr!(preceded!(\n      tag!(\"data: \"),\n      delimited!(\n        tag!(\"(\"),\n        separated_list!(\n          tr!(\"in list\", tag!(\",\")),\n          tr!(\"in list\", digit)\n        ),\n        tag!(\")\")\n      )\n   ))\n  );\n```\n\n# nom 5 functions support\n\nThe `tr` function supports the same combinator design as introduced in nom 5.\nUnfortunately, it cannot manipulate its arguments directly from inside the\ncode like macros do, so it must receive explicitely the `tag` argument,\nand a `name` for this trace point (in macros, that name is generated\nfrom a `stringify` call of the argument of `tr!`).\n\nSo using `tr` directly, you would need to to tr(\"default\", \"name\", parser1)`.\nIt is recommended to make you own trace parser, as follows:\n\n```rust,ignore\nfn t\u003cI,O,E,F\u003e(name: \u0026'static str, f: F) -\u003e impl Fn(I) -\u003e IResult\u003cI,O,E\u003e\n  where Input: From\u003cI\u003e,\n        F: Fn(I) -\u003e IResult\u003cI,O,E\u003e,\n        I: Clone,\n        O: Debug,\n        E: Debug {\n  tr(name, f)\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frust-bakery%2Fnom-trace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frust-bakery%2Fnom-trace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frust-bakery%2Fnom-trace/lists"}