{"id":16354567,"url":"https://github.com/jeasonstudio/solidity-antlr4","last_synced_at":"2025-07-29T02:42:00.507Z","repository":{"id":212432270,"uuid":"731474955","full_name":"jeasonstudio/solidity-antlr4","owner":"jeasonstudio","description":"✨  Solidity Language Lexer and Parser, generated by official ANTLR4 grammar.","archived":false,"fork":false,"pushed_at":"2024-02-02T09:02:10.000Z","size":2354,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-17T19:13:23.768Z","etag":null,"topics":["antlr4-grammar","ast","parser","solidity"],"latest_commit_sha":null,"homepage":"https://solidity-antlr4.vercel.app/","language":"TypeScript","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/jeasonstudio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-14T06:59:31.000Z","updated_at":"2024-10-26T15:07:59.000Z","dependencies_parsed_at":"2023-12-14T08:27:47.723Z","dependency_job_id":"c5d9ac21-daf9-431c-94d4-150b27a20943","html_url":"https://github.com/jeasonstudio/solidity-antlr4","commit_stats":null,"previous_names":["jeasonstudio/solidity-antlr4"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeasonstudio%2Fsolidity-antlr4","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeasonstudio%2Fsolidity-antlr4/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeasonstudio%2Fsolidity-antlr4/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeasonstudio%2Fsolidity-antlr4/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeasonstudio","download_url":"https://codeload.github.com/jeasonstudio/solidity-antlr4/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244717369,"owners_count":20498282,"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-grammar","ast","parser","solidity"],"created_at":"2024-10-11T01:35:38.601Z","updated_at":"2025-03-21T00:31:24.550Z","avatar_url":"https://github.com/jeasonstudio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\u003ca name=\"readme-top\"\u003e\u003c/a\u003e\n\n\u003ch1\u003eSolidity ANTLR4\u003c/h1\u003e\n\n[Solidity](https://soliditylang.org/) Language Lexer and Parser, generated by official ANTLR4 grammar.\n\n[![NPM version][npm-image]][npm-url]\n[![NPM downloads][download-image]][download-url]\n[![CI status][github-action-image]][github-action-url]\n[![codecov][codecov-image]][codecov-url]\n[![MIT License][license-shield]][license-url]\n\n[![Contributors][contributors-shield]][contributors-url]\n[![Issues][issues-shield]][issues-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Follow Twitter][twitter-image]][twitter-url]\n\n[Change Log](./CHANGELOG.md) · [Report Bug](https://github.com/jeasonstudio/solidity-antlr4/issues/new) · [Pull Request](https://github.com/jeasonstudio/solidity-antlr4/compare)\n\n![](https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png)\n\n[npm-image]: https://img.shields.io/npm/v/solidity-antlr4?style=for-the-badge\n[npm-url]: http://npmjs.org/package/solidity-antlr4\n[download-image]: https://img.shields.io/npm/dm/solidity-antlr4.svg?style=for-the-badge\n[download-url]: https://npmjs.org/package/solidity-antlr4\n[github-action-image]: https://img.shields.io/github/actions/workflow/status/jeasonstudio/solidity-antlr4/test.yml?style=for-the-badge\n[github-action-url]: https://github.com/jeasonstudio/solidity-antlr4/actions?query=workflow=%22test%22\n[codecov-image]: https://img.shields.io/codecov/c/github/jeasonstudio/solidity-antlr4/master.svg?style=for-the-badge\n[codecov-url]: https://codecov.io/gh/jeasonstudio/solidity-antlr4/branch/master\n[license-shield]: https://img.shields.io/github/license/jeasonstudio/solidity-antlr4.svg?style=for-the-badge\n[license-url]: https://github.com/jeasonstudio/solidity-antlr4/blob/master/LICENSE\n\n[contributors-shield]: https://img.shields.io/github/contributors/jeasonstudio/solidity-antlr4.svg?style=for-the-badge\n[contributors-url]: https://github.com/jeasonstudio/solidity-antlr4/graphs/contributors\n[stars-shield]: https://img.shields.io/github/stars/jeasonstudio/solidity-antlr4.svg?style=for-the-badge\n[stars-url]: https://github.com/jeasonstudio/solidity-antlr4/stargazers\n[issues-shield]: https://img.shields.io/github/issues/jeasonstudio/solidity-antlr4.svg?style=for-the-badge\n[issues-url]: https://github.com/jeasonstudio/solidity-antlr4/issues\n[twitter-image]: https://img.shields.io/twitter/follow/jeasonstudio?style=for-the-badge\u0026logo=x\n[twitter-url]: https://twitter.com/jeasonstudio\n\n\u003c/div\u003e\n\n## Installation\n\n```bash\n$ npm install solidity-antlr4\n```\n\n\u003e It will be `pnpm/yarn add solidity-antlr4` if you use pnpm or yarn.\n\n## Usage\n\n### Language Parser\n\n* `parse(code, [options])`: `parse()` parses the provided code as an entire Solidity source unit.\n* `options`:\n  * `tolerant`: `boolean`, default is `false`. If `true`, the parser will try to parse as much as possible, even if the input is invalid, and never throw an error.\n  * `selector`: `function`, default is `(p) =\u003e p.sourceUnit()`. If provided, the parser will only return the nodes that match the selector. It will be useful when you want to parse a specific node.\n* `output`: `SyntaxNode`, the root node of the AST.\n\n```js\n// parse.mjs\nimport { parse } from 'solidity-antlr4';\n\nconst code = `// SPDX-License-Identifier: MIT\npragma solidity ^0.8.20;\n\ncontract HelloWorld {\n  string public greet = \"Hello World!\";\n}\n`;\n\nconst ast = parse(code, { tolerant: true, selector: (p) =\u003e p.sourceUnit() });\n// SourceUnit {\n//   type: 'SourceUnit',\n//   src: '32:88',\n//   range: [ 32, 120 ],\n//   location: Location {\n//     start: Position { line: 2, column: 0 },\n//     end: Position { line: 6, column: 0 }\n//   },\n//   context: SourceUnitContext {...},\n//   nodes: [\n//     PragmaDirective {\n//       type: 'PragmaDirective',\n//       literals: [Array]\n//     },\n//     ContractDefinition {\n//       type: 'ContractDefinition',\n//       name: [Identifier],\n//       contractKind: 'contract',\n//       abstract: false,\n//       baseContracts: [],\n//       nodes: [Array]\n//     }\n//   ]\n// }\n```\n\n### Tokenizer\n\n* `tokenizer(code, [options])`: `tokenizer()` parses the provided code as tokens.\n* `options`:\n  * `tolerant`: `boolean`, default is `false`.\n* `output`: `SyntaxToken[]`.\n\n```js\n// tokenizer.mjs\nimport { tokenizer } from 'solidity-antlr4';\n\nconst tokens = tokenizer(code, { tolerant: true });\n// [\n//   {\n//     type: 'SourceUnit',\n//     src: '32:88',\n//     range: [ 32, 120 ],\n//     location: Location {\n//       start: Position { line: 2, column: 0 },\n//       end: Position { line: 6, column: 0 }\n//     }\n//   },\n//   ...\n// ]\n```\n\n### Traverse AST\n\nWe can use it alongside the parser to traverse nodes.\n\n```js\n// visit.mjs\nimport { parse, visit, serialize } from 'solidity-antlr4';\n\nconst ast = parse(code);\n\n// Use `visit` to traverse ast by enter/exit node type.\nvisit(ast, {\n  enter: ({ node, parent }) =\u003e {\n    console.log(node.type, parent?.type); // print node type\n  },\n  exit: () =\u003e {}, // will call when exit node\n  Identifier: ({ node: identifierNode }) =\u003e {\n    console.log(identifierNode.name); // print identifier name\n  },\n  exitContractDefinition: ({ node: contractDefinitionNode }) =\u003e {\n    // will call when exit ContractDefinition node\n  }\n});\n\n// Use `serialize` to modify ast.\nconst newAST = serialize(ast, ({ node }) =\u003e {\n  // do something\n  if (node.type === 'Identifier') {\n    return node.name;\n  }\n  return node;\n})\n```\n\n```js\n// traverse.mjs\nimport { parse, traverse } from 'solidity-antlr4';\n\nconst ast = parse(code);\n\nconst newAST = traverse(ast, (path) =\u003e {\n  // path.path =\u003e `SourceUnit.ContractDefinition.FunctionDefinition` ...\n  // path.node =\u003e current node\n  // path.parentPath =\u003e parent node path\n  // path.depth =\u003e current node depth\n  // path.stop(); =\u003e stop traverse\n  // path.rewrite({...}); =\u003e rewrite current node\n  // path.matches({ type: 'xxx' }); =\u003e check if current node matches the given filter\n  // return () =\u003e {}; =\u003e will call when exit node\n});\n```\n\n### Low-level API\n\n\u003e Not recommended, but you can use it if you want.\n\n```ts\nimport { SolidityLexer, SolidityParser, CharStreams, CommonTokenStream } from 'solidity-antlr4';\n\nconst code = `...`; // code here\n\nconst input = CharStreams.fromString(code);\nconst lexer = new SolidityLexer(input);\nconst tokens = new CommonTokenStream(lexer);\nconst parser = new SolidityParser(tokens);\n\nconst parseTree = parser.sourceUnit();\n\n// do something with parseTree\n```\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeasonstudio%2Fsolidity-antlr4","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeasonstudio%2Fsolidity-antlr4","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeasonstudio%2Fsolidity-antlr4/lists"}