- JavaDoc

# Jep Java

- Introduction
- Basic Usage
- Variables
- Data types
- Operators
- Functions
- Custom Functions
- BigDecimal
- FAQ
- Migration
- Version History

# Advanced Features

- Manipulating Expressions
- Components
- Configurable Parser
- Serialization
- Threads
- Localization
- Grammar
- Other advanced features

# Variables

- Basics
- Undeclared and undefined variables
- Constants
- Assignment
- Obtaining a list of variables
- Observers for variables

## Basics

Variables are represented by the Variable class and stored in a VariableTable. The value of a variable can be set using

    Jep.addVariable(String name,Object val)

and retrieved with

    Object Jep.getVariableValue(String name)

The `addVariable()` method can also be used to change the value of existing variables. For `double` values, use the Jep.addVariable(String, double) method and for complex numbers, use the Jep.addVariable(String, double, double) method. A further method, getVariable(String), returns the Variable object. This class allows variables to be observed and offers a marginally faster method for getting and setting variable values.

## Undeclared and undefined variables

During parsing, the parser looks up whether variables exists. The Jep.setAllowUndeclared(boolean flag) sets the behaviour for undeclared variables:

1. Allow undeclared variables (default): undeclared variables will be added to the VariableTable while parsing an expression.
2. Do not allow undeclared variables: In this case it is necessary to add a variable using `addVariable()` methods before parsing. A ParseException will be thrown if an undeclared variable is encountered. This option is useful if you wish to restrict the variables which can appear in an expression.

During evaluation the value of a variable will be retrieved. If the value is undefined (`null`), then an EvaluationException will be thrown. Null values will occur if the variable values have not been set using `addVariable()`. In particular this will occur if `allowUndeclared` is true and a variable is created while parsing. This behaviour can be changed by calling the `StandardEvaluator.setTrapNullValues(boolean flag)` method. The `Jep.setDefaultValue(Object)` method can be used to set the default value variables.

## Constants

Variables can be defined as being constants, whos values is fixed. By default Jep defines the constants `e` (2.718281828459045), `pi` (3.141592653589793), `i` (Complex number i) and boolean constants `true` and `false`.

To add a constant use

    jep.addConstant("tau", (1+Math.sqrt(5))/2.);

To remove a constant use

    jep.getVariableTable().remove("e");

To initilise Jep with no constants use the VariableTable component

    Jep jep = new Jep(new VariableTable());

Individual variables have an isConstant field, which can be accessed via the `isConstant()` method and set via `setIsConstant(boolean b)`. If the field is set then variable value cannot be changed.

## Assignment

Assignment allows the values of variables to be set by using the `=` operator in equations so it is possible to assign values with expressions like

    x = 3

then use the assigned values in an expression such as

    y = x^2

and `y` will have the value 9. Assignment is enabled by default. To disable assignment facilities, the setAllowAssignment(boolean) method of the main Jep object should be called. Calling setAllowUndeclared(true) is required for Jep to parse the assignment equations.

Important: It is necessary to call the evaluate() method after parsing for the variable value to be assigned.

    // standard initialisation
    Jep j = new Jep();
    j.setAllowUndeclared(true);

    // switch assignment facilities on
    j.setAllowAssignment(true);

    // parse assignment equations
    try {j.parse("x=3");} catch (ParseException e) {}
    // evaluate it - no need to save the value returned
    try {j.evaluate();} catch (EvaluationException e) {}

    // parse a second equation
    try {j.parse("y=2");} catch (ParseException e) {}
    try {j.evaluate();} catch (EvaluationException e) {}

    // an equation involving the above variables
    try {j.parse("x^y");} catch (ParseException e) {}
    try {
    	Object val3 = j.evaluate();
    	System.out.println("Value is " + val3);
    } catch (EvaluationException e) {}

## Obtaining a list of variables

If you parse an expression with an unknown set of variables (when the allowUndeclared option is enabled), you may need to know which variables occurred in the expression. There are two ways of obtaining a list of the variables.

One approach is to use the getVariableTable method. With the returned variable table you can then check its contents to see which variables have been added while parsing. In particular the VariableTable.getVariables() returns a list of all variables. The VariableTable's `toString()` will produce a printable list.

The second approach is to use the TreeAnalyzer class to examine an expression tree after parsing an expression. See the JavaDoc documentation for more information on how to use it.

## Observers for variables

The Variable class implements the Observer/Observable pattern. This allows objects to be informed whenever variable values change. To register a class as an observer of a variable, use the `Variable.addObserver(Observer)` methods. The VariableTable can also be observed to check for the addition of new variables, see VariableTableObserver for a class to facilitate observing the VariableTable and its Variables.