Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ANTLRInputStream
✓ import { ANTLRInputStream } from 'antlr4ts';
✗ const ANTLRInputStream = require('antlr4ts').ANTLRInputStream;
Primary usage is with ES modules. CommonJS `require` works but is not idiomatic for modern TypeScript projects using this library.
CommonTokenStream
✓ import { CommonTokenStream } from 'antlr4ts';
✗ import CommonTokenStream from 'antlr4ts/CommonTokenStream';
Most core runtime components are named exports from the root package.
ParseTreeWalker
✓ import { ParseTreeWalker } from 'antlr4ts/tree/ParseTreeWalker';
✗ import { ParseTreeWalker } from 'antlr4ts';
Utility classes like `ParseTreeWalker` are often found in submodules like `antlr4ts/tree/ParseTreeWalker`.
MyGrammarLexer
✓ import { MyGrammarLexer } from './MyGrammarLexer';
✗ import { MyGrammarLexer } from 'antlr4ts';
Lexer and parser classes (`MyGrammarLexer`, `MyGrammarParser`) are generated from your `.g4` grammar file and reside in your project's local directory, not within the `antlr4ts` package itself.
Demonstrates the basic workflow of parsing an input string using a generated ANTLR 4 lexer and parser in TypeScript, including traversing the parse tree with a listener.
import { ANTLRInputStream, CommonTokenStream } from 'antlr4ts';
import { MyGrammarLexer } from './MyGrammarLexer'; // Assuming generated lexer
import { MyGrammarParser, FunctionDeclarationContext } from './MyGrammarParser'; // Assuming generated parser and context
import { MyGrammarParserListener } from './MyGrammarParserListener'; // Assuming generated listener interface
import { ParseTreeWalker } from 'antlr4ts/tree/ParseTreeWalker';
// Step 1: Define your input text
const inputText = "function myFunction() { return 42; }";
// Step 2: Create an ANTLRInputStream from the input
let inputStream = new ANTLRInputStream(inputText);
// Step 3: Create a lexer (generated from your grammar) and tokenize the input
let lexer = new MyGrammarLexer(inputStream);
let tokenStream = new CommonTokenStream(lexer);
// Step 4: Create a parser (generated from your grammar) and parse the token stream
let parser = new MyGrammarParser(tokenStream);
// Step 5: Specify the entry point rule for parsing
let tree = parser.compilationUnit(); // Assuming 'compilationUnit' is your grammar's starting rule
// Step 6: (Optional) Implement a listener to traverse the parse tree
class MyFunctionListener implements MyGrammarParserListener {
enterFunctionDeclaration(context: FunctionDeclarationContext) {
console.log(`Found function: ${context.text} on line ${context._start.line}`);
// Additional logic to extract details from the function declaration
}
// Implement other enter/exit methods as needed for your grammar rules
}
// Step 7: Walk the parse tree with your listener
const listener = new MyFunctionListener();
ParseTreeWalker.DEFAULT.walk(listener, tree);
console.log("Parsing complete. Check console for listener output.");
antlr4ts --version
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use CommonJS `require()` syntax in an ES Module context (e.g., in a modern TypeScript project configured for ES Modules or in a browser environment without a bundler).
fixChange `const MyClass = require('antlr4ts').MyClass;` to `import { MyClass } from 'antlr4ts';`. Ensure your `tsconfig.json` targets `ES2015` or later and has `"module": "ESNext"` or `"ES2020"` for Node.js environments, or `"UMD"`/`"AMD"` for browser environments if using a bundler. error TS2307: Cannot find module './MyGrammarLexer' or its corresponding type declarations.
The generated lexer/parser files (`.ts` or `.js` and `.d.ts`) were not created or are not in the expected path. This typically means the `antlr4ts-cli` command was not run or failed.
fixRun your `antlr4ts` script (e.g., `npm run antlr4ts`) to generate the lexer and parser files from your `.g4` grammar. Verify the output directory and adjust your import paths accordingly.
Error: Java Runtime Environment (JRE) 1.6+ is required.
The `antlr4ts-cli` command failed because a compatible Java Runtime Environment is not installed or not accessible in the system's PATH.
fixInstall a JRE version 1.6 or higher (JRE 8 or newer is recommended). Ensure the `java` executable is available in your system's PATH environment variable.
Upgrade
Version history
0.5.0-alpha.4latest on npm
Audit
Dependencies
antlr4ts-clirequiredDevelopment dependency for compiling .g4 grammars into TypeScript source files.