org.inria.ns.reflex.util
Class Scanner

java.lang.Object
  org.inria.ns.reflex.util.Scanner

Direct Known Subclasses:

ReaderScanner, StringScanner

public abstract class Scanner
extends Object

A scanner can read characters from an input stream under conditions.

Convenient methods are available for testing for example whether the next content is a number or not, for reading characters, strings and numbers.

Additional classes can help to read an object under constraints, for example "get the next number that has less than 5 digits", or the next number that fit in a specific type.

It is a progressive scanner in the sense that the next content is inherently independent of what was read before. To hold a context and go back when successive items doesn't satisfy a specific grammar, the user will have to set markers.

The mark(int), consume(), and cancel() methods can help to read some characters and go back to the marked position. Several successive positions can be marked without canceling or consuming the previous ones ; as marks are stacked, it falls to the user to apply the appropriate number of cancel + consume calls.

A specific device is available for single characters : just use hasNextChar(char, boolean), hasNextChar(String, boolean), or get it simply with lookAhead() ; you don't need to set a mark for testing the next character to read.

It is markable-reentrant that is to say that once marked, it can used itself for further scanning with or without setting new marks.

Author:

Philippe Poulard

Constructor Summary

Scanner()

Method Summary

abstract void	cancel() Cancel the characters read since the last marked position (the next read will start from the last marked position).
abstract void	consume() Consume the characters read so far.
int	getPosition() Return the current position from the unique physical mark.
abstract Reader	getRemainder() Return the remainder to read from the current position.
abstract String	getRemainderString() Return the remainder to read from the current position.
int	getSourceIndex() Return the index in the source after parsing successfully an item under constraint.
boolean	hasNext() Indicates whether there remains characters to read in the input.
boolean	hasNextChar(char c, boolean consume) Indicates whether the next character in the input is the given character.
boolean	hasNextChar(String chars, boolean consume) Indicates whether the next character in the input is one of the given characters.
boolean	hasNextString(String string, boolean consume) Test whether or not the next string in the input is those given.
char	lookAhead() Return the next character to read without advancing the cursor.
abstract void	mark(int limit) Mark the present position in the stream.
char	nextChar() Read the next character.
char	nextChar(String chars, boolean consume) Return the next character in the input that is one of the given characters.
Number	nextNumber() Read the next number.
Number	nextNumber(NumberConstraint constraint) Read the next number.
UserData	nextObject(ObjectConstraint constraint) Read the next object.
int	nextString(StringConstraint constraint) Skip the next string (under constraint).
int	nextString(StringConstraint constraint, StringBuffer buf) Append the next string in the given buffer.
abstract void	read() Read the next character.

Methods inherited from class java.lang.Object

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

Constructor Detail

Scanner

public Scanner()

Method Detail

nextString

public int nextString(StringConstraint constraint,
                      StringBuffer buf)
               throws IOException

Append the next string in the given buffer.

The string stops at the first separator specified by the stop condition of the constraint or at the end of the stream. Each character to append is filtered by the constraint (for example to allow escaping characters).

The characters involved in the stop condition can be preserved (they will be the next characters to read) or not according to the stop condition.

*** It is the responsibility of the {@link StringConstraint#stopCondition(int, int, Scanner)} method to mark and reset the scanner if necessary ***

.

In any case the characters involved in the stop condition are not appended to the buffer.

Parameters:

constraint - The non-null constraint that the string to read has to satisfy.

buf - The buffer to which the next string will be appended.

Returns:

The number of characters appended to the buffer.

Throws:

IOException - When an I/O error occur.

nextString

public int nextString(StringConstraint constraint)
               throws IOException

Skip the next string (under constraint).

The string stops at the first separator specified by the stop condition of the constraint or at the end of the stream.

The characters involved in the stop condition can be preserved (they will be the next characters to read) or not according to the stop condition.

*** It is the responsibility of the {@link StringConstraint#stopCondition(int, int, Scanner)} method to mark and reset the scanner if necessary ***

.

Parameters:

constraint - The constraints to apply on the string.

Returns:

The number of characters read, excluding those involved in the stop condition.

Throws:

IOException - When an I/O error occur.

See Also:

nextString(StringConstraint, StringBuffer)

lookAhead

public char lookAhead()

Return the next character to read without advancing the cursor.

It is a convenient method that avoids to use a marker for reading a single char.

Returns:

The next character if any, or EOF.

See Also:

nextChar()

nextChar

public char nextChar()
              throws IOException

Read the next character.

Returns:

The next character if any, or EOF.

Throws:

IOException - When an I/O error occur.

See Also:

lookAhead()

nextNumber

public Number nextNumber()
                  throws IOException

Read the next number.

Returns:

The next number read, or null if none found. The type of the number will be the more suitable.

Throws:

IOException - When an I/O error occur.

See Also:

nextNumber(NumberConstraint)

nextNumber

public Number nextNumber(NumberConstraint constraint)
                  throws IOException

Read the next number.

Parameters:

constraint - The non-null constraint that the number to read has to satisfy.

Returns:

The next number read, or null if none found under the constraints.

Throws:

IOException - When an I/O error occur.

See Also:

NumberOperator.parseNumber(String, boolean, Class)

nextObject

public UserData nextObject(ObjectConstraint constraint)
                    throws IOException

Read the next object.

Parameters:

constraint - The non-null constraint that the object to read has to satisfy.

Returns:

The next object read wrapped in a user data which length is the number of characters read, excluding those involved in the stop condition. Once unwrapped, the target object can be null.

Throws:

IOException - When an I/O error occur.

hasNext

public boolean hasNext()

Indicates whether there remains characters to read in the input.

Returns:

true if at least 1 character can be read, false if the end of the input stream was reached.

See Also:

getPosition()

getPosition

public int getPosition()

Return the current position from the unique physical mark.

Returns:

The number of characters actually read from the mark.

See Also:

hasNext()

getSourceIndex

public int getSourceIndex()

Return the index in the source after parsing successfully an item under constraint. Indicates the number of characters involved for building the item.

Returns:

The number of characters actually read in the source for parsing the last item.

See Also:

nextNumber(), nextNumber(NumberConstraint), nextObject(ObjectConstraint), nextString(StringConstraint), nextString(StringConstraint, StringBuffer)

hasNextChar

public boolean hasNextChar(char c,
                           boolean consume)
                    throws IOException

Indicates whether the next character in the input is the given character. When found it can be consumed in the source or not.

Parameters:

c - The character to test.

consume - true if the character found have to be consumed, false otherwise.

Returns:

true if the next character in the input matches the one given, false otherwise.

Throws:

IOException - When an I/O error occur.

hasNextChar

public boolean hasNextChar(String chars,
                           boolean consume)
                    throws IOException

Indicates whether the next character in the input is one of the given characters. When found it can be consumed in the source or not.

Parameters:

chars - The string that contains the characters to test.

consume - true if the character found have to be consumed, false otherwise.

Returns:

true if the next character in the input matches one of those given, false otherwise.

Throws:

IOException - When an I/O error occur.

nextChar

public char nextChar(String chars,
                     boolean consume)
              throws IOException

Return the next character in the input that is one of the given characters. When found it can be consumed in the source or not.

Parameters:

chars - The string that contains the characters to test.

consume - true if the character found have to be consumed, false otherwise.

Returns:

the next character in the input if it matches one of those given, (char) -1 otherwise.

Throws:

IOException - When an I/O error occur.

hasNextString

public boolean hasNextString(String string,
                             boolean consume)
                      throws IOException

Test whether or not the next string in the input is those given. When found it can be consumed or not.

Parameters:

string - The string to test.

consume - true if the string found have to be consumed, false otherwise.

Returns:

true if the string matches the input, false otherwise.

Throws:

IOException - When an I/O error occur.

read

public abstract void read()
                   throws IOException

Read the next character.

Throws:

IOException - When an I/O error occur.

See Also:

#hasNextChar(char), nextChar(), lookAhead()

mark

public abstract void mark(int limit)
                   throws IOException

Mark the present position in the stream.

This method can be called safely several times.

For each mark set, there should be sooner or later a consume or cancel.

Some convenient methods are available for getting a single character without using a mark : lookAhead(), nextChar(), hasNextChar(char, boolean) and hasNextChar(String, boolean).

Parameters:

limit - The maximum number of characters that can be read before loosing the mark.

Throws:

IOException - When an I/O error occur.

See Also:

Reader.mark(int), cancel(), consume()

cancel

public abstract void cancel()
                     throws IOException

Cancel the characters read since the last marked position (the next read will start from the last marked position).

Throws:

IOException - When an I/O error occur.

IllegalStateException - When this method is called whereas no position was marked so far.

See Also:

mark(int)

consume

public abstract void consume()
                      throws IOException

Consume the characters read so far.

This implies that the last marked position is removed and the next read goes on from the current position. If there wasn't other marker, it will be impossible to go back. If there was at least another one marker, it can be itself cancelled or consumed independently.

Throws:

IOException - When an I/O error occur.

IllegalStateException - When this method is called whereas no position was marked so far.

See Also:

mark(int)

getRemainder

public abstract Reader getRemainder()
                             throws IOException

Return the remainder to read from the current position.

Returns:

The remainder to read, or null if the end was reached.

Throws:

IOException - When an I/O error occur.

See Also:

getRemainderString()

getRemainderString

public abstract String getRemainderString()
                                   throws IOException

Return the remainder to read from the current position.

Returns:

The remainder to read, or null if the end was reached.

Throws:

IOException - When an I/O error occur.

See Also:

getRemainder()