ANTLR 4 JavaScript Runtime

Common errors

• Error: The '`MyLexer`' class extends '`Lexer`' but is missing the following properties from type '`Lexer`': `tokenFactory`

  cause This error typically occurs in TypeScript projects when the generated lexer/parser files (e.g., `MyLexer.js` or `MyLexer.ts`) are out of sync with the `antlr4` runtime library's type definitions. This happens after upgrading the `antlr4` package without regenerating the grammar files.
  fix Regenerate your lexer and parser JavaScript/TypeScript files using the ANTLR tool that matches the version of your `antlr4` npm package. For example, if you updated to `antlr4@4.13.2`, use `antlr-4.13.2-complete.jar` to generate your grammar files.

• TypeError: Cannot read properties of undefined (reading 'CommonTokenStream')

  cause This usually indicates an incorrect CommonJS `require` call where the named export is not directly accessible or a missing dependency.
  fix For CommonJS, use `const { CommonTokenStream } = require('antlr4');` or `const antlr4 = require('antlr4'); const CommonTokenStream = antlr4.CommonTokenStream;`. Ensure `antlr4` is installed.

• Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()

  cause This error occurs in a CommonJS context when a module, explicitly marked as ESM-only, is attempted to be `require()`-d. While `antlr4` supports both, specific deep imports or usage in older build tools might trigger this.
  fix If your project is CommonJS-based, ensure you are using `const { NamedExport } = require('antlr4');`. If this specific error persists for deep imports, consider refactoring the affected part of your code to use dynamic `import()` or switch your project to ES Modules.

Warnings

• breaking ANTLR's versioning does not strictly follow npm semantic versioning, prioritizing consistency across its 10 target languages. This means minor version updates (e.g., 4.x.0 to 4.y.0) can introduce breaking changes. Developers are strongly advised to remove the `^` or `~` from `antlr4` entries in `package.json` to pin specific versions (e.g., `"antlr4": "4.13.2"`) and manually update.
  Fix: Update your `package.json` to pin the exact version of `antlr4` you are using (e.g., `"antlr4": "4.13.2"`) to prevent unexpected breaking changes with `npm install`.
• breaking Starting with ANTLR 4.10.0, lexers and parsers generated by the ANTLR tool are often incompatible with code generated by previous versions of the tool. While the JavaScript runtime specifically noted 'except probably javascript' for 4.10.0, this general rule applies across targets. If you upgrade the `antlr4` runtime, you should also regenerate all your grammar-based lexer and parser code using the ANTLR tool (e.g., the `antlr4` JAR) of the *same major version* as the runtime to ensure compatibility.
  Fix: After updating the `antlr4` npm package, regenerate your lexer and parser JavaScript files using the ANTLR tool (e.g., `java -jar antlr-4.13.2-complete.jar -Dlanguage=JavaScript MyGrammar.g4`) matching the new runtime version.
• breaking The `antlr4` package requires Node.js version 16 or newer. Using it with older Node.js versions will result in runtime errors or failures during installation.
  Fix: Ensure your Node.js environment is updated to version 16 or higher. You can use `nvm` or your system's package manager to upgrade Node.js.
• deprecated The `ANTLRInputStream` class, used for creating input streams, has been deprecated in favor of `CharStreams.fromString()` (or other `CharStreams` methods for files/buffers). While still functional, using `ANTLRInputStream` directly is discouraged.
  Fix: Replace `new ANTLRInputStream(inputString)` with `CharStreams.fromString(inputString)`.

Install

• npm install antlr4 npm
• yarn add antlr4 yarn
• pnpm add antlr4 pnpm

Imports

• CharStreams
  wrong:

  import { ANTLRInputStream } from 'antlr4'; // ANTLRInputStream is deprecated

  correct:

  import { CharStreams } from 'antlr4';

  `CharStreams.fromString()` is the recommended way to create an input stream from a string since ANTLR 4.9. The older `ANTLRInputStream` is still available but deprecated.
• CommonTokenStream
  wrong:

  const CommonTokenStream = require('antlr4').CommonTokenStream;

  correct:

  import { CommonTokenStream } from 'antlr4';

  The library supports both ES Modules and CommonJS. Use named imports for ESM. CJS users should access exports directly from the main `antlr4` module.
• ParserRuleContext

  import { ParserRuleContext } from 'antlr4';

  Base class for all generated parser rule contexts. Essential for working with parse trees.
• error.ErrorListener

  import { error } from 'antlr4';
  const { ErrorListener } = error;

  Error handling components are nested under the `error` namespace.

Quickstart

This quickstart demonstrates the core pipeline of using the ANTLR 4 JavaScript runtime to parse a simple input string. It shows how to initialize `CharStreams`, `CommonTokenStream`, and use placeholder lexer and parser classes (which would be generated by the ANTLR tool from your grammar), including custom error handling.

import { CharStreams, CommonTokenStream, error } from 'antlr4';
// IMPORTANT: MyLexer and MyParser are GENERATED by the ANTLR tool from your grammar.
// For example, if you have 'Hello.g4', run 'antlr4 -Dlanguage=JavaScript Hello.g4'
// This will create 'HelloLexer.js', 'HelloParser.js', etc. in your output directory.
// Replace './MyLexer' and './MyParser' with the correct paths to your generated files.

// A minimal mock for demonstration. In a real app, these would be generated.
class MyLexer extends error.DefaultErrorListener {
  constructor(input) { super(input); this.tokenFactory = null; this.charPositionInLine = 0; this.line = 1; }
  nextToken() { return null; /* Real lexer logic */ }
  getAllTokens() { return [{ type: 1, text: 'hello' }, { type: 2, text: 'world' }]; }
}
class MyParser extends error.DefaultErrorListener {
  constructor(tokens) { super(tokens); this.ruleNames = ['start']; this.errorHandler = null; this.tokenStream = tokens; }
  start() { return { text: 'parsed hello world' }; /* Real parser logic */ }
}

class CustomErrorListener extends error.ErrorListener {
  syntaxError(recognizer, offendingSymbol, line, charPositionInLine, msg, e) {
    console.error(`Line ${line}, column ${charPositionInLine}: ${msg}`);
  }
}

// 1. Create an input stream from your source code
const input = CharStreams.fromString('hello world');

// 2. Create a lexer (tokenizer) from the input stream
//    (Replace MyLexer with your generated lexer, e.g., 'HelloLexer')
const lexer = new MyLexer(input);
lexer.removeErrorListeners(); // Remove default console error listener
lexer.addErrorListener(new CustomErrorListener());

// 3. Create a token stream from the lexer
const tokens = new CommonTokenStream(lexer);

// 4. Create a parser from the token stream
//    (Replace MyParser with your generated parser, e.g., 'HelloParser')
const parser = new MyParser(tokens);
parser.removeErrorListeners(); // Remove default console error listener
parser.addErrorListener(new CustomErrorListener());

// 5. Invoke the parser's entry rule (e.g., 'start')
const tree = parser.start();

console.log('Successfully attempted to parse:', input.getText());
// In a real scenario, 'tree' would be a parse tree object
// console.log('Parse tree:', tree.toStringTree(parser.ruleNames));