Skip to content

tunnelvisionlabs/antlr4ts

Repository files navigation

antlr4ts - TypeScript/JavaScript target for ANTLR 4

Join the chat at https://gitter.im/tunnelvisionlabs/antlr4ts

Build status

License

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