org.nfunk.jep
Class JEP

java.lang.Object
  |
  +--org.nfunk.jep.JEP

public class JEP

extends java.lang.Object

The JEP class is the main interface with which the user should interact. It contains all neccessary methods to parse and evaluate expressions.

The most important methods are parseExpression(String), for parsing the mathematical expression, and getValue() for obtaining the value of the expression.

Visit http://jep.sourceforge.net/ for the newest version of JEP, and complete documentation.

Author:

Nathan Funk

Field Summary

protected boolean	allowUndeclared Allow undeclared variables option
protected java.util.Vector	errorList Error List
protected FunctionTable	funTab Function Table
protected boolean	implicitMul Implicit multiplication option
protected SymbolTable	symTab Symbol Table

Constructor Summary

JEP()
Creates a new JEP instance with the default settings.

JEP(boolean traverse_in, boolean allowUndeclared_in, boolean implicitMul_in, NumberFactory numberFactory_in)
Creates a new JEP instance with custom settings.

Method Summary

void	addComplex() Call this function if you want to parse expressions which involve complex numbers.
Complex	addComplexVariable(java.lang.String name, double re, double im) Adds a new complex variable to the parser, or updates the value of an existing variable.
void	addFunction(java.lang.String functionName, PostfixMathCommandI function) Adds a new function to the parser.
void	addStandardConstants() Adds the constants pi and e to the parser.
void	addStandardFunctions() Adds the standard functions to the parser.
java.lang.Double	addVariable(java.lang.String name, double value) Adds a new variable to the parser, or updates the value of an existing variable.
void	addVariableAsObject(java.lang.String name, java.lang.Object object) Adds a new variable to the parser as an object, or updates the value of an existing variable.
Complex	getComplexValue() Evaluates and returns the value of the expression as a complex number.
java.lang.String	getErrorInfo() Reports information on the errors that occured during the most recent action.
NumberFactory	getNumberFactory() Returns the number factory.
SymbolTable	getSymbolTable() Returns the symbol table (the list of all variables that the parser recognises).
Node	getTopNode() Returns the top node of the expression tree.
double	getValue() Evaluates and returns the value of the expression.
java.lang.Object	getValueAsObject() Evaluates and returns the value of the expression as an object.
boolean	hasError() Returns true if an error occured during the most recent action (parsing or evaluation).
void	initFunTab() Creates a new FunctionTable object as funTab.
void	initSymTab() Creates a new SymbolTable object as symTab.
void	parseExpression(java.lang.String expression_in) Parses the expression.
java.lang.Object	removeFunction(java.lang.String name) Removes a function from the parser.
java.lang.Object	removeVariable(java.lang.String name) Removes a variable from the parser.
void	setAllowUndeclared(boolean value) Sets the value for the undeclared variables option.
void	setImplicitMul(boolean value) Sets the value of the implicit multiplication option.
void	setTraverse(boolean value) Sets the value of the traverse option.

Methods inherited from class java.lang.Object

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

Field Detail

allowUndeclared

protected boolean allowUndeclared

Allow undeclared variables option

implicitMul

protected boolean implicitMul

Implicit multiplication option

symTab

protected SymbolTable symTab

Symbol Table

funTab

protected FunctionTable funTab

Function Table

errorList

protected java.util.Vector errorList

Error List

Constructor Detail

JEP

public JEP()

Creates a new JEP instance with the default settings.

Traverse = false
Allow undeclared variables = false
Implicit multiplication = false
Number Factory = DoubleNumberFactory

JEP

public JEP(boolean traverse_in,
           boolean allowUndeclared_in,
           boolean implicitMul_in,
           NumberFactory numberFactory_in)

Creates a new JEP instance with custom settings. If the numberFactory_in is null, the default number factory is used.

Parameters:

traverse_in - The traverse option.

allowUndeclared_in - The "allow undeclared variables" option.

implicitMul_in - The implicit multiplication option.

numberFactory_in - The number factory to be used.

Method Detail

initSymTab

public void initSymTab()

Creates a new SymbolTable object as symTab.

initFunTab

public void initFunTab()

Creates a new FunctionTable object as funTab.

addStandardFunctions

public void addStandardFunctions()

Adds the standard functions to the parser. If this function is not called before parsing an expression, functions such as sin() or cos() would produce an "Unrecognized function..." error. In most cases, this method should be called immediately after the JEP object is created.

addStandardConstants

public void addStandardConstants()

Adds the constants pi and e to the parser. As addStandardFunctions(), this method should be called immediatly after the JEP object is created.

addComplex

public void addComplex()

Call this function if you want to parse expressions which involve complex numbers. This method specifies "i" as the imaginary unit (0,1). Two functions re() and im() are also added for extracting the real or imaginary components of a complex number respectively.

addFunction

public void addFunction(java.lang.String functionName,
                        PostfixMathCommandI function)

Adds a new function to the parser. This must be done before parsing an expression so the parser is aware that the new function may be contained in the expression.

Parameters:

functionName - The name of the function

function - The function object that is used for evaluating the function

addVariable

public java.lang.Double addVariable(java.lang.String name,
                                    double value)

Adds a new variable to the parser, or updates the value of an existing variable. This must be done before parsing an expression so the parser is aware that the new variable may be contained in the expression.

Parameters:

name - Name of the variable to be added

value - Initial value or new value for the variable

Returns:

Double object of the variable

addComplexVariable

public Complex addComplexVariable(java.lang.String name,
                                  double re,
                                  double im)

Adds a new complex variable to the parser, or updates the value of an existing variable. This must be done before parsing an expression so the parser is aware that the new variable may be contained in the expression.

Parameters:

name - Name of the variable to be added

re - Initial real value or new real value for the variable

Returns:

Complex object of the variable

addVariableAsObject

public void addVariableAsObject(java.lang.String name,
                                java.lang.Object object)

Adds a new variable to the parser as an object, or updates the value of an existing variable. This must be done before parsing an expression so the parser is aware that the new variable may be contained in the expression.

Parameters:

name - Name of the variable to be added

object - Initial value or new value for the variable

removeVariable

public java.lang.Object removeVariable(java.lang.String name)

Removes a variable from the parser. For example after calling addStandardConstants(), removeVariable("e") might be called to remove the euler constant from the set of variables.

Returns:

The value of the variable if it was added earlier. If the variable is not in the table of variables, null is returned.

removeFunction

public java.lang.Object removeFunction(java.lang.String name)

Removes a function from the parser.

Returns:

If the function was added earlier, the function class instance is returned. If the function was not present, null is returned.

setTraverse

public void setTraverse(boolean value)

Sets the value of the traverse option. setTraverse is useful for debugging purposes. When traverse is set to true, the parse-tree will be dumped to the standard ouput device.

The default value is false.

Parameters:

value - The boolean traversal option.

setImplicitMul

public void setImplicitMul(boolean value)

Sets the value of the implicit multiplication option. If this option is set to true before parsing, implicit multiplication will be allowed. That means that an expression such as

"1 2"

is valid and is interpreted as

"1*2"

.

The default value is false.

Parameters:

value - The boolean implicit multiplication option.

setAllowUndeclared

public void setAllowUndeclared(boolean value)

Sets the value for the undeclared variables option. If this option is set to true, expressions containing variables that were not previously added to JEP will not produce an "Unrecognized Symbol" error. The new variables will automatically be added while parsing, and initialized to 0.

If this option is set to false, variables that were not previously added to JEP will produce an error while parsing.

The default value is false.

Parameters:

value - The boolean option for allowing undeclared variables.

parseExpression

public void parseExpression(java.lang.String expression_in)

Parses the expression. If there are errors in the expression, they are added to the errorList member.

Parameters:

expression_in - The input expression string

getValue

public double getValue()

Evaluates and returns the value of the expression. If the value is complex, the real component of the complex number is returned. To get the complex value, use getComplexValue().

Returns:

The calculated value of the expression. If the value is complex, the real component is returned. If an error occurs during evaluation, 0 is returned.

getComplexValue

public Complex getComplexValue()

Evaluates and returns the value of the expression as a complex number.

Returns:

The calculated value of the expression as a complex number if no errors occur. Returns null otherwise.

getValueAsObject

public java.lang.Object getValueAsObject()

Evaluates and returns the value of the expression as an object. The EvaluatorVisitor member ev is used to do the evaluation procedure. This method is useful when the type of the value is unknown, or not important.

Returns:

The calculated value of the expression if no errors occur. Returns null otherwise.

hasError

public boolean hasError()

Returns true if an error occured during the most recent action (parsing or evaluation).

Returns:

Returns true if an error occured during the most recent action (parsing or evaluation).

getErrorInfo

public java.lang.String getErrorInfo()

Reports information on the errors that occured during the most recent action.

Returns:

A string containing information on the errors, each separated by a newline character; null if no error has occured

getTopNode

public Node getTopNode()

Returns the top node of the expression tree. Because all nodes are pointed to either directly or indirectly, the entire expression tree can be accessed through this node. It may be used to manipulate the expression, and subsequently evaluate it manually.

Returns:

The top node of the expression tree

getSymbolTable

public SymbolTable getSymbolTable()

Returns the symbol table (the list of all variables that the parser recognises).

Returns:

The symbol table

getNumberFactory

public NumberFactory getNumberFactory()

Returns the number factory.