com.codemesh.terp.api
Class CharacterStream

java.lang.Object
  com.codemesh.terp.api.CharacterStream

public class CharacterStream
extends java.lang.Object

The wrapper type for various input sources. This type is used internally by the TokenStream types but for ease of programmatic use, all CharacterStream constructors have been exposed in the TokenStream types as well. This means that you don't have to create a CharacterStream first and then use it as an argument for a TokenStream constructor but you can use the CharacterStream constructor arguments directly to create a TokenStream. As a consequence, you will rarely use a CharacterStream directly.

Field Summary

protected java.util.Stack<com.codemesh.terp.api.CharacterStream.StreamState>	marks
protected java.lang.String	theExtension
protected java.lang.String	theInput
protected java.lang.String	theName
protected java.lang.String	theRoot
protected int	theSize
protected java.lang.Object	theSource
protected com.codemesh.terp.api.CharacterStream.StreamState	theState
protected long	theTimestamp

Constructor Summary

CharacterStream(java.io.File source)
Creates a stream that reads from the given file.

CharacterStream(java.io.File source, java.lang.String encoding)
Creates a stream that reads from the given string in the given encoding.

CharacterStream(java.io.InputStream is)
Creates a stream that reads from the given input stream.

CharacterStream(java.io.InputStream is, java.lang.String encoding)
Creates a stream that reads from the given input stream.

CharacterStream(java.lang.Object theSource, java.lang.String encoding, boolean bBuiltin)

CharacterStream(java.io.Reader r)
Creates a stream that reads from the given reader.

CharacterStream(java.lang.String source)
Creates a stream that reads from the given string.

CharacterStream(java.net.URI sourceUri)
Creates a stream that reads from the given uri.

CharacterStream(java.net.URI sourceUri, java.lang.String encoding)
Creates a stream that reads from the given uri in the given encoding.

CharacterStream(java.net.URL sourceUrl)
Creates a stream that reads from the given url.

CharacterStream(java.net.URL sourceUrl, java.lang.String encoding)
Creates a stream that reads from the given url in the given encoding.

Method Summary

int	getColumn() Returns the current column in the source.
int	getIndex() Returns the current position in the source.
int	getLine() Returns the current line in the source.
java.lang.String	getRange(int start, int end) Returns the source substring for the given indices or the empty string if the indices are invalid.
InputSource	getSource() Returns the input source of the stream.
int	LA(int offset) Returns the next lookahead character.
void	mark() Marks the current position in source.
boolean	match(int ch) Returns true if the next character is equal to the given character and advances the current position accordingly.
boolean	match(int[] chs) If the next character to be read matches one of the given array of characters, index is advanced and true is returned.
boolean	matchRange(int[] ranges) If the next character to be read matches one of the given character ranges, index is advanced and true is returned.
boolean	matchRange(int lowest, int highest) If the next character to be read is in the given range of characters, index is advanced and true is returned.
int	next() Returns the next character in the source.
void	read(java.lang.String encoding)
void	rewind() Forgets a previously marked position while restoring the current position to the marked position.
void	unmark() Forgets a previously marked position while maintaining the current position.

Methods inherited from class java.lang.Object

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

Field Detail

theSource

protected java.lang.Object theSource

theName

protected java.lang.String theName

theRoot

protected java.lang.String theRoot

theExtension

protected java.lang.String theExtension

theInput

protected java.lang.String theInput

theSize

protected int theSize

theTimestamp

protected long theTimestamp

marks

protected java.util.Stack<com.codemesh.terp.api.CharacterStream.StreamState> marks

theState

protected com.codemesh.terp.api.CharacterStream.StreamState theState

Constructor Detail

CharacterStream

public CharacterStream(java.lang.String source)

Creates a stream that reads from the given string.

Parameters:

source - the string to read from.

CharacterStream

public CharacterStream(java.io.File source)

Creates a stream that reads from the given file.

Parameters:

source - the file to read from.

CharacterStream

public CharacterStream(java.io.File source,
                       java.lang.String encoding)

Creates a stream that reads from the given string in the given encoding.

Parameters:

source - the string to read from.

encoding - the file encoding.

CharacterStream

public CharacterStream(java.net.URI sourceUri)

Creates a stream that reads from the given uri.

Parameters:

sourceUri - the uri to read from.

CharacterStream

public CharacterStream(java.net.URI sourceUri,
                       java.lang.String encoding)

Creates a stream that reads from the given uri in the given encoding.

Parameters:

sourceUri - the uri to read from.

encoding - the content encoding.

CharacterStream

public CharacterStream(java.net.URL sourceUrl)

Creates a stream that reads from the given url.

Parameters:

sourceUrl - the url to read from.

CharacterStream

public CharacterStream(java.net.URL sourceUrl,
                       java.lang.String encoding)

Creates a stream that reads from the given url in the given encoding.

Parameters:

sourceUrl - the url to read from.

encoding - the content encoding.

CharacterStream

public CharacterStream(java.io.InputStream is)

Creates a stream that reads from the given input stream.

Parameters:

is - the stream to read from.

CharacterStream

public CharacterStream(java.io.InputStream is,
                       java.lang.String encoding)

Creates a stream that reads from the given input stream.

Parameters:

is - the stream to read from.

encoding - the content encoding.

CharacterStream

public CharacterStream(java.io.Reader r)

Creates a stream that reads from the given reader. Readers do not require the specification of an encoding because the content is already translated into unicode characters.

Parameters:

r - the reader to read from.

CharacterStream

public CharacterStream(java.lang.Object theSource,
                       java.lang.String encoding,
                       boolean bBuiltin)

Method Detail

read

public void read(java.lang.String encoding)

getIndex

public int getIndex()

Returns the current position in the source. Index values are 0-based.

Returns:

an integer representing the offset from the beginning of the source.

getLine

public int getLine()

Returns the current line in the source. Line values are 1-based.

Returns:

an integer representing the line number of the current character.

getColumn

public int getColumn()

Returns the current column in the source. Column values are 1-based.

Returns:

an integer representing the column number of the current character.

next

public int next()

Returns the next character in the source.

Returns:

a character.

mark

public void mark()

Marks the current position in source. All mark() operations need to be matched by either an unmark() or a rewind().

unmark

public void unmark()

Forgets a previously marked position while maintaining the current position.

rewind

public void rewind()

Forgets a previously marked position while restoring the current position to the marked position.

LA

public int LA(int offset)

Returns the next lookahead character. This method does not adjust the current state (index, line, column).

Parameters:

offset - the offset from the current position. Negative values are legal.

Returns:

the specified lookahead or -1 if lookhead extends beyond the source limits.

match

public boolean match(int ch)

Returns true if the next character is equal to the given character and advances the current position accordingly. Leaves state unchanged if characters don't match.

Parameters:

ch - the character to look for.

Returns:

true for match, false for mismatch.

match

public boolean match(int[] chs)

If the next character to be read matches one of the given array of characters, index is advanced and true is returned.

Parameters:

chs - the characters, one of which is to be matched.

Returns:

true if matched, false otherwise.

matchRange

public boolean matchRange(int lowest,
                          int highest)

If the next character to be read is in the given range of characters, index is advanced and true is returned.

Parameters:

lowest - the lower bound (inclusive) to be matched.

highest - the upper bound (inclusive) to be matched.

Returns:

true if matched, false otherwise.

matchRange

public boolean matchRange(int[] ranges)

If the next character to be read matches one of the given character ranges, index is advanced and true is returned.

Parameters:

ranges - the character ranges, one of which is to be matched. The ranges are represented as an even-sized array of integers. The sequence of numbers is lowest0, highest0, lowest1, highest1, ..., lowest(n), highest(n).

Returns:

true if matched, false otherwise.

getRange

public java.lang.String getRange(int start,
                                 int end)

Returns the source substring for the given indices or the empty string if the indices are invalid.

Parameters:

start - the first character's index.

end - the last character's index.

Returns:

result substring.

getSource

public InputSource getSource()

Returns the input source of the stream. The input stream provides one layer of abstraction over the various, typed input types this class supports.

Returns:

the input source.