lava.io
Class UnreadBuffer

java.lang.Object
  |
  +--lava.io.UnreadBuffer

public class UnreadBuffer

extends java.lang.Object

Enhanced unread support for PushbackReaders.

Details: UnreadBuffer works in tandem with PushbackReader to provide sophisticated "undo" support while parsing text streams. An UnreadBuffer can be attached to a PushbackReader at any stage in the parsing process and used to remember the characters while you are parsing them. This makes it easy to unread entire segments as your parser discovers it has gone down an incorrect grammar path, or to recall data that has been read as you discover that the parsing path was correct. Essentially, this class eliminates the need for peek, unread, mark, and reset in the client code.

Example: Here is a function that (greedily) parses strings of letters that begin with 'a' and end with 'z', while rejecting everything else. If a qualifying string is parsed, it is removed from the stream and returned. If such a string is not next in the stream, however, null is returned and no characters are consumed from the stream (i.e., everything read is pushed back).

static String parseAtoZ (PushbackReader pr) throws IOException
{
	UnreadBuffer ub = new UnreadBuffer (pr);
parsing:
	{
		if (ub . read () != 'a')
			break parsing;
		while (true)
		{
			int c = ub . read ();
			if (c == 'z')
				return ub . getContents ();
			if (! Ctype.isalpha (c))
				break parsing;
		}
	}
	ub . unreadAll ();
	return null;
}

Since the idea of this class is to allow you to do a whole bunch of reading while still retaining your ability to unread, you should make sure that the source input stream is capable of the amount of consecutive unreads that your use of this class may require. You may also consider using the UnlimitedPushbackReader so that you don't have to worry about it.

Since:

2000.06.01

Author:

Sharky

Constructor Summary

UnreadBuffer(java.io.PushbackReader in)
Sets source stream.

Method Summary

java.lang.String	getContents() Returns entire unread stack.
java.io.PushbackReader	getReader() Returns source stream.
int	peek() Peeks ahead one character.
int	peekPop() Peeks top of stack.
int	pop() Removes character from unread stack.
java.lang.String	popAll() Pops entire unread stack.
void	push(char c) Pushes character onto unread stack.
void	push(int c) Pushes character onto unread stack.
void	push(java.lang.String s) Pushes string onto unread stack.
int	read() Reads single character.
void	unread() Unreads one character.
void	unreadAll() Unreads all characters.
void	unreadEos() Unreads if not EOS.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UnreadBuffer

public UnreadBuffer(java.io.PushbackReader in)

Sets source stream.

Details: This constructor sets the source PushbackReader from which data is read and to which data is unread.

Parameters:

in - the source PushbackReader

Method Detail

getReader

public java.io.PushbackReader getReader()

Returns source stream.

Details: getReader returns the source stream that was given in the constructor. There should be very little need to call this method in well-designed code, but it is available as a convenience.

Returns:

source stream

read

public int read()
         throws java.io.IOException

Reads single character.

Details: read reads a single character from the source stream, pushes it onto the internal unread stack in case it needs to be referenced later, and then returns the character. If the source stream contains no more characters and produces an EOS symbol, that symbol will be returned, but it will not be pushed onto the unread stack.

Returns:

character read

Throws:

java.io.IOException - if an I/O error occurs

unread

public void unread()
            throws java.io.IOException

Unreads one character.

Details: unread pops a character from the unread stack and pushes it back onto the source stream. If there are no characters on the stack to pop, this method does nothing. (This makes it safe to call unread after detecting an unexpected character, which may or may not be the EOS symbol.)

Throws:

java.io.IOException - if an I/O error occurs

unreadEos

public void unreadEos()
               throws java.io.IOException

Unreads if not EOS.

Details: unreadEos performs the same operation as unread, but only if the last call to read did not return the EOS symbol.

Throws:

java.io.IOException - if an I/O error occurs

Since:

2000.09.28

unreadAll

public void unreadAll()
               throws java.io.IOException

Unreads all characters.

Details: unreadAll pops all the characters from the unread stack and pushes them back onto the source stream.

push

public void push(int c)

Pushes character onto unread stack.

Details: push appends a single character (c) to the unread stack. c is automatically cast to a char first. If c is negative, this method does nothing.

Parameters:

c - character to push

push

public void push(char c)

Pushes character onto unread stack.

Details: push appends a single character (c) to the unread stack.

Parameters:

c - character to push

push

public void push(java.lang.String s)

Pushes string onto unread stack.

Details: push appends a string (s) to the unread stack. The last character in the string is pushed last.

Parameters:

s - string to push

pop

public int pop()

Removes character from unread stack.

Details: pop removes a single character from the unread stack and returns it. If the stack is empty, pop returns -1.

Returns:

popped character

popAll

public java.lang.String popAll()

Pops entire unread stack.

Details: popAll pops the entire unread stack and returns it as a string. If the stack is empty, an empty string is returned.

Returns:

popped string

See Also:

getContents()

getContents

public java.lang.String getContents()

Returns entire unread stack.

Details: Like popAll, getContents returns the entire contents of the unread stack, but it does so without affecting the stack's contents.

Returns:

unread stack

See Also:

popAll()

peek

public int peek()
         throws java.io.IOException

Peeks ahead one character.

Details: Although not very useful and certainly not necessary, peek is available as a convenience. It does what most peeks do: it allows you to preview the next character in the stream without consuming it and, in this case, without adding it to the unread stack. In other words, peek returns what read would return if you called it, but without affect the state of this UnreadBuffer.

Returns:

peeked character

peekPop

public int peekPop()

Peeks top of stack.

Details: peekPop returns the character on the top of the unread stack. If the stack is empty, peekPop returns -1.

Returns:

character on top

Since:

2000.09.28