net.sf.mmm.util.scanner.api

Interface CharStreamScanner

All Known Implementing Classes:

CharSequenceScanner

public interface CharStreamScanner

This is the interface for a scanner that can be used to parse a stream or sequence of characters.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

Modifier and Type	Method and Description
boolean	expect(char expected) This method checks that the current character is equal to the given expected character.
boolean	expect(String expected, boolean ignoreCase) This method skips all next characters as long as they equal to the according character of the expected string.
boolean	expectStrict(String expected, boolean ignoreCase) This method acts as expect(String, boolean) but if the expected String is NOT completely present, no character is consumed and the state of the scanner remains unchanged.
char	forceNext() Like next() this method reads the current character and increments the index.
char	forcePeek() This method reads the current character without incrementing the index.
int	getCurrentIndex() This method gets the current position in the stream to scan.
boolean	hasNext() This method determines if there is at least one more character available.
char	next() This method reads the current character and increments the index stepping to the next character.
char	peek() This method reads the current character without incrementing the index.
String	read(int count) This method reads the number of next characters given by count and returns them as string.
int	readDigit() This method reads the next character if it is a digit.
double	readDouble() This method reads the double value (decimal number) starting at the current position by reading as many matching characters as available and returns its parsed value.
float	readFloat() This method reads the float value (decimal number) starting at the current position by reading as many matching characters as available and returns its parsed value.
long	readLong(int maxDigits) This method reads the long starting at the current position by reading as many Latin digits as available but at maximum the given maxDigits and returns its parsed value.
String	readUntil(char stop, boolean acceptEof) This method reads all next characters until the given stop character or the end is reached.
String	readUntil(char stop, boolean acceptEof, char escape) This method reads all next characters until the given (un-escaped) stop character or the end is reached.
String	readUntil(char stop, boolean acceptEof, CharScannerSyntax syntax) This method reads all next characters until the given stop character or the end of the string to parse is reached.
String	readUntil(CharFilter filter, boolean acceptEof) This method reads all next characters until the first character accepted by the given filter or the end is reached.
String	readWhile(CharFilter filter) This method reads all next characters that are accepted by the given filter.
String	readWhile(CharFilter filter, int max) This method reads all next characters that are accepted by the given filter.
void	require(char expected) This method verifies that the current character is equal to the given expected character.
void	require(String expected, boolean ignoreCase) This method verifies that the expected string gets consumed from this scanner with respect to ignoreCase.
boolean	skipOver(String substring, boolean ignoreCase) This method reads all next characters until the given substring has been detected.
boolean	skipOver(String substring, boolean ignoreCase, CharFilter stopFilter) This method reads all next characters until the given substring has been detected.
boolean	skipUntil(char stop) This method skips all next characters until the given stop character or the end is reached.
boolean	skipUntil(char stop, char escape) This method reads all next characters until the given stop character or the end of the string to parse is reached.
int	skipWhile(char c) This method reads all next characters that are identical to the character given by c.
int	skipWhile(CharFilter filter) This method reads all next characters that are accepted by the given filter.
int	skipWhile(CharFilter filter, int max) This method reads all next characters that are accepted by the given filter.

Method Detail

getCurrentIndex

int getCurrentIndex()

This method gets the current position in the stream to scan. It will initially be 0. In other words this method returns the number of characters that have already been consumed.

Returns:

the current index position.

hasNext

boolean hasNext()

This method determines if there is at least one more character available.

Returns:

true if there is at least one character available, false if the end has been reached.

next

char next()

This method reads the current character and increments the index stepping to the next character. You need to check if a character is available before calling this method.

Returns:

the current character.

forceNext

char forceNext()

Like next() this method reads the current character and increments the index. If there is no character available this method will do nothing and returns 0 (the NULL character and NOT '0').

Returns:

the current character or 0 if none is available.

peek

char peek()

This method reads the current character without incrementing the index. You need to check if a character is available before calling this method.

Returns:

the current character.

forcePeek

char forcePeek()

This method reads the current character without incrementing the index. If there is no character available this method will return 0 (the NULL character and NOT '0').

Returns:

the current character or 0 if none is available.

readDigit

int readDigit()

This method reads the next character if it is a digit. Else the state remains unchanged.

Returns:

the numeric value of the next Latin digit (e.g. 0 if '0') or -1 if the current character is no Latin digit.

readLong

long readLong(int maxDigits)
       throws NumberFormatException

This method reads the long starting at the current position by reading as many Latin digits as available but at maximum the given maxDigits and returns its parsed value.
ATTENTION:
This method does NOT treat signs (+ or -) to do so, scan them yourself before and negate the result as needed.

Parameters:

maxDigits - is the maximum number of digits that will be read. The value has to be positive (greater than zero). Use 19 or higher to be able to read any long number.

Returns:

the parsed number.

Throws:

NumberFormatException - if the current current position does NOT point to a number.

readDouble

double readDouble()
           throws NumberFormatException

This method reads the double value (decimal number) starting at the current position by reading as many matching characters as available and returns its parsed value.

Returns:

the parsed number.

Throws:

NumberFormatException - if the current current position does NOT point to a number.

Since:

4.0.0

readFloat

float readFloat()
         throws NumberFormatException

This method reads the float value (decimal number) starting at the current position by reading as many matching characters as available and returns its parsed value.

Returns:

the parsed number.

Throws:

NumberFormatException - if the current current position does NOT point to a number.

Since:

4.0.0

read

String read(int count)

This method reads the number of next characters given by count and returns them as string. If there are less characters available the returned string will be shorter than count and only contain the available characters.

Parameters:

count - is the number of characters to read. You may use Integer.MAX_VALUE to read until the end of data if the data-size is suitable.

Returns:

a string with the given number of characters or all available characters if less than count. Will be the empty string if no character is available at all.

expect

boolean expect(String expected,
               boolean ignoreCase)

This method skips all next characters as long as they equal to the according character of the expected string.
If a character differs this method stops and the parser points to the first character that differs from expected. Except for the latter circumstance, this method behaves like the following code:

 read(expected.length).equals[IgnoreCase](expected)
 

ATTENTION:
Be aware that if already the first character differs, this method will NOT change the state of the scanner. So take care NOT to produce infinity loops.

Parameters:

expected - is the expected string.

ignoreCase - - if true the case of the characters is ignored when compared.

Returns:

true if the expected string was successfully consumed from this scanner, false otherwise.

expectStrict

boolean expectStrict(String expected,
                     boolean ignoreCase)

This method acts as expect(String, boolean) but if the expected String is NOT completely present, no character is consumed and the state of the scanner remains unchanged.

Parameters:

expected - is the expected string.

ignoreCase - - if true the case of the characters is ignored when compared.

Returns:

true if the expected string was successfully consumed from this scanner, false otherwise.

expect

boolean expect(char expected)

This method checks that the current character is equal to the given expected character.
If the current character was as expected, the parser points to the next character. Otherwise its position will remain unchanged.

Parameters:

expected - is the expected character.

Returns:

true if the current character is the same as expected, false otherwise.

require

void require(String expected,
             boolean ignoreCase)
      throws NlsParseException

This method verifies that the expected string gets consumed from this scanner with respect to ignoreCase. Otherwise an exception is thrown indicating the problem.
This method behaves functionally equivalent to the following code:

 if (!scanner.expectStrict(expected, ignoreCase)) {
   throw new NlsParseException(scanner.read(expected.length), expected);
 }
 

Parameters:

expected - is the expected string.

ignoreCase - - if true the case of the characters is ignored during comparison.

Throws:

NlsParseException - if the expected string was NOT found.

Since:

3.0.0

require

void require(char expected)
      throws NlsParseException

This method verifies that the current character is equal to the given expected character.
If the current character was as expected, the parser points to the next character. Otherwise an exception is thrown indicating the problem.

Parameters:

expected - is the expected character.

Throws:

NlsParseException - if the expected character was NOT found.

Since:

3.0.0

skipUntil

boolean skipUntil(char stop)

This method skips all next characters until the given stop character or the end is reached. If the stop character was reached, this scanner will point to the next character after stop when this method returns.

Parameters:

stop - is the character to read until.

Returns:

true if the first occurrence of the given stop character has been passed, false if there is no such character.

skipUntil

boolean skipUntil(char stop,
                  char escape)

This method reads all next characters until the given stop character or the end of the string to parse is reached. In advance to skipUntil(char), this method will read over the stop character if it is escaped with the given escape character.

Parameters:

stop - is the character to read until.

escape - is the character used to escape the stop character (e.g. '\').

Returns:

true if the first occurrence of the given stop character has been passed, false if there is no such character.

readUntil

String readUntil(char stop,
                 boolean acceptEof)

This method reads all next characters until the given stop character or the end is reached.
After the call of this method, the current index will point to the next character after the (first) stop character or to the end if NO such character exists.

Parameters:

stop - is the character to read until.

acceptEof - if true EOF will be treated as stop, too.

Returns:

the string with all read characters excluding the stop character or null if there was no stop character and acceptEof is false.

readUntil

String readUntil(CharFilter filter,
                 boolean acceptEof)

This method reads all next characters until the first character accepted by the given filter or the end is reached.
After the call of this method, the current index will point to the next character after the first accepted character or to the end if NO such character exists and acceptEof is true. Otherwise, if null is returned, the current index will remain unchanged.

Parameters:

filter - is used to decide where to stop.

acceptEof - if true EOF will be treated as stop, too.

Returns:

the string with all read characters not accepted by the given filter character or null if there was no accepted character and acceptEof is false.

Since:

7.0.0

readUntil

String readUntil(char stop,
                 boolean acceptEof,
                 char escape)

This method reads all next characters until the given (un-escaped) stop character or the end is reached.
In advance to readUntil(char, boolean), this method allows that the stop character may be used in the input-string by adding the given escape character. After the call of this method, the current index will point to the next character after the (first) stop character or to the end if NO such character exists.
This method is especially useful when quoted strings should be parsed. E.g.:

 CharStreamScanner scanner = getScanner();
 doSomething();
 char c = scanner.forceNext();
 if ((c == '"') || (c == '\'')) {
   char escape = c; // may also be something like '\'
   String quote = scanner.readUntil(c, false, escape)
 } else {
   doOtherThings();
 }
 

Parameters:

stop - is the character to read until.

acceptEof - if true EOF will be treated as stop, too.

escape - is the character used to escape the stop character. To add an occurrence of the escape character it has to be duplicated (occur twice). The escape character may also be equal to the stop character. If other regular characters are escaped the escape character is simply ignored.

Returns:

the string with all read characters excluding the stop character or null if there was no stop character and acceptEof is false.

readUntil

String readUntil(char stop,
                 boolean acceptEof,
                 CharScannerSyntax syntax)

This method reads all next characters until the given stop character or the end of the string to parse is reached. In advance to readUntil(char, boolean), this method will scan the input using the given syntax which e.g. allows to escape the stop character.
After the call of this method, the current index will point to the next character after the (first) stop character or to the end of the string if NO such character exists.

Parameters:

stop - is the character to read until.

acceptEof - if true EOF will be treated as stop, too.

syntax - contains the characters specific for the syntax to read.

Returns:

the string with all read characters excluding the stop character or null if there was no stop character.

readWhile

String readWhile(CharFilter filter)

This method reads all next characters that are accepted by the given filter.
After the call of this method, the current index will point to the next character that was NOT accepted by the given filter or to the end if NO such character exists.

Parameters:

filter - is used to decide which characters should be accepted.

Returns:

a string with all characters accepted by the given filter. Will be the empty string if no character was accepted.

See Also:

skipWhile(CharFilter)

readWhile

String readWhile(CharFilter filter,
                 int max)

This method reads all next characters that are accepted by the given filter.
After the call of this method, the current index will point to the next character that was NOT accepted by the given filter. If the next max characters or the characters left until the end of this scanner are accepted, only that amount of characters are skipped.

Parameters:

filter - is used to decide which characters should be accepted.

max - is the maximum number of characters that should be read.

Returns:

a string with all characters accepted by the given filter limited to the length of max and the end of this scanner. Will be the empty string if no character was accepted.

See Also:

skipWhile(char)

skipOver

boolean skipOver(String substring,
                 boolean ignoreCase)

This method reads all next characters until the given substring has been detected.
After the call of this method, the current index will point to the next character after the first occurrence of substring or to the end of the string if the given substring was NOT found.

Parameters:

substring - is the substring to search and skip over starting at the current index.

ignoreCase - - if true the case of the characters is ignored when compared with characters from substring.

Returns:

true if the given substring occurred and has been passed and false if the end of the string has been reached without any occurrence of the given substring.

skipOver

boolean skipOver(String substring,
                 boolean ignoreCase,
                 CharFilter stopFilter)

This method reads all next characters until the given substring has been detected.
If a stop character is detected by the given stopFilter this method returns false pointing to the character next to that stop character. Otherwise after this method, the current index will point to the next character after the first occurrence of substring or to the end of the string if the given substring was NOT found.

Parameters:

substring - is the substring to search and skip over starting at the current index.

ignoreCase - - if true the case of the characters is ignored when compared with characters from substring.

stopFilter - is the filter used to detect stop characters. If such character was detected, the skip is stopped and the parser points to the character after the stop character. The substring should NOT contain a stop character.

Returns:

true if the given substring occurred and has been passed and false if a stop character has been detected or the end of the string has been reached without any occurrence of the given substring or stop character.

skipWhile

int skipWhile(char c)

This method reads all next characters that are identical to the character given by c.
E.g. use readWhile(' ') to skip all blanks from the current index. After the call of this method, the current index will point to the next character that is different to c or to the end if NO such character exists.

Parameters:

c - is the character to read over.

Returns:

the number of characters that have been skipped.

skipWhile

int skipWhile(CharFilter filter)

This method reads all next characters that are accepted by the given filter.
After the call of this method, the current index will point to the next character that was NOT accepted by the given filter or to the end if NO such character exists.

Parameters:

filter - is used to decide which characters should be accepted.

Returns:

the number of characters accepted by the given filter that have been skipped.

See Also:

skipWhile(char)

skipWhile

int skipWhile(CharFilter filter,
              int max)

This method reads all next characters that are accepted by the given filter.
After the call of this method, the current index will point to the next character that was NOT accepted by the given filter. If the next max characters or the characters left until the end of this scanner are accepted, only that amount of characters are skipped.

Parameters:

filter - is used to decide which characters should be accepted.

max - is the maximum number of characters that should be skipped.

Returns:

the number of skipped characters.

See Also:

skipWhile(char)