README.md

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

1. Add antlr4ts to package.json as a runtime dependency

   "dependencies": {
     // ...
     "antlr4ts": "^0.2.0"
   }
   

2. Add antlr4ts-cli to package.json as a development dependency

   "devDependencies": {
     // ...
     "antlr4ts-cli": "^0.2.0"
   }
   

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

   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 result = parser.compilationUnit();