|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.io.Reader
bb.io.ParseReader
public class ParseReader
A Reader class designed for convenient and high performance parsing.
This class satisfies the exact same API as the PushbackReader
class,
so that it can be a drop-in replacement.
The main differences between this class and PushbackReader are:
This class also satisfies the exact same line number API as the LineNumberReader
class.
In particular, whenever data is read from the stream, it increments the line number count
if have just read thru a complete line terminator sequence.
(This class uses the same set of line termination sequences as LineNumberReader).
The main differences between this class and LineNumberReader are:
In addition to the above APIs, this class adds some useful parsing methods like
See also this constructor
for more discussion on the optimal Reader type.
This class is not multithread safe.
Nested Class Summary | |
---|---|
static class |
ParseReader.UnitTest
See the Overview page of the project's javadocs for a general description of this unit test class. |
Field Summary | |
---|---|
private char[] |
buffer
The single buffer simulataneously used for read ahead, pushback, and skip purposes. |
private static int |
bufferLength_default
|
private static String |
charEncoding_default
|
private int |
end
Index (exclusive) of the position in buffer where data ends. |
private Reader |
in
The underlying character-input stream. |
private int |
lineNumber
Current line number. |
private static int |
lineNumberInitial_default
|
private int |
pushbackCapacity
Records how much space at the beginning of buffer should be reserved for future pushbacks. |
private int |
start
Index (inclusive) of the position in buffer where data starts. |
Fields inherited from class java.io.Reader |
---|
lock |
Constructor Summary | |
---|---|
ParseReader(char[] buffer)
Calls this ( null, buffer, 0, buffer.length ). |
|
ParseReader(File file)
Calls this ( new FileInputStream (file) ). |
|
ParseReader(InputStream in)
Calls this (in, charEncoding_default ). |
|
ParseReader(InputStream in,
String charEncoding)
Calls this ( new InputStreamReader (in, charEncoding) ). |
|
ParseReader(Reader in)
Calls this ( in, new char[bufferLength_default ], 0, 0 ). |
|
ParseReader(Reader in,
char[] buffer,
int start,
int end)
Calls this ( in, buffer, start, end, lineNumberInitial_default ). |
|
ParseReader(Reader in,
char[] buffer,
int start,
int end,
int lineNumber)
The fundamental constructor. |
Method Summary | |
---|---|
private static Reader |
checkReader(Reader in)
|
void |
close()
Sets start > end, since that is one signal of the closed state. |
void |
confirmTokenNext(String token)
Returns (i.e. is always case sensitive). |
void |
confirmTokenNext(String token,
boolean isCaseSensitive)
Confirms that the supplied token's chars next occur on the stream. |
private void |
ensureBufferHasData()
Checks that buffer has at least 1 char of data. |
private void |
ensureOpen()
Checks that the stream has not been closed. |
private void |
ensurePushbackCapacity(int pushbackCapacityNeeded)
Checks that buffer has the requested free space, increasing its size if necessary. |
int |
getLineNumber()
Get the current line number. |
boolean |
hasData()
Reports whether or not data can still be read. |
private boolean |
isNewLineNext()
Reports if the next character on the stream is a newline char (i.e. |
boolean |
isTokenNext(String token)
Returns (i.e. is always case sensitive). |
boolean |
isTokenNext(String token,
boolean isCaseSensitive)
Determines if token's chars next occur on the stream. |
void |
mark(int readAheadLimit)
Mark the present position in the stream. |
boolean |
markSupported()
Tell whether this stream supports the mark() operation. |
int |
read()
Returns the next char from the stream. |
int |
read(char[] cbuf,
int offset,
int length)
Attempts to read chars into the specified portion of cbuf. |
String |
readLine()
Reads all the characters in the stream up to but not including the next line termination sequence or until end of stream is hit. |
String |
readThruToken(String token)
Returns (i.e. is always case sensitive and excludes token from result). |
String |
readThruToken(String token,
boolean isCaseSensitive,
boolean includeToken)
Reads over as many chars as necessary until token is read thru. |
boolean |
ready()
Tell whether this stream is ready to be read. |
void |
reset()
Reset the stream. |
private void |
resizeBuffer(int capacityNew)
Resizes buffer to the requested (greater) capacity. |
void |
setLineNumber(int lineNumber)
Set the current line number. |
long |
skip(long n)
This method attempts to skip over the requested number of characters. |
void |
skipFully(long n)
This method guarantees to skip over the specified number of chars. |
long |
skipTillTokenNext(String token)
Returns (i.e. is always case sensitive). |
long |
skipTillTokenNext(String token,
boolean isCaseSensitive)
Skips over as many chars as necessary until token is next on the stream. |
int |
skipWhitespace()
Skips over all whitespace on the stream until hit first non-whitespace char (or end of stream); that first non-whitespace char will be what is next read from the stream. |
void |
unread(char[] cbuf)
Convenience method that simply calls . |
void |
unread(char[] cbuf,
int offset,
int length)
Pushes back the specified portion of cbuf to the stream. |
void |
unread(int charAsInt)
Pushes back the supplied char to the stream. |
Methods inherited from class java.io.Reader |
---|
read, read |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
private static final int lineNumberInitial_default
private static final int bufferLength_default
private static final String charEncoding_default
private Reader in
buffer
.
Will be null after this instance is closed.
private char[] buffer
private int start
buffer
where data starts.
Along with end
, this field defines where valid data exists in buffer, namely,
for indices in the interval [start, end).
All other space in buffer is considered to be free, and may be overwritten at will.
The relation start < end is always satisfied except (a) when there is no more data in the buffer, which is always signified by start == end or (b) when this instance has been closed, in which case start > end. In every case, start and end must both always be a value in the range [0, buffer.length].
The next read will usually return the char at start (and start will subsequently be incremented).
Exception: if there is no data in buffer, then buffer will first be populated from in
,
with start (and end) assigned appropriate values for the data read in.
The next unread will usually write to start - 1 (and start will subsequently be decremented). Exception: if start == 0, then buffer will first be resized to allow pushback near the beginning of the array, with start incremented appropriate for the resize.
private int end
buffer
where data ends.
See documentation on start
for more details on buffer's data format.
Like start, end must always be a value in the range [0, buffer.length].
private int pushbackCapacity
buffer
should be reserved for future pushbacks.
private int lineNumber
Constructor Detail |
---|
public ParseReader(Reader in, char[] buffer, int start, int end, int lineNumber) throws IllegalArgumentException
in
- the underlying Reader from which characters will be read; may be null (i.e. reads solely come from contents of buffer)buffer
- assigned to the buffer
field;
for peak performance, user should ensure that it is sufficiently large;
see also start
for further details concerning the data format of bufferstart
- will be assigned to the start fieldlineNumber
- will be assigned to the lineNumber
field
IllegalArgumentException
- if buffer == null; buffer.length == 0; start < 0; start > buffer.length;
(in == null) && (start == buffer.length)public ParseReader(Reader in, char[] buffer, int start, int end) throws IllegalArgumentException
this
( in, buffer, start, end, lineNumberInitial_default
).
Note: the best performance is obtained when Reader is an unbuffered "low Level" Reader (e.g. FileReader) and not when it is a higher level buffered Reader (e.g. BufferedReader). This is because this class always does it own buffering, so any buffering done by Reader will simply waste memory and involve extra method calls.
in
- Reader from which chars will be read
IllegalArgumentException
- if buffer == null; buffer.length == 0; start < 0; start > buffer.length;
if (in == null) && (start == buffer.length)public ParseReader(char[] buffer) throws IllegalArgumentException
this
( null, buffer, 0, buffer.length ).
buffer
- an array into which all chars have already been read
IllegalArgumentException
- if buffer == nullpublic ParseReader(Reader in) throws IllegalArgumentException
this
( in, new char[bufferLength_default
], 0, 0 ).
in
- Reader from which chars will be read
IllegalArgumentException
- if in == nullpublic ParseReader(InputStream in, String charEncoding) throws UnsupportedEncodingException
this
( new InputStreamReader
(in, charEncoding) ).
in
- File InputStream which chars will be readcharEncoding
- name of the Charset
to use to decode bytes into chars
UnsupportedEncodingException
- if charEncoding is not supportedpublic ParseReader(InputStream in) throws UnsupportedEncodingException
this
(in, charEncoding_default
).
in
- File InputStream which chars will be read
UnsupportedEncodingException
- if charEncoding_default
is not supported (this should never happen)public ParseReader(File file) throws FileNotFoundException, SecurityException, UnsupportedEncodingException
this
( new FileInputStream
(file) ).
file
- File from which chars will be read
FileNotFoundException
- if file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.
SecurityException
- if a security manager exists and its checkRead method denies read access to file
UnsupportedEncodingException
- if charEncoding_default
is not supported (this should never happen)Method Detail |
---|
private static Reader checkReader(Reader in) throws IllegalArgumentException
IllegalArgumentException
public int getLineNumber()
public void setLineNumber(int lineNumber)
private void ensureOpen() throws IOException
IOException
private void ensureBufferHasData() throws RuntimeException, IOException
Will read from in, if it exists, if necessary. If it reads from in, it will, of course, change the start and end values as appropriate. In this case, however, this method guarantees that pushbackCapacity will be respected (i.e. after a read from in, start = pushbackCapacity).
RuntimeException
- if unable to guarantee that buffer has data
IOException
- if an I/O problem occursprivate void ensurePushbackCapacity(int pushbackCapacityNeeded)
private void resizeBuffer(int capacityNew)
public int read() throws IOException
read
in class Reader
IOException
- if an I/O problem occurspublic int read(char[] cbuf, int offset, int length) throws IllegalArgumentException, IOException
read
in class Reader
cbuf
- destination bufferoffset
- offset in cbuf at which to start writing charslength
- maximum number of chars to read
IllegalArgumentException
- if cbuf == null; offset < 0; length <= 0; offset + length > cbuf.length
IOException
- if an I/O problem occurspublic String readLine() throws IOException
IOException
- if an I/O problem occurspublic long skip(long n) throws IllegalArgumentException, IOException
skip
in class Reader
n
- the number of chars to attempt to skip
IllegalArgumentException
- if n < 0
IOException
- if an I/O problem occursskipFully
public void skipFully(long n) throws IOException, EOFException
n
- the number of chars required to skip
IOException
- if an I/O problem occurs
EOFException
- if hit end of stream before skipping n charsskip
public int skipWhitespace() throws IOException
Character.isWhitespace
defines what constitutes whitespace.
IOException
- if an I/O problem occurspublic void unread(int charAsInt) throws IllegalArgumentException, IOException
If charAsInt equals -1, this method immediately returns without doing anything.
Thus, this method can always undo a call to read
if supply the result returned by read.
IllegalArgumentException
- if charAsInt is neither a legitimate char value nor -1
IOException
- if an I/O problem occurspublic void unread(char[] cbuf, int offset, int length) throws IllegalArgumentException, IOException
After this method returns, the next chars to be read will be cbuf[offset], cbuf[offset+1], etc.
Thus, this method can undo a call to read
if supply the char[] just read into.
cbuf
- char arrayoffset
- offset of first char to push backlength
- number of chars to push back
IllegalArgumentException
- if cbuf == null; offset < 0; length <= 0; offset + length > cbuf.length
IOException
- if an I/O problem occurspublic void unread(char[] cbuf) throws IllegalArgumentException, IOException
unread
(cbuf, 0, cbuf.length)
.
IllegalArgumentException
- if there is a problem with one of the args
IOException
- If an I/O problem occurspublic void close()
in
then nulls the reference to it.
close
in interface Closeable
close
in class Reader
public void mark(int readAheadLimit) throws IOException
The implementation here always throws an IOException.
mark
in class Reader
IOException
- since mark is not supportedpublic boolean markSupported()
The implementation here always returns false.
markSupported
in class Reader
public boolean ready() throws IOException
ready
in class Reader
IOException
- if an I/O problem occurspublic void reset() throws IOException
The implementation here always throws an IOException.
reset
in class Reader
IOException
- since reset is not supportedprivate boolean isNewLineNext() throws IOException
From the caller's perspective, the stream's state is unaffected by this method. (Internally, reads into the buffer etc may have to be performed.)
IOException
- if an I/O problem occurspublic boolean hasData() throws IOException
ready
, this method will block if necessary,
because it returns false only if end of stream has been reached,
which is a stronger guarantee than ready provides.
From the caller's perspective, the stream's state is unaffected by this method. (Internally, reads into the buffer etc may have to be performed.)
IOException
- if an I/O problem occurspublic boolean isTokenNext(String token) throws IllegalArgumentException, IOException
isTokenNext
(token, true)
(i.e. is always case sensitive).
IllegalArgumentException
IOException
public boolean isTokenNext(String token, boolean isCaseSensitive) throws IllegalArgumentException, IOException
From the caller's perspective, the stream's state is unaffected by this method. (Internally, various buffer operations may have to be performed.)
isCaseSensitive
- if true, specifies that case matters in matching the chars of token; false means that case is irrelevant
IllegalArgumentException
- if token is null or zero-length
IOException
- if an I/O problem occurspublic long skipTillTokenNext(String token) throws IllegalArgumentException, IOException
skipTillTokenNext
(token, true)
(i.e. is always case sensitive).
IllegalArgumentException
IOException
public long skipTillTokenNext(String token, boolean isCaseSensitive) throws IllegalArgumentException, IOException
isCaseSensitive
- if true, specifies that case matters in matching the chars of token; false means that case is irrelevant
IllegalArgumentException
- if token is null or zero-length
IOException
- if an I/O problem occurspublic void confirmTokenNext(String token) throws IllegalArgumentException, IOException, ParseException
confirmTokenNext
(token, true)
(i.e. is always case sensitive).
IllegalArgumentException
IOException
ParseException
public void confirmTokenNext(String token, boolean isCaseSensitive) throws IllegalArgumentException, IOException, ParseException
If token is fully read, then the stream's state is affected by this method: all the values are read off and the line number count may be increased. If a mismatch is encountered, however, the stream state is restored before return which, in this case, will be abnormal termination with a ParseException thrown. Abnormal termination thru any other exception, however, may leave the stream in an indeterminate state.
IllegalArgumentException
- if token is null or zero-length
IOException
- if an I/O problem occurs
ParseException
- if token is not fully matched by the stream's next contents;
the stream's state will be restored before returnpublic String readThruToken(String token) throws IllegalArgumentException, IOException, IllegalStateException
readThruToken
(token, true, false)
(i.e. is always case sensitive and excludes token from result).
IllegalArgumentException
IOException
IllegalStateException
public String readThruToken(String token, boolean isCaseSensitive, boolean includeToken) throws IllegalArgumentException, IOException, IllegalStateException
isCaseSensitive
- if true, specifies that case matters in matching the chars of token; false means that case is irrelevantincludeToken
- if true, specifies that token's chars are included (at the end) of the result; false means that they are left out;
note that if includeToken is true and isCaseSensitive is false, then the case of these token chars included in the result
may differ from the case of what occurred on the stream
IllegalArgumentException
- if token is null or zero-length
IOException
- if an I/O problem occurs
IllegalStateException
- if fail to read thru token
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |