antlr4ts

What is antlr4ts?

The antlr4ts npm package is a TypeScript target for ANTLR (Another Tool for Language Recognition), which is a powerful parser generator for reading, processing, executing, or translating structured text or binary files. It is widely used for building languages, tools, and frameworks.

What are antlr4ts's main functionalities?

Grammar Definition

Define a grammar using ANTLR syntax. This example defines a simple grammar that recognizes the word 'hello' followed by an identifier.

grammar Hello;

r  : 'hello' ID;
ID : [a-z]+;
WS : [ \t\r\n]+ -> skip;

Generating Parser and Lexer

Generate a lexer and parser from the defined grammar and use them to parse an input string. This example shows how to create a lexer and parser for the 'Hello' grammar and parse the input 'hello world'.

const antlr4ts = require('antlr4ts');
const HelloLexer = require('./HelloLexer');
const HelloParser = require('./HelloParser');

const input = 'hello world';
const inputStream = antlr4ts.CharStreams.fromString(input);
const lexer = new HelloLexer.HelloLexer(inputStream);
const tokenStream = new antlr4ts.CommonTokenStream(lexer);
const parser = new HelloParser.HelloParser(tokenStream);
const tree = parser.r();
console.log(tree.toStringTree(parser));

Tree Walking

Walk the parse tree using a custom listener. This example shows how to create a custom listener that logs when entering a rule and how to walk the parse tree using this listener.

const antlr4ts = require('antlr4ts');
const HelloLexer = require('./HelloLexer');
const HelloParser = require('./HelloParser');
const HelloListener = require('./HelloListener');

class CustomHelloListener extends HelloListener.HelloListener {
  enterR(ctx) {
    console.log('Entering R: ' + ctx.getText());
  }
}

const input = 'hello world';
const inputStream = antlr4ts.CharStreams.fromString(input);
const lexer = new HelloLexer.HelloLexer(inputStream);
const tokenStream = new antlr4ts.CommonTokenStream(lexer);
const parser = new HelloParser.HelloParser(tokenStream);
const tree = parser.r();

const listener = new CustomHelloListener();
antlr4ts.tree.ParseTreeWalker.DEFAULT.walk(listener, tree);

Other packages similar to antlr4ts

pegjs

PEG.js is a simple parser generator for JavaScript that produces fast parsers with excellent error reporting. Unlike ANTLR, which uses LL(*) parsing, PEG.js uses Parsing Expression Grammars (PEGs). PEG.js is simpler to use for smaller projects but may not handle complex grammars as efficiently as ANTLR.

nearley

Nearley is a fast, powerful parser toolkit for JavaScript. It uses Earley parsing, which can parse all context-free grammars, including ambiguous ones. Nearley is more flexible than ANTLR but can be slower for certain types of grammars.

jison

Jison is a parser generator that converts a context-free grammar into a JavaScript parser. It is similar to Bison but for JavaScript. Jison is easier to integrate with JavaScript projects but may not offer the same level of optimization and features as ANTLR.

README

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.

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. Install antlr4ts as a runtime dependency using your preferred package manager.

npm install antlr4ts --save

yarn add antlr4ts

1. Install antlr4ts-cli as a development dependency using your preferred package manager.

npm install antlr4ts-cli --save-dev

yarn add -D antlr4ts-cli

1. Add a grammar to your project, e.g. path/to/MyGrammar.g4

2. Add a script to package.json for compiling your grammar to TypeScript

   "scripts": {
     // ...
     "antlr4ts": "antlr4ts -visitor path/to/MyGrammar.g4"
   }
   

3. 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)