or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

atn-dfa.mdcontext.mdcore-classes.mderror-handling.mdindex.mdparse-trees.mdstreams.mdutilities.md
tile.json

tessl/npm-antlr4

JavaScript runtime for ANTLR4 parsers and lexers providing complete parsing infrastructure

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/antlr4@4.13.x

To install, run

npx @tessl/cli install tessl/npm-antlr4@4.13.0

index.mddocs/

ANTLR4 JavaScript Runtime

ANTLR4 JavaScript Runtime is a comprehensive parsing infrastructure library that enables building parsers, lexers, and language processors in JavaScript/TypeScript. It provides the complete runtime environment for parsers generated by the ANTLR4 parser generator, supporting both browser and Node.js environments with full TypeScript definitions.

Package Information

  • Package Name: antlr4
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install antlr4
  • Node.js: Requires Node.js >= 16
  • Browsers: Tested in Chrome, Firefox, Safari, IE

Core Imports

ESM imports:

import {
  CommonTokenStream,
  CharStreams,
  Parser,
  Lexer,
  ParseTreeWalker,
  ParseTreeListener,
  ParseTreeVisitor,
  RecognitionException,
  Token,
  ParserRuleContext,
  RuleContext,
  TerminalNode,
  RuleNode,
  ErrorListener
} from "antlr4";

CommonJS imports:

const {
  CommonTokenStream,
  CharStreams,
  Parser,
  Lexer,
  ParseTreeWalker,
  ParseTreeListener,
  ParseTreeVisitor,
  RecognitionException,
  Token,
  ParserRuleContext,
  RuleContext,
  TerminalNode,
  RuleNode,
  ErrorListener
} = require("antlr4");

Basic Usage

import { CharStreams, CommonTokenStream } from "antlr4";
import MyLexer from "./MyLexer.js";  // Generated lexer
import MyParser from "./MyParser.js"; // Generated parser

// Create input stream from string
const input = CharStreams.fromString("your input text here");

// Create lexer
const lexer = new MyLexer(input);

// Create token stream
const tokens = new CommonTokenStream(lexer);

// Create parser
const parser = new MyParser(tokens);

// Parse starting from a specific rule (replace 'startRule' with your grammar's start rule)
const tree = parser.startRule();

// Access parse tree
console.log(tree.toStringTree(parser.ruleNames, parser));

Architecture

ANTLR4 JavaScript Runtime is built around several key architectural components:

  • Input Processing: Character and token streams (CharStream, TokenStream) for handling various input sources
  • Core Recognition: Base classes (Recognizer, Parser, Lexer) that provide the fundamental parsing infrastructure
  • Parse Tree Management: Complete AST representation (ParseTree, RuleNode, TerminalNode) with visitor/listener patterns
  • Error Handling: Comprehensive error reporting and recovery mechanisms (RecognitionException, ErrorStrategy)
  • ATN Engine: Advanced parser simulation using Augmented Transition Networks for optimized parsing decisions
  • Stream Processing: Multiple input stream types supporting strings, files, buffers, and other data sources

Capabilities

Core Classes

Essential parser and lexer base classes that provide the fundamental parsing infrastructure for language recognition.

abstract class Recognizer<TSymbol> {
  state: number;
  removeErrorListeners(): void;
  addErrorListener(listener: ErrorListener<TSymbol>): void;
  getLiteralNames(): string[];
  getSymbolicNames(): string[];
}

class Parser extends Recognizer<Token> {
  static EOF: number;
  buildParseTrees: boolean;
  
  constructor(input: TokenStream);
  match(ttype: number): Token;
  matchWildcard(): Token;
  consume(): Token;
  getCurrentToken(): Token;
  getTokenStream(): TokenStream;
  setTokenStream(input: TokenStream): void;
  reset(): void;
  addParseListener(listener: ParseTreeListener): void;
  removeParseListener(listener: ParseTreeListener): void;
  getParseListeners(): ParseTreeListener[];
  notifyErrorListeners(msg: string, offendingToken: Token, err: RecognitionException | undefined): void;
}

class Lexer extends Recognizer<number> {
  static DEFAULT_MODE: number;
  static DEFAULT_TOKEN_CHANNEL: number;
  static HIDDEN: number;
  
  constructor(input: CharStream);
  nextToken(): Token;
  reset(): void;
  getAllTokens(): Token[];
  getCharStream(): CharStream;
  setCharStream(input: CharStream): void;
}

Core Classes

Input and Output Streams

Comprehensive stream processing for handling character data, tokens, and various input sources including strings, files, and buffers.

class CharStreams {
  static fromString(data: string, decodeToUnicodeCodePoints?: boolean): CharStream;
  static fromBuffer(buffer: Buffer, encoding?: string): CharStream;
  static fromBlob(blob: Blob, encoding: string, onLoad: (stream: CharStream) => void, onError: (error: Error) => void): void;
  static fromPath(path: string, encoding: string, callback: (err: Error, stream: CharStream) => void): void;
  static fromPathSync(path: string, encoding: string): CharStream;
}

class BufferedTokenStream extends TokenStream {
  tokenSource: Lexer;
}

class CommonTokenStream extends BufferedTokenStream {
  constructor(lexer: Lexer, channel?: number);
  fill(): void;
  tokens: Token[];
}

Streams

Parse Tree Processing

Complete parse tree representation and manipulation including visitor and listener patterns for AST traversal and processing.

abstract class ParseTree extends SyntaxTree {
  getText(): string;
}

class ParseTreeWalker {
  static DEFAULT: ParseTreeWalker;
  walk<T extends ParseTreeListener>(listener: T, t: ParseTree): void;
}

abstract class ParseTreeVisitor<Result> {
  visit(tree: ParseTree): Result;
  visitChildren(node: RuleNode): Result;
  visitTerminal(node: TerminalNode): Result;
  visitErrorNode(node: ErrorNode): Result;
}

Parse Trees

Error Handling

Robust error reporting and recovery strategies for handling syntax errors and providing meaningful diagnostics during parsing.

class RecognitionException extends Error {
  ctx: RuleContext;
  offendingToken: Token | null;
  constructor(params: ExceptionParams);
}

abstract class ErrorStrategy {
  reset(recognizer: Parser): void;
  recover(recognizer: Parser, e: RecognitionException): void;
  recoverInline(recognizer: Parser): Token;
}

Error Handling

ATN and DFA

Advanced Augmented Transition Network and Deterministic Finite Automaton classes for parser optimization and configuration.

class ATN {
  states: ATNState[];
  decisionToState: DecisionState[];
  getExpectedTokens(stateNumber: number, ctx: RuleContext): IntervalSet;
}

class ParserATNSimulator extends ATNSimulator {
  predictionMode: PredictionMode;
  adaptivePredict(input: TokenStream, decision: number, outerContext: ParserRuleContext): number;
}

ATN and DFA

Rule and Prediction Contexts

Context management for parse rules and prediction contexts that maintain parsing state and enable advanced parsing features.

class RuleContext extends RuleNode {
  parentCtx: RuleContext | undefined;
  invokingState: number;
  toStringTree(ruleNames: string[] | null, recog: Parser): string;
}

class ParserRuleContext extends RuleContext {
  start: Token;
  stop: Token | undefined;
  children: ParseTree[] | null;
  getToken(ttype: number, i: number): TerminalNode;
  getTokens(ttype: number): TerminalNode[];
}

Context

Utilities

Utility classes and functions for common operations including bit sets, intervals, string processing, and debugging support.

class BitSet {
  readonly length: number;
  get(index: number): number;
  values(): Array<number>;
  toString(): string;
}

class IntervalSet {
  intervals: Interval[];
  contains(i: number): boolean;
  toString(literalNames?: (string | null)[], symbolicNames?: string[]): string;
}

Utilities

Additional Core Exports

Key additional classes and interfaces exported by the ANTLR4 runtime.

// Token and Stream Processing
class TokenStreamRewriter {
  constructor(tokens: TokenStream);
  insertAfter(index: number, text: string): void;
  insertBefore(index: number, text: string): void;
  replace(index: number, text: string): void;
  delete(index: number): void;
  getText(): string;
}

// Error Handling Extensions
class InputMismatchException extends RecognitionException {
  constructor(recognizer: Parser);
}

class NoViableAltException extends RecognitionException {
  constructor(recognizer: Parser, input: TokenStream, startToken: Token, offendingToken: Token, deadEndConfigs: any, ctx: ParserRuleContext);
}

class FailedPredicateException extends RecognitionException {
  constructor(recognizer: Parser, predicate?: string, message?: string);
}

// Error Strategies
class BailErrorStrategy {
  recover(recognizer: Parser, e: RecognitionException): void;
  recoverInline(recognizer: Parser): Token;
}

class DefaultErrorStrategy {
  recover(recognizer: Parser, e: RecognitionException): void;
  recoverInline(recognizer: Parser): Token;
  sync(recognizer: Parser): void;
}

// Error Listeners
abstract class ErrorListener<TSymbol> {
  syntaxError(recognizer: Recognizer<TSymbol>, offendingSymbol: TSymbol, line: number, column: number, msg: string, e: RecognitionException | undefined): void;
}

class DiagnosticErrorListener extends ErrorListener<Token> {
  exactOnly: boolean;
  constructor(exactOnly?: boolean);
}

Key Constants

// Token constants
Token.INVALID_TYPE = 0;
Token.EOF = -1;
Token.DEFAULT_CHANNEL = 0;
Token.HIDDEN_CHANNEL = 1;
Token.EPSILON = -2;
Token.MIN_USER_TOKEN_TYPE = 1;

// Lexer constants  
Lexer.DEFAULT_MODE = 0;
Lexer.MORE = -2;
Lexer.SKIP = -3;
Lexer.DEFAULT_TOKEN_CHANNEL = 0;
Lexer.HIDDEN = 1;
Lexer.MIN_CHAR_VALUE = 0x0000;
Lexer.MAX_CHAR_VALUE = 0x10FFFF;

// Parser constants
Parser.EOF = -1;

// Prediction modes
PredictionMode.SLL;           // Strong LL
PredictionMode.LL;            // Full LL  
PredictionMode.LL_EXACT_AMBIG_DETECTION;