Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jeasonstudio/solidity-antlr4
✨ Solidity Language Lexer and Parser, generated by official ANTLR4 grammar.
https://github.com/jeasonstudio/solidity-antlr4
antlr4-grammar ast parser solidity
Last synced: 4 months ago
JSON representation
✨ Solidity Language Lexer and Parser, generated by official ANTLR4 grammar.
- Host: GitHub
- URL: https://github.com/jeasonstudio/solidity-antlr4
- Owner: jeasonstudio
- License: mit
- Created: 2023-12-14T06:59:31.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-02-02T09:02:10.000Z (about 1 year ago)
- Last Synced: 2024-10-12T01:35:39.570Z (4 months ago)
- Topics: antlr4-grammar, ast, parser, solidity
- Language: TypeScript
- Homepage: https://solidity-antlr4.vercel.app/
- Size: 2.24 MB
- Stars: 16
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Solidity ANTLR4
[Solidity](https://soliditylang.org/) Language Lexer and Parser, generated by official ANTLR4 grammar.
[![NPM version][npm-image]][npm-url]
[![NPM downloads][download-image]][download-url]
[![CI status][github-action-image]][github-action-url]
[![codecov][codecov-image]][codecov-url]
[![MIT License][license-shield]][license-url]
[![Contributors][contributors-shield]][contributors-url]
[![Issues][issues-shield]][issues-url]
[![Stargazers][stars-shield]][stars-url]
[![Follow Twitter][twitter-image]][twitter-url]
[Change Log](./CHANGELOG.md) · [Report Bug](https://github.com/jeasonstudio/solidity-antlr4/issues/new) · [Pull Request](https://github.com/jeasonstudio/solidity-antlr4/compare)
[npm-image]: https://img.shields.io/npm/v/solidity-antlr4?style=for-the-badge
[npm-url]: http://npmjs.org/package/solidity-antlr4
[download-image]: https://img.shields.io/npm/dm/solidity-antlr4.svg?style=for-the-badge
[download-url]: https://npmjs.org/package/solidity-antlr4
[github-action-image]: https://img.shields.io/github/actions/workflow/status/jeasonstudio/solidity-antlr4/test.yml?style=for-the-badge
[github-action-url]: https://github.com/jeasonstudio/solidity-antlr4/actions?query=workflow=%22test%22
[codecov-image]: https://img.shields.io/codecov/c/github/jeasonstudio/solidity-antlr4/master.svg?style=for-the-badge
[codecov-url]: https://codecov.io/gh/jeasonstudio/solidity-antlr4/branch/master
[license-shield]: https://img.shields.io/github/license/jeasonstudio/solidity-antlr4.svg?style=for-the-badge
[license-url]: https://github.com/jeasonstudio/solidity-antlr4/blob/master/LICENSE
[contributors-shield]: https://img.shields.io/github/contributors/jeasonstudio/solidity-antlr4.svg?style=for-the-badge
[contributors-url]: https://github.com/jeasonstudio/solidity-antlr4/graphs/contributors
[stars-shield]: https://img.shields.io/github/stars/jeasonstudio/solidity-antlr4.svg?style=for-the-badge
[stars-url]: https://github.com/jeasonstudio/solidity-antlr4/stargazers
[issues-shield]: https://img.shields.io/github/issues/jeasonstudio/solidity-antlr4.svg?style=for-the-badge
[issues-url]: https://github.com/jeasonstudio/solidity-antlr4/issues
[twitter-image]: https://img.shields.io/twitter/follow/jeasonstudio?style=for-the-badge&logo=x
[twitter-url]: https://twitter.com/jeasonstudio
## Installation
```bash
$ npm install solidity-antlr4
```
> It will be `pnpm/yarn add solidity-antlr4` if you use pnpm or yarn.
## Usage
### Language Parser
* `parse(code, [options])`: `parse()` parses the provided code as an entire Solidity source unit.
* `options`:
* `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.
* `selector`: `function`, default is `(p) => 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.
* `output`: `SyntaxNode`, the root node of the AST.
```js
// parse.mjs
import { parse } from 'solidity-antlr4';
const code = `// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract HelloWorld {
string public greet = "Hello World!";
}
`;
const ast = parse(code, { tolerant: true, selector: (p) => p.sourceUnit() });
// SourceUnit {
// type: 'SourceUnit',
// src: '32:88',
// range: [ 32, 120 ],
// location: Location {
// start: Position { line: 2, column: 0 },
// end: Position { line: 6, column: 0 }
// },
// context: SourceUnitContext {...},
// nodes: [
// PragmaDirective {
// type: 'PragmaDirective',
// literals: [Array]
// },
// ContractDefinition {
// type: 'ContractDefinition',
// name: [Identifier],
// contractKind: 'contract',
// abstract: false,
// baseContracts: [],
// nodes: [Array]
// }
// ]
// }
```
### Tokenizer
* `tokenizer(code, [options])`: `tokenizer()` parses the provided code as tokens.
* `options`:
* `tolerant`: `boolean`, default is `false`.
* `output`: `SyntaxToken[]`.
```js
// tokenizer.mjs
import { tokenizer } from 'solidity-antlr4';
const tokens = tokenizer(code, { tolerant: true });
// [
// {
// type: 'SourceUnit',
// src: '32:88',
// range: [ 32, 120 ],
// location: Location {
// start: Position { line: 2, column: 0 },
// end: Position { line: 6, column: 0 }
// }
// },
// ...
// ]
```
### Traverse AST
We can use it alongside the parser to traverse nodes.
```js
// visit.mjs
import { parse, visit, serialize } from 'solidity-antlr4';
const ast = parse(code);
// Use `visit` to traverse ast by enter/exit node type.
visit(ast, {
enter: ({ node, parent }) => {
console.log(node.type, parent?.type); // print node type
},
exit: () => {}, // will call when exit node
Identifier: ({ node: identifierNode }) => {
console.log(identifierNode.name); // print identifier name
},
exitContractDefinition: ({ node: contractDefinitionNode }) => {
// will call when exit ContractDefinition node
}
});
// Use `serialize` to modify ast.
const newAST = serialize(ast, ({ node }) => {
// do something
if (node.type === 'Identifier') {
return node.name;
}
return node;
})
```
```js
// traverse.mjs
import { parse, traverse } from 'solidity-antlr4';
const ast = parse(code);
const newAST = traverse(ast, (path) => {
// path.path => `SourceUnit.ContractDefinition.FunctionDefinition` ...
// path.node => current node
// path.parentPath => parent node path
// path.depth => current node depth
// path.stop(); => stop traverse
// path.rewrite({...}); => rewrite current node
// path.matches({ type: 'xxx' }); => check if current node matches the given filter
// return () => {}; => will call when exit node
});
```
### Low-level API
> Not recommended, but you can use it if you want.
```ts
import { SolidityLexer, SolidityParser, CharStreams, CommonTokenStream } from 'solidity-antlr4';
const code = `...`; // code here
const input = CharStreams.fromString(code);
const lexer = new SolidityLexer(input);
const tokens = new CommonTokenStream(lexer);
const parser = new SolidityParser(tokens);
const parseTree = parser.sourceUnit();
// do something with parseTree
```
## License
[MIT](./LICENSE)