{"id":10503,"library":"antlr4ts","title":"ANTLR 4 Runtime for TypeScript/JavaScript","description":"antlr4ts is the official TypeScript/JavaScript runtime for ANTLR 4, a powerful parser generator. It enables developers to execute grammars written in ANTLR 4 within JavaScript or TypeScript applications, providing core parsing functionalities such as lexers, parsers, and tree walkers/visitors. Currently, the package is in an alpha state (v0.5.0-alpha.4), indicating ongoing development and potential API changes. Releases are made periodically to incorporate updates from the main ANTLR 4 Java target, fix bugs, and ensure compatibility with newer TypeScript versions. Its key differentiators include strong typing due to its TypeScript foundation, full support for ANTLR 4 features like listeners and visitors, and an integrated CLI for grammar compilation.","status":"active","version":"0.5.0-alpha.4","language":"javascript","source_language":"en","source_url":"https://github.com/tunnelvisionlabs/antlr4ts","tags":["javascript","ANTLR4","typescript"],"install":[{"cmd":"npm install antlr4ts","lang":"bash","label":"npm"},{"cmd":"yarn add antlr4ts","lang":"bash","label":"yarn"},{"cmd":"pnpm add antlr4ts","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Development dependency for compiling .g4 grammars into TypeScript source files.","package":"antlr4ts-cli","optional":false}],"imports":[{"note":"Primary usage is with ES modules. CommonJS `require` works but is not idiomatic for modern TypeScript projects using this library.","wrong":"const ANTLRInputStream = require('antlr4ts').ANTLRInputStream;","symbol":"ANTLRInputStream","correct":"import { ANTLRInputStream } from 'antlr4ts';"},{"note":"Most core runtime components are named exports from the root package.","wrong":"import CommonTokenStream from 'antlr4ts/CommonTokenStream';","symbol":"CommonTokenStream","correct":"import { CommonTokenStream } from 'antlr4ts';"},{"note":"Utility classes like `ParseTreeWalker` are often found in submodules like `antlr4ts/tree/ParseTreeWalker`.","wrong":"import { ParseTreeWalker } from 'antlr4ts';","symbol":"ParseTreeWalker","correct":"import { ParseTreeWalker } from 'antlr4ts/tree/ParseTreeWalker';"},{"note":"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.","wrong":"import { MyGrammarLexer } from 'antlr4ts';","symbol":"MyGrammarLexer","correct":"import { MyGrammarLexer } from './MyGrammarLexer';"}],"quickstart":{"code":"import { ANTLRInputStream, CommonTokenStream } from 'antlr4ts';\nimport { MyGrammarLexer } from './MyGrammarLexer'; // Assuming generated lexer\nimport { MyGrammarParser, FunctionDeclarationContext } from './MyGrammarParser'; // Assuming generated parser and context\nimport { MyGrammarParserListener } from './MyGrammarParserListener'; // Assuming generated listener interface\nimport { ParseTreeWalker } from 'antlr4ts/tree/ParseTreeWalker';\n\n// Step 1: Define your input text\nconst inputText = \"function myFunction() { return 42; }\";\n\n// Step 2: Create an ANTLRInputStream from the input\nlet inputStream = new ANTLRInputStream(inputText);\n\n// Step 3: Create a lexer (generated from your grammar) and tokenize the input\nlet lexer = new MyGrammarLexer(inputStream);\nlet tokenStream = new CommonTokenStream(lexer);\n\n// Step 4: Create a parser (generated from your grammar) and parse the token stream\nlet parser = new MyGrammarParser(tokenStream);\n\n// Step 5: Specify the entry point rule for parsing\nlet tree = parser.compilationUnit(); // Assuming 'compilationUnit' is your grammar's starting rule\n\n// Step 6: (Optional) Implement a listener to traverse the parse tree\nclass MyFunctionListener implements MyGrammarParserListener {\n    enterFunctionDeclaration(context: FunctionDeclarationContext) {\n        console.log(`Found function: ${context.text} on line ${context._start.line}`);\n        // Additional logic to extract details from the function declaration\n    }\n    // Implement other enter/exit methods as needed for your grammar rules\n}\n\n// Step 7: Walk the parse tree with your listener\nconst listener = new MyFunctionListener();\nParseTreeWalker.DEFAULT.walk(listener, tree);\n\nconsole.log(\"Parsing complete. Check console for listener output.\");","lang":"typescript","description":"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."},"warnings":[{"fix":"Regularly check the GitHub releases and README for breaking changes when updating versions. Pinning exact alpha versions might be necessary for stability.","message":"The package is currently in an 'alpha' state. This means the API is subject to change without strict adherence to semantic versioning for breaking changes, and stability cannot be guaranteed. Use in production with caution.","severity":"gotcha","affected_versions":">=0.4.0-alpha.1"},{"fix":"Review the release notes for each alpha version when upgrading and adjust code to match new API surfaces, such as accessing properties directly instead of through getter/setter methods.","message":"Between alpha versions, method signatures and property access patterns can change. For example, some 'get'/'set' methods were converted to properties in `0.4.0-alpha.3`.","severity":"breaking","affected_versions":">=0.4.0-alpha.3"},{"fix":"Ensure Java is installed and configured in your system's PATH. If `antlr4ts-cli` fails, verify your Java installation.","message":"Compiling ANTLR 4 grammars (`.g4` files) into TypeScript code requires a Java Runtime Environment (JRE 1.6+, 1.8+ recommended) installed on the development machine, as the ANTLR tool itself is Java-based.","severity":"gotcha","affected_versions":">=0.4.0-alpha.1"},{"fix":"Always use a compatible TypeScript version as specified in the package's requirements. Update your `tsconfig.json` and `typescript` dependency if compilation errors related to language features occur.","message":"Older versions of `antlr4ts` and its generated code had specific TypeScript version requirements. For instance, TypeScript 2.1 became mandatory in `0.4.0-alpha.2`, and `0.5.0-alpha.4` included fixes for TypeScript 4 compatibility.","severity":"breaking","affected_versions":">=0.4.0-alpha.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `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.","cause":"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).","error":"ReferenceError: require is not defined"},{"fix":"Run 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.","cause":"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.","error":"error TS2307: Cannot find module './MyGrammarLexer' or its corresponding type declarations."},{"fix":"Install 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.","cause":"The `antlr4ts-cli` command failed because a compatible Java Runtime Environment is not installed or not accessible in the system's PATH.","error":"Error: Java Runtime Environment (JRE) 1.6+ is required."}],"ecosystem":"npm"}