0
# ANTLR Runtime
1

2
ANTLR (ANother Tool for Language Recognition) runtime library for Java. This is a framework for constructing recognizers, interpreters, compilers, and translators from grammatical descriptions containing actions in a variety of target languages. The runtime provides excellent support for tree construction, tree walking, translation, error recovery, and error reporting.
3

4
## Package Information
5

6
- **Package Name**: org.antlr:antlr-runtime
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to pom.xml: `<dependency><groupId>org.antlr</groupId><artifactId>antlr-runtime</artifactId><version>3.5.3</version></dependency>`
10

11
## Core Imports
12

13
```java
14
import org.antlr.runtime.*;
15
import org.antlr.runtime.tree.*;
16
```
17

18
For specific classes:
19

20
```java
21
import org.antlr.runtime.ANTLRStringStream;
22
import org.antlr.runtime.CommonTokenStream;
23
import org.antlr.runtime.Parser;
24
import org.antlr.runtime.Lexer;
25
import org.antlr.runtime.tree.CommonTree;
26
import org.antlr.runtime.tree.CommonTreeAdaptor;
27
```
28

29
## Basic Usage
30

31
```java
32
import org.antlr.runtime.*;
33

34
// Create input stream from string
35
CharStream input = new ANTLRStringStream("hello world");
36

37
// Create lexer (assuming MyLexer is generated by ANTLR)
38
MyLexer lexer = new MyLexer(input);
39

40
// Create token stream
41
TokenStream tokens = new CommonTokenStream(lexer);
42

43
// Create parser (assuming MyParser is generated by ANTLR) 
44
MyParser parser = new MyParser(tokens);
45

46
// Parse input
47
try {
48
    MyParser.program_return result = parser.program();
49
    CommonTree tree = (CommonTree) result.getTree();
50
    System.out.println(tree.toStringTree());
51
} catch (RecognitionException e) {
52
    System.err.println("Parsing failed: " + e.getMessage());
53
}
54
```
55

56
## Architecture
57

58
ANTLR runtime is built around several key components:
59

60
- **Input Streams**: Character and token streams for reading input data
61
- **Lexical Analysis**: Lexer classes for tokenizing character streams  
62
- **Parsing**: Parser classes for syntactic analysis of token streams
63
- **Tree Construction**: AST building and manipulation utilities
64
- **Error Handling**: Comprehensive exception hierarchy for parse errors
65
- **Debug Support**: Debugging and profiling tools for parser development
66

67
## Capabilities
68

69
### Character Input Streams
70

71
Character stream implementations for reading input from various sources including strings, files, and readers.
72

73
```java { .api }
74
public interface CharStream extends IntStream {
75
    public static final int EOF = -1;
76
    public String substring(int start, int stop);
77
    public int LT(int i);
78
    int getLine();
79
    void setLine(int line);
80
    void setCharPositionInLine(int pos);
81
    int getCharPositionInLine();
82
}
83

84
public class ANTLRStringStream implements CharStream {
85
    public ANTLRStringStream(String input);
86
}
87

88
public class ANTLRFileStream extends ANTLRStringStream {
89
    public ANTLRFileStream(String fileName) throws IOException;
90
    public ANTLRFileStream(String fileName, String encoding) throws IOException;
91
}
92
```
93

94
[Character Input Streams](./character-streams.md)
95

96
### Token Streams
97

98
Token stream implementations for managing sequences of tokens produced by lexers.
99

100
```java { .api }
101
public interface TokenStream extends IntStream {
102
    public Token LT(int k);
103
    int range();
104
    public Token get(int i);
105
    public TokenSource getTokenSource();
106
    public String toString(int start, int stop);
107
    public String toString(Token start, Token stop);
108
}
109

110
public class CommonTokenStream implements TokenStream {
111
    public CommonTokenStream(TokenSource tokenSource);
112
    public CommonTokenStream(TokenSource tokenSource, int channel);
113
}
114
```
115

116
[Token Streams](./token-streams.md)
117

118
### Lexical Analysis
119

120
Base classes and interfaces for implementing lexers and token sources.
121

122
```java { .api }
123
public abstract class Lexer extends BaseRecognizer implements TokenSource {
124
    protected CharStream input;
125
    public Lexer(CharStream input);
126
    public Lexer(CharStream input, RecognizerSharedState state);
127
    public abstract Token nextToken();
128
}
129

130
public interface Token {
131
    public static final int EOF = CharStream.EOF;
132
    public static final int DEFAULT_CHANNEL = 0;
133
    public static final int HIDDEN_CHANNEL = 99;
134
    
135
    public String getText();
136
    public void setText(String text);
137
    public int getType();
138
    public void setType(int ttype);
139
    public int getLine();
140
    public void setLine(int line);
141
    public int getCharPositionInLine();
142
    public void setCharPositionInLine(int pos);
143
}
144
```
145

146
[Lexical Analysis](./lexical-analysis.md)
147

148
### Parsing
149

150
Core parsing infrastructure including parser base classes and rule return scopes.
151

152
```java { .api }
153
public class Parser extends BaseRecognizer {
154
    public TokenStream input;
155
    public Parser(TokenStream input);
156
    public Parser(TokenStream input, RecognizerSharedState state);
157
    public void setTokenStream(TokenStream input);
158
    public TokenStream getTokenStream();
159
}
160

161
public abstract class BaseRecognizer {
162
    public static final int MEMO_RULE_FAILED = -2;
163
    public static final int MEMO_RULE_UNKNOWN = -1;
164
    
165
    public void reset();
166
    public Object match(IntStream input, int ttype, BitSet follow) throws RecognitionException;
167
}
168
```
169

170
[Parsing](./parsing.md)
171

172
### Tree Construction and Manipulation
173

174
Abstract Syntax Tree (AST) construction, traversal, and manipulation utilities.
175

176
```java { .api }
177
public interface Tree {
178
    public Tree getChild(int i);
179
    public int getChildCount();
180
    public Tree getParent();
181
    public void setParent(Tree t);
182
    public void addChild(Tree t);
183
    public void setChild(int i, Tree t);
184
    public Object deleteChild(int i);
185
    public String toString();
186
    public String toStringTree();
187
}
188

189
public abstract class BaseTree implements Tree {
190
    protected List<Tree> children;
191
    public void addChild(Tree t);
192
    public void setChild(int i, Tree t);
193
    public String toStringTree();
194
}
195

196
public class CommonTree extends BaseTree {
197
    public Token token;
198
    public CommonTree(Token t);
199
    public String toString();
200
}
201
```
202

203
[Tree Construction and Manipulation](./tree-construction.md)
204

205
### Error Handling
206

207
Comprehensive exception hierarchy and error recovery mechanisms for robust parsing.
208

209
```java { .api }
210
public class RecognitionException extends Exception {
211
    public IntStream input;
212
    public int index;
213
    public Token token;
214
    public Object node;
215
    public int c;
216
    public int line;
217
    public int charPositionInLine;
218
    public boolean approximateLineInfo;
219
}
220

221
public class MismatchedTokenException extends RecognitionException {
222
    public int expecting;
223
}
224

225
public class NoViableAltException extends RecognitionException {
226
    public int decisionNumber;
227
    public int stateNumber;
228
}
229
```
230

231
[Error Handling](./error-handling.md)
232

233
### Debug Support
234

235
Debugging, profiling, and tracing tools for parser development and optimization.
236

237
```java { .api }
238
public interface DebugEventListener {
239
    public void enterRule(String grammarFileName, String ruleName);
240
    public void exitRule(String grammarFileName, String ruleName);
241
    public void consumeToken(Token token);
242
    public void consumeHiddenToken(Token token);
243
    public void LT(int i, Token t);
244
}
245

246
public class DebugParser extends Parser {
247
    protected DebugEventListener dbg;
248
    public void setDebugListener(DebugEventListener dbg);
249
}
250

251
public class Profiler extends BlankDebugEventListener {
252
    public ProfileStats getDecisionProfile();
253
    public String getReport();
254
}
255
```
256

257
[Debug Support](./debug-support.md)
258

259
## Types
260

261
### Core Interfaces
262

263
```java { .api }
264
public interface IntStream {
265
    public static final int EOF = -1;
266
    public void consume();
267
    public int LA(int i);
268
    public int mark();
269
    public int index();
270
    public void rewind(int marker);
271
    public void rewind();
272
    public void release(int marker);
273
    public void seek(int index);
274
    public int size();
275
    public String getSourceName();
276
}
277

278
public interface TokenSource {
279
    public Token nextToken();
280
    public String getSourceName();
281
}
282

283
public class CommonToken implements Token, Serializable {
284
    protected int type;
285
    protected int line;
286
    protected int charPositionInLine;
287
    protected int channel;
288
    protected transient CharStream input;
289
    protected String text;
290
    protected int index;
291
    protected int start;
292
    protected int stop;
293
    
294
    public CommonToken(int type);
295
    public CommonToken(CharStream input, int type, int channel, int start, int stop);
296
    public CommonToken(int type, String text);
297
    public CommonToken(Token oldToken);
298
    
299
    public String getText();
300
    public void setText(String text);
301
    public int getType();
302
    public void setType(int ttype);
303
    public int getLine();
304
    public void setLine(int line);
305
    public int getCharPositionInLine();
306
    public void setCharPositionInLine(int pos);
307
    public int getChannel();
308
    public void setChannel(int channel);
309
    public int getTokenIndex();
310
    public void setTokenIndex(int index);
311
    public CharStream getInputStream();
312
    public void setInputStream(CharStream input);
313
    public int getStartIndex();
314
    public void setStartIndex(int start);
315
    public int getStopIndex();
316
    public void setStopIndex(int stop);
317
    public String toString();
318
}
319
```
320

321
### State and Configuration
322

323
```java { .api }
324
public class RecognizerSharedState {
325
    public BitSet[] following;
326
    public int _fsp;
327
    public boolean errorRecovery;
328
    public int lastErrorIndex;
329
    public boolean failed;
330
    public int syntaxErrors;
331
    public int backtracking;
332
    public Map<Integer, Integer>[] ruleMemo;
333
    public int tokenStartLine;
334
    public int tokenStartCharPositionInLine;
335
    public int channel;
336
    public int type;
337
    public String text;
338
}
339

340
public class RuleReturnScope {
341
    public Token getStart();
342
    public Token getStop(); 
343
    public Object getTree();
344
}
345
```