antlr4ts - TypeScript/JavaScript target for ANTLR 4




Overview

* Releases: See the GitHub Releases page for release notes and
links to the distribution
* Feedback: Use GitHub 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 for contributor documentation.

$3

Parsers generated by the ANTLR 4 TypeScript target have a runtime dependency on the
antlr4ts package. The package is tested and known to work with Node.js 6.7.

$3

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.

###### 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 implements MyGrammarParserVisitor {

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)
``