com.singularsys.jep
Class Jep

java.lang.Object
  extended by com.singularsys.jep.Jep
All Implemented Interfaces:
java.io.Serializable

public class Jep
extends java.lang.Object
implements java.io.Serializable

The Jep class is the main interface with which the user should interact. It contains all necessary methods to parse and evaluate expressions. To evaluate an expression, simply call the parse(String) and evaluate methods after each other. The following code snippet shows a parsing and evaluating a simple expression with a single variable:

Jep jep = new Jep();
 try {
      jep.addVariable("x", 10);
        jep.parse("x+1");
        Object result = jep.evaluate();
        System.out.println("x + 1 = " + result);
 } catch (JepException e) {
        System.out.println("An error occurred: " + e.getMessage());
 }
 

The class is serializable. Please see the documentation section "Serialization" for more information on the various options for serializing.

See Also:
Serialized Form

Field Summary
protected  java.util.List<JepComponent> additionalComponents
          Additional components out side the standard set
protected  boolean allowAssignment
          Allow Assignment option
protected  boolean allowUndeclared
          Allow Undeclared Variables option
protected  Evaluator evaluator
          Evaluator instance used for evaluating parse trees
protected  FunctionTable funTab
          Function Table
protected  boolean implicitMul
          Implicit Multiplication option
protected  Node lastRootNode
          Root node of the last parsed expression
protected  NodeFactory nodeFac
          Node Factory
protected  NumberFactory numFac
          Number Factory
protected  OperatorTableI opTab
          Operator Table
protected  Parser parser
          Parser instance used for parsing expressions
protected  PrintVisitor pv
          PrintVisitor
protected  VariableFactory varFac
          Variable Factory
protected  VariableTable varTab
          Variable Table
 
Constructor Summary
Jep()
          Creates a new Jep instance using the standard components with default settings.
Jep(ComponentSet compSet)
          Creates a new Jep instance with a specific component set.
Jep(JepComponent... components)
          Creates a new Jep instance with a set of components.
 
Method Summary
 Variable addConstant(java.lang.String name, java.lang.Object value)
          Add a constant: a variable who's value cannot be changed.
protected  void addDefaultComponents()
          Set the default values for components if none are specified.
 PostfixMathCommandI addFunction(java.lang.String name, PostfixMathCommandI pfmc)
          Adds a function to the parser.
 boolean addStandardConstants()
          Adds the constants pi and e to the parser.
 Variable addVariable(java.lang.String name)
          Adds a variable with a given name.
 Variable addVariable(java.lang.String name, double value)
          Adds or sets a double variable with a given name and value.
 Variable addVariable(java.lang.String name, double re, double im)
          Adds or sets a complex variable with a given name and value.
 Variable addVariable(java.lang.String name, java.lang.Object value)
          Adds or sets a variable with a given name and value.
 Node continueParsing()
          Continue parsing without re-initialising the stream.
 java.lang.Object evaluate()
          Evaluates the most recently parsed expression.
 java.lang.Object evaluate(Node node)
          Evaluates the expression tree pointed to by the node parameter.
 double evaluateD()
          Evaluates the most recently parsed expression and returns the result as a double.
 JepComponent getAdditionalComponent(java.lang.Class<?> cl)
          Return an additional component which is an instance of a particular class.
 java.util.List<JepComponent> getAdditionalComponents()
          Returns the additional components.
 boolean getAllowAssignment()
          Whether assignment equation y=x+1 equations are allowed.
 boolean getAllowUndeclared()
          Returns the value of the allowUndeclared option.
 java.lang.Object getDefaultValue()
          Returns the default value used for new variables.
 Evaluator getEvaluator()
          Returns the evaluator
 FunctionTable getFunctionTable()
          Returns the function table
 boolean getImplicitMul()
          Returns the value of the implicit multiplication option.
 Node getLastRootNode()
          Returns the root node of the last successfully parsed expression
 NodeFactory getNodeFactory()
          Returns the node factory
 NumberFactory getNumberFactory()
          Returns the number factory
 OperatorTableI getOperatorTable()
          Returns the operator table
 Parser getParser()
          Returns the parser
 PrintVisitor getPrintVisitor()
          Returns the print visitor
 Variable getVariable(java.lang.String name)
          Returns the Variable instance of the variable name.
 VariableFactory getVariableFactory()
          Returns the variable factory
 VariableTable getVariableTable()
          Returns the variable table
 java.lang.Object getVariableValue(java.lang.String name)
          Returns the value of the variable name.
 void initMultiParse(java.io.Reader reader)
          Initialises the parser with a Reader for parsing with multiple expressions.
 void initMultiParse(java.lang.String str)
          Initialises the parser for parsing a string with multiple expressions.
 Node parse(java.io.Reader reader)
          Parses the input from a Reader.
 Node parse(java.lang.String str)
          Parses a string.
 void print()
          Print the last parsed expression to System.out.
 void print(Node node)
          Print an expression to System.out.
 void print(Node node, java.io.PrintStream out)
          Print an expression to a given stream.
 void println()
          Print the last parsed expression to System.out with a new line.
 void println(Node node)
          Print an expression to System.out with a new line.
 void println(Node node, java.io.PrintStream out)
          Print an expression to a given stream with a newline.
 void reinitializeComponents()
          Calls the init method of all components.
 java.lang.String rootNodeToString()
          Returns a string representation of the last expression parsed.
 void setAllowAssignment(boolean value)
          Sets whether assignment equations like y=x+1 are allowed.
 void setAllowUndeclared(boolean value)
          Sets the value for the undeclared variables option.
 void setComponent(JepComponent component)
          Sets a single component.
protected  void setComponentInternal(JepComponent comp)
          Identifies the type of comp and set the associated member accordingly.
 void setComponents(JepComponent... components)
          Sets one or more components for this Jep instance.
protected  void setComponentsInternal(ComponentSet compSet)
           
 void setDefaultValue(java.lang.Object defaultValue)
          Sets the default value used for new variables.
 void setImplicitMul(boolean value)
          Sets the value of the implicit multiplication option.
 java.lang.String toString(Node node)
          Returns a string representation of an expression.
 boolean tryAddConstant(java.lang.String name, java.lang.Object value)
          Tries to add a constant.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

numFac

protected NumberFactory numFac
Number Factory


varFac

protected VariableFactory varFac
Variable Factory


nodeFac

protected NodeFactory nodeFac
Node Factory


varTab

protected VariableTable varTab
Variable Table


funTab

protected FunctionTable funTab
Function Table


opTab

protected OperatorTableI opTab
Operator Table


pv

protected PrintVisitor pv
PrintVisitor


lastRootNode

protected transient Node lastRootNode
Root node of the last parsed expression


parser

protected Parser parser
Parser instance used for parsing expressions


evaluator

protected Evaluator evaluator
Evaluator instance used for evaluating parse trees


additionalComponents

protected java.util.List<JepComponent> additionalComponents
Additional components out side the standard set


implicitMul

protected boolean implicitMul
Implicit Multiplication option


allowUndeclared

protected boolean allowUndeclared
Allow Undeclared Variables option


allowAssignment

protected boolean allowAssignment
Allow Assignment option

Constructor Detail

Jep

public Jep()
Creates a new Jep instance using the standard components with default settings. The StandardComponents component set is used.


Jep

public Jep(ComponentSet compSet)
Creates a new Jep instance with a specific component set.

Parameters:
compSet - The component set to be used.

Jep

public Jep(JepComponent... components)
Creates a new Jep instance with a set of components. If the full set of components is not specified then default components will be used.

Parameters:
components -
Since:
3.3 now varargs, default components used
Method Detail

setComponent

public void setComponent(JepComponent component)
Sets a single component. The component passed in as a parameter overrides the active component and the active component is no longer used. reinitializeComponents() is called after the component is added.

Parameters:
component - The component to be set.

setComponents

public void setComponents(JepComponent... components)
Sets one or more components for this Jep instance. The current components are overridden by the components passed in. Each component can be one of the following:

Parameters:
components - An array of components to be set.

addDefaultComponents

protected void addDefaultComponents()
Set the default values for components if none are specified. Called after any components specified in the constructor has been set.


setComponentsInternal

protected void setComponentsInternal(ComponentSet compSet)

setComponentInternal

protected void setComponentInternal(JepComponent comp)
Identifies the type of comp and set the associated member accordingly. This overrides the current component set.

Parameters:
comp - The component to be set.

reinitializeComponents

public void reinitializeComponents()
Calls the init method of all components. This is necessary in a few cases such as after adding new operators to the configurable parser.


getNumberFactory

public NumberFactory getNumberFactory()
Returns the number factory


getNodeFactory

public NodeFactory getNodeFactory()
Returns the node factory


getVariableFactory

public VariableFactory getVariableFactory()
Returns the variable factory


getFunctionTable

public FunctionTable getFunctionTable()
Returns the function table


getOperatorTable

public OperatorTableI getOperatorTable()
Returns the operator table


getVariableTable

public VariableTable getVariableTable()
Returns the variable table


getParser

public Parser getParser()
Returns the parser


getEvaluator

public Evaluator getEvaluator()
Returns the evaluator


getPrintVisitor

public PrintVisitor getPrintVisitor()
Returns the print visitor


getAdditionalComponents

public java.util.List<JepComponent> getAdditionalComponents()
Returns the additional components. Any modification to the list should be followed by a call to reinitializeComponents(). New components should be added by calling setComponent(JepComponent).

Returns:
the list

getAdditionalComponent

public JepComponent getAdditionalComponent(java.lang.Class<?> cl)
Return an additional component which is an instance of a particular class.

Parameters:
cl - The class to test for
Returns:
the first component found which is an instance or null if none found.
Since:
3.4.0

addVariable

public Variable addVariable(java.lang.String name)
Adds a variable with a given name. The value is undefined. If the variable already exists, no changes are made.

Parameters:
name - the name of the variable to be added
Returns:
the Variable instance

addVariable

public Variable addVariable(java.lang.String name,
                            java.lang.Object value)
                     throws JepException
Adds or sets a variable with a given name and value. If a variable with the same name already exists, the value of that variable is updated.

Parameters:
name - the name of the variable to be added
value - the value of the variable to be added
Returns:
the Variable instance
Throws:
JepException - if an attempt is made to set the value of a constant variable

addVariable

public Variable addVariable(java.lang.String name,
                            double value)
                     throws JepException
Adds or sets a double variable with a given name and value. If a variable with the same name already exists, the value of that variable is updated.

Parameters:
name - the name of the variable to be added
value - the value of the variable to be added
Returns:
the Variable instance
Throws:
JepException - if an attempt is made to set the value of a constant variable

addVariable

public Variable addVariable(java.lang.String name,
                            double re,
                            double im)
                     throws JepException
Adds or sets a complex variable with a given name and value. If a variable with the same name already exists, the value of that variable is updated.

Parameters:
name - the name of the variable to be added
re - the real component of the variable to be added
im - the imaginary component of the variable to be added
Returns:
the Variable instance
Throws:
JepException - if an attempt is made to set the value of a constant variable

addConstant

public Variable addConstant(java.lang.String name,
                            java.lang.Object value)
                     throws JepException
Add a constant: a variable who's value cannot be changed.

Parameters:
name -
value -
Returns:
the corresponding Variable
Throws:
JepException - if a constant variable already exists

tryAddConstant

public boolean tryAddConstant(java.lang.String name,
                              java.lang.Object value)
Tries to add a constant.

Parameters:
name -
value -
Returns:
true if successfully added or a constant with same name and value already exists. false if the constant has a different value

addStandardConstants

public boolean addStandardConstants()
Adds the constants pi and e to the parser. The values are added as the Math.PI and Math.E values.

Returns:
true if successful, false otherwise

getVariable

public Variable getVariable(java.lang.String name)
Returns the Variable instance of the variable name. If the variable has not been added, null is returned.

Parameters:
name - the name of the variable
Returns:
the Variable instance, or null if the variable has not been added.

getVariableValue

public java.lang.Object getVariableValue(java.lang.String name)
Returns the value of the variable name. If the variable has not been added, or if it's value is null, null is returned.

Parameters:
name - the name of the variable
Returns:
the value of the variable, or null if the variable has not been added or has the value null.

setAllowAssignment

public void setAllowAssignment(boolean value)
Sets whether assignment equations like y=x+1 are allowed. The default is true (assignment allowed).


getAllowAssignment

public boolean getAllowAssignment()
Whether assignment equation y=x+1 equations are allowed.


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 be automatically be added while parsing, and initialized to 0. Note this only affects the parsing stage, EvaluationException will still be thrown when trying to evaluate a variable with an undefined value.

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

The default value is true.

Parameters:
value - The boolean option for allowing undeclared variables.

getAllowUndeclared

public boolean getAllowUndeclared()
Returns the value of the allowUndeclared option.

Returns:
True if the allowUndeclared option is enabled. False otherwise.

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 true.

Parameters:
value - The boolean implicit multiplication option.

getDefaultValue

public java.lang.Object getDefaultValue()
Returns the default value used for new variables.

Returns:
the value

setDefaultValue

public void setDefaultValue(java.lang.Object defaultValue)
Sets the default value used for new variables. If the value is null (the default) then exceptions will be thrown when trying to evaluate the variables which do not have values set.

Parameters:
defaultValue -
See Also:
StandardEvaluator.setTrapNullValues(boolean)

getImplicitMul

public boolean getImplicitMul()
Returns the value of the implicit multiplication option.

Returns:
True if the implicit multiplication option is enabled. False otherwise.

addFunction

public PostfixMathCommandI addFunction(java.lang.String name,
                                       PostfixMathCommandI pfmc)
Adds a function to the parser.

Parameters:
name - the name of the function
pfmc - the function class instance to be used to evaluate the function
Returns:
the function class added

getLastRootNode

public Node getLastRootNode()
Returns the root node of the last successfully parsed expression

Returns:
the root node of the last successfully parsed expression

parse

public Node parse(java.io.Reader reader)
           throws ParseException
Parses the input from a Reader.

Parameters:
reader - the input reader
Returns:
the root node of the parse tree
Throws:
ParseException

parse

public Node parse(java.lang.String str)
           throws ParseException
Parses a string.

Parameters:
str - the input string
Returns:
the root node of the parse tree
Throws:
ParseException

initMultiParse

public void initMultiParse(java.lang.String str)
Initialises the parser for parsing a string with multiple expressions. This method does not perform any parsing. Use continueParsing to parse the first expression and subsequent expressions from the input.

Parameters:
str - String containing a sequence of expressions separated by semi-colons.
See Also:
continueParsing()

initMultiParse

public void initMultiParse(java.io.Reader reader)
Initialises the parser with a Reader for parsing with multiple expressions. This method does not perform any parsing. Use continueParsing to parse the first expression and subsequent expressions from the input.

Parameters:
reader - Reader from which equations separated by semi-colons will be read.
See Also:
continueParsing()

continueParsing

public Node continueParsing()
                     throws ParseException
Continue parsing without re-initialising the stream. This requires initMultiParse to be called first. Allows re-entrance of parser so that strings like "x=1; y=2; z=3;" can be parsed. When a semicolon is encountered parsing finishes leaving the rest of the string unparsed. Parsing can be resumed from the current position by using this method. For example
 XJep j = new XJep();
 j.initMultiParse("x=1;y=2; z=3;");
 Node node;
 try {
 while((node = j.continueParsing())!=null) {
    j.println(node);
 } }catch(ParseException e) {}
 
Empty equations such as "x=1;;y=2" are silently ignored, in this case the second call will return the node representing y=2.

Returns:
top node of equation parsed to date or null at EOF.
Throws:
ParseException
See Also:
initMultiParse(String)

evaluateD

public double evaluateD()
                 throws EvaluationException
Evaluates the most recently parsed expression and returns the result as a double.

Returns:
Returns the value of the expression tree. If node is null, null is returned.
Throws:
EvaluationException - if an error occurs while evaluating or if the returned data type can not be converted to a double number.

evaluate

public java.lang.Object evaluate()
                          throws EvaluationException
Evaluates the most recently parsed expression.

Returns:
Returns the value of the expression tree. If node is null, null is returned.
Throws:
EvaluationException - if an error occurs

evaluate

public java.lang.Object evaluate(Node node)
                          throws EvaluationException
Evaluates the expression tree pointed to by the node parameter.

Returns:
Returns the value of the expression tree. If node is null, null is returned.
Throws:
EvaluationException - if an error occurs

print

public void print(Node node,
                  java.io.PrintStream out)
Print an expression to a given stream.

Parameters:
node - root node of the expression to print
out - stream to print to

print

public void print(Node node)
Print an expression to System.out.

Parameters:
node - root node of the expression to print

print

public void print()
Print the last parsed expression to System.out.


println

public void println(Node node,
                    java.io.PrintStream out)
Print an expression to a given stream with a newline.

Parameters:
node - root node of the expression to print
out - stream to print to

println

public void println(Node node)
Print an expression to System.out with a new line.

Parameters:
node - root node of the expression to print

println

public void println()
Print the last parsed expression to System.out with a new line.


toString

public java.lang.String toString(Node node)
Returns a string representation of an expression.

Parameters:
node - root node of the expression.
Returns:
string representation

rootNodeToString

public java.lang.String rootNodeToString()
Returns a string representation of the last expression parsed.

Returns:
string representation


Copyright © 2010 Singular Systems http://www.singularsys.com/jep