{"owner":"antlr","repo":"grammars-v4","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# Claude Notes\n\n@GLOSSARY.md\n\n## Trash Toolkit\n\nThe Trash Toolkit is a collection of .NET tools for working with Antlr4 grammars.\nSource and documentation: https://github.com/kaby76/Trash\n\nThe tools are declared in `.config/dotnet-tools.json` at the repo root and must be\nrestored once before use (or after a fresh clone):\n\n```sh\ncd <repo-root>       # i.e. the grammars-v4 clone root\ndotnet tool restore\n```\n\nThis installs all `tr*` tools (`trgen`, `trwdog`, `trperf`, `trglob`, `triconv`,\n`trparse`, `trquery`, `trxml2`, etc.) as local .NET tools available via `dotnet <toolname>`.\n\n## Testing a Grammar\n\nTo test a grammar (e.g. `csharp/v8-spec`), follow these steps from the repo root.\n\n**1. Restore the Trash Toolkit (once per clone), and note location:**\n\n```sh\ndotnet tool restore\ncloneroot=`pwd`\n```\n\n**2. Generate the C# sandbox:**\n\n```sh\ncd csharp/v8-spec\ndotnet trash gen -t CSharp\n```\n\n`trgen` reads `desc.xml` in the current directory for grammar and test configuration,\ndiscovers all `.g4` files, resolves their dependencies, and writes the complete driver\napplication into `Generated-CSharp/`.\n\n> **trgen rules:**\n> - Only ever use `-t <target>` — no other options (no `--template-sources-directory`, etc.).\n> - Always run `dotnet trash gen` from the directory that contains `desc.xml` (the grammar dir).\n> - Never run it from the repo root or any other directory.\n> - For Java: `dotnet trash gen -t Java` → generates `Generated-Java/`.\n\n**3. Build the driver:**\n\n```sh\ncd Generated-CSharp\nbash build.sh\n```\n\n`build.sh` runs `antlr4` to regenerate the lexer/parser C# sources from the `.g4`\nfiles, then `dotnet build` to compile the driver. You will need to install prerequisites\nfor building and compiling the generated driver.\n\n**4. Run the test suite, and test individual parses:**\n\n```sh\nbash test.sh\n```\n\n`test.sh` parses all example files listed in `desc.xml`, writes `.tree` and `.errors`\nfiles alongside the inputs, and diffs them against the committed baselines. It prints\n`Test succeeded.` on success or `Test failed.` with a diff on failure.\n\n```sh\nbash run.sh *.txt\n```\n\n`run.sh` parses individual files.\n\n## Maven Antlr4 Tester (old/Java-based)\n\nEach grammar directory contains a `pom.xml` that uses the `antlr4test-maven-plugin`.\nFor the `pom.xml` format, see https://maven.apache.org/guides/introduction/introduction-to-the-pom.html.\n\n**Test a single grammar:**\n\n```sh\ncd <grammar-dir>   # directory containing pom.xml\nmvn clean test\n```\n\n**Test all grammars:**\n\n```sh\ncd <repo-root>\nmvn clean test\n```\n\n**Test only grammars changed in a PR:**\n\n```sh\n_scripts/maven.sh <before-git-sha> <after-git-sha>\n```\n\n### Common Maven test failure: \"no errors found, but errors file exists\"\n\nThis happens when zero-length `.errors` files (generated by the Trash Toolkit test runner)\nare left in the examples directory. The Maven plugin treats any `.errors` file as a baseline\nthat expects parse failures, so if parsing succeeds it fails the test.\n\nFix: delete only the zero-length `.errors` files from the test directory (check `pom.xml` for\n`<exampleFiles>` to confirm the directory; default is `examples/`):\n\n```sh\nfind examples/ -name \"*.errors\" -size 0 -delete\n```\n\nThis is safer than `git clean -f .`, which would remove *all* untracked files (including any\nnew test inputs you've added but not yet staged with `git add`).\n\n### Common Maven test failure: unexpected file extensions in examples/\n\nIf people add test inputs or documentation into `examples/` with extensions that the plugin\ndoesn't expect, the plugin may try to parse them and fail. This is caused by not specifying\n`<testFileExtension>` in `pom.xml`. Check the `pom.xml` for that element; if it's absent,\nthe plugin will attempt to parse every file in the examples directory.\n\n## Checking for Ambiguity (Trash Toolkit / C# target)\n\nThe generated C# test harness is in `.../Generated-CSharp/`.\n\n**Build** (only needed once, or after grammar changes):\n\n```sh\ncd Generated-CSharp\nbash build.sh\n```\n\n**Check a single file for ambiguity:**\n\nUsing the built binary directly:\n\n```sh\n./bin/Debug/net10.0/Test.exe --ambig <file>\n```\n\nThe `--ambig` flag enables ANTLR's profiling mode. After parsing, it reports every\nATN decision where more than one alternative was viable for the actual input (a true\ngrammar ambiguity). For each ambiguity it prints all distinct parse trees, one per\nline, prefixed with `d=<decision>.a=<alt>` (e.g. `d=195.a=1`, `d=195.a=2`).\n\n**Restrict output to specific decisions:**\n\n```sh\n./bin/Debug/net10.0/Test.exe --ambig=195,42 <file>\n```\n\n**Limit the number of parse trees returned:**\n\n```sh\n./bin/Debug/net10.0/Test.exe --ambig --limit=4 <file>\n```\n\n**Using trparse/trtree to show ambiguities:**\n\n```sh\ndotnet trash parse --ambig <file> | dotnet trash tree\n```\n"},"files":{"CLAUDE.md":"# Claude Notes\n\n@GLOSSARY.md\n\n## Trash Toolkit\n\nThe Trash Toolkit is a collection of .NET tools for working with Antlr4 grammars.\nSource and documentation: https://github.com/kaby76/Trash\n\nThe tools are declared in `.config/dotnet-tools.json` at the repo root and must be\nrestored once before use (or after a fresh clone):\n\n```sh\ncd <repo-root>       # i.e. the grammars-v4 clone root\ndotnet tool restore\n```\n\nThis installs all `tr*` tools (`trgen`, `trwdog`, `trperf`, `trglob`, `triconv`,\n`trparse`, `trquery`, `trxml2`, etc.) as local .NET tools available via `dotnet <toolname>`.\n\n## Testing a Grammar\n\nTo test a grammar (e.g. `csharp/v8-spec`), follow these steps from the repo root.\n\n**1. Restore the Trash Toolkit (once per clone), and note location:**\n\n```sh\ndotnet tool restore\ncloneroot=`pwd`\n```\n\n**2. Generate the C# sandbox:**\n\n```sh\ncd csharp/v8-spec\ndotnet trash gen -t CSharp\n```\n\n`trgen` reads `desc.xml` in the current directory for grammar and test configuration,\ndiscovers all `.g4` files, resolves their dependencies, and writes the complete driver\napplication into `Generated-CSharp/`.\n\n> **trgen rules:**\n> - Only ever use `-t <target>` — no other options (no `--template-sources-directory`, etc.).\n> - Always run `dotnet trash gen` from the directory that contains `desc.xml` (the grammar dir).\n> - Never run it from the repo root or any other directory.\n> - For Java: `dotnet trash gen -t Java` → generates `Generated-Java/`.\n\n**3. Build the driver:**\n\n```sh\ncd Generated-CSharp\nbash build.sh\n```\n\n`build.sh` runs `antlr4` to regenerate the lexer/parser C# sources from the `.g4`\nfiles, then `dotnet build` to compile the driver. You will need to install prerequisites\nfor building and compiling the generated driver.\n\n**4. Run the test suite, and test individual parses:**\n\n```sh\nbash test.sh\n```\n\n`test.sh` parses all example files listed in `desc.xml`, writes `.tree` and `.errors`\nfiles alongside the inputs, and diffs them against the committed baselines. It prints\n`Test succeeded.` on success or `Test failed.` with a diff on failure.\n\n```sh\nbash run.sh *.txt\n```\n\n`run.sh` parses individual files.\n\n## Maven Antlr4 Tester (old/Java-based)\n\nEach grammar directory contains a `pom.xml` that uses the `antlr4test-maven-plugin`.\nFor the `pom.xml` format, see https://maven.apache.org/guides/introduction/introduction-to-the-pom.html.\n\n**Test a single grammar:**\n\n```sh\ncd <grammar-dir>   # directory containing pom.xml\nmvn clean test\n```\n\n**Test all grammars:**\n\n```sh\ncd <repo-root>\nmvn clean test\n```\n\n**Test only grammars changed in a PR:**\n\n```sh\n_scripts/maven.sh <before-git-sha> <after-git-sha>\n```\n\n### Common Maven test failure: \"no errors found, but errors file exists\"\n\nThis happens when zero-length `.errors` files (generated by the Trash Toolkit test runner)\nare left in the examples directory. The Maven plugin treats any `.errors` file as a baseline\nthat expects parse failures, so if parsing succeeds it fails the test.\n\nFix: delete only the zero-length `.errors` files from the test directory (check `pom.xml` for\n`<exampleFiles>` to confirm the directory; default is `examples/`):\n\n```sh\nfind examples/ -name \"*.errors\" -size 0 -delete\n```\n\nThis is safer than `git clean -f .`, which would remove *all* untracked files (including any\nnew test inputs you've added but not yet staged with `git add`).\n\n### Common Maven test failure: unexpected file extensions in examples/\n\nIf people add test inputs or documentation into `examples/` with extensions that the plugin\ndoesn't expect, the plugin may try to parse them and fail. This is caused by not specifying\n`<testFileExtension>` in `pom.xml`. Check the `pom.xml` for that element; if it's absent,\nthe plugin will attempt to parse every file in the examples directory.\n\n## Checking for Ambiguity (Trash Toolkit / C# target)\n\nThe generated C# test harness is in `.../Generated-CSharp/`.\n\n**Build** (only needed once, or after grammar changes):\n\n```sh\ncd Generated-CSharp\nbash build.sh\n```\n\n**Check a single file for ambiguity:**\n\nUsing the built binary directly:\n\n```sh\n./bin/Debug/net10.0/Test.exe --ambig <file>\n```\n\nThe `--ambig` flag enables ANTLR's profiling mode. After parsing, it reports every\nATN decision where more than one alternative was viable for the actual input (a true\ngrammar ambiguity). For each ambiguity it prints all distinct parse trees, one per\nline, prefixed with `d=<decision>.a=<alt>` (e.g. `d=195.a=1`, `d=195.a=2`).\n\n**Restrict output to specific decisions:**\n\n```sh\n./bin/Debug/net10.0/Test.exe --ambig=195,42 <file>\n```\n\n**Limit the number of parse trees returned:**\n\n```sh\n./bin/Debug/net10.0/Test.exe --ambig --limit=4 <file>\n```\n\n**Using trparse/trtree to show ambiguities:**\n\n```sh\ndotnet trash parse --ambig <file> | dotnet trash tree\n```\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# Claude Notes\n\n@GLOSSARY.md\n\n## Trash Toolkit\n\nThe Trash Toolkit is a collection of .NET tools for working with Antlr4 grammars.\nSource and documentation: https://github.com/kaby76/Trash\n\nThe tools are declared in `.config/dotnet-tools.json` at the repo root and must be\nrestored once before use (or after a fresh clone):\n\n```sh\ncd <repo-root>       # i.e. the grammars-v4 clone root\ndotnet tool restore\n```\n\nThis installs all `tr*` tools (`trgen`, `trwdog`, `trperf`, `trglob`, `triconv`,\n`trparse`, `trquery`, `trxml2`, etc.) as local .NET tools available via `dotnet <toolname>`.\n\n## Testing a Grammar\n\nTo test a grammar (e.g. `csharp/v8-spec`), follow these steps from the repo root.\n\n**1. Restore the Trash Toolkit (once per clone), and note location:**\n\n```sh\ndotnet tool restore\ncloneroot=`pwd`\n```\n\n**2. Generate the C# sandbox:**\n\n```sh\ncd csharp/v8-spec\ndotnet trash gen -t CSharp\n```\n\n`trgen` reads `desc.xml` in the current directory for grammar and test configuration,\ndiscovers all `.g4` files, resolves their dependencies, and writes the complete driver\napplication into `Generated-CSharp/`.\n\n> **trgen rules:**\n> - Only ever use `-t <target>` — no other options (no `--template-sources-directory`, etc.).\n> - Always run `dotnet trash gen` from the directory that contains `desc.xml` (the grammar dir).\n> - Never run it from the repo root or any other directory.\n> - For Java: `dotnet trash gen -t Java` → generates `Generated-Java/`.\n\n**3. Build the driver:**\n\n```sh\ncd Generated-CSharp\nbash build.sh\n```\n\n`build.sh` runs `antlr4` to regenerate the lexer/parser C# sources from the `.g4`\nfiles, then `dotnet build` to compile the driver. You will need to install prerequisites\nfor building and compiling the generated driver.\n\n**4. Run the test suite, and test individual parses:**\n\n```sh\nbash test.sh\n```\n\n`test.sh` parses all example files listed in `desc.xml`, writes `.tree` and `.errors`\nfiles alongside the inputs, and diffs them against the committed baselines. It prints\n`Test succeeded.` on success or `Test failed.` with a diff on failure.\n\n```sh\nbash run.sh *.txt\n```\n\n`run.sh` parses individual files.\n\n## Maven Antlr4 Tester (old/Java-based)\n\nEach grammar directory contains a `pom.xml` that uses the `antlr4test-maven-plugin`.\nFor the `pom.xml` format, see https://maven.apache.org/guides/introduction/introduction-to-the-pom.html.\n\n**Test a single grammar:**\n\n```sh\ncd <grammar-dir>   # directory containing pom.xml\nmvn clean test\n```\n\n**Test all grammars:**\n\n```sh\ncd <repo-root>\nmvn clean test\n```\n\n**Test only grammars changed in a PR:**\n\n```sh\n_scripts/maven.sh <before-git-sha> <after-git-sha>\n```\n\n### Common Maven test failure: \"no errors found, but errors file exists\"\n\nThis happens when zero-length `.errors` files (generated by the Trash Toolkit test runner)\nare left in the examples directory. The Maven plugin treats any `.errors` file as a baseline\nthat expects parse failures, so if parsing succeeds it fails the test.\n\nFix: delete only the zero-length `.errors` files from the test directory (check `pom.xml` for\n`<exampleFiles>` to confirm the directory; default is `examples/`):\n\n```sh\nfind examples/ -name \"*.errors\" -size 0 -delete\n```\n\nThis is safer than `git clean -f .`, which would remove *all* untracked files (including any\nnew test inputs you've added but not yet staged with `git add`).\n\n### Common Maven test failure: unexpected file extensions in examples/\n\nIf people add test inputs or documentation into `examples/` with extensions that the plugin\ndoesn't expect, the plugin may try to parse them and fail. This is caused by not specifying\n`<testFileExtension>` in `pom.xml`. Check the `pom.xml` for that element; if it's absent,\nthe plugin will attempt to parse every file in the examples directory.\n\n## Checking for Ambiguity (Trash Toolkit / C# target)\n\nThe generated C# test harness is in `.../Generated-CSharp/`.\n\n**Build** (only needed once, or after grammar changes):\n\n```sh\ncd Generated-CSharp\nbash build.sh\n```\n\n**Check a single file for ambiguity:**\n\nUsing the built binary directly:\n\n```sh\n./bin/Debug/net10.0/Test.exe --ambig <file>\n```\n\nThe `--ambig` flag enables ANTLR's profiling mode. After parsing, it reports every\nATN decision where more than one alternative was viable for the actual input (a true\ngrammar ambiguity). For each ambiguity it prints all distinct parse trees, one per\nline, prefixed with `d=<decision>.a=<alt>` (e.g. `d=195.a=1`, `d=195.a=2`).\n\n**Restrict output to specific decisions:**\n\n```sh\n./bin/Debug/net10.0/Test.exe --ambig=195,42 <file>\n```\n\n**Limit the number of parse trees returned:**\n\n```sh\n./bin/Debug/net10.0/Test.exe --ambig --limit=4 <file>\n```\n\n**Using trparse/trtree to show ambiguities:**\n\n```sh\ndotnet trash parse --ambig <file> | dotnet trash tree\n```\n","category":"root","tokens":1193}]}