- JavaDoc

# JEP

- Basic Usage
- Variables
- Data types
- Operators
- Functions
- Advanced Features
- Grammar
- FAQ
- Version History

# Extensions

- Overview
- XJep
- Differentiation
- Vectors and Matrices
- Groups
- Version History

# Variables

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

## Basics

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 method.
2. Allow undeclared variables: If you allow undeclared variables, they are automatically added to the symbol table while parsing an expression.

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

The value of a variable can be queried using getVarValue method. A further method getVar returns an object representing the variable.

Variables can be constants which cannot have their values changed. To add a new constant use addConstant to add a mutable variable use addVariable.

The SymbolTable class stores objects representing variables rather than just their values. The get and put methods of this class are deprecated. This results in a slight speed up during evaluation.

## 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 getSymbolTable method. This method is most useful when the undeclared variables option is enabled. The return value is a SymbolTable object. Note that SymbolTable extends Hashtable.

## Assignment

Assignment allows the values of variables to be set by using the `=` operator in equations so it is possible to do something like `x=3` then `y=x^2` and `y` will have the value 9. Assignment can be used with the standard JEP package, there is no need to use any of the packages in the org.lsmp.djep tree. To switch on assignment facilities the setAllowAssignment method of the main JEP object should be called.

    // standard initialisation
    JEP j = new JEP();
    j.addStandardConstants();
    j.addStandardFunctions();
    j.addComplex();
    j.setAllowUndeclared(true);
    j.setImplicitMul(true);

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

    // parse assignment equations
    j.parseExpression("x=3");
    // evaluate it - no need to save the value returned
    j.getValueAsObject();
    // parse a second equation
    j.parseExpression("y=2");
    j.getValueAsObject();

    // an equation involving above variables
    j.parseExpression("x^y");
    Object val3 = j.getValueAsObject();
    System.out.println("Value is " + val3);

## Observers for variables

Both SymbolTable and Variable implement the Observer/Observable pattern. This allows objects to be informed whenever a new variable is created or when its value has been changed. An example of use is

    public class MyObserver implements Observer
    {
        public void initialise()
        {
            SymbolTable st = j.getSymbolTable();
            st.addObserver(this);
            st.addObserverToExistingVariables(this);
        }

        public void update(Observable arg0, Object arg1)
        {
            if(arg0 instanceof Variable)
                println("Var changed: " + arg0);
            else if(arg0 instanceof SymbolTable.StObservable)
            {
                println("New var: "+arg1);

                // This line is vital to ensure that
                // any new variable created will be observed.
                ((Variable) arg1).addObserver(this);
            }
        }
    }