JarCastingantlr4ts - 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
antlr4tsas a runtime dependency using your preferred package manager.
npm install antlr4ts --save
yarn add antlr4ts
- Install
antlr4ts-clias 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
-visitorflag 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)
