Sharkysoft home

lava.io
Class StreamParser

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

public class StreamParser
extends java.lang.Object

Stream parsing utilities.

Details: StreamParser contains a variety of methods for parsing elements from PushbackReaders. Each method is designed to read and parse a certain type of object. If the object sought by a particular parsing method is next in the stream, that method parses the object and returns it. If the requested object is not immediately next in the stream, however, the parsing method returns a failure indicator (usually null).

In cases of success, the stream is left so that the next character to be read is the first character immediately after the object that was parsed. In cases of failure, however, the stream is left as if nothing had been read. This is possible only because the supplied stream supports unread and each method is configured to consume no more data than is necessary to define the parsed result.

Because StreamParser's parsing methods use unread liberally, the supplied PushbackReader's pushback buffer should be allocated large enough to handle the pushback resulting from failed parse attempts. For example, suppose there was a method called "parseFoo" whose purpose was to parse grammatically correct sentences. In some cases, parseFoo would need to read from the beginning of the sentence all the way to the sentence's terminating punctuation mark before it could determine that the sentence was malformed. But then, parseFoo would be obligated to push all of the examined characters back onto the stream, and there might be a lot of them. When you create PushbackReaders for use with this class, you should carefully consider the amount of pushback that may be required.

Since:
2000.01.29
Version:
2000.07.07

Constructor Summary
StreamParser()
           
 
Method Summary
static java.lang.String expectClassString(java.io.PushbackReader in, ICharacterClass cl)
          Expects class string.
static java.lang.String expectDigitsString(java.io.PushbackReader in, int radix)
          Expects digits string.
static void expectExactString(java.io.PushbackReader in, java.lang.String s)
           
static java.lang.String expectHorizontalWhiteString(java.io.PushbackReader in)
          Expects horizontal white string.
static java.lang.String expectHtmlIdentifier(java.io.PushbackReader in)
          Expects HTML identifier.
static java.lang.String expectIntegerString(java.io.PushbackReader in)
          Expects integer string.
static java.lang.String expectJavaIdentifier(java.io.PushbackReader in)
          Expects Java identifier.
static java.lang.String expectQuotedCString(java.io.PushbackReader in)
          Expects quoted C string.
static java.lang.String expectRealString(java.io.PushbackReader in)
          Expects real number string.
static java.lang.String expectShellArgument(java.io.PushbackReader in)
          Expects shell argument.
static java.lang.String expectString(java.io.PushbackReader in)
          Expects a string.
static java.lang.String expectWhiteString(java.io.PushbackReader in)
          Expects white string.
static java.io.PushbackReader getLineParser(java.lang.String line)
          Creates line parser.
static boolean searchString(java.io.Reader in, java.lang.String target, int limit, java.lang.StringBuffer skipped_text)
          Searches for string.
static java.lang.String tryClassString(java.io.PushbackReader in, ICharacterClass cl)
          Parses class string.
static java.lang.String tryDigitsString(java.io.PushbackReader in, int radix)
          Parses digit string.
static java.lang.String tryEmailAddress(java.io.PushbackReader in)
          Parses email address.
static boolean tryExactString(java.io.PushbackReader in, java.lang.String s)
           
static java.lang.String tryHorizontalWhiteString(java.io.PushbackReader in)
          Parses horizontal white space.
static java.lang.String tryHtmlIdentifier(java.io.PushbackReader in)
          Parses HTML identifier.
static java.lang.String tryIntegerString(java.io.PushbackReader in)
          Parses integer string.
static java.lang.String tryJavaIdentifier(java.io.PushbackReader in)
          Parses Java identifier.
static java.lang.String tryQuotedCString(java.io.PushbackReader in)
          Parses quoted C string.
static java.lang.String tryRealString(java.io.PushbackReader in)
          Reads a real number string.
static java.lang.String tryShellArgument(java.io.PushbackReader in)
          Parses shell argument.
static java.lang.String tryString(java.io.PushbackReader in)
          Parses string.
static java.lang.String tryWhiteString(java.io.PushbackReader in)
          Parses white space.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StreamParser

public StreamParser()
Method Detail

expectQuotedCString

public static final java.lang.String expectQuotedCString(java.io.PushbackReader in)
                                                  throws java.io.IOException
Expects quoted C string.

Details: expectQuotedCString does the same thing as tryQuotedCString but throws a StreamFormatException if the parsing is unsuccessful.

Parameters:
in - the input source
Returns:
the C string
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.02.21

tryQuotedCString

public static final java.lang.String tryQuotedCString(java.io.PushbackReader in)
                                               throws java.io.IOException
Parses quoted C string.

Details: tryQuotedCString parses a C-style string literal surrounded by either single quotes ('\'') or double quotes ('"'). If parsing succeeds, the entire quoted C string is returned, complete with surrounding quotes and undecoded, escaped characters. If parsing fails, null is returned.

Parameters:
in - the input source
Returns:
the parsed C string
Throws:
java.io.IOException - if an I/O error occurs
Since:
unknown

expectString

public static final java.lang.String expectString(java.io.PushbackReader in)
                                           throws java.io.IOException
Expects a string.

Details: expectString does the same thing as tryString, but throws a StreamFormatException if the parsing operation fails.

Parameters:
in - the input source
Returns:
the string
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.02.21

tryString

public static final java.lang.String tryString(java.io.PushbackReader in)
                                        throws java.io.IOException
Parses string.

Details: tryString parses and returns a string, where a string is defined as any continuous sequence of non-space characters. A character c is considered non-space if and only if Character.isWhitespace (c) returns false. If a string by this definition is not immediately next in the stream, tryString returns null. Otherwise, tryString returns the string.

Parameters:
in - the input source
Returns:
the string
Throws:
java.io.IOException - if an I/O error occurs
Since:
1998.09.26

expectShellArgument

public static java.lang.String expectShellArgument(java.io.PushbackReader in)
                                            throws java.io.IOException
Expects shell argument.

Details: expectShellArgument does the same thing as tryShellArgument but throws a StreamFormatException if the parsing operation fails.

Parameters:
in - the input source
Returns:
the parsed argument
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.02.21

tryShellArgument

public static final java.lang.String tryShellArgument(java.io.PushbackReader in)
                                               throws java.io.IOException
Parses shell argument.

Details: tryShellArgument parses a single shell-like token from the stream, such as a sequence of characters that might be considered one argument in a Unix command interpreter like bash. tryShellArgument recognizes shell meta-characters, single and double quotes, backslash escapes, etc. man bash for more information.

Parameters:
in - the input source
Returns:
the parsed argument
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.01.29

expectClassString

public static java.lang.String expectClassString(java.io.PushbackReader in,
                                                 ICharacterClass cl)
                                          throws java.io.IOException
Expects class string.

Details: expectClassString is functionally identical to tryClassString, except that expectClassString throws a StreamFormatException if the parsing operation fails.

Parameters:
in - the input source
cl - the character class
Returns:
the class string
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.06.03

tryClassString

public static java.lang.String tryClassString(java.io.PushbackReader in,
                                              ICharacterClass cl)
                                       throws java.io.IOException
Parses class string.

Details: tryClassString parses a "character class string" from the stream. A character class string is a string consisting only of characters in the given character class.

Parameters:
in - the input source
cl - the character class
Returns:
the class string
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.06.03

expectWhiteString

public static java.lang.String expectWhiteString(java.io.PushbackReader in)
                                          throws java.io.IOException
Expects white string.

Details: expectWhiteString is functionally identical to tryWhiteString, except that expectWhiteString throws a StreamFormatException if the parsing operation fails.

Parameters:
in - the input source
Returns:
the white string
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.02.21

tryWhiteString

public static java.lang.String tryWhiteString(java.io.PushbackReader in)
                                       throws java.io.IOException
Parses white space.

Details: tryWhiteString parses a "white string" from the stream. A white string is a string consisting only of characters for which Character.isWhitespace returns true.

Parameters:
in - the input source
Returns:
the white string
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.01.30

expectHorizontalWhiteString

public static java.lang.String expectHorizontalWhiteString(java.io.PushbackReader in)
                                                    throws java.io.IOException
Expects horizontal white string.

Details: expectHorizontalWhiteString is functionally identical to tryHorizontalWhiteString, except that expectHorizontalWhiteString throws a StreamFormatException if the parsing operation fails.

Parameters:
in - the input source
Returns:
the horizontal white string
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.06.03

tryHorizontalWhiteString

public static java.lang.String tryHorizontalWhiteString(java.io.PushbackReader in)
                                                 throws java.io.IOException
Parses horizontal white space.

Details: tryHorizontalWhiteString parses a "horizontal white string" from the stream. A horizontal white string is a string consisting only of characters for which Ctype.ishspace returns true.

Parameters:
in - the input source
Returns:
the horizontal white string
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.06.03

expectDigitsString

public static java.lang.String expectDigitsString(java.io.PushbackReader in,
                                                  int radix)
                                           throws java.io.IOException
Expects digits string.

Details: expectDigitsString is functionally identical to tryDigitsString, except that expectDigitsString throws a StreamFormatException if the parsing operation fails.

Parameters:
in - the stream
Returns:
the digits string
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.02.21

tryDigitsString

public static final java.lang.String tryDigitsString(java.io.PushbackReader in,
                                                     int radix)
                                              throws java.io.IOException
Parses digit string.

Details: parseDigitsString reads a contiguous sequence of digits from the given stream (in). As many digits as possible are read and consumed, until the first non-digit character is encountered. Only characters that fall below the given radix (radix) are considered digits. tryDigitsString does not accept or consume sign characters, the radix point, or base-specific prefixes such as "0x". If the first character in the stream does not qualify as a digit, tryDigitsString returns null.

Parameters:
in - the stream
Returns:
the digits string
Throws:
java.io.IOException - if an I/O error occurs

expectIntegerString

public static java.lang.String expectIntegerString(java.io.PushbackReader in)
                                            throws java.io.IOException
Expects integer string.

Details: expectIntegerString is functionally identical to tryIntegerString, except that expectIntegerString throws a StreamFormatException if the parsing operation fails.

Parameters:
in - the input source
Returns:
the parsed integer string
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.02.21

tryIntegerString

public static java.lang.String tryIntegerString(java.io.PushbackReader in)
                                         throws java.io.IOException
Parses integer string.

Details: tryIntegerString attempts to parse an "integer string" from the stream. An integer string is a numeric string in the following form:

The longest string possible that matches any of these forms is consumed from the stream. (The radix is automatically selected.) If none of these forms can be parsed, tryIntegerString returns null. Otherwise, it returns the numeric string that it parsed.

Parameters:
in - the input source
Returns:
the parsed integer string
Throws:
java.io.IOException - if an I/O error occurs

expectExactString

public static void expectExactString(java.io.PushbackReader in,
                                     java.lang.String s)
                              throws java.io.IOException

tryExactString

public static boolean tryExactString(java.io.PushbackReader in,
                                     java.lang.String s)
                              throws java.io.IOException

expectJavaIdentifier

public static java.lang.String expectJavaIdentifier(java.io.PushbackReader in)
                                             throws java.io.IOException
Expects Java identifier.

Details: expectJavaIdentifier does the same thing as tryJavaIdentifier but throws a StreamFormatException if the parsing is unsuccessful.

Parameters:
in - the input source
Returns:
the Java identifier
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.06.01

tryJavaIdentifier

public static java.lang.String tryJavaIdentifier(java.io.PushbackReader in)
                                          throws java.io.IOException
Parses Java identifier.

Details: tryJavaIdentifier parses and returns a valid Java identifier. If a valid Java identifier cannot be parsed, null is returned.

Parameters:
in - the input source
Returns:
the Java identifier
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.06.01

expectHtmlIdentifier

public static java.lang.String expectHtmlIdentifier(java.io.PushbackReader in)
                                             throws java.io.IOException
Expects HTML identifier.

Details: expectHtmlIdentifier does the same thing as tryHtmlIdentifier but throws a StreamFormatException if the parsing is unsuccessful.

Parameters:
in - the input source
Returns:
the HTML identifier
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.07.07

tryHtmlIdentifier

public static java.lang.String tryHtmlIdentifier(java.io.PushbackReader in)
                                          throws java.io.IOException
Parses HTML identifier.

Details: tryHtmlIdentifier parses and returns a valid HTML identifier. If a valid HTML identifier cannot be parsed, null is returned.

An HTML identifier is any string beginning with an upper or lower case letter (A-Z) that consists only of letters, numbers, '_', and '-'.

Parameters:
in - the input source
Returns:
the HTML identifier
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.07.07

expectRealString

public static java.lang.String expectRealString(java.io.PushbackReader in)
                                         throws java.io.IOException
Expects real number string.

Details: expectRealString does the same thing as tryRealString but throws a StreamFormatException if the parsing is unsuccessful.

Parameters:
in - the input source
Returns:
the real number string
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.06.01

tryRealString

public static final java.lang.String tryRealString(java.io.PushbackReader in)
                                            throws java.io.IOException
Reads a real number string.

Details: tryRealString parses and returns a real number string. The string may be in the form +123.456e+789 or any sensible variation of that.

Parameters:
in - the input source
Returns:
the real number string
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.06.01

tryEmailAddress

public static final java.lang.String tryEmailAddress(java.io.PushbackReader in)
                                              throws java.io.IOException
Parses email address.

Details: tryEmailAddress parses and returns an email address from the stream. Email addresses parsed by this function are expected to have the following format (using a loose regular expression syntax):

[a-zA-Z][a-zA-Z0-9\-\.]*@[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*

Parameters:
in - the input source
Returns:
the email address
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.09.27

searchString

public static boolean searchString(java.io.Reader in,
                                   java.lang.String target,
                                   int limit,
                                   java.lang.StringBuffer skipped_text)
                            throws java.io.IOException
Searches for string.

Details: searchString consumes characters from the given stream (in) until the given string (target) is found, the search limit (limit) is exceeded, or the stream runs out. The search limit is the number of characters within which the first character of the target must be observed.

If the target string is found, and a non-null StringBuffer is supplied, then all of the characters that were skipped, including the target, will be written into (appended to) the supplied StringBuffer (skipped_text). If the target is not found, and a StringBuffer was supplied, then it will contain the characters that were read before the search was aborted.

true is returned if the string is found, false otherwise.

Note that setting limit to 0 results in behavior similar to tryExactString.

Parameters:
in - the input source
target - the string to find and skip
limit - how far ahead to search
skipped_text - the skipped characters
Returns:
true iff target is found
Throws:
java.io.IOException - if an I/O error occurs
Since:
2000.06.29

getLineParser

public static java.io.PushbackReader getLineParser(java.lang.String line)
Creates line parser.

Details: getLineParser returns a PushbackReader that reads characters from the given string (line) and which has enough pushback buffer to push back the entire string if necessary.

Parameters:
line - the line to parse
Returns:
the PushbackReader
Since:
2000.11.13

Sharkysoft home