unm.cs351.f11.tdrl.p1
Interface Parser<S,T extends Enum<T> & HasPattern>

public interface Parser<S,T extends Enum<T> & HasPattern>

Version:

1.0

Author:

terran

Method Summary

Token<T>	consume() Remove and return the next token from the token stream.
Token<T>	consume(EnumSet<T> expectedClass) Expect a token matching any one of a number of possible types, and consume/return it.
Token<T>	consume(T expected) Expect a particular token type and consume/return it.
Token<T>	consume(T expected, Matcher ePat) Expect a token by both type and string pattern, and consume/return it.
void	consumeUntil(T until) Consume and discard every token until a token matching the type specification is found.
void	consumeUntil(T until, Matcher untilPat) Consume and discard every token until a token matching the type and content (regex) specification is found.
boolean	expect(EnumSet<T> expected) Check whether the next token on the token stream matches any one of a number of token types.
boolean	expect(T expected) Check whether the next token on the token stream matches an expected token type.
boolean	expect(T expected, Matcher ePat) Check whether the next token on the token stream matches both an expected token type and an expected regular expression pattern.
void	parse(S db) Parse the data sequence, writing results into the state object db as it goes.
void	shutDown() Carry out any housekeeping to clean up after the parse is completed.

Method Detail

parse

void parse(S db)
           throws ParseException

Parse the data sequence, writing results into the state object db as it goes. This is the entry point to the parse, and it should correspond to the top-most non-terminal of the target grammar. This method, in turn, should invoke the various sub-rules via calls to other non-terminal methods.

Parameters:

db - State object for recording information generated during the parse.

Throws:

ParseException - If a lexical or syntactic error is encountered during the parse.

shutDown

void shutDown()
              throws IOException

Carry out any housekeeping to clean up after the parse is completed. For example, if the implementation maintains a reference to an open file handle, this could be called to close that file handle after the parse is completed.

Throws:

IOException - If there is an error shutting down any file resources.

expect

boolean expect(T expected)

Check whether the next token on the token stream matches an expected token type. This method examines the type (Token.getType()) of the next Token from the token stream without removing it from the stream or discarding it and compares it to an "expected" token type. This returns true iff the two match. That is, it checks that nextToken.getType()==expected

The intended use of this method is something like:

   // inside some non-terminal rule
   if (expect(QUOTED_STRING)) {
     Token t=consume(QUOTED_STRING);
     // do something with t or t.getContent()
   }
 


Parameters:
expected - The type of token to query.
Returns:
true iff the next token on the stream matches
 the specified token type.

expect

boolean expect(T expected,
               Matcher ePat)

Check whether the next token on the token stream matches both an expected token type and an expected regular expression pattern. This is a convenience method that allows the parser to check simultaneously that the next token matches both a specified token type (that is, nextToken.getType()==expected) and that the token's string content matches the expected pattern (that is, ePat matches nextToken.getContent()). Like expect(Enum), it does not remove the token from the stream.

Parameters:

expected - Expected type of the next token

ePat - Regex pattern expected of the next token on the stream

Returns:

True iff expected type and expected pattern match the next token.

expect

boolean expect(EnumSet<T> expected)

Check whether the next token on the token stream matches any one of a number of token types. This is just shorthand for:

   T nType=nextTok.getType();
   return ((nType == expected0) || (nType == expected1) || ... )
 
 It is helpful when you want to test whether the next token is any
 one of a variety of "acceptable" types.
 

 Like expect(Enum), this does not remove the next token
 from the token stream -- it only tests it, without changing the stream's
 state.


Parameters:
expected - The set of possible types that the next token could match.
Returns:
true iff the next token matches any of the
 token types.

consume

Token<T> consume()
                                             throws ParseException

Remove and return the next token from the token stream. This removes the next available token from the token stream, and returns it. The token stream will be advanced to the succeeding token (for future calls to expect(Enum), consume(), etc.).

Returns:

Next token from the stream, if any.

Throws:

ParseException - If no such token is available (e.g., because EOF has been passed.)

consume

Token<T> consume(T expected)
                                             throws ParseException

Expect a particular token type and consume/return it. This examines the type of the next token available from the token stream. If that type matches the expected type, this consume()s the token (i.e., removes it from the token stream and returns it). If it does not match, this generates a ParseException, indicating an attempt to consume an unexpected token.

Parameters:

expected - Type predicted for the next token on the token stream

Returns:

Token matching expected

Throws:

ParseException - Iff next token does not match expected

consume

Token<T> consume(T expected,
                 Matcher ePat)
                                             throws ParseException

Expect a token by both type and string pattern, and consume/return it. This examines both the type (Token.getType()) and string content (Token.getContent()) of the next token available on the token stream. If both match the expected values (literal type and regexp match), then the token is removed from the stream and returned. Otherwise, this generates a ParseException, indicating an attempt to consume an unexpected token.

Parameters:

expected - Type predicted for the next token on the token stream

ePat - Regex pattern expected of the next token on the stream

Returns:

Token matching both expected and ePat

Throws:

ParseException - Iff next token does not match one of expected or ePat

consume

Token<T> consume(EnumSet<T> expectedClass)
                                             throws ParseException

Expect a token matching any one of a number of possible types, and consume/return it. This examines the type (Token.getType()) of the next token on the token stream against a set of acceptable types. If it matches any of them, it is removed from the token stream and returned. Otherwise, this generates a ParseException, indicating an attempt to consume an unexpected token.

Parameters:

expectedClass - Set of allowable types for the next token

Returns:

Token matching at least one of expectedClass

Throws:

ParseException - Iff next token does not match any of the expectedClass

consumeUntil

void consumeUntil(T until)
                  throws ParseException

Consume and discard every token until a token matching the type specification is found. Halt and return without consuming the matching token. This is a convenience method to quickly consume and ignore a large number of tokens. It leaves the token stream positioned at the first token matching the specified type.

Parameters:

until - Specification for token to stop on.

Throws:

ParseException - If EOF is encountered before the specified token type.

consumeUntil

void consumeUntil(T until,
                  Matcher untilPat)
                  throws ParseException

Consume and discard every token until a token matching the type and content (regex) specification is found. Halt and return without consuming the matching token. This is a convenience method to quickly consume and ignore a large number of tokens. It leaves the token stream positioned at the first token matching the specified type and regular expression.

Parameters:

until - Token type specification to stop on.

untilPat - Regular expression pattern to match against.

Throws:

ParseException - If EOF is encountered before the specified token.