JEP - Java Math Expression Parser

- 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

# Basic Usage

- Getting started
- Error handling
- Evaluating expressions
- Alternate parsing and evaluation functions
- Implicit multiplication

## Getting started

Using the JEP package of classes in your project is simple! The following steps will get you started quickly.

1. Download the JEP package
2. Unpack the archive
3. Move the jep-x.x.x.jar file to a directory of your choice (optional)
4. IMPORTANT: For the Java compiler to be able to find the JEP classes when compiling your program, it needs to know their location. So you will need to add the location of the .jar file to your CLASSPATH environment variable (if you don't know how, read this). Your CLASSPATH variable should contain something like C:\java\packages\jep-x.x.x.jar, depending on where you place the jar file. Alternatively you may need to set the location of the jar archive in your Java IDE so that the compiler finds the library.
5. In your program, create a new parser object with

       org.nfunk.jep.JEP myParser = new org.nfunk.jep.JEP();

6. Add the standard functions and constants if you want to be able to evaluate expressions with trigonometric functions and the constants pi and e.

       myParser.addStandardFunctions();
       myParser.addStandardConstants();

7. By default you need to specify which variables can be used in the expression. If a variable is not added before the expression is parsed, the parser will claim that the expression is invalid (this can be changed by allowing undeclared variables).
   To add the variable x and initialize it to 0 for example, write

       myParser.addVariable("x", 0);

8. Parse the expression, and evaluate it:

       myParser.parseExpression(ExpressionString);
       result = myParser.getValue();

9. The values of variables can be changed with the addVariable(String, double) method.

The code of the sample applets provide more extensive look at how the parser methods are used.

## Error handling

Errors can occur both while parsing an expression and while evaluating an expression. The hasError() method reports whether an error has occurred during the most recent action (either parsing or evaluation). If the result is `true`, you can then use getErrorInfo() to obtain further information on the errors that have occurred.

## Evaluating expressions

Four methods for evaluating an expression are available:

- getValue(): Use this if you are expecting a normal floating point value.
- getComplexValue(): Use this if you are expecting a complex value.
- getValueAsObject(): Returns the result as an Object (any type)
- evaluate(Node root): Evaluates a tree with from a root node and returns the result as an Object.

The first two methods call getValueAsObject() internally, and perform the necessary conversions into either a `double` value, or a `Complex` object.

## Alternate parsing and evaluation functions

There is an alternative method to parsing and evaluating expression which allows a little more flexibility in applications especially when working with a set of related equations. These are:

    public Node parse(String expression) throws ParseException
    public Object evaluate(Node node) throws Exception

which parse and evaluate the expression. These can be used like

    try
    {
    	// Alternative syntax
    	Node node1 = j.parse("z=i*pi");
    	j.evaluate(node1);
    	Node node2 = j.parse("exp(z)");
    	Object val2 = j.evaluate(node2);
    	System.out.println("Value: "+val2);
    }
    catch(ParseException e)	{
    	System.out.println("Error with parsing");
    }
    catch(Exception e)	{
    	System.out.println("Error with evaluation");
    }

Hence its a bit easier to keep track of a number of equations. Note that using this syntax Exceptions need to be caught and the getTopNode() method will not return meaningful results.

## Implicit multiplication

You can enable the implicit multiplication option with setImplicitMul(true). The default setting is false (no implicit multiplication).

Implicit multiplication allows expressions such as "2 x" to be interpreted as "2*x". Note that a space is required between two variables for them to be interpreted as being multiplied. The same holds for a variable followed by a number. For example "y 3" is interpreted as "y*3", but "y3" is interpreted as a single variable with the name y3. If a variable is preceded by a number, no space is required between them for implicit multiplication to come in effect.