Simple Runtime Calculations with ELAM

From time to time it is necessary to do calculations at runtime that cannot be predetermined at compile time - for example if you want to allow your users or administrators to enter a simple function to calculate coordinates, manipulate strings, etc.

Usually you have the choice of either making this task very cumbersome for the user - for example using XML constructs to serialize the calculation into a machine readable format - or you have to include a very large statistics/mathematics package or a complete language into your project. The statistics packages have the bad habit of becoming quite large and complex, and languages, while often doing the same, have the side effect of giving the user access to far more facilities than is usually intended.

The ELAM (Elementary Logic and Arithmetic Machine) library is located in the middle between those extremes. It is specialized on very simple expressions and simple extendability of the engine. It is based on Qt and as such integrates tightly with many classes inside Qt by using the QVariant type as its main vehicle.

When (Not) to Use ELAM

ELAM is meant for very simple user driven calculations, it is not very fast and it does not scale well to very complex mathematical constructs. But it can handle pretty much any type that can be put into QVariant and for which you provide operators and/or functions.

So you use it when:

• you want your users to be able to enter simple expressions (like newprice = oldprice / 2 + 1)
• you do not want to confuse them with a complex syntax (<calc result="newprice"><divide op1="oldprice" ...)
• the calculation is not speed critical
• you need a simple way of adding new types, operators, and functions
• you need integration with Qt

You do not use it:

• if you have to use very extensive statistical analysis (use a statistics package instead)
• you have to do really complex maths (like solving equations, use a mathematics package instead)
• you need imperative statements, extensive logic, etc. (use a script language, like QtScript or Tcl)
• your calculations are speed critical (there are specialized packages for this)
• your project is not Qt based (sorry, ELAM needs Qt)

Getting Started

Download the source from SVN:

svn co https://silmor.de/svn/softmagic/elam/trunk elam

Enter the src directory and simply call qmake and make.

To get more complete documentation I recommend calling doxygen from the src directory.

Then call qmake and make in the demo directory and start the demo program.

The plain ELAM engine only knows some very basic rules how to parse expressions, it does not have any predefined types, literals, operators or functions. However, ELAM comes with a default library that provides some basic functionality for integers, floating point numbers, strings, and booleans. The demo program loads all those parts automatically and then allows you to enter arbitrary expressions:

The example above shows the main view of the demo. The expression there only utilizes integer mathematics, but it already shows that ELAM knows about operator precedence and variable assignments. You can have a look at the variables and constants in the "Values" tab:

ELAM keeps track of variables and constants at run-time. You can also inspect part of the current syntactic environment:

ELAMs syntax can be changed on many levels:

• you can manipulate variables and constants
• you can add operators and functions
• you can change operator precedence
• you can change the symbols used to represent different tokens in ELAM
• you can add data types and their literal forms

Including ELAM in your own Qt project is rather simple: all you need is an engine instance that is configured to your needs and then you can feed it expressions from your configuration files or user interface:

//create an integer-enabled engine:
ELAM::IntEngine myengine;
//add floating point math:
ELAM::FloatEngine::configureFloatEngine(myengine);

QString expression="1+2";
qDebug()<<myengine.evaluate(expression);

The expression string above could as well come from any other source.

Please see ELAMs own documentation for more details on what you can do with an engine and how you can adjust it to your needs.