Package com.singularsys.jep

# Class Jep

java.lang.Object
com.singularsys.jep.Jep

All Implemented Interfaces:
  `Serializable`

Direct Known Subclasses:
  `MultipleEquationParsingJep`

public class Jep extends Object implements 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.toString());
     }

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

  Fields
  Modifier and Type
  Field
  Description
  `protected final List<JepComponent>`
  `additionalComponents`
  Additional components outside 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

  Constructors
  Constructor
  Description
  `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

  Modifier and Type
  Method
  Description
  `Variable`
  `addConstant(String name, Object value)`
  Add a constant: a variable whose value cannot be changed.
  `protected void`
  `addDefaultComponents()`
  Set the default values for components if none are specified.
  `PostfixMathCommandI`
  `addFunction(String name, PostfixMathCommandI pfmc)`
  Adds a function to the parser.
  `boolean`
  `addStandardConstants()`
  Adds the constants pi and e to the parser.
  `Variable`
  `addVariable(String name)`
  Adds a variable with a given name.
  `Variable`
  `addVariable(String name, double value)`
  Adds or sets a double variable with a given name and value.
  `Variable`
  `addVariable(String name, double re, double im)`
  Adds or sets a complex variable with a given name and value.
  `Variable`
  `addVariable(String name, Object value)`
  Adds or sets a variable with a given name and value.
  `Node`
  `continueParsing()`
  Continue parsing without re-initialising the stream.
  `Object`
  `evaluate()`
  Evaluates the most recently parsed expression.
  `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.
  `<T> T`
  `getAdditionalComponent(Class<T> cl)`
  Return an additional component which is an instance of a particular class.
  `<T> T`
  `getAdditionalComponentExact(Class<T> cl)`
  Return an additional component which is exactly a particular class.
  `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.
  `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
  `OperatorTable2`
  `getOperatorTable2()`
  Returns the operator table cast to OperatorTable2
  `Parser`
  `getParser()`
  Returns the parser
  `PrintVisitor`
  `getPrintVisitor()`
  Returns the print visitor
  `Variable`
  `getVariable(String name)`
  Returns the `Variable` instance of the variable `name`.
  `VariableFactory`
  `getVariableFactory()`
  Returns the variable factory
  `VariableTable`
  `getVariableTable()`
  Returns the variable table
  `Object`
  `getVariableValue(String name)`
  Returns the value of the variable `name`.
  `void`
  `initMultiParse(Reader reader)`
  Initialises the parser with a Reader for parsing with multiple expressions.
  `void`
  `initMultiParse(String str)`
  Initialises the parser for parsing a string with multiple expressions.
  `Node`
  `parse(Reader reader)`
  Parses the input from a Reader.
  `Node`
  `parse(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, 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, PrintStream out)`
  Print an expression to a given stream with a newline.
  `void`
  `reinitializeComponents()`
  Calls the `init` method of all components.
  `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(Object defaultValue)`
  Sets the default value used for new variables.
  `void`
  `setImplicitMul(boolean value)`
  Sets the value of the implicit multiplication option.
  `Variable`
  `setVariable(String name, Object value)`
  Adds or sets a variable with a given name and value.
  `boolean`
  `setVariableValue(String name, Object value)`
  Sets the value of the variable `name`.
  `String`
  `toString(Node node)`
  Returns a string representation of an expression.
  `boolean`
  `tryAddConstant(String name, 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 Details

  - ### 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 final List<JepComponent> additionalComponents
    Additional components outside 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 Details

  - ### 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` - a set of components which are used to build this Jep instance
    Since:
      3.3 now varargs, default components used

- ## Method Details

  - ### 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:
    - NumberFactory
    - VariableFactory
    - NodeFactory
    - VariableTable
    - FunctionTable
    - OperatorTable
    - Parser
    - Evaluator
    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
    Returns:
      number factor used

  - ### getNodeFactory

    public NodeFactory getNodeFactory()
    Returns the node factory
    Returns:
      node factory used

  - ### getVariableFactory

    public VariableFactory getVariableFactory()
    Returns the variable factory
    Returns:
      variable factory used

  - ### getFunctionTable

    public FunctionTable getFunctionTable()
    Returns the function table
    Returns:
      Function table used

  - ### getOperatorTable

    public OperatorTableI getOperatorTable()
    Returns the operator table
    Returns:
      Operator table used

  - ### getOperatorTable2

    public OperatorTable2 getOperatorTable2()
    Returns the operator table cast to OperatorTable2
    Returns:
      Operator table used
    Since:
      Jep 4.1

  - ### getVariableTable

    public VariableTable getVariableTable()
    Returns the variable table
    Returns:
      variable table used

  - ### getParser

    public Parser getParser()
    Returns the parser
    Returns:
      parser used

  - ### getEvaluator

    public Evaluator getEvaluator()
    Returns the evaluator
    Returns:
      evaluator used

  - ### getPrintVisitor

    public PrintVisitor getPrintVisitor()
    Returns the print visitor
    Returns:
      print visitor used

  - ### getAdditionalComponents

    public 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 <T> T getAdditionalComponent(Class<T> cl)
    Return an additional component which is an instance of a particular class. Since Jep 4.1 this is now a Template method so a cast is not required.
    Parameters:
      `cl` - The class to test for
    Returns:
      the first component found which is an instance or null if none found.
    Throws:
      `IllegalStateException` - if multiple components of the same class are found
    Since:
      3.4.0

  - ### getAdditionalComponentExact

    public <T> T getAdditionalComponentExact(Class<T> cl)
    Return an additional component which is exactly a particular class.
    Parameters:
      `cl` - The class to test for
    Returns:
      the first component found which is an instance or null if none found.
    Throws:
      `IllegalStateException` - if multiple components of the same class are found
    Since:
      4.1.0

  - ### addVariable

    public Variable addVariable(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(String name, 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

  - ### setVariable

    public Variable setVariable(String name, Object value)
    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, return null if error setting variable
    Since:
      Jep 3.5

  - ### addVariable

    public Variable addVariable(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(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(String name, Object value) throws JepException
    Add a constant: a variable whose value cannot be changed.
    Parameters:
      `name` - constants name
      `value` - its value
    Returns:
      the corresponding Variable
    Throws:
      `JepException` - if a constant variable already exists

  - ### tryAddConstant

    public boolean tryAddConstant(String name, Object value)
    Tries to add a constant.
    Parameters:
      `name` - name of constant
      `value` - value of constant
    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(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 Object getVariableValue(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.

  - ### setVariableValue

    public boolean setVariableValue(String name, Object value)
    Sets the value of the variable `name`. If the variable does not exist or is a constant, then false is returned.
    Parameters:
      `name` - the name of the variable
      `value` - the value to be set
    Returns:
      true if the variable exists and its values was set, false otherwise
    Since:
      Jep 4.1

  - ### setAllowAssignment

    public void setAllowAssignment(boolean value)
    Sets whether assignment equations like `y=x+1` are allowed. The default is true (assignment allowed).
    Parameters:
      `value` - true is assignment equations are allowed, false otherwise

  - ### getAllowAssignment

    public boolean getAllowAssignment()
    Whether assignment equation `y=x+1` equations are allowed.
    Returns:
      true is assignment equations are allowed, false otherwise

  - ### 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 Object getDefaultValue()
    Returns the default value used for new variables.
    Returns:
      the value

  - ### setDefaultValue

    public void setDefaultValue(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` - value new variables have if not explicitly given
    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(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:
      null unless there was a previous function with the same name in which case return the previous pfmc

  - ### 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(Reader reader) throws ParseException
    Parses the input from a Reader. Set the last root node. See `getLastRootNode()`
    Parameters:
      `reader` - the input reader
    Returns:
      the root node of the parse tree
    Throws:
      `ParseException` - if there is a syntax error in expression

  - ### parse

    public Node parse(String str) throws ParseException
    Parses a string. Set the last root node. See `getLastRootNode()`
    Parameters:
      `str` - the input string
    Returns:
      the root node of the parse tree
    Throws:
      `ParseException` - if there is a syntax error in expression or a null string encountered

  - ### initMultiParse

    public void initMultiParse(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 semicolons.
    See Also:
      - `continueParsing()`

  - ### initMultiParse

    public void initMultiParse(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 semicolons 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

         Jep j = new Jep();
         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. Since Jep 4.1 set the last root node on successful parses. See `getLastRootNode()`
    Returns:
      top node of equation parsed to date or null at EOF.
    Throws:
      `ParseException` - if there is a syntax error in expression
    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 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 Object evaluate(Node node) throws EvaluationException
    Evaluates the expression tree pointed to by the node parameter.
    Parameters:
      `node` - root of expression tree to be evaluated
    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, 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, 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 String toString(Node node)
    Returns a string representation of an expression.
    Parameters:
      `node` - root node of the expression.
    Returns:
      string representation

  - ### rootNodeToString

    public String rootNodeToString()
    Returns a string representation of the last expression parsed.
    Returns:
      string representation or null if no equation parsed