edu.neu.ccs.parser
Class BaseParser

java.lang.Object
  edu.neu.ccs.parser.BaseParser

All Implemented Interfaces:

Parser

Direct Known Subclasses:

JPTParser

public class BaseParser

extends Object

implements Parser

The class BaseParser is the base class for classes of objects that provide functionality for evaluating strings into primitive types and objects using a language with a simple syntactic structure.

Revisions in 2.5.0:

• The name of this class has been changed from AbstractParser to BaseParser since the class is no longer an abstract class.
• We have refactored the parse method and other related algorithmic methods from the derived class JPTParser into this class. This is why this class is no longer an abstract class. Nevertheless this class has limited functionality since no constants, functions, or operations have been predefined. We have introduced various special forms: set, let, if, eval, and random. We treat random as a special form in order to allow 0, 1, or 2 arguments.
• We have added a method parseWithArgumentList to enable the parser to set local variables for use during the parse operation.
• The parse methods may be called recursively. If an exception is thrown, the error message now accumulates context information.
• The parser now permits replacement of functions and operations by new definitions.
• We have refactored all static inner classes into separate class files.
• We have constrained constant and variable id's and function names to follow the rules for identifiers in Java and also to be distinct.
• We have constrained operation symbols to be created from a specific list of characters.
• We have changed critical member data from protected to private.
• We have added several public and protected methods and renamed a few methods to increase clarity.
• We have, in particular, added methods to call mathematical functions installed in the parser and to create tables of values for such functions.
• We have made many utility methods final but have kept algorithmic methods as protected and non-final so that they may be overridden in a derived class.
• We have improved code comments and error messages.
• We have fixed small bugs.

Further comments:

BaseParser contains all fundamental parsing algorithms but has no installed abstract functions, operations, or constants.

BaseParser has the ability to define special forms and five such forms are introduced: set, let, if, eval, and random. Here is a brief synopsis of these special forms.

Special Form	Typical Usage
set	set(identifier,expression)
let	let(identifier,expression)
if	if(test,expression-1,expression-2)
eval	eval(expression-1,...,expression-n)
random	random() or random(x) or random(x,y)

The special forms are interpreted as follows.

• set evaluates the expression and assigns it to the identifier in a persistant fashion that will be available across invocations of the parser.
  set returns the evaluated expression as its value.
• let evaluates the expression and assigns it to the identifier in a temporary fashion that will be available only in this invocation of the parser.
  let returns the evaluated expression as its value.
• if evaluates the test expression as a boolean. If the result is true, expression-1 is evaluated and returned and expression-2 is skipped. If the result is false, expression-2 is evaluated and returned and expression-1 is skipped.
• eval evaluates all expressions from left to right and returns the value of the last expression.
• random() returns a random double between 0 and 1.
• random(x) returns a random double between 0 and x.
• random(x,y) returns a random double between x and y.

random is introduced as a special form since in our simple parsing scheme ordinary functions cannot be overloaded to take different numbers of arguments.

Version:

2.5

Field Summary

protected String	ARGUMENT_LIST_END String token representing the end of an argument list.
protected String	ARGUMENT_LIST_START String token representing the start of an argument list.
protected String	ARGUMENT_SEPARATOR String token representing the argument separator.
protected String	ASSIGNMENT_BY_LET The reserved keyword "let" to indicate variable assignment that is temporary, that is, one that affects only the current invocation of the parse method.
protected String	ASSIGNMENT_BY_SET The reserved keyword "set" to indicate variable assignment that is persistent across invocations of the parse method.
private Hashtable	constants Table of constant identifiers and their corresponding values.
protected String	data The current String to be evaluated by the current call of parse.
protected String	EVAL The reserved keyword "eval" to indicate the special function that evaluates its arguments from left to right and then returns the value of the rightmost argument.
protected static int	FLOATING Value designating string data that has form of a floating number.
private Hashtable	functions Table of function names and their corresponding functions.
static Operation	IDENTITY The IDENTITY operation, equivalent to the function f(x,y)=y.
protected String	IF_THEN_ELSE The reserved keyword "if" to indicate if-then-else.
protected static int	INTEGRAL Value designating string data that has form of an integer number.
private Hashtable	let_variables Table of variable identifiers defined by "let" in the current invocation of the parse method and their corresponding values.
protected String	NESTED_EXPRESSION_END String token representing the end of a nested expression.
protected String	NESTED_EXPRESSION_START String token representing the start of a nested expression.
protected int	next The index of the next character to examine in the current String to be evaluated by the current call of parse.
static Operation	OPERATION_PREFIX The singleton operation object which designates that a symbol is a prefix for a known operation.
private Hashtable	operations Table of operation symbols and their corresponding operations.
private Vector	parserContextStack The vector that operates as a stack to save and restore the parser context in each call of parse.
private Vector	precedence List of hashtables storing the precedence relationship between operations.
private Hashtable	prefixes Table of prefixes of operation symbols.
protected String	RADIX_POINT String token representing the radix point.
protected String	RANDOM The reserved keyword "random" to indicate the special function that takes 0, 1, or 2 numeric arguments and has the following interpretation.
private Hashtable	reserved Table of reserved identifiers for special functions or operations.
private Hashtable	set_variables Table of variable identifiers defined by "set" and their corresponding values.
protected int	suspend The member data to control whether the parser should be evaluating operations, functions, and special functions or should rather be parsing formally in order to extract the next expression that is to be parsed as a string.
protected char	UNDERSCORE Char with UNDERSCORE character for identifiers.

Constructor Summary

BaseParser()
Constructs a new parser by initializing structures and by adding the standard operations, functions, and constants available for this parser.

Method Summary

void	addConstant(String id, Object value) Adds the given constant to the table of constants using the given identifier and value.
protected void	addConstants() Adds the standard constants for this parser to the environment.
void	addFunction(AbstractFunction function) Adds the given function to the table of recognized functions.
protected void	addFunctions() Adds the standard functions for this parser to the function table.
protected void	addOperation(Operation op, int pos) Adds the given operation to the operation table at the given index in the precedence list.
Operation	addOperationAfterPrecedenceOf(Operation compare, Operation op) Adds the given operation op to the table of recognized operations, at a level of precedence immediately after the precendence of the existing operation compare installed in this parser.
Operation	addOperationAtPrecedenceOf(Operation compare, Operation op) Adds the given operation op to the table of recognized operations, at the same level of precedence as the existing operation compare installed in this parser.
Operation	addOperationBeforePrecedenceOf(Operation compare, Operation op) Adds the given operation op to the table of recognized operations, at a level of precedence immediately before the precendence of the existing operation compare installed in this parser.
protected void	addOperations() Adds the standard operations for this parser to the operation table.
protected void	addReserved() Installs the reserved identifiers for the special functions.
protected int	afterDigits(int start) Return the first character position at or after start that is not a digit.
protected int	afterSign(int start) If the character at position start is '+' or '-' return (start + 1) otherwise return start.
void	assignArgumentList(String[] ids, Object[] values) This method takes id-value pairs from corresponding positions in the lists ids and values and performs the assignment using assignLetVariable.
Object	assignLetVariable(String id, Object value) Assigns the given value to the given identifier as a temporary "let" variable in the context of the current call to the parse method of this parser, replacing any previous "let" variable associated with the same identifier in this same context.
Object	assignSetVariable(String id, Object value) Assigns the given value to the given identifier as a persistant "set" variable for this parser, replacing any previous "set" variable associated with the same identifier.
protected Object	assignVariable(String id, Object value, Hashtable binding) Assigns the given value to the given identifier in the given binding environment, replacing any previous value in the environment associated with the same identifier.
static double	call(AbstractFunction f, double x) Call the given abstract function using the given double x as the argument and return a double value.
static double	call(AbstractFunction f, double[] arguments) Call the given abstract function using the given double data as arguments and return a double value.
static double	call(AbstractFunction f, double x, double y) Call the given abstract function using the given doubles x,y as arguments and return a double value.
static double	call(AbstractFunction f, double x, double y, double z) Call the given abstract function using the given doubles x,y,z as arguments and return a double value.
static double	call(AbstractFunction f, double x, double y, double z, double w) Call the given abstract function using the given doubles x,y,z,w as arguments and return a double value.
double	call(String name, double x) Call the function with the given name that is installed in this parser using the given double x as the argument and return a double value.
double	call(String name, double[] arguments) Call the function with the given name that is installed in this parser using the given double data as arguments and return a double value.
double	call(String name, double x, double y) Call the function with the given name that is installed in this parser using the given doubles x,y as arguments and return a double value.
double	call(String name, double x, double y, double z) Call the function with the given name that is installed in this parser using the given doubles x,y,z as arguments and return a double value.
double	call(String name, double x, double y, double z, double w) Call the function with the given name that is installed in this parser using the given doubles x,y,z,w as arguments and return a double value.
String[]	constants() Returns an array of the constant id's.
protected boolean	evaluate() Controls whether or not the parser evaluates or simply parses formally without evaluation.
protected Object	evaluateIdentifier(String identifier) Evaluate a constant or variable identifier and return its value.
protected String	extractExpression() Extracts the next pending expression as a string without performing any operations or evaluations.
String[]	functionNames() Returns an array of all function names.
AbstractFunction[]	functions() Returns an array of all functions.
AbstractFunction	getFunction(String name) Returns the function with the given name or null if no such function is defined.
Operation	getOperation(String symbol) Returns the operation with the given symbol or null if no such operation is defined.
Object	getValue(String id) Returns the value associated with a constant or variable with the given id or null if no such value is defined.
protected void	initializeStructures() Initialize the operation and precedence structures prior to any additions defined in derived classes by adding the IDENTITY operation at precedence 0.
boolean	isConstantID(String id) Returns whether or not the given id is associated with a constant.
boolean	isEnvironmentID(String id) Returns whether or not the given id is associated with a constant or variable.
protected boolean	isExponentAt(int start) Return true if the character at start is 'E' or 'e'.
boolean	isFunctionName(String name) Returns whether or not the given name is associated with a function.
boolean	isLetVariableID(String id) Returns whether or not the given id is associated with a "let" variable in the current invocation of the parse method.
protected Operation	isOperationOrPrefix(String symbol) Performs a lookup in the operation and prefix tables to determine if the given String symbol represents an existing operation or is a prefix of the symbol for an existing operation.
boolean	isOperationSymbol(String symbol) Returns whether or not the given symbol is associated with an operation.
boolean	isOrdinaryFunctionName(String name) Returns whether or not the given name is associated with a function whose class does NOT extend SimpleFunction.
static boolean	isPossibleIdentifier(String id) Returns true if the given id is a possible identifier for a constant, variable, function or reserved function.
static boolean	isPossibleOperation(String string) Returns true if the given string is a possible symbol for an operation.
boolean	isPossibleVariableID(String id) Returns true if the given string is a possible variable id in the current parser context.
boolean	isReservedID(String id) Returns whether or not the given id is associated with a constant.
boolean	isSetVariableID(String id) Returns whether or not the given id is associated with a "set" variable.
protected boolean	isSignAt(int start) Return true if the character at start is '+' or '-'.
boolean	isSimpleFunctionName(String name) Returns whether or not the given name is associated with a function whose class is or extends SimpleFunction.
static XPoint2D[]	makeTable(AbstractFunction f, double endpointA, double endpointB, int divisions) Make an XPoint2D array of pairs (x,f(x)) where x is sampled on the given interval divided into the given number of divisions.
static XPoint2D[]	makeTable(AbstractFunction f, XInterval limits, int divisions) Make an XPoint2D array of pairs (x,f(x)) where x is sampled on the given interval divided into the given number of divisions.
XPoint2D[][]	makeTable(String names, double endpointA, double endpointB, int divisions) Views the given String as a comma separated list of names of AbstractFunction objects installed in this parser; for each such function object f, makes an XPoint2D array of pairs (x,f(x)) where x is sampled on the given interval divided into the given number of divisions; all such arrays are collected and returned in a 2-dimensional array.
XPoint2D[][]	makeTable(String names, XInterval limits, int divisions) Views the given String as a comma separated list of names of AbstractFunction objects installed in this parser; for each such function object f, makes an XPoint2D array of pairs (x,f(x)) where x is sampled on the given interval divided into the given number of divisions; all such arrays are collected and returned in a 2-dimensional array.
protected String	nextIdentifier() Gets the next identifier in the data String and returns it.
protected Operation	nextOperation() If the next token in the data represents an operation then return the corresponding Operation otherwise return null.
protected Object	nextSimpleTerm() Returns the next simple term in the data string or throws a ParseException if no term is present.
protected Object	nextTerm() Returns the next term in the data string with all leading unary operations already applied or throws a ParseException if no term is present.
protected boolean	nextTokenIs(String pattern) Returns true if the given String exactly matches the next non-whitespace characters in the data, or false if it does not.
protected boolean	nextTokenIs(String pattern, int start) Returns true if the given String exactly matches the characters in the data starting at the given index, or false if it does not.
protected Operation[]	nextUnaryOperations() Returns the array of unary operations that occur after the current position in the data string and throws a ParseException if an operation is encountered that is binary but not unary.
Operation[]	operations() Returns an array of the operations.
String[]	operationSymbols() Returns an array of the operation symbols.
String[]	ordinaryFunctionNames() Returns an array of the function names that correspond to functions whose class does NOT extend SimpleFunction.
AbstractFunction[]	ordinaryFunctions() Returns an array of the ordinary functions, that is, functions whose class does NOT extend SimpleFunction.
Object	parse(String d) Parses the given string d and returns the Object it represents, given this parsing scheme.
protected Object[]	parseArgumentList() Parses the next argument list in the data String assuming that each argument is to be evaluated and returns an array of objects representing the list.
protected Object	parseAssignment(Hashtable binding) Parse assignment, that is, "set" or "let".
protected Object	parseEval() Parse the "eval" operation.
protected Object	parseExpression() Returns the result of parsing the next expression in the data string.
protected ObjectOperationPair	parseExpression(ObjectOperationPair pending) Recursive method that parses the next expression in the data string.
protected Object	parseFunctionCall(String identifier) Parse a function with arguments and return its value.
protected Object	parseIdentifierExpression() Parse an expression that is introduced by an identifier.
protected Object[]	parseIdentifierExpressionList() Parses the next argument list that consists of an identifier that is to be returned literally and a value expression to be evaluated.
protected Object	parseIfThenElse() Parse if-then-else, that is, "if".
protected Object	parseNestedExpression() Parse an expression in parentheses, that is, a nested expression, and return its value.
protected Object	parseNumber() Parses the next numeric token in the data String and returns an object representation of its value.
protected Object	parseRandom() The "random" function is a special function that takes 0, 1, or 2 numeric arguments and has the following interpretation.
protected Object	parseSpecialFunction(String identifier) Parse a special function whose parameter list may not be completely evaluated.
Object	parseWithArgumentList(String d, String[] ids, Object[] values) Parses the given string d in the context of a symbolic argument list and associated values and returns the Object represented by the string d given this parsing scheme.
protected void	popContext() Pop and restore the previous parser context.
protected int	precedenceOf(Operation op) Returns the index in the precedence list corresponding to the precedence of the given operation, or -1 if the given operation is null or is not in the precedence list.
protected void	pushContext(String d) Save the current parser context and initialize a new context to parse the string d.
AbstractFunction	removeFunction(String name) Removes the function with the given name from this parser.
String[]	reserved() Returns an array of the reserved id's.
void	reserveID(String id) Add this identifier to the table of reserved identifiers so it may not be used for a constant or variable id or a function name.
String[]	set_variables() Returns an array of the set variable id's.
protected void	setArgumentSeparatorToken(String token) Sets the token representing the argument separator in this parsing scheme to the given String token.
protected void	setLeftParenthesisToken(String token) Sets the token representing the start of an argument list in this parsing scheme to the given String token.
protected void	setRadixPointToken(String token) Sets the token representing the radix point in this parsing scheme to the given String token.
protected void	setRightParenthesisToken(String token) Sets the token representing the end of an argument list in this parsing scheme to the given String token.
String[]	simpleFunctionNames() Returns an array of the function names that correspond to functions whose class is or extends SimpleFunction.
SimpleFunction[]	simpleFunctions() Returns an array of the simple functions, that is, functions whose class is or extends SimpleFunction.
String	simpleFunctionsToString() Returns a String representation of all Simple Function objects currently installed in this parser.
protected void	skipWhitespace() Skips over whitespace characters starting at the current parse position, until a non-whitespace character or the end of the data String is found.
protected void	specialPush(String d) Save the current parser context and prepare to parse the string d using the current "let" variable context.
protected boolean	startsIdentifier() Returns true if the next non-whitespace character starts an identifier.
protected boolean	startsNumber() Returns true if the next non-whitespace character starts a number.
void	stringToSimpleFunctions(String string) Treats the given String as a representation for a list of SimpleFunction objects, builds those objects, and installs them in this parser.
protected void	throwAgainAndPop(String message, String d) Throws a ParseException with information about the string d being parsed and the parser position appended to the given exception message.
protected boolean	withinIdentifier() Returns true if the next character is within an identifier.

Methods inherited from class java.lang.Object

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

Field Detail

IDENTITY

public static final Operation IDENTITY

The IDENTITY operation, equivalent to the function f(x,y)=y.

This operation is inserted with the lowest level of precedence and is used as the base for evaluation of an expression.

This object is identical to Operation.IDENTITY.

OPERATION_PREFIX

public static final Operation OPERATION_PREFIX

The singleton operation object which designates that a symbol is a prefix for a known operation.

This operation operates as a return flag and may not be inserted into the precedence structure of this class.

This object is identical to Operation.OPERATION_PREFIX.

INTEGRAL

protected static final int INTEGRAL

Value designating string data that has form of an integer number.

See Also:

Constant Field Values

FLOATING

protected static final int FLOATING

Value designating string data that has form of a floating number.

See Also:

Constant Field Values

NESTED_EXPRESSION_START

protected String NESTED_EXPRESSION_START

String token representing the start of a nested expression.

NESTED_EXPRESSION_END

protected String NESTED_EXPRESSION_END

String token representing the end of a nested expression.

ARGUMENT_LIST_START

protected String ARGUMENT_LIST_START

String token representing the start of an argument list.

ARGUMENT_LIST_END

protected String ARGUMENT_LIST_END

String token representing the end of an argument list.

RADIX_POINT

protected String RADIX_POINT

String token representing the radix point.

ARGUMENT_SEPARATOR

protected String ARGUMENT_SEPARATOR

String token representing the argument separator.

UNDERSCORE

protected char UNDERSCORE

Char with UNDERSCORE character for identifiers.

ASSIGNMENT_BY_SET

protected final String ASSIGNMENT_BY_SET

The reserved keyword "set" to indicate variable assignment that is persistent across invocations of the parse method.

See Also:

Constant Field Values

ASSIGNMENT_BY_LET

protected final String ASSIGNMENT_BY_LET

The reserved keyword "let" to indicate variable assignment that is temporary, that is, one that affects only the current invocation of the parse method.

See Also:

Constant Field Values

IF_THEN_ELSE

protected final String IF_THEN_ELSE

The reserved keyword "if" to indicate if-then-else.

See Also:

Constant Field Values

EVAL

protected final String EVAL

The reserved keyword "eval" to indicate the special function that evaluates its arguments from left to right and then returns the value of the rightmost argument.

See Also:

Constant Field Values

RANDOM

protected final String RANDOM

The reserved keyword "random" to indicate the special function that takes 0, 1, or 2 numeric arguments and has the following interpretation.

Function Name	Typical Usage	Interpretation
random	random()	Random number between 0 and 1
random	random(x)	Random number between 0 and x
random	random(x,y)	Random number between x and y

See Also:

Constant Field Values

reserved

private Hashtable reserved

Table of reserved identifiers for special functions or operations.

constants

private Hashtable constants

Table of constant identifiers and their corresponding values.

set_variables

private Hashtable set_variables

Table of variable identifiers defined by "set" and their corresponding values.

let_variables

private Hashtable let_variables

Table of variable identifiers defined by "let" in the current invocation of the parse method and their corresponding values.

functions

private Hashtable functions

Table of function names and their corresponding functions.

operations

private Hashtable operations

Table of operation symbols and their corresponding operations.

prefixes

private Hashtable prefixes

Table of prefixes of operation symbols.

precedence

private Vector precedence

List of hashtables storing the precedence relationship between operations. Operations with the same precedence are placed in the same hashtable. The list is ordered from lowest precedence to highest.

parserContextStack

private Vector parserContextStack

The vector that operates as a stack to save and restore the parser context in each call of parse.

data

protected String data

The current String to be evaluated by the current call of parse.

next

protected int next

The index of the next character to examine in the current String to be evaluated by the current call of parse.

suspend

protected int suspend

The member data to control whether the parser should be evaluating operations, functions, and special functions or should rather be parsing formally in order to extract the next expression that is to be parsed as a string.

The default value is 0.

A value of 0 or negative signals that the parser should proceed to evaluate.

A positive value signals that the parser should suspend evaluation and parse formally.

Normally, methods that wish to suspend evaluation should increment suspend on entry and decrement suspend prior to exit. This protocol will make it easy for such methods to be recursive and to interact well with similar methods.

Constructor Detail

BaseParser

public BaseParser()

Constructs a new parser by initializing structures and by adding the standard operations, functions, and constants available for this parser.

Calls the following 5 methods in turn:

• initializeStructures()
• addReserved()
• addConstants()
• addFunctions()
• addOperations()

Normally the last 3 methods should be overridden in a derived class.

Method Detail

parse

public final Object parse(String d)
                   throws ParseException

Parses the given string d and returns the Object it represents, given this parsing scheme.

This implementation proceeds as follows.

Checks that the data is not null.

To enable recursive calls of this method, pushes the current parsing context on a stack.

Calls the recursive method parseExpression together with a default ObjectOperationPair to initiate the parsing operation on this data.

Checks for errors:

Requires the value returned by the call to parseExpression to be non-null.

Requires that the parse operation consumed all of the characters in the data.

Restores the original parsing context.

Returns the value returned by the call to parseExpression.

Implementation note: This method simply calls parseWithArgumentList with the last 2 parameters null.

Specified by:

parse in interface Parser

Parameters:

d - the String to be parsed

Throws:

ParseException - if the data is malformed

parseWithArgumentList

public final Object parseWithArgumentList(String d,
                                          String[] ids,
                                          Object[] values)
                                   throws ParseException

Parses the given string d in the context of a symbolic argument list and associated values and returns the Object represented by the string d given this parsing scheme.

This implementation proceeds as follows.

To enable recursive calls of this method, pushes the current parsing context on a stack.

Checks that the data is not null.

Assigns the values to corresponding ids. Will ignore the lists ids and values if both lists are null.

Calls the recursive method parseExpression together with a default ObjectOperationPair to initiate the parsing operation on this data.

Checks for errors.

Requires the value returned by the call to parseExpression to be non-null.

Requires that the parse operation consumed all of the characters in the data.

Restores the original parsing context.

Returns the value returned by the call to parseExpression.

Parameters:

d - the string data to be parsed

ids - the argument list ids

values - the argument list values

Throws:

ParseException - if the data is malformed

call

public final double call(String name,
                         double[] arguments)
                  throws ParseException

Call the function with the given name that is installed in this parser using the given double data as arguments and return a double value.

The function should in effect expect doubles as arguments and should return a number.

The length of the arguments array must equal the number of arguments expected by the function.

Throws ParseException if an error occurs.

Parameters:

name - the name of the function installed in this parser

arguments - the arguments given as an array of double

Throws:

ParseException

call

public final double call(String name,
                         double x)
                  throws ParseException

Call the function with the given name that is installed in this parser using the given double x as the argument and return a double value.

The function should in effect expect 1 double as an argument and should return a number.

Throws ParseException if an error occurs.

Parameters:

name - the name of the function of 1 argument installed in this parser

x - argument 1

Throws:

ParseException

call

public final double call(String name,
                         double x,
                         double y)
                  throws ParseException

Call the function with the given name that is installed in this parser using the given doubles x,y as arguments and return a double value.

The function should in effect expect 2 doubles as an arguments and should return a number.

Throws ParseException if an error occurs.

Parameters:

name - the name of the function of 2 arguments installed in this parser

x - argument 1

y - argument 2

Throws:

ParseException

call

public final double call(String name,
                         double x,
                         double y,
                         double z)
                  throws ParseException

Call the function with the given name that is installed in this parser using the given doubles x,y,z as arguments and return a double value.

The function should in effect expect 3 doubles as an arguments and should return a number.

Throws ParseException if an error occurs.

Parameters:

name - the name of the function of 3 arguments installed in this parser

x - argument 1

y - argument 2

z - argument 3

Throws:

ParseException

call

public final double call(String name,
                         double x,
                         double y,
                         double z,
                         double w)
                  throws ParseException

Call the function with the given name that is installed in this parser using the given doubles x,y,z,w as arguments and return a double value.

The function should in effect expect 4 doubles as an arguments and should return a number.

Throws ParseException if an error occurs.

Parameters:

name - the name of the function of 4 arguments installed in this parser

x - argument 1

y - argument 2

z - argument 3

w - argument 4

Throws:

ParseException

makeTable

public final XPoint2D[][] makeTable(String names,
                                    double endpointA,
                                    double endpointB,
                                    int divisions)
                             throws ParseException

Views the given String as a comma separated list of names of AbstractFunction objects installed in this parser; for each such function object f, makes an XPoint2D array of pairs (x,f(x)) where x is sampled on the given interval divided into the given number of divisions; all such arrays are collected and returned in a 2-dimensional array.

If names is null, returns null.

Otherwise, assume that the string names contains N function names for some N>=0.

If divisions is less than 1, it will be set to 1.

The 2 dimensions of the output array will be N by (divisions+1).

Throws ParseException if an error occurs.

See also the makeTable methods in DataTables2D.

Parameters:

names - a comma separated list of names of functions installed in this parser

endpointA - an endpoint of the interval

endpointB - an endpoint of the interval

divisions - the number of subdivisions of the interval

Returns:

the 2-dimensional array of (x,f(x)) pairs

Throws:

ParseException

makeTable

public final XPoint2D[][] makeTable(String names,
                                    XInterval limits,
                                    int divisions)
                             throws ParseException

Views the given String as a comma separated list of names of AbstractFunction objects installed in this parser; for each such function object f, makes an XPoint2D array of pairs (x,f(x)) where x is sampled on the given interval divided into the given number of divisions; all such arrays are collected and returned in a 2-dimensional array.

If names is null or limits is null, returns null.

Otherwise, assume that the string names contains N function names for some N>=0.

If divisions is less than 1, it will be set to 1.

The 2 dimensions of the output array will be N by (divisions+1).

Throws ParseException if an error occurs.

See also the makeTable methods in DataTables2D.

Parameters:

names - a comma separated list of names of functions installed in this parser

limits - the interval

divisions - the number of subdivisions of the interval

Returns:

the 2-dimensional array of (x,f(x)) pairs

Throws:

ParseException

call

public static double call(AbstractFunction f,
                          double[] arguments)
                   throws ParseException

Call the given abstract function using the given double data as arguments and return a double value.

The function should in effect expect doubles as arguments and should return a number.

The length of the arguments array must equal the number of arguments expected by the function.

Throws ParseException if an error occurs.

Parameters:

f - the abstract function

arguments - the arguments given as an array of double

Throws:

ParseException

call

public static double call(AbstractFunction f,
                          double x)
                   throws ParseException

Call the given abstract function using the given double x as the argument and return a double value.

The function should in effect expect 1 double as an argument and should return a number.

Throws ParseException if an error occurs.

Parameters:

f - the abstract function of 1 argument

x - argument 1

Throws:

ParseException

call

public static double call(AbstractFunction f,
                          double x,
                          double y)
                   throws ParseException

Call the given abstract function using the given doubles x,y as arguments and return a double value.

The function should in effect expect 2 doubles as an arguments and should return a number.

Throws ParseException if an error occurs.

Parameters:

f - the abstract function of 2 arguments

x - argument 1

y - argument 2

Throws:

ParseException

call

public static double call(AbstractFunction f,
                          double x,
                          double y,
                          double z)
                   throws ParseException

Call the given abstract function using the given doubles x,y,z as arguments and return a double value.

The function should in effect expect 3 doubles as an arguments and should return a number.

Throws ParseException if an error occurs.

Parameters:

f - the abstract function of 3 arguments

x - argument 1

y - argument 2

z - argument 3

Throws:

ParseException

call

public static double call(AbstractFunction f,
                          double x,
                          double y,
                          double z,
                          double w)
                   throws ParseException

Call the given abstract function using the given doubles x,y,z,w as arguments and return a double value.

The function should in effect expect 4 doubles as an arguments and should return a number.

Throws ParseException if an error occurs.

Parameters:

f - the abstract function of 4 arguments

x - argument 1

y - argument 2

z - argument 3

w - argument 4

Throws:

ParseException

makeTable

public static XPoint2D[] makeTable(AbstractFunction f,
                                   double endpointA,
                                   double endpointB,
                                   int divisions)
                            throws ParseException

Make an XPoint2D array of pairs (x,f(x)) where x is sampled on the given interval divided into the given number of divisions.

If the given function is null, returns null.

If divisions is less than 1, it will be set to 1. The size of the output array will be (divisions+1).

See also the makeTable methods in DataTables2D.

Parameters:

f - the function of one argument to evaluate

endpointA - an endpoint of the interval

endpointB - an endpoint of the interval

divisions - the number of subdivisions of the interval

Returns:

the array of (x,f(x)) pairs

Throws:

ParseException

makeTable

public static XPoint2D[] makeTable(AbstractFunction f,
                                   XInterval limits,
                                   int divisions)
                            throws ParseException

Make an XPoint2D array of pairs (x,f(x)) where x is sampled on the given interval divided into the given number of divisions.

If the given function is null or limits is null, returns null.

If divisions is less than 1, it will be set to 1. The size of the output array will be (divisions+1).

See also the makeTable methods in DataTables2D.

Parameters:

f - the function of one argument to evaluate

limits - the interval

divisions - the number of subdivisions of the interval

Returns:

the array of (x,f(x)) pairs

Throws:

ParseException

reserveID

public final void reserveID(String id)

Add this identifier to the table of reserved identifiers so it may not be used for a constant or variable id or a function name.

A reserved identifier is intended to be the identifier for a special function that may have an indefinite number of arguments and may not fully evaluate the arguments.

Reserving an identifier does not define the special function or implement the test that makes that behavior accessible to the parser. For examples of how to do this, see the source for this class and examine how the special functions set, let, if, eval, and random have been defined.

Throws IllegalArgumentException in the following cases:

• The id is not valid when tested by isPossibleIdentfier
• The id is already installed in the parser as a constant id or as a function name.

If a reserved id is introduced after the definition of the id as a variable id, then the variable will become inaccessible.

It is recommended that reserved id's be set before any other id's are introduced.

Parameters:

id - the id to set as reserved

addConstant

public final void addConstant(String id,
                              Object value)

Adds the given constant to the table of constants using the given identifier and value.

Does nothing if either argument is null.

A constant identifier once installed may not be removed or redefined.

Throws IllegalArgumentException in the following cases:

• The id is not valid when tested by isPossibleIdentfier
• The id is already installed in the parser as a reserved id, as a constant id, or as a function name.

If a constant id is introduced after the definition of the id as a variable id, then the variable will become inaccessible.

It is recommended that constant id's be set before variable id's are introduced.

Parameters:

id - the identifier for the constant

value - the value for the constant

Throws:

IllegalArgumentException

isPossibleVariableID

public final boolean isPossibleVariableID(String id)

Returns true if the given string is a possible variable id in the current parser context.

Specifically, returns true if:

• isPossibleIdentifier(id) is true
• the string is not installed as a reserved or constant id or as a function name in the current parser context

Parameters:

id - the string to test as a variable id

assignSetVariable

public final Object assignSetVariable(String id,
                                      Object value)

Assigns the given value to the given identifier as a persistant "set" variable for this parser, replacing any previous "set" variable associated with the same identifier.

Does nothing if id is null.

Assigns the variable if value is non-null and removes the variable otherwise.

Returns value.

Throws IllegalArgumentException if isPossibleVariableID(id) is false.

Parameters:

id - the identifier for the variable

value - the value of the variable

Throws:

IllegalArgumentException

assignLetVariable

public final Object assignLetVariable(String id,
                                      Object value)

Assigns the given value to the given identifier as a temporary "let" variable in the context of the current call to the parse method of this parser, replacing any previous "let" variable associated with the same identifier in this same context.

If there is no invocation of a parse method that is pending, this method call will be useless.

Does nothing if id is null.

Assigns the variable if value is non-null and removes the variable otherwise.

Returns value.

Throws IllegalArgumentException if isPossibleVariableID(id) is false.

Parameters:

id - the identifier for the variable

value - the value of the variable

Throws:

IllegalArgumentException

assignArgumentList

public void assignArgumentList(String[] ids,
                               Object[] values)

This method takes id-value pairs from corresponding positions in the lists ids and values and performs the assignment using assignLetVariable.

If there is no invocation of a parse method that is pending, this method call will be useless.

Does nothing if both lists are null.

Otherwise throws IllegalArgumentException in any of the following circumstances.

• One list is null and the other is not.
• The two lists do not have the same length.
• Some id in the list ids is null or fails to satisfy isPossibleVariableID.
• Some value in the list values is null.

Parameters:

ids - the list of identifiers to assign

values - the list of values to assign to the identifiers

Throws:

IllegalArgumentException

addFunction

public final void addFunction(AbstractFunction function)

Adds the given function to the table of recognized functions.

Does nothing if the function is null.

As of 2.5.0, permits the replacement of an installed function by adding a new function whose name is the same as the older installed function. This allows experimentation with implementation.

Throws IllegalArgumentException in the following case:

• The function name is already installed as a reserved or constant id

If the function name is the same as the id of a previously defined variable, then the variable will become inaccessible.

A function may be removed based on its name using removeFunction.

Parameters:

function - the function to be added

Throws:

IllegalArgumentException

removeFunction

public final AbstractFunction removeFunction(String name)

Removes the function with the given name from this parser.

Returns the removed AbstractFunction or null if no such function was found.

Parameters:

name - the function name

addOperationAtPrecedenceOf

public final Operation addOperationAtPrecedenceOf(Operation compare,
                                                  Operation op)

Adds the given operation op to the table of recognized operations, at the same level of precedence as the existing operation compare installed in this parser.

The operation IDENTITY is initially installed in the parser at precedence level 0 and may be used as the base for adding additional operators.

Throws IllegalArgumentException if the operation compare is not an existing operation for this parser.

As of 2.5.0, permits the replacement of an installed operation by an operation with the same symbol.

This method will work correctly if the compare operation has the same symbol as the operation op. The precedence of the compare operation will be determined and then the compare operation will be replaced by the operation op.

Parameters:

compare - an existing operation at the desired level of precedence

op - the operation to be added

Returns:

the operation object op that was added to the operation table

Throws:

IllegalArgumentException

addOperationBeforePrecedenceOf

public final Operation addOperationBeforePrecedenceOf(Operation compare,
                                                      Operation op)

Adds the given operation op to the table of recognized operations, at a level of precedence immediately before the precendence of the existing operation compare installed in this parser.

A new precedence level is inserted between that of the compare operation and all lower precedence operations.

The operation IDENTITY is initially installed in the parser at precedence level 0 and may be used as the base for adding additional operators. However, you may NOT install an operation before the IDENTITY.

Throws IllegalArgumentException if:

• the operation compare is not an existing operation for this parser
• the operation compare is at precedence 0 since it is illegal to insert an operation at precedence -1

As of 2.5.0, permits the replacement of an installed operation by an operation with the same symbol.

This method will "work" if the compare operation has the same symbol as the operation op but it may not do what is desired. The problem is that it is likely that you want to keep the current precedence level and not insert a new level in this case. Therefore, it is recommended that you use the method addOperationAtPrecedenceOf to perform the replacement of an operator.

Parameters:

compare - an existing operation at the desired level of precedence

op - the operation to be added

Returns:

the operation object op that was added to the operation table

Throws:

IllegalArgumentException

addOperationAfterPrecedenceOf

public final Operation addOperationAfterPrecedenceOf(Operation compare,
                                                     Operation op)

Adds the given operation op to the table of recognized operations, at a level of precedence immediately after the precendence of the existing operation compare installed in this parser.

A new precedence level is inserted between that of the compare operation and all higher precedence operations.

The operation IDENTITY is initially installed in the parser at precedence level 0 and may be used as the base for adding additional operators.

Throws IllegalArgumentException if the operation compare is not an existing operation for this parser.

As of 2.5.0, permits the replacement of an installed operation by an operation with the same symbol.

This method will "work" if the compare operation has the same symbol as the operation op but it may not do what is desired. The problem is that it is likely that you want to keep the current precedence level and not insert a new level in this case. Therefore, it is recommended that you use the method addOperationAtPrecedenceOf to perform the replacement of an operator.

Parameters:

compare - an existing operation at the desired level of precedence

op - the operation to be added

Returns:

the operation object op that was added to the operation table

Throws:

IllegalArgumentException

isReservedID

public final boolean isReservedID(String id)

Returns whether or not the given id is associated with a constant.

Parameters:

id - the constant id

isConstantID

public final boolean isConstantID(String id)

Returns whether or not the given id is associated with a constant.

Parameters:

id - the constant id

isSetVariableID

public final boolean isSetVariableID(String id)

Returns whether or not the given id is associated with a "set" variable.

Parameters:

id - the variable id

isLetVariableID

public final boolean isLetVariableID(String id)

Returns whether or not the given id is associated with a "let" variable in the current invocation of the parse method.

Parameters:

id - the variable id

isEnvironmentID

public final boolean isEnvironmentID(String id)

Returns whether or not the given id is associated with a constant or variable.

Parameters:

id - the constant or variable id

isFunctionName

public final boolean isFunctionName(String name)

Returns whether or not the given name is associated with a function.

Parameters:

name - the function name

isSimpleFunctionName

public final boolean isSimpleFunctionName(String name)

Returns whether or not the given name is associated with a function whose class is or extends SimpleFunction.

Parameters:

name - the function name

isOrdinaryFunctionName

public final boolean isOrdinaryFunctionName(String name)

Returns whether or not the given name is associated with a function whose class does NOT extend SimpleFunction.

Parameters:

name - the function name

isOperationSymbol

public final boolean isOperationSymbol(String symbol)

Returns whether or not the given symbol is associated with an operation.

Parameters:

symbol - the operation symbol

getValue

public final Object getValue(String id)

Returns the value associated with a constant or variable with the given id or null if no such value is defined.

Looks for values in the following order:

• constant
• variable defined by "let"
• variable defined by "set"

Parameters:

id - the constant or variable id

getFunction

public final AbstractFunction getFunction(String name)

Returns the function with the given name or null if no such function is defined.

Parameters:

name - the function name

getOperation

public final Operation getOperation(String symbol)

Returns the operation with the given symbol or null if no such operation is defined.

Parameters:

symbol - the operation symbol

reserved

public final String[] reserved()

Returns an array of the reserved id's.

The id's are sorted alphabetically.

constants

public final String[] constants()

Returns an array of the constant id's.

The id's are sorted alphabetically.

set_variables

public final String[] set_variables()

Returns an array of the set variable id's.

The id's are sorted alphabetically.

functionNames

public final String[] functionNames()

Returns an array of all function names.

The names are sorted alphabetically.

simpleFunctionNames

public final String[] simpleFunctionNames()

Returns an array of the function names that correspond to functions whose class is or extends SimpleFunction.

The names are sorted alphabetically.

ordinaryFunctionNames

public final String[] ordinaryFunctionNames()

Returns an array of the function names that correspond to functions whose class does NOT extend SimpleFunction.

The names are sorted alphabetically.

functions

public final AbstractFunction[] functions()

Returns an array of all functions.

The functions are sorted by name.

simpleFunctions

public final SimpleFunction[] simpleFunctions()

Returns an array of the simple functions, that is, functions whose class is or extends SimpleFunction.

The functions are sorted by name.

ordinaryFunctions

public final AbstractFunction[] ordinaryFunctions()

Returns an array of the ordinary functions, that is, functions whose class does NOT extend SimpleFunction.

The functions are sorted by name.

operationSymbols

public final String[] operationSymbols()

Returns an array of the operation symbols.

operations

public final Operation[] operations()

Returns an array of the operations.

simpleFunctionsToString

public final String simpleFunctionsToString()

Returns a String representation of all Simple Function objects currently installed in this parser.

This representation is constructed as follows:

• The method simpleFunctions() is called to obtain all simple functions.
• For each simple function, its toString() method is called. This string is appended to a temporary StringBuffer object.
• The final contents of the buffer is then returned as the value of this method.

As a consequence, the string returned by this method will contain 3*N lines where N is the number of simple functions installed and the 3 lines for each function will consist of its function name, the comma separated list of its function parameters, and its function body.

If a function has 0 parameters, the line for its parameters will contain a blank to act as a placeholder for parsing purposes.

stringToSimpleFunctions

public void stringToSimpleFunctions(String string)

Treats the given String as a representation for a list of SimpleFunction objects, builds those objects, and installs them in this parser. Existing simple functions with the same name as one in the list will be replaced.

Expectations:

• The string has 3*N lines for some N.
• Each group of 3 lines should consist of a function name, a comma separated list of function parameters, and a function body.
• If a function has 0 parameters then the line corresponding to its parameters should contain one blank and therefore should NOT be empty.

Throws IllegalArgumentException if an error is detected. Those definitions that have been successful before the error was detected will stand.

Parameters:

string - the string representation of a list of simple functions

Throws:

IllegalArgumentException

isPossibleIdentifier

public static final boolean isPossibleIdentifier(String id)

Returns true if the given id is a possible identifier for a constant, variable, function or reserved function.

More precisely:

• the id must have length at least 1
• the first character must be a letter or underscore
• all subsequent characters must be letters, digits, or underscores

This method is static and does not consider the relation of this id to any identifiers installed in any particular parser.

Parameters:

id - the id to test

isPossibleOperation

public static final boolean isPossibleOperation(String string)

Returns true if the given string is a possible symbol for an operation.

More precisely, the following punctuation characters will be considered valid for an operation symbol:

    + - * / % = < > ! ? : @ # $ ^ & ' " ` ~ | \

A string that consists of one or more of these characters will be considered valid.

In addition, to support the built-in Operation objects IDENTITY and OPERATION_PREFIX, the strings "" and "\0" will be considered valid via an ad hoc check.

Parameters:

string - the string to test

addReserved

protected void addReserved()

Installs the reserved identifiers for the special functions.

This method may be overridden by a derived class if the derived class defines additional special functions. In that case, this method should be called first by the override method in order that the reserved identifiers defined by this parser are installed.

This method reserves:

• ASSIGNMENT_BY_SET
• ASSIGNMENT_BY_LET
• IF_THEN_ELSE
• EVAL
• RANDOM

addConstants

protected void addConstants()

Adds the standard constants for this parser to the environment.

This method must be overridden by a derived class if the derived class has constants defined in its environment.

This method does nothing at present.

addFunctions

protected void addFunctions()

Adds the standard functions for this parser to the function table.

This method must be overridden by a derived class if the derived class makes use of functions.

This method does nothing at present.

addOperations

protected void addOperations()

Adds the standard operations for this parser to the operation table.

This method must be overridden by a derived class if the derived class makes use of operations.

This method does nothing at present.

nextTerm

protected Object nextTerm()
                   throws ParseException

Returns the next term in the data string with all leading unary operations already applied or throws a ParseException if no term is present.

Throws:

ParseException

nextSimpleTerm

protected Object nextSimpleTerm()
                         throws ParseException

Returns the next simple term in the data string or throws a ParseException if no term is present.

A simple term is a term that is not preceded by unary operations that will need to be applied later. The work of collecting and applying unary operations is done in the method nextTerm().

This method orchestrates the dispatch to the methods that handle important special cases.

• Nested expresssions
• Numbers
• Expressions introduced by an identifier

Throws:

ParseException

nextUnaryOperations

protected Operation[] nextUnaryOperations()
                                   throws ParseException

Returns the array of unary operations that occur after the current position in the data string and throws a ParseException if an operation is encountered that is binary but not unary.

The array returned may be empty but will not be null.

Throws:

ParseException

parseIdentifierExpression

protected Object parseIdentifierExpression()
                                    throws ParseException

Parse an expression that is introduced by an identifier.

This includes in the following order:

• special function call
• function call
• constant value
• variable value

Throws:

ParseException

parseSpecialFunction

protected Object parseSpecialFunction(String identifier)
                               throws ParseException

Parse a special function whose parameter list may not be completely evaluated. The id's of such special functions should be installed as reserved id's.

Throws ParseException if:

• The identifier is not a reserved id
• The parse/evaluation does not run successfully

To add additional special functions this method must be suitably overridden in a derived class. To facilitate an override, this method returns null if the identifier is a reserved id but there is no code in this method to handle that id. A method that overrides this method should first call this method and should intervene only if this method returns null; otherwise the override method should simply return what this method has returned to it.

As a consequnce of this design, it is entirely valid for this method to return null. This is what permits a sequence of derived classes to add reserved identifiers and the parsing code for them. Of course, each derived class should follow the same design and provide parsing code for each new reserved word that it adds but return null if it encounters a reserved word that it does not know how to parse.

Note that if you build a derived class based on JPTParser then take care not to introduce a conflict with the function names and constant id's defined in that class.

Throws:

ParseException

pushContext

protected final void pushContext(String d)

Save the current parser context and initialize a new context to parse the string d.

This method sets the new string to parse to d, sets the start position to zero, and creates a new context for "let" variables.

Use popContext() to restore the previous context.

Parameters:

d - the string to parse

specialPush

protected final void specialPush(String d)

Save the current parser context and prepare to parse the string d using the current "let" variable context.

This method sets the new string to parse to d and sets the start position to zero but does not change the context for the "let" variables.

This method permits the parsing of d to be carried out in the context of its caller rather than in a new "let" variable context of its own.

This method is provided to support unusual situations and should be used with great care.

Use popContext() to restore the previous context.

Parameters:

d - the string to parse

popContext

protected final void popContext()

Pop and restore the previous parser context.

throwAgainAndPop

protected final void throwAgainAndPop(String message,
                                      String d)
                               throws ParseException

Throws a ParseException with information about the string d being parsed and the parser position appended to the given exception message.

Nothing is appended if d is null.

Restores the previous parser context just before the exception is thrown. This will enable the parser methods to recursively accumulate error information and report all information in a manner similar to a stack trace.

Parameters:

message - the current exception message

d - the parsed string at this level of recursion

Throws:

ParseException

parseExpression

protected final ObjectOperationPair parseExpression(ObjectOperationPair pending)
                                             throws ParseException

Recursive method that parses the next expression in the data string.

The given ObjectOperationPair object should represent a binary operation together with its left operand as the value component.

It is permitted for the left operand to be null if it is unused by the operation. This is in fact the case with the default pair whose operation is Operation.IDENTITY.

The given binary operation must NOT be null.

In this implementation, the following additional constraints are true.

As the parse proceeds, all valid unary operators will be collected and applied to a subsequent term.

As the parse proceeds, all binary operations at the same or higher precedence will be processed and the results will be accumulated in the value slot of the return pair.

The ObjectOperationPair pair returned will have the following characteristics.

Normally, the value component of pair will be non-null and will represent the final result of applying the various binary operations, functions, and special functions encountered along the way. However, if this method is called by the method extractExpression then the parser will suspend evaluation and so the return value within pair may be null.

The operation component of pair will either be null or be an operation of lower precedence than the incoming operation.

In particular, if the input pair has the default operation, Operation.IDENTITY, then the operation in the return pair must be null.

Parameters:

pending - the ObjectOperationPair object whose value is the left operand and whose operation is the operation immediately preceding the expression to be parsed

Returns:

the ObjectOperationPair object with the value of the parsed expression and the lower precedence operation that immediately follows it or the null operation

Throws:

ParseException - if the expression is malformed or if the incoming operation is null

Since:

2.2

parseExpression

protected final Object parseExpression()
                                throws ParseException

Returns the result of parsing the next expression in the data string.

Shorthand for:

    parseExpression(new ObjectOperationPair()).value()

Throws:

parseException

ParseException

extractExpression

protected final String extractExpression()
                                  throws ParseException

Extracts the next pending expression as a string without performing any operations or evaluations. The string will be stripped of leading and trailing white space.

The parser will be positioned at the end of the expression parsed.

Throws ParseException if parsing detects errors even when evaluation is turned off. In other words, the expression must be valid in a formal sense.

This method is supplied as a helper method for the definition of special functions that may not evaluate all of their arguments.

This method adheres to the protocol specified in the comments on the suspend member data, that is, it increments suspend on entry and decrements suspend on exit.

Throws:

ParseException

parseNestedExpression

protected final Object parseNestedExpression()
                                      throws ParseException

Parse an expression in parentheses, that is, a nested expression, and return its value.

Returns null if the next token in the data is NOT the start of a nested expression.

Throws:

ParseException

evaluateIdentifier

protected final Object evaluateIdentifier(String identifier)
                                   throws ParseException

Evaluate a constant or variable identifier and return its value.

If this method is called when the member method evaluate() returns false then this method will return null.

Throws:

ParseException

parseAssignment

protected final Object parseAssignment(Hashtable binding)
                                throws ParseException

Parse assignment, that is, "set" or "let".

The syntax for "set" is:

    set(identifier,expression)

The syntax for "let" is:

    let(identifier,expression)

A variable defined by "set" will be installed in this parser in a persistant way so it may be used over the course of many invocations of the parse method.

A variable defined by "let" will be installed in this parser for use in the current invocation of the parse method but will be unavailable in any other invocation including any recursive invocations. Thus, a "let" variable is effectively a local variable.

The method parseSpecialFunction calls this method and selects the appropriate hash table in which to store the binding information.

The identifier must be a valid identifier and must not overlap with a constant or reserved id or with a function name. In that case, the expression is evaluated, assigned to the identifier in the given binding, and also returned as the value of this method.

This method assumes that the "set" or "let keyword has already been extracted and that it is the () expression that must be parsed and evaluated.

Parameters:

binding - the binding used to store the id-value expression

Throws:

ParseException

assignVariable

protected final Object assignVariable(String id,
                                      Object value,
                                      Hashtable binding)

Assigns the given value to the given identifier in the given binding environment, replacing any previous value in the environment associated with the same identifier.

Does nothing if id is null or binding is null.

Assigns the variable if value is non-null and removes the variable otherwise.

Returns value.

Throws IllegalArgumentException if isPossibleVariableID(id) is false.

Parameters:

id - the identifier for the variable

value - the value of the variable

binding - the hash table to store the id-value binding

Throws:

IllegalArgumentException

parseFunctionCall

protected final Object parseFunctionCall(String identifier)
                                  throws ParseException

Parse a function with arguments and return its value.

Throws:

ParseException

parseIfThenElse

protected final Object parseIfThenElse()
                                throws ParseException

Parse if-then-else, that is, "if".

The syntax is:

    if(boolean,expression1,expression2)

If evaluation is on, this special function will first evaluate the boolean expression to obtain a true-false value. Evaluates either expression1 or expression2 but not both and returns the result. Returns expression1 if the boolean is true otherwise returns expression2.

If evaluation is off, then all three parts of this form will be extracted but not evaluated.

This method assumes that the "if" keyword has already been extracted and that it is the () expression that must be parsed and evaluated.

Throws:

ParseException

parseEval

protected final Object parseEval()
                          throws ParseException

Parse the "eval" operation.

The syntax is:

    eval(expression-1,...,expression-n)

If evaluation is on, this special function will evaluate each expression from left to right and then will return the value of the rightmost expression, that is, expression-n.

If evaluation is off, then the expressions will be extracted but not evaluated and the return value will be null.

This method assumes that the "eval" keyword has already been extracted and that it is the () expression that must be parsed and evaluated.

An important application of "eval" is to permit the definition of "let" variables which are then used in the final expression. A simple example of this is as follows.

    eval(let(a,3),let(b,5),let(c,2),b*b-4*a*c)

In this example, a, b, c are temporary variables used in the final expression b*b-4*a*c.

Throws:

ParseException

parseRandom

protected final Object parseRandom()
                            throws ParseException

The "random" function is a special function that takes 0, 1, or 2 numeric arguments and has the following interpretation.

Function Name	Typical Usage	Interpretation
random	random()	Random number between 0 and 1
random	random(x)	Random number between 0 and x
random	random(x,y)	Random number between x and y

Throws:

ParseException

evaluate

protected final boolean evaluate()

Controls whether or not the parser evaluates or simply parses formally without evaluation.

Returns true if the internal variable named suspend is zero or negative.

parseArgumentList

protected final Object[] parseArgumentList()
                                    throws ParseException

Parses the next argument list in the data String assuming that each argument is to be evaluated and returns an array of objects representing the list.

By default, an argument list:

• begins with an argument list start token
• is followed by a possibly zero-length list of expressions to be evaluated that are separated by argument separator tokens
• ends with an argument list end token.

Throws:

ParseException - if the argument list is malformed

parseIdentifierExpressionList

protected final Object[] parseIdentifierExpressionList()
                                                throws ParseException

Parses the next argument list that consists of an identifier that is to be returned literally and a value expression to be evaluated.

If the argument list ends are parentheses and the argument list separator is a comma then the argument list should look like:

    (identifier,expression)

The method returns a 2-element array with the identifier and the evaluated expression.

Throws ParseException if the next position in the data does not contain a list with the required properties.

Throws:

ParseException

initializeStructures

protected final void initializeStructures()

Initialize the operation and precedence structures prior to any additions defined in derived classes by adding the IDENTITY operation at precedence 0.

addOperation

protected final void addOperation(Operation op,
                                  int pos)

Adds the given operation to the operation table at the given index in the precedence list.

If an operation with the same symbol is already in the operation table, that operation is removed from both the operation table and the precedence list before the insertion. This is a change in policy introduced in 2.5.0 to permit users to make changes to a given parser more easily.

Does nothing if the given operation is null.

Does nothing if pos is negative or is beyond the last valid index in the precedence list.

Does nothing if the symbol for this operation is "" or "\0" to prevent user defined operators from overriding IDENTITY or OPERATION_PREFIX.

Note that IDENTITY is installed directly in the constructor and that OPERATION_PREFIX is a flag object that is never installed.

Parameters:

op - an operation to be added

pos - the position in the precedence list

precedenceOf

protected final int precedenceOf(Operation op)

Returns the index in the precedence list corresponding to the precedence of the given operation, or -1 if the given operation is null or is not in the precedence list.

Parameters:

op - the operation whose precedence is needed

isOperationOrPrefix

protected final Operation isOperationOrPrefix(String symbol)

Performs a lookup in the operation and prefix tables to determine if the given String symbol represents an existing operation or is a prefix of the symbol for an existing operation.

The return value OPERATION_PREFIX acts as a flag to signal that the symbol is a prefix but is not an operation.

Parameters:

symbol - the symbol to look up in the operation table

Returns:

the Operation object if it is represented by the given symbol, or the flag OPERATION_PREFIX if the symbol is a prefix, or null if the symbol is neither an operation nor a prefix

nextOperation

protected final Operation nextOperation()

If the next token in the data represents an operation then return the corresponding Operation otherwise return null.

nextTokenIs

protected final boolean nextTokenIs(String pattern)

Returns true if the given String exactly matches the next non-whitespace characters in the data, or false if it does not.

nextTokenIs

protected final boolean nextTokenIs(String pattern,
                                    int start)

Returns true if the given String exactly matches the characters in the data starting at the given index, or false if it does not.

nextIdentifier

protected final String nextIdentifier()

Gets the next identifier in the data String and returns it.

Returns "" if the next non-whitespace entity in the data String does not begin with the start of an identifier.

startsIdentifier

protected final boolean startsIdentifier()

Returns true if the next non-whitespace character starts an identifier.

By convention, this means the character is a letter or an underscore.

withinIdentifier

protected final boolean withinIdentifier()

Returns true if the next character is within an identifier.

By convention, this means the character is a letter or a digit or an underscore.

parseNumber

protected final Object parseNumber()
                            throws ParseException

Parses the next numeric token in the data String and returns an object representation of its value.

By default, a number is either of the form s(d*), where s is an optional sign in {+-} and each d is in {0 .. 9} or of the form s(d*).(d*)etx where s is an optional sign in {+-}, each d is in {0 .. 9}, . is the radix point token, E is a character in {Ee}, t is an optional sign in {+-}, and x is one to three characters in {0 .. 9}.

Integral values are represented by XBigInteger objects and floating point values are represented by XDouble objects.

Throws:

ParseException - if the number is malformed

startsNumber

protected final boolean startsNumber()

Returns true if the next non-whitespace character starts a number.

Although parseNumber can deal with leading signs, this method tests whether the next non-whitespace character is a digit or the RADIX_POINT. Therefore, if this method is called, it is assumed that any leading signs have been collected prior to reaching this point in the data and will be handled once the rest of the number is parsed.

isSignAt

protected final boolean isSignAt(int start)

Return true if the character at start is '+' or '-'.

isExponentAt

protected final boolean isExponentAt(int start)

Return true if the character at start is 'E' or 'e'.

afterSign

protected final int afterSign(int start)

If the character at position start is '+' or '-' return (start + 1) otherwise return start.

afterDigits

protected final int afterDigits(int start)

Return the first character position at or after start that is not a digit.

skipWhitespace

protected final void skipWhitespace()

Skips over whitespace characters starting at the current parse position, until a non-whitespace character or the end of the data String is found.

By default, whitespace is defined as a character considered to be whitespace by the Java Character class.

setLeftParenthesisToken

protected final void setLeftParenthesisToken(String token)

Sets the token representing the start of an argument list in this parsing scheme to the given String token.

Parameters:

token - the desired String token

setRightParenthesisToken

protected final void setRightParenthesisToken(String token)

Sets the token representing the end of an argument list in this parsing scheme to the given String token.

Parameters:

token - a String token

setRadixPointToken

protected final void setRadixPointToken(String token)

Sets the token representing the radix point in this parsing scheme to the given String token.

Parameters:

token - a String token

setArgumentSeparatorToken

protected final void setArgumentSeparatorToken(String token)

Sets the token representing the argument separator in this parsing scheme to the given String token.

Parameters:

token - a String token