jevaluate
Project home

First release of JEvaluate can be downloaded here

Description:

JEvaluate provides a simple and easy way to embed a java expression evaluator in an application. Unlike scripting languages (jython, groovy…), it is not "programming orinted",  and the end user can understand the syntax quickly.

Features:

-       JEvaluate uses a simple type system : (there is no double, float or others, but simply a numeric type)

-       Provides object-oriented approach to variables parsing and handling : variable are object that can be precompiled and serialized to disk.

-       The parser can detect circular references between variables.

-       Functions can be easily added to the parser, you can have multiples parsers, each with its own function set.

-       Support for internationalization, functions registered in a parser can be simply renamed with a one method call.

-       The Workspace class can manage many variables and references between them; it recalculates automatically the values if a variable is changed.

Usage Example:

Expressions can include:

-       Constants : Numeric (ex.: 156.33), Text (ex.: 'a text'),  Date (ex. : #31/05/2005#), and boolean (true/false)

-       Operators : Arithmetic (+, -, *, / and % (modulo)), comparaison (=, !=, <, >, <=, >=), Logical (&&(and), || (or))

-       Variables : Names of other variables, must be declared before used.

-       Functions : The parser contains a set of default functions for handling data (Text, numeric, dates) you can create your own functions by implementing the Function Interface (cf. below).

Extending the parser

The workspace uses an internal parser to parses expressions. You can obtain the actual instance of the parser by calling getParser method of the workspace object.

As mentioned earlier you can extend the parser by creating your own functions. A function must implement the Function interface or extends the AbstractFunction class. But you must before understand some terms.

 Symbols

Symbols gives information about names and types of variables used in an expression, the Symbol interface define methods for extracting the required informations:

Nodes

Nodes are operands that composes an expression, consider the simple expression below:

                  5+sin(2)

             This expression can be represented as a composition of operands (Nodes)

As illustrated above, the parser parses expressions and create a Node for every construct in the expressions, because expressions can includes nested expressions (like sin(2+3)), Nodes can also include other nodes.

Nodes are actually instances of object that implements the Node interface. It extends the Symbol interface by providing the tow additional methods

Environment

The Environment interface defines methods for storing and retrieving object by keys (like Hash tables). This interface serves for many purposes:

-       When parsing a variable : for example adding tow variables "x = 2+3" and  "y=x+2" tow the wokspace, involves many operations:

The workspace creates an instance of an Environment to hold symbols

                         Environment symbols = new EnvironmentImpl(); //this is the default implementation of Environment

It uses the parser instance for parsing expression

                         Node node = parser.parse(expression /*2+3*/,  symbols, variableName/*x*/)

Then add the "x" variable to the Environment

                         symbols.put("x", node);

When parsing the second variable "y", the parser encounters a reference to x, it then asks to the Environment symbols for that identifier, checks his type and eventually for circular references between x and y, and finally, if there are no errors, return a node representing the parsed expressions.

-       When evaluating variables, suppose we have a list of parsed variables x and y and  we want to evaluate them:

First we create an instance of an Environment to hold values

             Environment values = new EnvironmentImpl();

Then we ask the node "x" for his value and we add them to the Environment

             Object value = x.getValue(values);

             Values.put("x", value);

Then we ask y.getValue(values), but "y" contains a reference to a variable named "x", it uses the provided Environment to get the value of "x", performs the addition and the return the result.

The sample code following illustrate the use of Environment and Parser

   Variables

                         The Variable class serves as rapid way to create variables, can be used as symbols, nodes and can be serialized to disk

                         Example creation:

Variable a =  new Variable("a", 'n' /*or Type.Numeric*/, "(6+10.33)*(15-(33+55))"));

/*Type can be specified as Integer constants: Type.NUMERIC, Type.TEXT; Type.DATE, Type.BOOLEAN

Or characters 'n': numeric, 't': Text, 'd': Date, 'b': Boolean */

                         Example parsing :

                                      variable.parse(parser, symbols, true /* true for adding variable to symbols*/);

   Creating Functions

                         The Function interface defines methods for creating your own functions:

                         Because Function extends Node (it self extending Symbol), you must also implements this interface. Total methods that must be implemented are:

You can extends the AbstractFunction Class to avoid defining all methods, for example

Correspondence Type vs. Java

When getting values from Nodes, you need to cast values returned as Object's, generally you know the type of the node by asking the getType method (this is typically down in the setArg method), then following the type, you cast to the appropriate value:

                         NUMERIC -> cast to BigDecimal

                         TEXT -> cast to String

                         Date -> cast to Date

                         BOOLEAN -> cast to Boolean.

Example, Function for calculating the maximum of tow numbers:

After creating this function, you can add it to the parser by calling

               parser.registerFunction("max", MaxFunctionNode.class);

If a function already exists with the supplied name, the parser throws a DuplicateFunctionException.

If you want override a function you must call overrideFunction

               parser. overrideFunction("max", MaxFunctionNode.class);

if the overridden function does not exists, the parser add the function and return false.

Arithmetic parameters (precision, scale…)

You can specify various parameters for arithmetic operations (precision of numbers, the significant digits for comparison) :

When instantiating the parser, the constructor can take an instance of MathContext class (see javaDoc):

                          public Parser(MathContext mathCtxt)

You can also specify the number significant digits when comparing tow numbers

                      public void setCompScale(int compScale)

          compScale the number of digits after the decimal points) used for number comparison, for example, with a precision of 3, the tow numbers 1.22350 and 1.22399 are considered to be equals. -1 means unlimited.

   Internationalization

The parser provides methods to facilitate internationalization:

-       first, you can provide a new name for any function registered in this parser

public boolean renameFunction(String oldName, String newName).

-       you can also provide your own names for the Boolean constants (default are true and false)

parser.TRUE_CONST = "vrai"

parser.FALSE_CONST = "faux"

                         (You must provide a name according to Variable name rules, i.e. alpahanumeric values and the '_'  and '.' symbols)