{"id":13668015,"url":"https://github.com/rrevenantt/antlr4rust","last_synced_at":"2025-05-15T17:07:40.405Z","repository":{"id":41104670,"uuid":"206076919","full_name":"rrevenantt/antlr4rust","owner":"rrevenantt","description":"ANTLR4 parser generator runtime for Rust programming laguage ","archived":false,"fork":false,"pushed_at":"2023-02-14T07:25:34.000Z","size":621,"stargazers_count":433,"open_issues_count":30,"forks_count":71,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-05-08T14:46:51.643Z","etag":null,"topics":["antlr4","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rrevenantt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-09-03T12:54:21.000Z","updated_at":"2025-05-06T14:05:05.000Z","dependencies_parsed_at":"2024-01-14T16:16:38.805Z","dependency_job_id":"7b3bf432-a4a2-4580-91a7-339a7e9f69c6","html_url":"https://github.com/rrevenantt/antlr4rust","commit_stats":{"total_commits":77,"total_committers":5,"mean_commits":15.4,"dds":"0.051948051948051965","last_synced_commit":"360bc024234ad9037b51fbfded93f7d3c914d15d"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrevenantt%2Fantlr4rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrevenantt%2Fantlr4rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrevenantt%2Fantlr4rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrevenantt%2Fantlr4rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rrevenantt","download_url":"https://codeload.github.com/rrevenantt/antlr4rust/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384988,"owners_count":22062422,"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":["antlr4","rust"],"created_at":"2024-08-02T07:00:59.619Z","updated_at":"2025-05-15T17:07:35.397Z","avatar_url":"https://github.com/rrevenantt.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# antlr4rust\n[![Crate](https://flat.badgen.net/crates/v/antlr-rust)](https://crates.io/crates/antlr_rust/0.3.0-beta)\n[![docs](https://flat.badgen.net/badge/docs.rs/v0.3.0-beta)](https://docs.rs/antlr-rust/0.3.0-beta)\n![ANTLR4 testsuite](https://github.com/rrevenantt/antlr4rust/workflows/ANTLR4%20testsuite/badge.svg?event=push)\n![cargo test](https://github.com/rrevenantt/antlr4rust/workflows/cargo%20test/badge.svg)\n[![](https://tokei.rs/b1/github/rrevenantt/antlr4rust)](https://github.com/rrevenantt/antlr4rust)\n\n[ANTLR4](https://github.com/antlr/antlr4) runtime for Rust programming language.\n\nFor examples you can see [grammars](grammars), [tests/gen](tests/gen) for corresponding generated code \nand [tests/my_tests.rs](tests/my_test.rs) for actual usage examples\n\n## ANTLR4 Tool(parser generator)\n\nGenerator part is currently located in rust-target branch of my antlr4 fork [rrevenantt/antlr4/tree/rust-target](https://github.com/rrevenantt/antlr4/tree/rust-target)\nLatest version is automatically built to [releases](https://github.com/rrevenantt/antlr4rust/releases) on this repository.\nSo if you just want to generate parser \nor if you want to contribute to only runtime part you don't have to do build it yourself. \n\nBut if you want to build or change generator yourself:\n* `git clone -b rust-target https://github.com/rrevenantt/antlr4` - clone my antlr4 fork  \n* `git submodule update --init --recursive --remote` - update Rust target submodule\n* `mvn -DskipTests install` - build generator\n\n### Implementation status\n\nFor now development is going on in this repository \nbut eventually it will be merged to main ANTLR4 repo\n\nSince version `0.3` works on stable rust.\nPrevious versions are not maintained any more \nso in case of nightly breakage you should migrate to the latest version. \n\n### Usage\n\nYou should use the ANTLR4 \"tool\" to generate a parser, that will use the ANTLR \nruntime located here. You can run it with the following command:\n```bash\njava -jar \u003cpath to ANTLR4 tool\u003e -Dlanguage=Rust MyGrammar.g4\n```\nFor a full list of antlr4 tool options, please visit the \n[tool documentation page](https://github.com/antlr/antlr4/blob/master/doc/tool-options.md).\n\nYou can also see [build.rs](build.rs) as an example of `build.rs` configuration \nto rebuild parser automatically if grammar file was changed.\n\nThen add following to `Cargo.toml` of the crate from which generated parser \nis going to be used:\n```toml \n[dependencies]\nantlr-rust = \"0.3\"\n```\n \n### Parse Tree structure\n\nIt is possible to generate idiomatic Rust syntax trees. For this you would need to use labels feature of ANTLR tool.\nYou can see [Labels](grammars/Labels.g4) grammar for example.\nConsider following rule :\n```text\ne   : a=e op='*' b=e   # mult\n    | left=e '+' b=e   # add\n\t\t \n```\nFor such rule ANTLR will generate enum `EContextAll` containing `mult` and `add` alternatives, \nso you will be able to match on them in your code. \nAlso corresponding struct for each alternative will contain fields you labeled. \nI.e. for `MultContext` struct will contain `a` and `b` fields containing child subtrees and \n`op` field with `TerminalNode` type which corresponds to individual `Token`.\nIt also is possible to disable generic parse tree creation to keep only selected children via\n`parser.build_parse_trees = false`, but unfortunately currently it will prevent visitors from working. \n  \n### Differences with Java\nAlthough Rust runtime API has been made as close as possible to Java, \nthere are quite some differences because Rust is not an OOP language and is much more explicit. \n\n - If you are using labeled alternatives, \n struct generated for the rule is an enum with variant for each alternative\n - Parser needs to have ownership for listeners, but it is possible to get listener back via `ListenerId`\n otherwise `ParseTreeWalker` should be used.\n - In embedded actions to access parser you should use `recog` variable instead of `self`/`this`. \n This is because predicates have to be inserted into two syntactically different places in generated parser \n and in one of them it is impossible to have parser as `self`.\n - str based `InputStream` have different index behavior when there are unicode characters. \n If you need exactly the same behavior, use `[u32]` based `InputStream`, or implement custom `CharStream`.\n - In actions you have to escape `'` in rust lifetimes with `\\ ` because ANTLR considers them as strings, e.g. `Struct\u003c\\'lifetime\u003e`\n - To make custom tokens you should use `@tokenfactory` custom action, instead of usual `TokenLabelType` parser option.\n ANTLR parser options can accept only single identifiers while Rust target needs know about lifetime as well. \n Also in Rust target `TokenFactory` is the way to specify token type. As example you can see [CSV](grammars/CSV.g4) test grammar.\n - All rule context variables (rule argument or rule return) should implement `Default + Clone`.\n \n### Benchmarks\nHere is comparison of antlr generated XML lexer and parser\n(from default XML grammar but with custom minimal Token/TokenFactory/InputStream/RuleContext) to hand-written implementations in rust ecosystem.\nKeep in mind that `xmlparser` and `quick_xml` are much closer to being lexer than parser, so they should be compared with antlr lexer.\nAlso while structs used by generated lexer and parser were customized to track as minimum data as required \n(which is possible by any user of antlr-rust), \ninternals of the lexer cannot be customized enough yet and still track quite a lot of data that might not be used in particular case. \nSo there is still room for improvement.\n```text\nlexers:\nlarge/large_xmlparser        time:   [1.8598 ms 1.8607 ms 1.8619 ms]                                   \nlarge/large_quick_xml        time:   [1.4623 ms 1.4645 ms 1.4675 ms]                                   \nlarge/large_antlr_xml_lexer  time:   [5.7866 ms 5.7877 ms 5.7891 ms]\nparsers:\nlarge/large_xmlrs            time:   [16.734 ms 16.748 ms 16.766 ms]\nlarge/large_minidom          time:   [7.0639 ms 7.0792 ms 7.0975 ms]                                \nlarge/large_roxmltree        time:   [4.9341 ms 4.9360 ms 4.9380 ms]                                   \nlarge/large_antlr_xml_full   time:   [10.243 ms 10.248 ms 10.252 ms]                                  \n```\n\n### Unsafe\nCurrently, unsafe is used only for downcasting (through separate crate) \nand to update data inside Rc via `get_mut_unchecked`(returned mutable reference is used immediately and not stored anywhere)\n\n### Versioning\nIn addition to usual Rust semantic versioning, \npatch version changes of the crate should not require updating of generator part \n  \n## Licence\n\nBSD 3-clause. \nUnless you explicitly state otherwise, \nany contribution intentionally submitted for inclusion in this project by you\nshall be licensed as above, without any additional terms or conditions.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrevenantt%2Fantlr4rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frrevenantt%2Fantlr4rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrevenantt%2Fantlr4rust/lists"}