0
# Tool API
1

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

4
## Capabilities
5

6
### Main Tool Class
7

8
The primary interface for ANTLR4 grammar compilation and code generation.
9

10
```java { .api }
11
/**
12
 * Main class for ANTLR4 grammar compilation
13
 */
14
public class Tool {
15
    /** Command-line interface entry point */
16
    public static void main(String[] args);
17
    
18
    /** Default constructor */
19
    public Tool();
20
    
21
    /** Constructor with command line arguments */
22
    public Tool(String[] args);
23
    
24
    /** Process grammar files specified on command line */
25
    public void processGrammarsOnCommandLine();
26
    
27
    /** Load and parse a grammar file */
28
    public Grammar loadGrammar(String fileName) throws IOException;
29
    
30
    /** Create grammar object from parsed AST */
31
    public Grammar createGrammar(GrammarRootAST ast);
32
    
33
    /** Parse grammar file into AST */
34
    public GrammarRootAST parseGrammar(String fileName);
35
    
36
    /** Parse grammar from string into AST */
37
    public GrammarRootAST parseGrammarFromString(String grammar);
38
    
39
    /** Main processing method for loaded grammars */
40
    public void process(Grammar g, boolean gencode);
41
    
42
    /** Process non-combined grammar */
43
    public void processNonCombinedGrammar(Grammar g, boolean gencode);
44
    
45
    /** Check grammar for rule issues */
46
    public boolean checkForRuleIssues(Grammar g);
47
    
48
    /** Load imported grammar */
49
    public Grammar loadImportedGrammar(Grammar g, GrammarAST nameNode);
50
    
51
    /** Generate ATNs for grammar */
52
    public void generateATNs(Grammar g);
53
    
54
    /** Get output file writer */
55
    public Writer getOutputFileWriter(Grammar g, String fileName) throws IOException;
56
    
57
    /** Get output directory for file */
58
    public File getOutputDirectory(String fileNameWithPath);
59
    
60
    /** Display help information */
61
    public void help();
62
    
63
    /** Log message with component */
64
    public void log(String component, String msg);
65
    
66
    /** Log message */
67
    public void log(String msg);
68
    
69
    /** Get number of errors */
70
    public int getNumErrors();
71
    
72
    /** Add tool listener */
73
    public void addListener(ANTLRToolListener tl);
74
    
75
    /** Remove tool listener */
76
    public void removeListener(ANTLRToolListener tl);
77
    
78
    /** Get all listeners */
79
    public List<ANTLRToolListener> getListeners();
80
    
81
    /** Report info message */
82
    public void info(String msg);
83
    
84
    /** Report error message */
85
    public void error(ANTLRMessage msg);
86
    
87
    /** Report warning message */
88
    public void warning(ANTLRMessage msg);
89
    
90
    /** Display version information */
91
    public void version();
92
    
93
    /** Exit with code */
94
    public void exit(int e);
95
    
96
    /** Panic exit */
97
    public void panic();
98
}
99
```
100

101
**Usage Examples:**
102

103
```java
104
import org.antlr.v4.Tool;
105

106
// Command line style usage
107
String[] args = {
108
    "-visitor",           // Generate visitor classes
109
    "-listener",          // Generate listener classes  
110
    "-o", "output/",      // Output directory
111
    "-lib", "grammars/",  // Library directory
112
    "MyGrammar.g4"        // Grammar file
113
};
114
Tool antlr = new Tool(args);
115
antlr.processGrammarsOnCommandLine();
116

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

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

127
### Grammar Representation
128

129
Classes representing parsed ANTLR grammars with their rules and options.
130

131
```java { .api }
132
/**
133
 * Represents a parsed ANTLR grammar
134
 */
135
public class Grammar {
136
    /** Grammar name from grammar declaration */
137
    public String name;
138
    
139
    /** Source file name */
140
    public String fileName;
141
    
142
    /** Map of rule name to Rule object */
143
    public Map<String, Rule> rules;
144
    
145
    /** Grammar type (parser, lexer, combined) */
146
    public GrammarType getType();
147
    
148
    /** Get rule by name */
149
    public Rule getRule(String name);
150
    
151
    /** Get all parser rules */
152
    public Collection<Rule> getRules();
153
    
154
    /** Get start rule for this grammar */
155
    public Rule getRule(int index);
156
    
157
    /** Get grammar options */
158
    public Map<String, Object> getOptions();
159
    
160
    /** Get token names defined in this grammar */
161
    public String[] getTokenNames();
162
    
163
    /** Get rule names defined in this grammar */
164
    public String[] getRuleNames();
165
}
166

167
/**
168
 * Specialized grammar for lexer rules
169
 */
170
public class LexerGrammar extends Grammar {
171
    /** Get lexer rules only */
172
    public Collection<Rule> getRules();
173
    
174
    /** Get lexer modes defined in grammar */
175
    public Set<String> getModes();
176
}
177
```
178

179
### Grammar Rules
180

181
Individual rule representation within grammars.
182

183
```java { .api }
184
/**
185
 * Represents a single grammar rule
186
 */
187
public class Rule {
188
    /** Rule name */
189
    public String name;
190
    
191
    /** Rule index within grammar */
192
    public int index;
193
    
194
    /** Whether this is a lexer rule */
195
    public boolean isLexerRule();
196
    
197
    /** Whether this is a parser rule */
198
    public boolean isParserRule();
199
    
200
    /** Get rule modifiers (fragment, etc.) */
201
    public Set<String> getModifiers();
202
    
203
    /** Get rule alternatives */
204
    public List<Alternative> getAlts();
205
    
206
    /** Get rule action blocks */
207
    public Map<String, Action> getActions();
208
}
209
```
210

211
### Tool Configuration
212

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

215
```java { .api }
216
/**
217
 * Tool configuration fields (direct field access)
218
 */
219
public class Tool {
220
    /** Output directory for generated files */
221
    public String outputDirectory;
222
    
223
    /** Library directory for imported grammars */
224
    public String libDirectory;
225
    
226
    /** Enable visitor generation */
227
    public boolean gen_visitor;
228
    
229
    /** Enable listener generation */
230
    public boolean gen_listener;
231
    
232
    /** Error manager instance */
233
    public ErrorManager errMgr;
234
    
235
    /** Generate dependencies file */
236
    public boolean gen_dependencies;
237
    
238
    /** Package name for generated classes */
239
    public String packageName;
240
    
241
    /** Force ATN use for all predictions */
242
    public boolean force_atn;
243
    
244
    /** Enable trace mode */
245
    public boolean trace;
246
    
247
    /** Treat warnings as errors */
248
    public boolean warnings_are_errors;
249
    
250
    /** Target language for code generation */
251
    public String language;
252
}
253
```
254

255
### Error Management
256

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

259
```java { .api }
260
/**
261
 * Centralized error reporting for ANTLR tool
262
 */
263
public class ErrorManager {
264
    /** Report an error message */
265
    public void grammarError(ErrorType etype, String fileName, Token token, Object... args);
266
    
267
    /** Report a warning message */
268
    public void grammarWarning(ErrorType etype, String fileName, Token token, Object... args);
269
    
270
    /** Report a tool error */
271
    public void toolError(ErrorType etype, Object... args);
272
    
273
    /** Get total number of errors */
274
    public int getNumErrors();
275
    
276
    /** Get total number of warnings */
277
    public int getNumWarnings();
278
    
279
    /** Check if any errors occurred */
280
    public boolean errorsExist();
281
    
282
    /** Set error listener for custom error handling */
283
    public void setErrorListener(ANTLRToolListener listener);
284
}
285

286
/**
287
 * Listener interface for tool events and messages
288
 */
289
public interface ANTLRToolListener {
290
    /** Called when tool encounters an error */
291
    void error(ANTLRMessage msg);
292
    
293
    /** Called when tool encounters a warning */
294
    void warning(ANTLRMessage msg);
295
    
296
    /** Called when tool provides info message */
297
    void info(String msg);
298
}
299
```
300

301
### Code Generation
302

303
Target-specific code generation functionality.
304

305
```java { .api }
306
/**
307
 * Base class for target-specific code generators
308
 */
309
public abstract class CodeGenerator {
310
    /** Generate parser code for target language */
311
    public abstract void generateParser();
312
    
313
    /** Generate lexer code for target language */
314
    public abstract void generateLexer();
315
    
316
    /** Generate visitor interface and base class */
317
    public abstract void generateVisitor();
318
    
319
    /** Generate listener interface and base class */
320
    public abstract void generateListener();
321
    
322
    /** Get target language name */
323
    public abstract String getLanguage();
324
}
325
```
326

327
## Usage Patterns
328

329
### Basic Grammar Compilation
330

331
```java
332
import org.antlr.v4.Tool;
333

334
// Simple compilation
335
Tool tool = new Tool();
336
Grammar g = tool.loadGrammar("Expr.g4");
337
tool.process(g, true);  // Process with code generation enabled
338
```
339

340
### Advanced Tool Configuration
341

342
```java
343
import org.antlr.v4.Tool;
344
import org.antlr.v4.tool.ErrorManager;
345

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

353
// Add custom error handling (access ErrorManager via errMgr field)
354
tool.errMgr.setErrorListener(new ANTLRToolListener() {
355
    @Override
356
    public void error(ANTLRMessage msg) {
357
        System.err.println("Grammar error: " + msg);
358
    }
359
    
360
    @Override 
361
    public void warning(ANTLRMessage msg) {
362
        System.err.println("Grammar warning: " + msg);
363
    }
364
    
365
    @Override
366
    public void info(String msg) {
367
        System.out.println("Info: " + msg);
368
    }
369
});
370

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

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

379
### Multi-Language Generation
380

381
```java
382
import org.antlr.v4.Tool;
383

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

389
// Java generation
390
Tool javaTool = new Tool(javaArgs);
391
javaTool.processGrammarsOnCommandLine();
392

393
// Python generation  
394
Tool pythonTool = new Tool(pythonArgs);
395
pythonTool.processGrammarsOnCommandLine();
396

397
// JavaScript generation
398
Tool jsTool = new Tool(jsArgs);
399
jsTool.processGrammarsOnCommandLine();
400
```
401

402
## Command Line Options
403

404
The tool supports extensive command-line configuration:
405

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

420
## Target Languages
421

422
ANTLR4 can generate code for multiple target languages:
423

424
- **Java** (default) - `org.antlr.v4.codegen.JavaTarget`
425
- **C#** - `-Dlanguage=CSharp`
426
- **Python 2** - `-Dlanguage=Python2`
427
- **Python 3** - `-Dlanguage=Python3` 
428
- **JavaScript** - `-Dlanguage=JavaScript`
429
- **Go** - `-Dlanguage=Go`
430
- **C++** - `-Dlanguage=Cpp`
431
- **Swift** - `-Dlanguage=Swift`
432

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