edu.neu.ccs.parser
Class BaseParser

java.lang.Object
  extended byedu.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:

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.

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:

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:

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:

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:

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.

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:

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:

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:

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:

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:

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:

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:


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.

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:

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:

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:

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