net.percederberg.grammatica.parser
Class Parser

java.lang.Object
  |
  +--net.percederberg.grammatica.parser.Parser
Direct Known Subclasses:
RecursiveDescentParser

public abstract class Parser
extends java.lang.Object

A base parser class. This class provides the standard parser interface, as well as token handling.

Version:
1.0
Author:
Per Cederberg,

Constructor Summary
protected Parser(Tokenizer tokenizer)
          Creates a new parser.
protected Parser(Tokenizer tokenizer, Analyzer analyzer)
          Creates a new parser.
 
Method Summary
protected  void addNode(Production node, Node child)
          Handles the parser adding a child node to a production.
 void addPattern(ProductionPattern pattern)
          Adds a new production pattern to the parser.
protected  void enterNode(Node node)
          Handles the parser entering a production.
protected  Node exitNode(Node node)
          Handles the parser leaving a production.
protected  ProductionPattern getPattern(int id)
          Returns the production pattern with the specified id.
protected  java.util.Collection getPatterns()
          Returns the unordered set of production patterns.
protected  ProductionPattern getStartPattern()
          Returns the production pattern for the starting production.
protected  Token nextToken()
          Reads and consumes the next token in the queue.
protected  Token nextToken(int id)
          Reads and consumes the next token in the queue.
abstract  Node parse()
          Parses the token stream and returns a parse tree.
protected  Token peekToken(int steps)
          Returns a token from the queue.
 void prepare()
          Initializes the parser.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Parser

protected Parser(Tokenizer tokenizer)
Creates a new parser.

Parameters:
tokenizer - the tokenizer to use

Parser

protected Parser(Tokenizer tokenizer,
                 Analyzer analyzer)
Creates a new parser.

Parameters:
tokenizer - the tokenizer to use
analyzer - the analyzer callback to use
Method Detail

addPattern

public void addPattern(ProductionPattern pattern)
                throws ParserCreationException
Adds a new production pattern to the parser. The first pattern added is assumed to be the starting point in the grammar. The patterns added may be validated to some extent.

Parameters:
pattern - the pattern to add
Throws:
ParserCreationException - if the pattern couldn't be added correctly to the parser

prepare

public void prepare()
             throws ParserCreationException
Initializes the parser. All the added production patterns will be analyzed for ambiguities and errors. This method also initializes internal data structures used during the parsing.

Throws:
ParserCreationException - if the parser couldn't be initialized correctly

parse

public abstract Node parse()
                    throws ParserCreationException,
                           ParseException
Parses the token stream and returns a parse tree. This method will call prepare() if not previously called.

Returns:
the parse tree
Throws:
ParserCreationException - if the parser couldn't be initialized correctly
ParseException - if the input couldn't be parsed correctly
See Also:
prepare()

getPattern

protected ProductionPattern getPattern(int id)
Returns the production pattern with the specified id.

Parameters:
id - the production pattern id
Returns:
the production pattern found, or null if non-existent

getStartPattern

protected ProductionPattern getStartPattern()
Returns the production pattern for the starting production.

Returns:
the start production pattern, or null if no patterns have been added

getPatterns

protected java.util.Collection getPatterns()
Returns the unordered set of production patterns.

Returns:
the unordered set of production patterns

enterNode

protected void enterNode(Node node)
                  throws ParseException
Handles the parser entering a production. This method calls the appropriate analyzer callback if the node is not hidden.

Parameters:
node - the parse tree node
Throws:
ParseException - if the node couldn't be handled correctly

exitNode

protected Node exitNode(Node node)
                 throws ParseException
Handles the parser leaving a production. This method calls the appropriate analyzer callback if the node is not hidden, and returns the result.

Parameters:
node - the parse tree node
Returns:
the parse tree node, or null if no parse tree should be created
Throws:
ParseException - if the node couldn't be handled correctly

addNode

protected void addNode(Production node,
                       Node child)
                throws ParseException
Handles the parser adding a child node to a production. This method calls the appropriate analyzer callback.

Parameters:
node - the parent parse tree node
child - the child parse tree node, or null
Throws:
ParseException - if the node couldn't be handled correctly

nextToken

protected Token nextToken()
                   throws ParseException
Reads and consumes the next token in the queue. If no token was available for consumation, a parse error will be thrown.

Returns:
the token consumed
Throws:
ParseException - if the input stream couldn't be read or parsed correctly

nextToken

protected Token nextToken(int id)
                   throws ParseException
Reads and consumes the next token in the queue. If no token was available for consumation, a parse error will be thrown. A parse error will also be thrown if the token id didn't match the specified one.

Parameters:
id - the expected token id
Returns:
the token consumed
Throws:
ParseException - if the input stream couldn't be parsed correctly, or if the token wasn't expected

peekToken

protected Token peekToken(int steps)
                   throws ParseException
Returns a token from the queue. This method is used to check coming tokens before they have been consumed. Any number of tokens forward can be checked.

Parameters:
steps - the token queue number, zero (0) for first
Returns:
the token in the queue, or null if no more tokens in the queue
Throws:
ParseException - if the input stream couldn't be read or parsed correctly