PushbackReader
The Java PushbackReader class, java.io.PushbackReader
, is intended to be used when you parse data from a Reader. Sometimes you need to read ahead a few characters to see what is coming, before you can determine how to interpret the current character. The Java PushbackReader
allows you to do that. Well, actually it allows you to push back the read characters into the Reader
. These characters will then be read again the next time you call read()
.
The Java PushbackReader
works much like the PushbackInputStream
except that the PushbackReader
works on characters, whereas the PushbackInputStream
works on bytes.
PushbackReader Example
Here is a simple PushbackReader
example:
The call to read()
reads a character from the PushbackReader
just like from any other Reader
. The call to unread()
pushes a character back into the PushbackReader
. The next time read()
is called the pushed back characters will be read first. If you push back multiple characters into the PushbackReader
, the latest pushed back character will be returned first from the read()
method, just like with a stack.
Create a PushbackReader
To use a Java PushbackReader
you must first create a PushbackReader
instance. You create a PushbackReader
using standard object instantiation - using the new
operator. To the PushbackReader
constructor you must pass a Java Reader from which the PushbackReader
will read its characters. Here is an example of creating a Java PushbackReader
:
This example passes a Java FileReader to the PushbackReader
constructor. This will make the PushbackReader
read its characters from this FileReader
.
Setting the Push Back Limit of a PushbackReader
You can set the number of characters you should be able to unread in the constructor of the PushbackReader
. Here is how to set the pushback limit using the PushbackReader
constructor:
This example sets an internal buffer of 8 characters in the PushbackReader
. That means you can unread at most 8 characters at a time, before reading them again.
Read Characters
You read characters from a Java PushbackReader
just like you do from a Java Reader
- because PushbackReader
is a Java Reader
subclass. In other words, you use its read()
method which is inherited from the Reader
class. Here is an example of reading characters from a Java PushbackReader
via its read()
method:
The read()
returns an int
which you will have to cast to a char
yourself, as shown in the example above. When there are no characters available in the PushbackReader
the read()
method will return the int
value -1.
Push Back Characters
To push a character back into a Java PushbackReader
you must call its unread()
method. Here is an example of pushing back a character into a PushbackReader
:
This example reads a character from a PushbackReader
, then pushes it back into the PushbackReader
, and then reads that character from the PushbackReader
again.
Closing a PushbackReader
When you are finished reading characters from the PushbackReader
you should remember to close it. Closing a PushbackReader
will also close the Reader
instance from which the PushbackReader
is reading.
Closing a PushbackReader
is done by calling its close()
method. Here is how closing a PushbackReader
looks:
You can also use the try-with-resources construct introduced in Java 7. Here is how to use and close a PushbackReader
looks with the try-with-resources construct:
Notice how there is no longer any explicit close()
method call. The try-with-resources construct takes care of that.
Notice also that the first FileReader
instance is not created inside the try-with-resources block. That means that the try-with-resources block will not automatically close this FileReader
instance. However, when the PushbackReader
is closed it will also close the Reader
instance it reads from, so the FileReader
instance will get closed when the PushbackReader
is closed.
Parsing Example
At the end of this Java PushbackReader
tutorial, lets see a slightly more elaborate example of how you can use the PushbackReader
when parsing a stream of characters. This example samples the first character of the next "token" to be read from a PushbackReader
to determine the type of the next token, then pushes back the character for the corresponding tokenizer to read. The example is a bit "constructed" for the occasion, meaning in a real parser you might do things a bit differently. However, the example serves mostly to show how the PushbackReader
can be used in a real parsing example, not as a text book example of writing great parsers.
The interesting part of this example is the nextToken()
method. This method first reads a character from the PushbackReader
into a variable, then pushes the read character back into the PushbackReader
. This way the nextToken()
method can "sample" the first character of the next token, and based on that decide what kind of token it is, and what read method to call for that kind of token.
Note, that for the single and double quoted tokens it would actually not be necessary to push the character back into the PushbackReader
, because the quotes themselves are typically not included as part of the token. For the readSingleTokenWord()
however, it is necessary, as the character read is the first character of the token's value.
The implementations of the readDoubleQuotedToken()
, readSingleQuotedToken()
and readSingleWordToken()
have been left out to keep the example short. Just imagine they read a token enclosed by double quotes ("), single quotes (') or a token which ends with a non-word character (e.g. a space, tab, line break etc.).
Last updated