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:

PushbackReader pushbackReader =
    new PushbackReader(new FileReader("c:\\data\\input.txt"));

int data = pushbackReader.read();

pushbackReader.unread(data);

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:

PushbackReader pushbackReader =
    new PushbackReader(new FileReader("c:\\data\\input.txt"));

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:

int pushbackLimit = 8;
PushbackReader reader = new PushbackReader(
                                new FileReader("c:\\data\\input.txt"),
                                pushbackLimit);

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:

int aChar = pushbackReader.read();
while(aChar != -1) {
    System.out.println((char) aChar);
    aChar = pushbackReader.read();
}

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 :

int aChar = pushbackReader.read();

pushbackReader.unread(aChar);

aChar = pushbackReader.read(); // reads character pushed back

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:

pushbackReader.close();

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:

Reader reader = new FileReader("data/data.bin");

try(PushbackReader pushbackReader =
    new PushbackReader(reader)){

    int data = pushbackReader.read();
    while(data != -1) {
        System.out.print((char) data);
        data = pushbackReader.read();
    }
}

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.

public class TextTokenizer {
    protected PushbackReader pushbackReader =  null;

    public TextTokenizer(Reader reader) {
        this.pushbackReader = new PushbackReader(reader);
    }

    public String nextToken() {
        int firstChar = this.pushbackReader.read();
        this.pushbackReader.unread(firstChar);

        if(((char)firstChar) == '"') {
           return readDoubleQuotedToken();
        }
        if((char)firstChar) == '\'') {
           return readSingleQuotedToken();
        }
        return readSingleWordToken();
    }

    protected String readDoubleQuotedToken() { ... }

    protected String readSingleQuotedToken() { ... }

    protected String readSingleWordToken()   { ... }
}

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.).