0
# Character Input Streams
1

2
Character stream implementations for reading input from various sources including strings, files, readers, and input streams. These classes form the foundation of the ANTLR lexical analysis pipeline.
3

4
## Capabilities
5

6
### CharStream Interface
7

8
Base interface for all character input streams providing lookahead and position tracking.
9

10
```java { .api }
11
/**
12
 * A source of characters for an ANTLR lexer
13
 */
14
public interface CharStream extends IntStream {
15
    public static final int EOF = -1;
16
    
17
    /**
18
     * For infinite streams, you don't need this; primarily I'm providing
19
     * a useful interface for action code. Just make sure actions don't
20
     * use this on streams that don't support it.
21
     */
22
    public String substring(int start, int stop);
23
    
24
    /**
25
     * Get the ith character of lookahead. This is the same usually as
26
     * LA(i). This will be used for labels in the generated
27
     * lexer code. I'd prefer to return a char here type-wise, but it's
28
     * probably better to be 32-bit clean and be consistent with LA.
29
     */
30
    public int LT(int i);
31
    
32
    /** ANTLR tracks the line information automatically */
33
    int getLine();
34
    
35
    /** Because this stream can rewind, we need to be able to reset the line */
36
    void setLine(int line);
37
    
38
    void setCharPositionInLine(int pos);
39
    
40
    /** The index of the character relative to the beginning of the line 0..n-1 */
41
    int getCharPositionInLine();
42
}
43
```
44

45
### String Input Stream
46

47
Read characters directly from a String in memory.
48

49
```java { .api }
50
/**
51
 * Character stream reading from a String
52
 */
53
public class ANTLRStringStream implements CharStream {
54
    protected String data;
55
    protected int n;
56
    protected int p;
57
    protected int line;
58
    protected int charPositionInLine;
59
    protected int markDepth;
60
    protected List<CharStreamState> markers;
61
    protected int lastMarker;
62
    protected String name;
63
    
64
    public ANTLRStringStream();
65
    public ANTLRStringStream(String input);
66
    public ANTLRStringStream(String input, String sourceName);
67
    public ANTLRStringStream(char[] data, int numberOfActualCharsInArray);
68
    public ANTLRStringStream(char[] data, int numberOfActualCharsInArray, String sourceName);
69
    
70
    public void reset();
71
    public String substring(int start, int stop);
72
    public int LT(int i);
73
    public int getLine();
74
    public void setLine(int line);
75
    public void setCharPositionInLine(int pos);
76
    public int getCharPositionInLine();
77
    public void consume();
78
    public int LA(int i);
79
    public int mark();
80
    public void rewind(int m);
81
    public void rewind();
82
    public void release(int marker);
83
    public void seek(int index);
84
    public int size();
85
    public int index();
86
    public String getSourceName();
87
}
88
```
89

90
**Usage Examples:**
91

92
```java
93
import org.antlr.runtime.ANTLRStringStream;
94
import org.antlr.runtime.CharStream;
95

96
// Create from string
97
CharStream input = new ANTLRStringStream("hello world");
98

99
// Create with source name 
100
CharStream input2 = new ANTLRStringStream("x = 42;", "example.txt");
101

102
// Create from character array
103
char[] chars = {'a', 'b', 'c'};
104
CharStream input3 = new ANTLRStringStream(chars, 3);
105

106
// Basic usage
107
System.out.println("First char: " + (char)input.LA(1));
108
System.out.println("Line: " + input.getLine());
109
System.out.println("Position: " + input.getCharPositionInLine());
110
```
111

112
### File Input Stream
113

114
Read characters from a file on disk with automatic encoding handling.
115

116
```java { .api }
117
/**
118
 * Character stream reading from a file
119
 */
120
public class ANTLRFileStream extends ANTLRStringStream {
121
    protected String fileName;
122
    
123
    public ANTLRFileStream(String fileName) throws IOException;
124
    public ANTLRFileStream(String fileName, String encoding) throws IOException;
125
    
126
    public void load(String fileName, String encoding) throws IOException;
127
    public String getSourceName();
128
}
129
```
130

131
**Usage Examples:**
132

133
```java
134
import org.antlr.runtime.ANTLRFileStream;
135
import org.antlr.runtime.CharStream;
136
import java.io.IOException;
137

138
// Read file with default encoding
139
try {
140
    CharStream input = new ANTLRFileStream("input.txt");
141
    System.out.println("File size: " + input.size());
142
} catch (IOException e) {
143
    System.err.println("Cannot read file: " + e.getMessage());
144
}
145

146
// Read file with specific encoding
147
try {
148
    CharStream input = new ANTLRFileStream("input.txt", "UTF-8");
149
    System.out.println("Source: " + input.getSourceName());
150
} catch (IOException e) {
151
    System.err.println("Cannot read file: " + e.getMessage());
152
}
153
```
154

155
### InputStream Character Stream
156

157
Read characters from any Java InputStream with encoding support.
158

159
```java { .api }
160
/**
161
 * Character stream reading from InputStream
162
 */
163
public class ANTLRInputStream extends ANTLRStringStream {
164
    public ANTLRInputStream();
165
    public ANTLRInputStream(InputStream input) throws IOException;
166
    public ANTLRInputStream(InputStream input, String encoding) throws IOException;
167
    public ANTLRInputStream(InputStream input, int size) throws IOException;
168
    public ANTLRInputStream(InputStream input, int size, String encoding) throws IOException;
169
    public ANTLRInputStream(InputStream input, int size, int readBufferSize) throws IOException;
170
    public ANTLRInputStream(InputStream input, int size, int readBufferSize, String encoding) throws IOException;
171
    
172
    public void load(InputStream input, int size, String encoding) throws IOException;
173
}
174
```
175

176
**Usage Examples:**
177

178
```java
179
import org.antlr.runtime.ANTLRInputStream;
180
import org.antlr.runtime.CharStream;
181
import java.io.*;
182

183
// Read from standard input
184
try {
185
    CharStream input = new ANTLRInputStream(System.in);
186
    // Process input...
187
} catch (IOException e) {
188
    System.err.println("Cannot read from stdin: " + e.getMessage());
189
}
190

191
// Read from file input stream with encoding
192
try {
193
    FileInputStream fis = new FileInputStream("data.xml");
194
    CharStream input = new ANTLRInputStream(fis, "UTF-8");
195
    // Process input...
196
    fis.close();
197
} catch (IOException e) {
198
    System.err.println("Cannot read file: " + e.getMessage());
199
}
200

201
// Read with buffer size control
202
try {
203
    FileInputStream fis = new FileInputStream("large-file.txt");
204
    CharStream input = new ANTLRInputStream(fis, 8192, 1024, "UTF-8");
205
    // Process input...
206
    fis.close();
207
} catch (IOException e) {
208
    System.err.println("Cannot read file: " + e.getMessage());
209
}
210
```
211

212
### Reader Character Stream
213

214
Read characters from any Java Reader with automatic buffer management.
215

216
```java { .api }
217
/**
218
 * Character stream reading from Reader
219
 */
220
public class ANTLRReaderStream extends ANTLRStringStream {
221
    public ANTLRReaderStream();
222
    public ANTLRReaderStream(Reader r) throws IOException;
223
    public ANTLRReaderStream(Reader r, int size) throws IOException;
224
    public ANTLRReaderStream(Reader r, int size, int readChunkSize) throws IOException;
225
    
226
    public void load(Reader r, int size, int readChunkSize) throws IOException;
227
}
228
```
229

230
**Usage Examples:**
231

232
```java
233
import org.antlr.runtime.ANTLRReaderStream;
234
import org.antlr.runtime.CharStream;
235
import java.io.*;
236

237
// Read from StringReader
238
StringReader sr = new StringReader("sample input text");
239
try {
240
    CharStream input = new ANTLRReaderStream(sr);
241
    // Process input...
242
} catch (IOException e) {
243
    System.err.println("Cannot read: " + e.getMessage());
244
}
245

246
// Read from FileReader with buffer control
247
try {
248
    FileReader fr = new FileReader("input.txt");
249
    CharStream input = new ANTLRReaderStream(fr, 4096, 512);
250
    // Process input...
251
    fr.close();
252
} catch (IOException e) {
253
    System.err.println("Cannot read file: " + e.getMessage());
254
}
255
```
256

257
## Types
258

259
### Character Stream State
260

261
```java { .api }
262
public class CharStreamState {
263
    int p;
264
    int line;
265
    int charPositionInLine;
266
}
267
```
268

269
## Common Patterns
270

271
### Error Handling
272

273
```java
274
try {
275
    CharStream input = new ANTLRFileStream("input.txt");
276
    // Use the stream...
277
} catch (IOException e) {
278
    System.err.println("Failed to read input: " + e.getMessage());
279
    // Handle error appropriately
280
}
281
```
282

283
### Stream Positioning
284

285
```java
286
CharStream input = new ANTLRStringStream("hello world");
287

288
// Mark current position
289
int marker = input.mark();
290

291
// Consume some characters
292
input.consume(); // 'h'
293
input.consume(); // 'e'
294

295
// Look ahead
296
int nextChar = input.LA(1); // 'l'
297

298
// Rewind to marked position
299
input.rewind(marker);
300

301
// Or rewind to last mark
302
input.rewind();
303
```
304

305
### Substring Extraction
306

307
```java
308
CharStream input = new ANTLRStringStream("hello world");
309

310
// Extract substring (inclusive start, exclusive stop)
311
String hello = input.substring(0, 5); // "hello"
312
String world = input.substring(6, 11); // "world"
313
```