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.
๐ก 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.
End user requirements
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.
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
- Install
antlr4ts
as a runtime dependency using your preferred package manager.
npm install antlr4ts --save
yarn add antlr4ts
- Install
antlr4ts-cli
as a development dependency using your preferred package manager.
npm install antlr4ts-cli --save-dev
yarn add -D antlr4ts-cli
-
Add a grammar to your project, e.g. path/to/MyGrammar.g4
-
Add a script to package.json for compiling your grammar to TypeScript
"scripts": { // ... "antlr4ts": "antlr4ts -visitor path/to/MyGrammar.g4" }
-
Use your grammar in 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
// ... 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.// ... 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)