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

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

Overview

Eval results

Files

Tool API

Name: tessl/maven-org-antlr--antlr4-master
Author: tessl

The ANTLR4 tool API provides comprehensive functionality for compiling grammar files into parser and lexer code for multiple target languages.

Capabilities

Main Tool Class

The primary interface for ANTLR4 grammar compilation and code generation.

/**
 * Main class for ANTLR4 grammar compilation
 */
public class Tool {
    /** Command-line interface entry point */
    public static void main(String[] args);
    
    /** Default constructor */
    public Tool();
    
    /** Constructor with command line arguments */
    public Tool(String[] args);
    
    /** Process grammar files specified on command line */
    public void processGrammarsOnCommandLine();
    
    /** Load and parse a grammar file */
    public Grammar loadGrammar(String fileName) throws IOException;
    
    /** Create grammar object from parsed AST */
    public Grammar createGrammar(GrammarRootAST ast);
    
    /** Parse grammar file into AST */
    public GrammarRootAST parseGrammar(String fileName);
    
    /** Parse grammar from string into AST */
    public GrammarRootAST parseGrammarFromString(String grammar);
    
    /** Main processing method for loaded grammars */
    public void process(Grammar g, boolean gencode);
    
    /** Process non-combined grammar */
    public void processNonCombinedGrammar(Grammar g, boolean gencode);
    
    /** Check grammar for rule issues */
    public boolean checkForRuleIssues(Grammar g);
    
    /** Load imported grammar */
    public Grammar loadImportedGrammar(Grammar g, GrammarAST nameNode);
    
    /** Generate ATNs for grammar */
    public void generateATNs(Grammar g);
    
    /** Get output file writer */
    public Writer getOutputFileWriter(Grammar g, String fileName) throws IOException;
    
    /** Get output directory for file */
    public File getOutputDirectory(String fileNameWithPath);
    
    /** Display help information */
    public void help();
    
    /** Log message with component */
    public void log(String component, String msg);
    
    /** Log message */
    public void log(String msg);
    
    /** Get number of errors */
    public int getNumErrors();
    
    /** Add tool listener */
    public void addListener(ANTLRToolListener tl);
    
    /** Remove tool listener */
    public void removeListener(ANTLRToolListener tl);
    
    /** Get all listeners */
    public List<ANTLRToolListener> getListeners();
    
    /** Report info message */
    public void info(String msg);
    
    /** Report error message */
    public void error(ANTLRMessage msg);
    
    /** Report warning message */
    public void warning(ANTLRMessage msg);
    
    /** Display version information */
    public void version();
    
    /** Exit with code */
    public void exit(int e);
    
    /** Panic exit */
    public void panic();
}

Usage Examples:

import org.antlr.v4.Tool;

// Command line style usage
String[] args = {
    "-visitor",           // Generate visitor classes
    "-listener",          // Generate listener classes  
    "-o", "output/",      // Output directory
    "-lib", "grammars/",  // Library directory
    "MyGrammar.g4"        // Grammar file
};
Tool antlr = new Tool(args);
antlr.processGrammarsOnCommandLine();

// Programmatic usage
Tool tool = new Tool();
tool.outputDirectory = "gen/";        // Set output directory (public field)
tool.gen_visitor = true;             // Enable visitor generation (public field)
tool.gen_listener = true;            // Enable listener generation (public field)

Grammar grammar = tool.loadGrammar("Calculator.g4");
tool.process(grammar, true);         // Process with code generation enabled

Grammar Representation

Classes representing parsed ANTLR grammars with their rules and options.

/**
 * Represents a parsed ANTLR grammar
 */
public class Grammar {
    /** Grammar name from grammar declaration */
    public String name;
    
    /** Source file name */
    public String fileName;
    
    /** Map of rule name to Rule object */
    public Map<String, Rule> rules;
    
    /** Grammar type (parser, lexer, combined) */
    public GrammarType getType();
    
    /** Get rule by name */
    public Rule getRule(String name);
    
    /** Get all parser rules */
    public Collection<Rule> getRules();
    
    /** Get start rule for this grammar */
    public Rule getRule(int index);
    
    /** Get grammar options */
    public Map<String, Object> getOptions();
    
    /** Get token names defined in this grammar */
    public String[] getTokenNames();
    
    /** Get rule names defined in this grammar */
    public String[] getRuleNames();
}

/**
 * Specialized grammar for lexer rules
 */
public class LexerGrammar extends Grammar {
    /** Get lexer rules only */
    public Collection<Rule> getRules();
    
    /** Get lexer modes defined in grammar */
    public Set<String> getModes();
}

Grammar Rules

Individual rule representation within grammars.

/**
 * Represents a single grammar rule
 */
public class Rule {
    /** Rule name */
    public String name;
    
    /** Rule index within grammar */
    public int index;
    
    /** Whether this is a lexer rule */
    public boolean isLexerRule();
    
    /** Whether this is a parser rule */
    public boolean isParserRule();
    
    /** Get rule modifiers (fragment, etc.) */
    public Set<String> getModifiers();
    
    /** Get rule alternatives */
    public List<Alternative> getAlts();
    
    /** Get rule action blocks */
    public Map<String, Action> getActions();
}

Tool Configuration

The Tool class uses public fields for configuration rather than setter methods:

/**
 * Tool configuration fields (direct field access)
 */
public class Tool {
    /** Output directory for generated files */
    public String outputDirectory;
    
    /** Library directory for imported grammars */
    public String libDirectory;
    
    /** Enable visitor generation */
    public boolean gen_visitor;
    
    /** Enable listener generation */
    public boolean gen_listener;
    
    /** Error manager instance */
    public ErrorManager errMgr;
    
    /** Generate dependencies file */
    public boolean gen_dependencies;
    
    /** Package name for generated classes */
    public String packageName;
    
    /** Force ATN use for all predictions */
    public boolean force_atn;
    
    /** Enable trace mode */
    public boolean trace;
    
    /** Treat warnings as errors */
    public boolean warnings_are_errors;
    
    /** Target language for code generation */
    public String language;
}

Error Management

Centralized error reporting and management for the tool (accessed via Tool.errMgr field).

/**
 * Centralized error reporting for ANTLR tool
 */
public class ErrorManager {
    /** Report an error message */
    public void grammarError(ErrorType etype, String fileName, Token token, Object... args);
    
    /** Report a warning message */
    public void grammarWarning(ErrorType etype, String fileName, Token token, Object... args);
    
    /** Report a tool error */
    public void toolError(ErrorType etype, Object... args);
    
    /** Get total number of errors */
    public int getNumErrors();
    
    /** Get total number of warnings */
    public int getNumWarnings();
    
    /** Check if any errors occurred */
    public boolean errorsExist();
    
    /** Set error listener for custom error handling */
    public void setErrorListener(ANTLRToolListener listener);
}

/**
 * Listener interface for tool events and messages
 */
public interface ANTLRToolListener {
    /** Called when tool encounters an error */
    void error(ANTLRMessage msg);
    
    /** Called when tool encounters a warning */
    void warning(ANTLRMessage msg);
    
    /** Called when tool provides info message */
    void info(String msg);
}

Code Generation

Target-specific code generation functionality.

/**
 * Base class for target-specific code generators
 */
public abstract class CodeGenerator {
    /** Generate parser code for target language */
    public abstract void generateParser();
    
    /** Generate lexer code for target language */
    public abstract void generateLexer();
    
    /** Generate visitor interface and base class */
    public abstract void generateVisitor();
    
    /** Generate listener interface and base class */
    public abstract void generateListener();
    
    /** Get target language name */
    public abstract String getLanguage();
}

Usage Patterns

Basic Grammar Compilation

import org.antlr.v4.Tool;

// Simple compilation
Tool tool = new Tool();
Grammar g = tool.loadGrammar("Expr.g4");
tool.process(g, true);  // Process with code generation enabled

Advanced Tool Configuration

import org.antlr.v4.Tool;
import org.antlr.v4.tool.ErrorManager;

// Configure tool with custom settings (using public fields)
Tool tool = new Tool();
tool.outputDirectory = "generated/java/";    // Set output directory
tool.gen_visitor = true;                    // Enable visitor generation
tool.gen_listener = false;                  // Disable listener generation
tool.packageName = "com.example.parser";    // Set package name

// Add custom error handling (access ErrorManager via errMgr field)
tool.errMgr.setErrorListener(new ANTLRToolListener() {
    @Override
    public void error(ANTLRMessage msg) {
        System.err.println("Grammar error: " + msg);
    }
    
    @Override 
    public void warning(ANTLRMessage msg) {
        System.err.println("Grammar warning: " + msg);
    }
    
    @Override
    public void info(String msg) {
        System.out.println("Info: " + msg);
    }
});

// Process multiple grammars
Grammar lexerGrammar = tool.loadGrammar("ExprLexer.g4");
tool.process(lexerGrammar, true);  // Process with code generation

Grammar parserGrammar = tool.loadGrammar("ExprParser.g4");
tool.process(parserGrammar, true); // Process with code generation

Multi-Language Generation

import org.antlr.v4.Tool;

// Generate for different target languages
String[] javaArgs = {"-o", "java/", "MyGrammar.g4"};
String[] pythonArgs = {"-Dlanguage=Python3", "-o", "python/", "MyGrammar.g4"};
String[] jsArgs = {"-Dlanguage=JavaScript", "-o", "js/", "MyGrammar.g4"};

// Java generation
Tool javaTool = new Tool(javaArgs);
javaTool.processGrammarsOnCommandLine();

// Python generation  
Tool pythonTool = new Tool(pythonArgs);
pythonTool.processGrammarsOnCommandLine();

// JavaScript generation
Tool jsTool = new Tool(jsArgs);
jsTool.processGrammarsOnCommandLine();

Command Line Options

The tool supports extensive command-line configuration:

-o <dir> - Output directory for generated files
-lib <dir> - Directory containing imported grammars
-visitor - Generate visitor interfaces and base classes
-listener - Generate listener interfaces and base classes (default)
-no-listener - Don't generate listener classes
-no-visitor - Don't generate visitor classes
-package <name> - Package/namespace for generated classes
-depend - Generate file dependencies
-D<option>=<value> - Set/override grammar options
-Werror - Treat warnings as errors
-Xdbg - Enable debug mode
-Xforce-atn - Use ATN simulator for all predictions
-Xlog - Enable logging

Target Languages

ANTLR4 can generate code for multiple target languages:

Java (default) - org.antlr.v4.codegen.JavaTarget
C# - -Dlanguage=CSharp
Python 2 - -Dlanguage=Python2
Python 3 - -Dlanguage=Python3
JavaScript - -Dlanguage=JavaScript
Go - -Dlanguage=Go
C++ - -Dlanguage=Cpp
Swift - -Dlanguage=Swift

Each target generates appropriate parser, lexer, visitor, and listener classes with language-specific conventions and APIs.

Install with Tessl CLI

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

docs