- JavaDoc

# JEP

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

# Advanced Features

- Manipulating Expressions
- Components
- Configurable Parser
- Serialization
- Grammar

# Variables

- Basics
- Undeclared and undefined variables
- 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 the

    Jep.addVariable(String name,Object val)

and retrieved with

    Object Jep.getVariableValue(String name)

The `addVariable()` method can be used to change the value of existing variables. For `double` values use the Jep.addVariable(String, double) and for complex numbers using 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.

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