-
Notifications
You must be signed in to change notification settings - Fork 106
/
README.md
143 lines (101 loc) · 4.96 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
# antlr4ts - TypeScript/JavaScript target for ANTLR 4
[![Join the chat at https://gitter.im/tunnelvisionlabs/antlr4ts](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/tunnelvisionlabs/antlr4ts?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Build status](https://ci.appveyor.com/api/projects/status/d4gpmnrkfo3tb2t1/branch/master?svg=true)](https://ci.appveyor.com/project/sharwell/antlr4ts/branch/master)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](./LICENSE)
## Overview
* **Releases:** See the [GitHub Releases](https://github.com/tunnelvisionlabs/antlr4ts/releases) page for release notes and
links to the distribution
* **Feedback:** Use [GitHub Issues](https://github.com/tunnelvisionlabs/antlr4ts/issues) for issues (bugs, enhancements,
features, and questions)
## Requirements
This project has separate requirements for developers and end users.
> :bulb: The requirements listed on this page only cover user scenarios - that is, scenarios where developers wish to
> use ANTLR 4 for parsing tasks inside of a TypeScript application. If you are interested in contributing to ANTLR 4
> itself, see [CONTRIBUTING.md](CONTRIBUTING.md) for contributor documentation.
### End user requirements
Parsers generated by the ANTLR 4 TypeScript target have a runtime dependency on the
[antlr4ts](https://www.npmjs.com/package/antlr4ts) package. The package is tested and known to work with Node.js 6.7.
### Development requirements
The tool used to generate TypeScript code from an ANTLR 4 grammar is written in Java. To fully utilize the ANTLR 4
TypeScript target (including the ability to regenerate code from a grammar file after changes are made), a Java Runtime
Environment (JRE) needs to be installed on the developer machine. The generated code itself uses several features new to
TypeScript 2.0.
* Java Runtime Environment 1.6+ (1.8+ recommended)
* TypeScript 2.0+
## Getting started
1. Install `antlr4ts` as a runtime dependency using your preferred package manager.
```bash
npm install antlr4ts --save
```
```bash
yarn add antlr4ts
```
2. Install `antlr4ts-cli` as a development dependency using your preferred package manager.
```bash
npm install antlr4ts-cli --save-dev
```
```bash
yarn add -D antlr4ts-cli
```
3. Add a grammar to your project, e.g. **path/to/MyGrammar.g4**
4. Add a script to **package.json** for compiling your grammar to TypeScript
```
"scripts": {
// ...
"antlr4ts": "antlr4ts -visitor path/to/MyGrammar.g4"
}
```
5. Use your grammar in TypeScript
```typescript
import { ANTLRInputStream, CommonTokenStream } from 'antlr4ts';
// Create the lexer and parser
let inputStream = new ANTLRInputStream("text");
let lexer = new MyGrammarLexer(inputStream);
let tokenStream = new CommonTokenStream(lexer);
let parser = new MyGrammarParser(tokenStream);
// Parse the input, where `compilationUnit` is whatever entry point you defined
let tree = parser.compilationUnit();
```
The two main ways to inspect the tree are by using a listener or a visitor, you can read about the differences between the two [here](https://github.com/antlr/antlr4/blob/master/doc/listeners.md).
###### Listener Approach
```typescript
// ...
import { MyGrammarParserListener } from './MyGrammarParserListener'
import { FunctionDeclarationContext } from './MyGrammarParser'
import { ParseTreeWalker } from 'antlr4ts/tree/ParseTreeWalker'
class EnterFunctionListener implements MyGrammarParserListener {
// Assuming a parser rule with name: `functionDeclaration`
enterFunctionDeclaration(context: FunctionDeclarationContext) {
console.log(`Function start line number ${context._start.line}`)
// ...
}
// other enterX functions...
}
// Create the listener
const listener: MyGrammarParserListener = new EnterFunctionListener();
// Use the entry point for listeners
ParseTreeWalker.DEFAULT.walk(listener, tree)
```
###### Visitor Approach
Note you must pass the `-visitor` flag to antlr4ts to get the generated visitor file.
```typescript
// ...
import { MyGrammarParserVisitor } from './MyGrammarParserVisitor'
import { AbstractParseTreeVisitor } from 'antlr4ts/tree/AbstractParseTreeVisitor'
// Extend the AbstractParseTreeVisitor to get default visitor behaviour
class CountFunctionsVisitor extends AbstractParseTreeVisitor<number> implements MyGrammarParserVisitor<number> {
defaultResult() {
return 0
}
aggregateResult(aggregate: number, nextResult: number) {
return aggregate + nextResult
}
visitFunctionDeclaration(context: FunctionDeclarationContext): number {
return 1 + super.visitChildren(context)
}
}
// Create the visitor
const countFunctionsVisitor = new CountFunctionsVisitor()
// Use the visitor entry point
countFunctionsVisitor.visit(tree)
```