com.coasttocoastresearch.apg
Class Parser

java.lang.Object
  com.coasttocoastresearch.apg.Parser

public class Parser
extends java.lang.Object

The Parser class is used to construct a parser for a specific grammar. It is initialized with a generated Grammar class object and optional UDT and rule callback functions. Optionally, the Parser class can be configured to generate an AST, parsing statistics, and/or a trace of the syntax tree nodes processed during the parse.

Nested Class Summary

class	Parser.CallbackData Provisioned by the Parser for rule and UDT callback functions.
class	Parser.Result Defines the Parser's results.
static class	Parser.RuleCallback The base class for all rule callback functions.
static class	Parser.UdtCallback Base class for all User-Defined Terminals (UDTs).

Constructor Summary

Parser(Grammar grammar)
The Parser constructor.

Method Summary

void	addAstRuleNode(int id, int offset, int length, boolean match) NOTE: This function should only be called from UdtCallback or RuleCallback callback functions.
void	addAstUdtNode(int id, int offset, int length, boolean match) NOTE: This function should only be called from UdtCallback or RuleCallback callback functions.
Ast	enableAst(boolean enable) Enables or disables the generation of an Abstract Syntax Tree (AST).
Statistics	enableStatistics(boolean enable) Enables or disables the generation of a parsing statistics.
Trace	enableTrace(boolean enable) Enables or disables the generation of a Trace.
int	executeRule(int id, int offset) NOTE: This function should only be called from UdtCallback or RuleCallback callback functions.
int	executeUdt(int id, int offset) NOTE: This function should only be called from UdtCallback or RuleCallback callback functions.
Parser.Result	parse() Call this function to parser the input string.
void	setInputString(char[] input) Sets the input string to be parsed.
void	setInputString(java.lang.String input) Sets the input string to be parsed.
void	setMyData(java.lang.Object data) Called to provision the callback functions with a user-defined data class.
void	setRuleCallback(int id, Parser.RuleCallback callback) Sets the user-defined callback function to be called when processing the identified rule nodes.
void	setStartRule(int start) Sets the start rule.
void	setUdtCallback(int id, Parser.UdtCallback callback) Sets the user-defined callback function to be called when processing the identified UDT nodes.

Methods inherited from class java.lang.Object

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

Constructor Detail

Parser

public Parser(Grammar grammar)

The Parser constructor.

Parameters:

grammar - an instance of a Generator-generated Grammar class.

Method Detail

addAstRuleNode

public void addAstRuleNode(int id,
                           int offset,
                           int length,
                           boolean match)
                    throws java.lang.IllegalArgumentException,
                           java.lang.Exception

NOTE: This function should only be called from UdtCallback or RuleCallback callback functions. Results will be unpredictable if called otherwise.

Adds a rule node to the AST. May alter the grammar the AST is representing and should only be used with care.

Parameters:

id - grammar id of the rule name node to add.

offset - offset into the input string to the first character of the phrase this node has matched.

length - length of the matched phrase. Must not be larger than the remaining input string length.

Throws:

java.lang.IllegalArgumentException - thrown if the id is out of range or the

java.lang.Exception - thrown if the callback function returns an illegal value. An illegal value would be a phrase length L >= n, where n is the remaining length of the input string, or a zero (empty) length by a UDT designated as non-empty. (UDTs having names beginning with "u_" are designated as non-empty. UDTs having names beginning with "e_" are designated as empty.)

addAstUdtNode

public void addAstUdtNode(int id,
                          int offset,
                          int length,
                          boolean match)
                   throws java.lang.IllegalArgumentException,
                          java.lang.Exception

NOTE: This function should only be called from UdtCallback or RuleCallback callback functions. Results will be unpredictable if called otherwise.

Adds a UDT node to the AST. May alter the grammar the AST is representing and should only be used with care.

Parameters:

id - grammar id of the UDT name node to add.

offset - offset into the input string to the first character of the phrase this node has matched.

length - length of the matched phrase. Must not be larger than the remaining input string length.

Throws:

java.lang.IllegalArgumentException - thrown if the id is out of range or the

java.lang.Exception - thrown if the callback function returns an illegal value. An illegal value would be a phrase length L >= n, where n is the remaining length of the input string, or a zero (empty) length by a UDT designated as non-empty. (UDTs having names beginning with "u_" are designated as non-empty. UDTs having names beginning with "e_" are designated as empty.)

enableAst

public Ast enableAst(boolean enable)

Enables or disables the generation of an Abstract Syntax Tree (AST). The Ast class has no public constructor and this function is the only way to generate an instance.

Parameters:

enable - if true, an AST will be generated, if false, not. By default enable is false.

Returns:

an instance of the Ast class.

See Also:

Ast

enableStatistics

public Statistics enableStatistics(boolean enable)

Enables or disables the generation of a parsing statistics. Statistics has no public constructor and this function is the only way to generate an instance.

Parameters:

enable - if true, statistics will be generated, if false, not. By default enable is false.

Returns:

an instance of the Statistics class.

See Also:

Statistics

enableTrace

public Trace enableTrace(boolean enable)

Enables or disables the generation of a Trace. Trace has no public constructor and this function is the only way to generate an instance.

Parameters:

enable - if true, an trace will be generated, if false, not. By default enable is false.

Returns:

an instance of the Trace class.

See Also:

Trace

executeRule

public int executeRule(int id,
                       int offset)
                throws java.lang.IllegalArgumentException,
                       java.lang.Exception

NOTE: This function should only be called from UdtCallback or RuleCallback callback functions. Results will be unpredictable if called otherwise.

Parses the requested rule as if it were a child node of the calling function. A call to this function alters the grammar being parsed and should be used with care.

Parameters:

id - grammar id of the rule to parse. Must be in the range 0 - (rule count-1).

offset - offset of the first character in the input string of the phrase to match.

Returns:

the length of the matched phrase if the parse is successful. -1 otherwise. Phrase lengths must in the range 0 - (n-1), where n is the remaining string length.

Throws:

java.lang.IllegalArgumentException - thrown if id is out of range (see above).

java.lang.Exception - thrown if the callback function returns an illegal value. An illegal value would be a phrase length L >= n or a zero (empty) length by a UDT designated as non-empty. (UDTs having names beginning with "u_" are designated as non-empty. UDTs having names beginning with "e_" are designated as empty.)

executeUdt

public int executeUdt(int id,
                      int offset)
               throws java.lang.Exception

NOTE: This function should only be called from UdtCallback or RuleCallback callback functions. Results will be unpredictable if called otherwise.

Parses the requested UDT as if it were a child node of the calling function. A call to this function alters the grammar being parsed and should be used with care.

Parameters:

id - grammar id of the UDT to parse. Must be in the range 0 - (UDT count-1).

offset - offset of the first character in the input string of the phrase to match.

Returns:

the length of the matched phrase if the parse is successful. -1 otherwise. Phrase lengths must in the range 0 - (n-1), where n is the remaining string length.

Throws:

java.lang.IllegalArgumentException - thrown if id is out of range (see above).

java.lang.Exception - thrown if the callback function returns an illegal value. An illegal value would be a phrase length L >= n or a zero (empty) length by a UDT designated as non-empty. (UDTs having names beginning with "u_" are designated as non-empty. UDTs having names beginning with "e_" are designated as empty.)

parse

public Parser.Result parse()
                    throws java.lang.Exception

Call this function to parser the input string. A call to setInputString is required prior to calling this function.

Returns:

a Result class with information about the parser results.

Throws:

java.lang.Exception - thrown if any callback function returns an illegal value. Illegal values are phrase lengths longer than the length of the remaining input string or a zero (empty) length by a UDT designated as non-empty. (UDTs having names beginning with "u_" are designated as non-empty. UDTs having names beginning with "e_" are designated as empty.)

See Also:

Parser.Result

setInputString

public void setInputString(char[] input)

Sets the input string to be parsed. A call to this function is required prior to calling parse()

Parameters:

input - the input string

setInputString

public void setInputString(java.lang.String input)

Sets the input string to be parsed. A call to this function is required prior to calling parse()

Parameters:

input - the input string

setMyData

public void setMyData(java.lang.Object data)

Called to provision the callback functions with a user-defined data class. null by default.

Parameters:

data - any object of the user's choice.

setRuleCallback

public void setRuleCallback(int id,
                            Parser.RuleCallback callback)

Sets the user-defined callback function to be called when processing the identified rule nodes.

Parameters:

id - identifier of the rule for which this callback is to be called.

callback - an instance of a user-written extension of the RuleCallback class.

See Also:

GeneratorGrammar.RuleNames

setStartRule

public void setStartRule(int start)
                  throws java.lang.IllegalArgumentException

Sets the start rule. By default start = 0 which identifies the first rule in the grammar definition.

Parameters:

start - the identifier for the desired start rule.

Throws:

java.lang.IllegalArgumentException - thrown if the start identifier is out of range.

See Also:

GeneratorGrammar.RuleNames

setUdtCallback

public void setUdtCallback(int id,
                           Parser.UdtCallback callback)

Sets the user-defined callback function to be called when processing the identified UDT nodes.

Parameters:

id - identifier of the UDT for which this callback is to be called.

callback - an instance of a user-written extension of the UdtCallback class.

See Also:

GeneratorGrammar.UdtNames