or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

error-handling.mdindex.mdparse-tree-api.mdruntime-api.mdtool-api.mdutilities.md
tile.json

tessl/maven-org-antlr--antlr4-master

ANTLR is a powerful parser generator for reading, processing, executing, or translating structured text or binary files

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.antlr/antlr4-master@4.7.x

To install, run

npx @tessl/cli install tessl/maven-org-antlr--antlr4-master@4.7.0

index.mddocs/

ANTLR4

ANTLR (ANother Tool for Language Recognition) is a powerful parser generator for reading, processing, executing, or translating structured text or binary files. It transforms formal grammars into parsers and lexers for multiple target languages including Java, C#, Python, JavaScript, Go, C++, and Swift.

Package Information

  • Package Name: ANTLR4
  • Package Type: Maven
  • Language: Java
  • Installation: 
    <dependency>
  <groupId>org.antlr</groupId>
  <artifactId>antlr4</artifactId>
  <version>4.7.2</version>
</dependency>
  • Runtime Dependency: 
    <dependency>
  <groupId>org.antlr</groupId>
  <artifactId>antlr4-runtime</artifactId>
  <version>4.7.2</version>
</dependency>

Core Imports

Tool API (grammar compilation):

import org.antlr.v4.Tool;
import org.antlr.v4.tool.Grammar;
import org.antlr.v4.tool.LexerGrammar;

Runtime API (parsing):

import org.antlr.v4.runtime.*;
import org.antlr.v4.runtime.tree.*;

Generated parser usage:

// Your generated classes
import MyLexer;
import MyParser;

Basic Usage

Grammar Compilation

import org.antlr.v4.Tool;

// Command line compilation
String[] args = {"-visitor", "-listener", "MyGrammar.g4"};
Tool antlr = new Tool(args);
antlr.processGrammarsOnCommandLine();

// Programmatic compilation
Tool tool = new Tool();
tool.outputDirectory = "generated/";  // Set output directory
tool.gen_visitor = true;            // Enable visitor generation
Grammar g = tool.loadGrammar("MyGrammar.g4");
tool.process(g, true);              // Process with code generation

Runtime Parsing

import org.antlr.v4.runtime.*;
import org.antlr.v4.runtime.tree.*;

// Create input stream
CharStream input = CharStreams.fromFileName("input.txt");

// Create lexer
MyLexer lexer = new MyLexer(input);
CommonTokenStream tokens = new CommonTokenStream(lexer);

// Create parser
MyParser parser = new MyParser(tokens);
ParseTree tree = parser.startRule();

// Walk tree with visitor
MyBaseVisitor<String> visitor = new MyBaseVisitor<String>() {
    @Override
    public String visitSomeRule(MyParser.SomeRuleContext ctx) {
        return "Processing: " + ctx.getText();
    }
};
String result = visitor.visit(tree);

// Or use listener
ParseTreeWalker walker = new ParseTreeWalker();
MyBaseListener listener = new MyBaseListener() {
    @Override
    public void enterSomeRule(MyParser.SomeRuleContext ctx) {
        System.out.println("Entering: " + ctx.getText());
    }
};
walker.walk(listener, tree);

Architecture

ANTLR4 consists of several key components:

  • Tool System: Grammar compilation and code generation (org.antlr.v4.Tool)
  • Runtime System: Parser and lexer execution framework (org.antlr.v4.runtime)
  • Parse Tree API: Tree construction and traversal utilities (org.antlr.v4.runtime.tree)
  • ATN System: Augmented Transition Network for parsing decisions (org.antlr.v4.runtime.atn)
  • Error Handling: Comprehensive error recovery and reporting (org.antlr.v4.runtime.*ErrorStrategy)
  • Multi-Language Support: Code generation for 8 target languages

Capabilities

Grammar Compilation Tool

Core functionality for compiling ANTLR4 grammars into parser and lexer code for various target languages.

public class Tool {
    public static void main(String[] args);
    public Tool();
    public Tool(String[] args);
    public void processGrammarsOnCommandLine();
    public Grammar loadGrammar(String fileName);
    public void process(Grammar g, boolean gencode);
    public Grammar createGrammar(GrammarRootAST ast);
    public GrammarRootAST parseGrammar(String fileName);
    public void processNonCombinedGrammar(Grammar g, boolean gencode);
    public boolean checkForRuleIssues(Grammar g);
    public void generateATNs(Grammar g);
    public int getNumErrors();
    public void addListener(ANTLRToolListener tl);
    public void info(String msg);
    public void error(ANTLRMessage msg);
    public void warning(ANTLRMessage msg);
    
    // Configuration fields (direct access)
    public String outputDirectory;
    public String libDirectory;
    public boolean gen_visitor;
    public boolean gen_listener;
    public ErrorManager errMgr;
    public String packageName;
    public String language;
}

public class Grammar {
    public String name;
    public String fileName;
    public Map<String, Rule> rules;
}

Tool API

Runtime Parser and Lexer Framework

Base classes and interfaces for generated parsers and lexers, providing the core parsing infrastructure.

public abstract class Parser extends Recognizer<Token, ParserATNSimulator> {
    public void reset();
    public Token match(int ttype) throws RecognitionException;
    public Token consume();
    public Token matchWildcard() throws RecognitionException;
    public void addParseListener(ParseTreeListener listener);
    public void removeParseListener(ParseTreeListener listener);
    public List<ParseTreeListener> getParseListeners();
    public void removeParseListeners();
    public TokenStream getTokenStream();
    public void setTokenStream(TokenStream input);
    public ParserRuleContext getContext();
    public void setBuildParseTree(boolean buildParseTrees);
    public boolean getBuildParseTree();
    public IntervalSet getExpectedTokens();
    public Token getCurrentToken();
    public void setTrace(boolean trace);
    public void enterRule(ParserRuleContext localctx, int state, int ruleIndex);
    public void exitRule();
    public ANTLRErrorStrategy getErrorHandler();
    public void setErrorHandler(ANTLRErrorStrategy handler);
    public int getNumberOfSyntaxErrors();
    public void notifyErrorListeners(String msg);
    public TerminalNode createTerminalNode(ParserRuleContext parent, Token t);
    public ErrorNode createErrorNode(ParserRuleContext parent, Token t);
    public void enterOuterAlt(ParserRuleContext localctx, int altNum);
    public int getPrecedence();
    public boolean isExpectedToken(int symbol);
    public IntervalSet getExpectedTokensWithinCurrentRule();
    public int getRuleIndex(String ruleName);
    public List<String> getRuleInvocationStack();
}

public abstract class Lexer extends Recognizer<Integer, LexerATNSimulator> {
    public Token nextToken();
    public void skip();
    public void more();
    public void mode(int m);
}

public interface Token {
    /** End-of-file token type */
    int EOF = -1;
    
    /** Invalid token type */
    int INVALID_TYPE = 0;
    
    /** Default channel for tokens */
    int DEFAULT_CHANNEL = 0;
    
    /** Hidden channel for whitespace/comments */
    int HIDDEN_CHANNEL = 1;
    
    /** Epsilon token used during lookahead */
    int EPSILON = -2;
    
    /** Minimum constant value for user-defined token types */
    int MIN_USER_TOKEN_TYPE = 1;
    
    /** Minimum constant value for user-defined token channels */
    int MIN_USER_CHANNEL_VALUE = 2;
    
    int getType();
    String getText();
    int getLine();
    int getCharPositionInLine();
    int getChannel();
    int getTokenIndex();
    int getStartIndex();
    int getStopIndex();
    TokenSource getTokenSource();
    CharStream getInputStream();
}

Runtime API

Parse Tree Construction and Traversal

Complete API for building, navigating, and manipulating parse trees with visitor and listener patterns.

public interface ParseTree extends SyntaxTree {
    ParseTree getParent();
    ParseTree getChild(int i);
    int getChildCount();
    <T> T accept(ParseTreeVisitor<? extends T> visitor);
}

public interface ParseTreeVisitor<T> {
    T visit(ParseTree tree);
    T visitChildren(RuleNode node);
    T visitTerminal(TerminalNode node);
    T visitErrorNode(ErrorNode node);
}

public interface ParseTreeListener {
    void enterEveryRule(ParserRuleContext ctx);
    void exitEveryRule(ParserRuleContext ctx);
    void visitTerminal(TerminalNode node);
    void visitErrorNode(ErrorNode node);
}

public class ParseTreeWalker {
    public static void walk(ParseTreeListener listener, ParseTree t);
}

Parse Tree API

Error Handling and Recovery

Comprehensive error handling system with customizable recovery strategies and detailed error reporting.

public interface ANTLRErrorListener {
    void syntaxError(Recognizer<?,?> recognizer, Object offendingSymbol, 
                    int line, int charPositionInLine, String msg, 
                    RecognitionException e);
}

public interface ANTLRErrorStrategy {
    void reset(Parser recognizer);
    Token recoverInline(Parser recognizer) throws RecognitionException;
    void recover(Parser recognizer, RecognitionException e) throws RecognitionException;
}

public class DefaultErrorStrategy implements ANTLRErrorStrategy;
public class BailErrorStrategy extends DefaultErrorStrategy;

Error Handling

Stream and Token Management

Input stream management and token processing infrastructure for feeding data to parsers and lexers.

public class CharStreams {
    public static CharStream fromFileName(String fileName) throws IOException;
    public static CharStream fromString(String s);
    public static CharStream fromReader(Reader r) throws IOException;
}

public class CommonTokenStream extends BufferedTokenStream {
    public CommonTokenStream(TokenSource tokenSource);
    public List<Token> getTokens();
    public List<Token> getTokens(int start, int stop);
}

public class CommonToken implements WritableToken {
    public CommonToken(int type, String text);
    public String getText();
    public int getType();
    public int getLine();
    public int getCharPositionInLine();
}

Runtime API

Utility Classes and Helpers

Supporting utilities for tree manipulation, data structures, and testing infrastructure.

public class Trees {
    public static String toStringTree(ParseTree t);
    public static List<ParseTree> getChildren(ParseTree t);
    public static List<ParseTree> getAncestors(ParseTree t);
    public static Collection<ParseTree> findAllTokenNodes(ParseTree t, int ttype);
    public static Collection<ParseTree> findAllRuleNodes(ParseTree t, int ruleIndex);
}

public class ParseTreeProperty<V> {
    public V get(ParseTree node);
    public void put(ParseTree node, V value);
    public V removeFrom(ParseTree node);
}

public class TestRig {
    public static void main(String[] args) throws Exception;
}

Utilities

Types

Core Interfaces

public interface CharStream extends IntStream {
    String getText(Interval interval);
    String toString();
}

public interface TokenStream extends IntStream {
    Token get(int index);
    TokenSource getTokenSource();
    String getText();
    String getText(Interval interval);
}

public interface IntStream {
    void consume();
    int LA(int i);
    int mark();
    void release(int marker);
    int index();
    void seek(int index);
    int size();
    String getSourceName();
}

Context Classes

public class ParserRuleContext extends RuleContext implements RuleNode {
    public ParserRuleContext parent;
    public int invokingState;
    public List<ParseTree> children;
    
    public void addChild(TerminalNode t);
    public void addChild(RuleContext ruleInvocation);
    public <T> T accept(ParseTreeVisitor<? extends T> visitor);
}

public class RuleContext {
    public RuleContext parent;
    public int invokingState;
    
    public int depth();
    public boolean isEmpty();
    public Interval getSourceInterval();
    public RuleContext getPayload();
}