- JavaDoc

# JEP

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

# Advanced Features

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

# Variables

- Basics
- Allowing undeclared variables
- Obtaining a list of variables
- Assignment
- Observers for variables

## Basics

Variables are stored in a variable table. This table can be accessed during parsing or evaluation. During parsing, the parser looks up whether variables exists. And during evaluation the variables are looked up in the table in order to obtain their values.

Two options are available in working with variables:

1. Do not allow undeclared variables (default): In this case it is necessary to add a variable before parsing an expression with that variable in it. This is accomplished with the addVariable(String, Object) method.
2. Allow undeclared variables: If you allow undeclared variables, they are automatically added to the symbol table while parsing an expression. See the section below on how to accomplish this.

After an expression has been parsed, variable values can be updated using either addVariable. This allows repeated evaluation of an expression with different variable values.

The value of a variable can be queried using getVariableValue(String) method. A further method getVariable(String) returns an object representing the variable.

Note that the VariableTable class stores objects representing variables rather than just their values.

## Allowing undeclared variables

To enable parsing of undeclared variables, use setAllowUndeclared(true). The default setting is `false` (undeclared variables are not allowed).

If you do not know what variable names may occur in the expression before parsing it, you can use `setAllowUndeclared(true)`. With this option enabled, it is not necessary to add variables to the parser before parsing an expression. If a new variable is found while parsing, it is automatically added to the symbol table. See Obtaining a list of variables to read about how to access these variables.

## Obtaining a list of variables

While parsing an expression with undeclared variables allowed, a list of all the variables and constants that have been added to the parser, can be obtained with the getVariableTable method. With the returned variable table you can then check its contents to see which variables have been added while parsing.

## 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. To switch on assignment facilities, the setAllowAssignment(boolean) method of the main JEP object should be called. Calling setAllowUndeclared(true) is also 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) {}

## 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 addObserver(Observer) methods.