Package com.singularsys.jep

Class Jep

  • All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    XJep
    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.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 Detail

      • 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 - a set of components which are used to build this Jep instance
        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:
        • 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

      • 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

      • 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

      • setVariable

        public Variable setVariable​(java.lang.String name,
                            java.lang.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​(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 - constants name
        value - its 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 - 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​(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).
        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 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 - 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​(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:
        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​(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 - if there is a syntax error in expression

      • 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 - if there is a syntax error in expression

      • 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 
         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.
        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 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.
        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,
                  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