0
# Runtime API
1

2
The ANTLR4 runtime API provides the core infrastructure for executing generated parsers and lexers, managing input streams, and handling tokens.
3

4
## Capabilities
5

6
### Parser Base Class
7

8
Base class for all generated parsers providing core parsing functionality.
9

10
```java { .api }
11
/**
12
 * Base class for all generated parsers
13
 */
14
public abstract class Parser extends Recognizer<Token, ParserATNSimulator> {
15
    /** Reset parser state to initial conditions */
16
    public void reset();
17
    
18
    /** Match expected token type, consuming if successful */
19
    public Token match(int ttype) throws RecognitionException;
20
    
21
    /** Consume current input token and return it */
22
    public Token consume();
23
    
24
    /** Match and consume wildcard token */
25
    public Token matchWildcard() throws RecognitionException;
26
    
27
    /** Enter a parser rule */
28
    public void enterRule(ParserRuleContext localctx, int state, int ruleIndex);
29
    
30
    /** Exit current parser rule */
31
    public void exitRule();
32
    
33
    /** Add parse listener to this parser */
34
    public void addParseListener(ParseTreeListener listener);
35
    
36
    /** Remove parse listener from this parser */
37
    public void removeParseListener(ParseTreeListener listener);
38
    
39
    /** Get all registered parse listeners */
40
    public List<ParseTreeListener> getParseListeners();
41
    
42
    /** Remove all parse listeners */
43
    public void removeParseListeners();
44
    
45
    /** Get current token stream */
46
    public TokenStream getTokenStream();
47
    
48
    /** Set token stream for this parser */
49
    public void setTokenStream(TokenStream input);
50
    
51
    /** Get current rule context */
52
    public ParserRuleContext getContext();
53
    
54
    /** Get error recovery strategy */
55
    public ANTLRErrorStrategy getErrorHandler();
56
    
57
    /** Set error recovery strategy */
58
    public void setErrorHandler(ANTLRErrorStrategy handler);
59
    
60
    /** Get number of syntax errors encountered */
61
    public int getNumberOfSyntaxErrors();
62
    
63
    /** Notify all error listeners with message */
64
    public void notifyErrorListeners(String msg);
65
    
66
    /** Notify error listeners with token and exception */
67
    public void notifyErrorListeners(Token offendingToken, String msg, RecognitionException e);
68
    
69
    /** Create terminal node for parse tree */
70
    public TerminalNode createTerminalNode(ParserRuleContext parent, Token t);
71
    
72
    /** Create error node for parse tree */
73
    public ErrorNode createErrorNode(ParserRuleContext parent, Token t);
74
    
75
    /** Enter outer alternative with number */
76
    public void enterOuterAlt(ParserRuleContext localctx, int altNum);
77
    
78
    /** Get current precedence level */
79
    public int getPrecedence();
80
    
81
    /** Enter recursion rule with precedence */
82
    public void enterRecursionRule(ParserRuleContext localctx, int state, int ruleIndex, int precedence);
83
    
84
    /** Push new recursion context */
85
    public void pushNewRecursionContext(ParserRuleContext localctx, int state, int ruleIndex);
86
    
87
    /** Unroll recursion contexts */
88
    public void unrollRecursionContexts(ParserRuleContext _parentctx);
89
    
90
    /** Get invoking context for rule */
91
    public ParserRuleContext getInvokingContext(int ruleIndex);
92
    
93
    /** Set current parser context */
94
    public void setContext(ParserRuleContext ctx);
95
    
96
    /** Check if token is expected at current position */
97
    public boolean isExpectedToken(int symbol);
98
    
99
    /** Check if matched EOF */
100
    public boolean isMatchedEOF();
101
    
102
    /** Get expected tokens within current rule */
103
    public IntervalSet getExpectedTokensWithinCurrentRule();
104
    
105
    /** Get rule index by name */
106
    public int getRuleIndex(String ruleName);
107
    
108
    /** Get current rule context */
109
    public ParserRuleContext getRuleContext();
110
    
111
    /** Get rule invocation stack */
112
    public List<String> getRuleInvocationStack();
113
    
114
    /** Get rule invocation stack from context */
115
    public List<String> getRuleInvocationStack(RuleContext p);
116
    
117
    /** Enable/disable profiling */
118
    public void setProfile(boolean profile);
119
    
120
    /** Check if trace is enabled */
121
    public boolean isTrace();
122
    
123
    /** Set whether to build parse trees */
124
    public void setBuildParseTree(boolean buildParseTrees);
125
    
126
    /** Check if building parse trees */
127
    public boolean getBuildParseTree();
128
    
129
    /** Set whether to trim parse trees */
130
    public void setTrimParseTree(boolean trimParseTrees);
131
    
132
    /** Check if trimming parse trees */
133
    public boolean getTrimParseTree();
134
    
135
    /** Get expected tokens at current position */
136
    public IntervalSet getExpectedTokens();
137
    
138
    /** Get current token */
139
    public Token getCurrentToken();
140
    
141
    /** Enable/disable parse trace output */
142
    public void setTrace(boolean trace);
143
}
144
```
145

146
**Usage Example:**
147

148
```java
149
import org.antlr.v4.runtime.*;
150
import org.antlr.v4.runtime.tree.*;
151

152
// Create parser instance
153
CharStream input = CharStreams.fromString("1 + 2 * 3");
154
ExprLexer lexer = new ExprLexer(input);
155
CommonTokenStream tokens = new CommonTokenStream(lexer);
156
ExprParser parser = new ExprParser(tokens);
157

158
// Configure parser
159
parser.setBuildParseTree(true);
160
parser.addParseListener(new ExprBaseListener() {
161
    @Override
162
    public void enterExpr(ExprParser.ExprContext ctx) {
163
        System.out.println("Entering expression: " + ctx.getText());
164
    }
165
});
166

167
// Parse
168
ParseTree tree = parser.expr();
169
```
170

171
### Lexer Base Class
172

173
Base class for all generated lexers providing tokenization functionality.
174

175
```java { .api }
176
/**
177
 * Base class for all generated lexers
178
 */
179
public abstract class Lexer extends Recognizer<Integer, LexerATNSimulator> {
180
    /** Get next token from input stream */
181
    public Token nextToken();
182
    
183
    /** Skip current token (don't return to parser) */
184
    public void skip();
185
    
186
    /** Emit more text for current token */
187
    public void more();
188
    
189
    /** Switch to specified lexer mode */
190
    public void mode(int m);
191
    
192
    /** Push current mode onto mode stack and switch to new mode */
193
    public void pushMode(int m);
194
    
195
    /** Pop mode from mode stack and switch to it */
196
    public int popMode();
197
    
198
    /** Get current lexer mode */
199
    public int getCurrentMode();
200
    
201
    /** Emit specified token */
202
    public void emit(Token token);
203
    
204
    /** Emit token of specified type with current text */
205
    public Token emit(int type);
206
    
207
    /** Get current input character stream */
208
    public CharStream getInputStream();
209
    
210
    /** Set input character stream */
211
    public void setInputStream(CharStream input);
212
    
213
    /** Get token source name for error reporting */
214
    public String getSourceName();
215
    
216
    /** Get current token factory */
217
    public TokenFactory<?> getTokenFactory();
218
    
219
    /** Set token factory for creating tokens */
220
    public void setTokenFactory(TokenFactory<?> factory);
221
    
222
    /** Reset lexer state */
223
    public void reset();
224
    
225
    /** Get all tokens from input as list */
226
    public List<? extends Token> getAllTokens();
227
}
228
```
229

230
**Usage Example:**
231

232
```java
233
import org.antlr.v4.runtime.*;
234

235
// Create lexer
236
CharStream input = CharStreams.fromString("hello world");
237
MyLexer lexer = new MyLexer(input);
238

239
// Tokenize input
240
Token token;
241
while ((token = lexer.nextToken()).getType() != Token.EOF) {
242
    System.out.println("Token: " + token.getText() + " Type: " + token.getType());
243
}
244
```
245

246
### Token Interface and Implementation
247

248
Token representation and management.
249

250
```java { .api }
251
/**
252
 * Basic token interface with type, text, and position information
253
 */
254
public interface Token {
255
    /** End-of-file token type */
256
    int EOF = -1;
257
    
258
    /** Invalid token type */
259
    int INVALID_TYPE = 0;
260
    
261
    /** Default channel for tokens */
262
    int DEFAULT_CHANNEL = 0;
263
    
264
    /** Hidden channel for whitespace/comments */
265
    int HIDDEN_CHANNEL = 1;
266
    
267
    /** Get token type */
268
    int getType();
269
    
270
    /** Get token text */
271
    String getText();
272
    
273
    /** Get line number (1-based) */
274
    int getLine();
275
    
276
    /** Get character position in line (0-based) */
277
    int getCharPositionInLine();
278
    
279
    /** Get channel number */
280
    int getChannel();
281
    
282
    /** Get token index in stream */
283
    int getTokenIndex();
284
    
285
    /** Get start character index in input */
286
    int getStartIndex();
287
    
288
    /** Get stop character index in input */
289
    int getStopIndex();
290
    
291
    /** Get token source */
292
    TokenSource getTokenSource();
293
    
294
    /** Get input stream where token originated */
295
    CharStream getInputStream();
296
}
297

298
/**
299
 * Standard token implementation
300
 */
301
public class CommonToken implements WritableToken {
302
    /** Create token with type and text */
303
    public CommonToken(int type, String text);
304
    
305
    /** Create token from another token */
306
    public CommonToken(Token oldToken);
307
    
308
    /** Create token with type */
309
    public CommonToken(int type);
310
    
311
    /** Create token from source and type */
312
    public CommonToken(Pair<TokenSource, CharStream> source, int type, 
313
                      int channel, int start, int stop);
314
    
315
    @Override
316
    public String getText();
317
    
318
    @Override
319
    public void setText(String text);
320
    
321
    @Override
322
    public int getType();
323
    
324
    @Override
325
    public void setType(int type);
326
    
327
    @Override
328
    public int getLine();
329
    
330
    @Override
331
    public void setLine(int line);
332
    
333
    @Override
334
    public int getCharPositionInLine();
335
    
336
    @Override
337
    public void setCharPositionInLine(int pos);
338
    
339
    @Override
340
    public int getChannel();
341
    
342
    @Override
343
    public void setChannel(int channel);
344
    
345
    @Override
346
    public int getTokenIndex();
347
    
348
    @Override
349
    public void setTokenIndex(int index);
350
}
351
```
352

353
### Token Stream Management
354

355
Token stream interfaces and implementations for feeding tokens to parsers.
356

357
```java { .api }
358
/**
359
 * Stream of tokens with buffering and seeking capabilities
360
 */
361
public interface TokenStream extends IntStream {
362
    /** Get token at specified index */
363
    Token get(int index);
364
    
365
    /** Get token source */
366
    TokenSource getTokenSource();
367
    
368
    /** Get all tokens from start to stop (inclusive) */
369
    List<Token> getTokens(int start, int stop);
370
    
371
    /** Get all tokens of specified type */
372
    List<Token> getTokens(int start, int stop, int ttype);
373
    
374
    /** Get all tokens of specified types */
375
    List<Token> getTokens(int start, int stop, Set<Integer> types);
376
    
377
    /** Get text from start to stop tokens */
378
    String getText(Interval interval);
379
    
380
    /** Get text from specified token range */
381
    String getText(RuleContext ctx);
382
    
383
    /** Get text from parse tree */
384
    String getText(ParseTree parseTree);
385
}
386

387
/**
388
 * Buffered token stream implementation
389
 */
390
public class BufferedTokenStream implements TokenStream {
391
    /** Create buffered stream from token source */
392
    public BufferedTokenStream(TokenSource tokenSource);
393
    
394
    /** Fill buffer up to specified index */
395
    protected void sync(int i);
396
    
397
    /** Fill buffer completely */
398
    public void fill();
399
    
400
    /** Get all tokens in buffer */
401
    public List<Token> getTokens();
402
    
403
    /** Get tokens between start and stop indices */
404
    public List<Token> getTokens(int start, int stop, int ttype);
405
    
406
    /** Get tokens by type set */
407
    public List<Token> getTokens(int start, int stop, Set<Integer> types);
408
    
409
    /** Get hidden tokens to left of token index */
410
    public List<Token> getHiddenTokensToLeft(int tokenIndex);
411
    
412
    /** Get hidden tokens to left of specified channel */
413
    public List<Token> getHiddenTokensToLeft(int tokenIndex, int channel);
414
    
415
    /** Get hidden tokens to right of token index */
416
    public List<Token> getHiddenTokensToRight(int tokenIndex);
417
    
418
    /** Get hidden tokens to right of specified channel */
419
    public List<Token> getHiddenTokensToRight(int tokenIndex, int channel);
420
}
421

422
/**
423
 * Common token stream filtering hidden tokens
424
 */
425
public class CommonTokenStream extends BufferedTokenStream {
426
    /** Create stream from token source */
427
    public CommonTokenStream(TokenSource tokenSource);
428
    
429
    /** Create stream with specified channel */
430
    public CommonTokenStream(TokenSource tokenSource, int channel);
431
    
432
    /** Adjust seek index to ignore tokens on hidden channels */
433
    protected int adjustSeekIndex(int i);
434
    
435
    /** Look backward for token on channel */
436
    protected Token LB(int k);
437
    
438
    /** Look forward for token on channel */
439
    public Token LT(int k);
440
    
441
    /** Get number of tokens on default channel */
442
    public int getNumberOfOnChannelTokens();
443
}
444
```
445

446
### Character Stream Management
447

448
Input stream management for feeding characters to lexers.
449

450
```java { .api }
451
/**
452
 * Character stream factory methods (4.7+)
453
 */
454
public final class CharStreams {
455
    /** Create character stream from file */
456
    public static CharStream fromFileName(String fileName) throws IOException;
457
    
458
    /** Create character stream from file with encoding */
459
    public static CharStream fromFileName(String fileName, Charset encoding) throws IOException;
460
    
461
    /** Create character stream from string */
462
    public static CharStream fromString(String s);
463
    
464
    /** Create character stream from string with source name */
465
    public static CharStream fromString(String s, String sourceName);
466
    
467
    /** Create character stream from Reader */
468
    public static CharStream fromReader(Reader r) throws IOException;
469
    
470
    /** Create character stream from Reader with source name */
471
    public static CharStream fromReader(Reader r, String sourceName) throws IOException;
472
    
473
    /** Create character stream from InputStream */
474
    public static CharStream fromStream(InputStream is) throws IOException;
475
    
476
    /** Create character stream from InputStream with encoding */
477
    public static CharStream fromStream(InputStream is, Charset encoding) throws IOException;
478
    
479
    /** Create character stream from ReadableByteChannel */
480
    public static CharStream fromChannel(ReadableByteChannel channel) throws IOException;
481
    
482
    /** Create character stream from ReadableByteChannel with encoding */
483
    public static CharStream fromChannel(ReadableByteChannel channel, Charset encoding) throws IOException;
484
}
485

486
/**
487
 * Character stream interface
488
 */
489
public interface CharStream extends IntStream {
490
    /** Get substring from start to stop (inclusive) */
491
    String getText(Interval interval);
492
    
493
    /** Convert stream to string */
494
    String toString();
495
}
496
```
497

498
### Base Recognizer Class
499

500
Common base class for Parser and Lexer with shared functionality.
501

502
```java { .api }
503
/**
504
 * Base class for Parser and Lexer with common functionality
505
 */
506
public abstract class Recognizer<Symbol, ATNInterpreter extends ATNSimulator> {
507
    /** Get rule names for this recognizer */
508
    public abstract String[] getRuleNames();
509
    
510
    /** Get vocabulary (token names) for this recognizer */
511
    public abstract Vocabulary getVocabulary();
512
    
513
    /** Get grammar file name */
514
    public abstract String getGrammarFileName();
515
    
516
    /** Get ATN used by this recognizer */
517
    public abstract ATN getATN();
518
    
519
    /** Get ATN interpreter/simulator */
520
    public ATNInterpreter getInterpreter();
521
    
522
    /** Set ATN interpreter/simulator */
523
    public void setInterpreter(ATNInterpreter interpreter);
524
    
525
    /** Get error recovery strategy */
526
    public ANTLRErrorStrategy getErrorHandler();
527
    
528
    /** Set error recovery strategy */
529
    public void setErrorHandler(ANTLRErrorStrategy handler);
530
    
531
    /** Get input stream */
532
    public abstract IntStream getInputStream();
533
    
534
    /** Set input stream */
535
    public abstract void setInputStream(IntStream input);
536
    
537
    /** Get current token factory */
538
    public TokenFactory<?> getTokenFactory();
539
    
540
    /** Set token factory */
541
    public void setTokenFactory(TokenFactory<?> factory);
542
    
543
    /** Add error listener */
544
    public void addErrorListener(ANTLRErrorListener listener);
545
    
546
    /** Remove error listener */
547
    public void removeErrorListener(ANTLRErrorListener listener);
548
    
549
    /** Remove all error listeners */
550
    public void removeErrorListeners();
551
    
552
    /** Get all error listeners */
553
    public List<ANTLRErrorListener> getErrorListeners();
554
    
555
    /** Get error count */
556
    public int getNumberOfSyntaxErrors();
557
    
558
    /** Get current state */
559
    public int getState();
560
    
561
    /** Set current state */
562
    public void setState(int atnState);
563
}
564
```
565

566
## Usage Patterns
567

568
### Basic Parser Setup
569

570
```java
571
import org.antlr.v4.runtime.*;
572
import org.antlr.v4.runtime.tree.*;
573

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

577
// Create lexer
578
MyLexer lexer = new MyLexer(input);
579

580
// Create token stream
581
CommonTokenStream tokens = new CommonTokenStream(lexer);
582

583
// Create parser
584
MyParser parser = new MyParser(tokens);
585

586
// Parse starting from rule
587
ParseTree tree = parser.startRule();
588
```
589

590
### Custom Token Factory
591

592
```java
593
import org.antlr.v4.runtime.*;
594

595
// Custom token factory
596
TokenFactory<CommonToken> factory = new CommonTokenFactory(true); // copyText=true
597

598
// Set on lexer
599
MyLexer lexer = new MyLexer(input);
600
lexer.setTokenFactory(factory);
601
```
602

603
### Stream Processing
604

605
```java
606
import org.antlr.v4.runtime.*;
607

608
// Create lexer
609
MyLexer lexer = new MyLexer(input);
610
CommonTokenStream tokens = new CommonTokenStream(lexer);
611

612
// Access all tokens
613
tokens.fill();
614
List<Token> allTokens = tokens.getTokens();
615

616
// Get specific token types
617
List<Token> identifiers = tokens.getTokens(0, tokens.size()-1, MyLexer.ID);
618

619
// Get hidden tokens (comments, whitespace)
620
List<Token> hiddenLeft = tokens.getHiddenTokensToLeft(5, Token.HIDDEN_CHANNEL);
621
List<Token> hiddenRight = tokens.getHiddenTokensToRight(5, Token.HIDDEN_CHANNEL);
622
```