{"id":18263835,"url":"https://github.com/atomist/antlr","last_synced_at":"2026-04-29T17:07:44.156Z","repository":{"id":55127395,"uuid":"106087880","full_name":"atomist/antlr","owner":"atomist","description":"Automation client ANTLR integration","archived":false,"fork":false,"pushed_at":"2021-01-08T04:44:37.000Z","size":2761,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-16T00:33:04.046Z","etag":null,"topics":["node"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/atomist.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-07T10:01:13.000Z","updated_at":"2021-01-08T04:18:23.000Z","dependencies_parsed_at":"2022-08-14T12:50:32.216Z","dependency_job_id":null,"html_url":"https://github.com/atomist/antlr","commit_stats":null,"previous_names":["atomist/antlr-ts"],"tags_count":93,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomist%2Fantlr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomist%2Fantlr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomist%2Fantlr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomist%2Fantlr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atomist","download_url":"https://codeload.github.com/atomist/antlr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247955966,"owners_count":21024489,"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":["node"],"created_at":"2024-11-05T11:12:51.097Z","updated_at":"2026-04-29T17:07:39.108Z","avatar_url":"https://github.com/atomist.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @atomist/antlr\n\n[![atomist sdm goals](http://badge.atomist.com/T29E48P34/atomist/antlr-ts/93a238be-3c16-456e-be12-76234a0caca5)](https://app.atomist.com/workspace/T29E48P34)\n[![npm version](https://img.shields.io/npm/v/@atomist/antlr.svg)](https://www.npmjs.com/package/@atomist/antlr)\n\nIntegration with [ANTLR for TypeScript](https://github.com/tunnelvisionlabs/antlr4ts) for Atomist automation [clients](https://github.com/atomist/automation-client-ts).\n\nANTLR is a powerful parser generator, for which many grammars are available.\n\nThis enables running path expressions against ANTLR ASTs in\na consistent manner to ASTs produced by other grammars.\n\nIncludes Java support, in the `JavaFileParser` implementation of `FileParser`,\nas an example, test and for actual Java support, as well as Kotlin support,\nto show how to handle a grammar with a distinct lexer and parser.\nOther ANTLR grammars can be integrated with Atomist\nusing this project as library, including offering an update model producing clean diffs.\n\nSee [overall path expression documentation](https://github.com/atomist/automation-client-ts/blob/master/docs/PathExpressions.md).\n\n## Usage\n\nFirst, create an instance of a `FileParser` or `FileParserRegistry`.\n\nA `FileParser` knows how to parse files using a single grammar: for example, `MicrogrammarBasedFileParser` (from automation client) that uses a single microgrammar, or `JavaFileParser` from this project. A `FileParserRegistry` can accommodate multiple `FileParser` instances, determining whichever is appropriate to execute a given path expression.\n\nThen use the `findMatches` method in `astUtils`, which has the following signature:\n\n```typescript\nexport function findMatches(p: ProjectNonBlocking,\n                            globPattern: string,\n                            parserOrRegistry: FileParser | FileParserRegistry,\n                            pathExpression: string | PathExpression): Promise\u003cTreeNode[]\u003e {\n```\n\nThe following example looks in all Java files in a project for a given path expression:\n\n```typescript\nfindMatches(project, JavaFiles, JavaFileParser,\n    \"//variableDeclaratorId/Identifier\")\n    .then(matches =\u003e {\n        ...\n\n```\nReturned matches are updatable after project flushing.\n\n## SPI: Supporting other ANTLR grammars\n\nThis project includes support for parsing Java using the [Java ANTLR grammar](../src/tree/ast/antlr/java/Java.g4).\n\nThere are [many available ANTLR grammars](https://github.com/antlr/grammars-v4), and the same approach can be used with most of them, making it possible to work with their ASTs in a consistent manner with Atomist.\n\nTo add support for another grammar, perform the following steps:\n\n### Generate TypeScript\n\nUse the ANTLR CLI to generate the necessary files from the grammar.\nIt is installed as a development dependency of this project.\n\nIf your grammar has a separate lexer, first generate the TypeScript\nfor that.  In this example, we'll use the Kotlin grammar.\n\n```\n$ ./node_modules/.bin/antlr4ts -visitor lib/tree/ast/antlr/kotlin/KotlinLexer.g4\n```\n\nThen generate the TypeScript for the parser.\n\n``` \n$ ./node_modules/.bin/antlr4ts -lib lib/tree/ast/antlr/kotlin -visitor lib/tree/ast/antlr/kotlin/KotlinParser.g4\n```\n\nYou may need to reorder some of the generated code to eliminate forward references to ensure compilation.\nIn your `antlr-gen/XXXXParser` file, reorder to put all classes _before_ the `XXXXParser` class.\n\nIf you are using `tslint` you may need to disable it for the generated sources as\nin this project.\n\nNote that antlr4ts is written in Java, and `npm` only wraps it, so\nyou'll need a recent JVM. A JVM is _not_ needed to execute the resulting\ngrammar, which is pure TypeScript. Documentation for the ANTLR CLI is\n[here](https://github.com/antlr/antlr4/blob/master/doc/tool-options.md).\n\n### Create a FileParser Implementation to Integrate your Grammar with your Atomist Automation Client\n\nCreate an instance of `FileParser` to work with your grammar. Use `TreeBuildingListener` to do the work of building an Atomist `TreeNode` from the ANTLR parse tree.\n\nCreate your `FileParser` in the style of `JavaFileParser` in this project,\npassing the top level production name and the lexer and parser classes.\n\n```typescript\nconst JavaFileParser = new AntlrFileParser(\"compilationUnit\", JavaLexer, JavaParser);\n```\n\nIf your grammar uses Java or other code you may need to port that code to JavaScript or TypeScript.\nPlease refer to ANTLR documentation in this case.\nPlease validate your grammar with an IDE plugin or other tool before generating code and attempting\nintegration.\n\n## Support\n\nGeneral support questions should be discussed in the `#help`\nchannel in the [Atomist community Slack workspace][slack].\n\nIf you find a problem, please create an [issue][].\n\n[issue]: https://github.com/atomist/antlr-ts/issues\n\n## Development\n\nYou will need to install [Node.js][node] to build and test this\nproject.\n\n[node]: https://nodejs.org/ (Node.js)\n\n### Build and test\n\nInstall dependencies.\n\n```\n$ npm install\n```\n\nUse the `build` package script to compile, test, lint, and build the\ndocumentation.\n\n```\n$ npm run build\n```\n\n### Release\n\nReleases are handled via the [Atomist SDM][atomist-sdm].  Just press\nthe 'Approve' button in the Atomist dashboard or Slack.\n\n[atomist-sdm]: https://github.com/atomist/atomist-sdm (Atomist Software Delivery Machine)\n\n---\n\nCreated by [Atomist][atomist].\nNeed Help?  [Join our Slack workspace][slack].\n\n[atomist]: https://atomist.com/ (Atomist - How Teams Deliver Software)\n[slack]: https://join.atomist.com/ (Atomist Community Slack)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomist%2Fantlr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatomist%2Fantlr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomist%2Fantlr/lists"}