Merge pull request #5 from jeasonstudio/feat-reduce-astnode-count

Feat reduce astnode count

.changeset/little-penguins-brake.md

@@ -0,0 +1,5 @@
+---
+"solidity-antlr4": patch
+---
+
+support traverse/walker and refact serialize

README.md

@@ -2,7 +2,7 @@
 
 <h1>Solidity ANTLR4</h1>
 
-Solidity Language Lexer and Parser, generated by official ANTLR4 grammar.
+[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]
@@ -41,15 +41,26 @@ Solidity Language Lexer and Parser, generated by official ANTLR4 grammar.
 
 </div>
 
-## Install
+## Installation
 
 ```bash
 $ npm install solidity-antlr4
 ```
 
+> It will be `pnpm/yarn add solidity-antlr4` if you use pnpm or yarn.
+
 ## Usage
 
-```ts
+### 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
@@ -60,11 +71,104 @@ contract HelloWorld {
 }
 `;
 
-const { parseTree, syntaxTree: ast, errors } = parse(code);
-// SyntaxTree: { type: "SourceUnit", nodes: [...], rage: [32, 120], location: {...} }
+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]
+//     }
+//   ]
+// }
 ```
 
-## Usage (low-level api)
+If you want to get a plain AST json object, you can use the following methods:
+
+```js
+// serialize.mjs
+import { parse, serialize } from 'solidity-antlr4';
+
+const astJSONObject = serialize(parse(code));
+// { type: 'SourceUnit', ... }
+```
+
+### 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
+// 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
+  }
+});
+```
+
+You can also create a traverse by `createTraverse`:
+
+```js
+import { createTraverse } from 'solidity-antlr4';
+
+export const traverse = createTraverse({ enter: () => {} });
+```
+
+### Low-level API
+
+> Not recommended, but you can use it if you want.
 
 ```ts
 import { SolidityLexer, SolidityParser, CharStreams, CommonTokenStream } from 'solididty-antlr4';

docs/assets/highlight.css

@@ -5,18 +5,16 @@
     --dark-hl-1: #D4D4D4;
     --light-hl-2: #A31515;
     --dark-hl-2: #CE9178;
-    --light-hl-3: #AF00DB;
-    --dark-hl-3: #C586C0;
-    --light-hl-4: #001080;
-    --dark-hl-4: #9CDCFE;
-    --light-hl-5: #0000FF;
-    --dark-hl-5: #569CD6;
-    --light-hl-6: #0070C1;
-    --dark-hl-6: #4FC1FF;
-    --light-hl-7: #008000;
-    --dark-hl-7: #6A9955;
-    --light-hl-8: #098658;
-    --dark-hl-8: #B5CEA8;
+    --light-hl-3: #008000;
+    --dark-hl-3: #6A9955;
+    --light-hl-4: #AF00DB;
+    --dark-hl-4: #C586C0;
+    --light-hl-5: #001080;
+    --dark-hl-5: #9CDCFE;
+    --light-hl-6: #0000FF;
+    --dark-hl-6: #569CD6;
+    --light-hl-7: #0070C1;
+    --dark-hl-7: #4FC1FF;
     --light-code-background: #FFFFFF;
     --dark-code-background: #1E1E1E;
 }
@@ -30,7 +28,6 @@
     --hl-5: var(--light-hl-5);
     --hl-6: var(--light-hl-6);
     --hl-7: var(--light-hl-7);
-    --hl-8: var(--light-hl-8);
     --code-background: var(--light-code-background);
 } }
 
@@ -43,7 +40,6 @@
     --hl-5: var(--dark-hl-5);
     --hl-6: var(--dark-hl-6);
     --hl-7: var(--dark-hl-7);
-    --hl-8: var(--dark-hl-8);
     --code-background: var(--dark-code-background);
 } }
 
@@ -56,7 +52,6 @@
     --hl-5: var(--light-hl-5);
     --hl-6: var(--light-hl-6);
     --hl-7: var(--light-hl-7);
-    --hl-8: var(--light-hl-8);
     --code-background: var(--light-code-background);
 }
 
@@ -69,7 +64,6 @@
     --hl-5: var(--dark-hl-5);
     --hl-6: var(--dark-hl-6);
     --hl-7: var(--dark-hl-7);
-    --hl-8: var(--dark-hl-8);
     --code-background: var(--dark-code-background);
 }
 
@@ -81,5 +75,4 @@
 .hl-5 { color: var(--hl-5); }
 .hl-6 { color: var(--hl-6); }
 .hl-7 { color: var(--hl-7); }
-.hl-8 { color: var(--hl-8); }
 pre, code { background: var(--code-background); }