Installation

$ npm install solidity-antlr4
Copy

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.

// 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]
//     }
//   ]
// }
Copy

If you want to get a plain AST json object, you can use the following methods:

// serialize.mjs
import { parse, serialize } from 'solidity-antlr4';

const astJSONObject = serialize(parse(code));
// { type: 'SourceUnit', ... }
Copy

Tokenizer

• tokenizer(code, [options]): tokenizer() parses the provided code as tokens.
• options:
  • tolerant: boolean, default is false.
• output: SyntaxToken[].

// 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 }
//     }
//   },
//   ...
// ]
Copy

Traverse AST

We can use it alongside the parser to traverse nodes.

// traverse.mjs
import { parse, traverse } from 'solidity-antlr4';

const ast = parse(code);

traverse(ast, {
  enter: (node) => {
    console.log(node.type); // print node type
  },
  exit: () => {}, // will call when exit node
  Identifier: (identifierNode) => {
    console.log(identifierNode.name); // print identifier name
  },
  exitContractDefinition: (contractDefinitionNode) => {
    // will call when exit ContractDefinition node
  }
});
Copy

You can also create a traverse by createTraverse:

import { createTraverse } from 'solidity-antlr4';

export const traverse = createTraverse({ enter: () => {} });
Copy

Low-level API

Not recommended, but you can use it if you want.

import { SolidityLexer, SolidityParser, CharStreams, CommonTokenStream } from 'solididty-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
Copy

License

MIT