forint-0.5.4
============
forint -- an extensible, C-compatible formula interpreter library. It's
meant for parsing a C-math expression (passed to the interpreter as a
C-string) and following calculations by the formula. For calculations two
ways are used:

  o By built-in virtual machine, in two variants -- a recursive call and a
    stack virtual machines (RVM and SVM mode),

  o By dynamic linking of a compiled formula (compilation is automatic).
    In the case some time for the compilation is spent but performance
    of an built-in in the object code formula is achieved.

The first mode may be interesting for you because in the library there is
a program interface allowing to get access to external variables,
pointers and functions with five signature types (see chapter 'Programmer
guide' of forint.texi), so the interpreter may be built-up by them (in the
second mode it's possible too).

The second mode may be very useful in some circumstances. Let user of some
program has to change many times some calculation formula, time for
calculation by a formula big enough and the user can't recompile the program
after each changing the formula (or don't want to make it). In the case
a virtual machine crawls through the formula and the user crawls along with
the program. The mode allows to make the program to run (see chapter
`Programmer guide' of forint.texi to compare run times (got by the
`speedtest.cc' test program in the package directory `examples') in different
modes).

I compared the library on a CPU heavy task with another calculator written
in pure C and made by lex & yacc, the last was slower in about 30 times
than forint in VM mode. Also I compared forint VMs with EiC -- full C
interpreter which also makes and executes byte-code. EiC was slightly (some
percents) faster than forint in SVM mode (and of course in RVM mode) on tests
I performed(*. But in DLF mode forint will outperform any interpreter in some
times because in the mode real compiled code is used for calculations.

(* After some optimization of VMs in the version 0.4.2 SVM became on some
percents faster than EiC.

In the `doc' directory two documents have been placed, the first one
`forint.texi' includes user guide, forint API and some internal structure
description (ps is made by texi2dvi and dvips or texi2dvi4a2ps), the second
one `diagrams.ps' describes execution diagrams for the virtual machines.

Features
========
  - C-compatibility (for more information see chapter `User guide' of
    forint.texi)

  - Literals with base 8(16) have  prefix  `0' (`0x').  Literals  in
    other bases (from 2 till 36) have prefix `N#', where N - number's
    base (the bash notation). In bases above 10, the letter  `A'  in
    either upper or lower case represents 10, `B' represents 11, and
    so forth, with `Z' representing 35. So  `0xA107'  and  `16#A107'
    represent the same hexadecimal number. Any base literals can  be
    used  in  one expression simultaneously.

  - Eleven built-in variables which can be made hidden (of course, they
    aren't built-in C variables):

      x, y, z, phi, psi, r, rad, t, u, v, rl.

  - Possibility to extend by external variables, pointers and arrays.

  - Possibility to extend by external functions with five types of
    signature (all of them must return double value):

      o with empty signature,
      o with a double argument,
      o with two double arguments,
      o with two generic (void*) pointers,
      o with a generic (void*) pointer and a double argument.

  - Possibility to override built-in variables.

  - Possibility to override built-in functions in virtual machine mode.

  - Recursive call of math expression by itself.

In the directory `examples' some programs using forint are placed:

  1. calc1.cc - CLI calculator with very simple user interface.

  2. calc2.cc - CLI calculator with external variables, pointers and
                functions.

  3. calc3.cc - CLI calculator with advanced user interface including
                history list (what makes it very convenient in use), with
                saved and loaded work environment.

  4. equivtest.cc - functional equivalence test of calculation modes.

  5. speedtest.cc - performance test of calculation modes.

Of course, the equivtest aren't a real extensive equivalence test. Writing
such a test for compiler or interpreter is a separate complex task.

Application areas
=================
I see three main application areas:

  1. programs requiring an interactive formula input,

  2. functional dependencies in configuration files,

  3. distributed computing (a (may be encrypted) transmission of some
     functional dependences from a computing center to machines making basic
     computing).

Bug report
==========
If you found an expression which gave different results calculated by forint
and by built-in in the C-code variant, please send me on

  filin@desert.ihep.su

a bug report, which must include:

  1. expression given invalid result or forint crash,

  2. calculation mode(s) in which a crash occurred, if it was,

  3. External variables, pointers or functions was added to a forint object
     and was used in crash expression (if there are no such variables,
     pointers or functions skip this point). There are some cases for which
     crash isn't a consequence of a bug in forint:

     - crash was caused by segmentation violation due to invalid extern
       pointer dereferencing in DLF mode (see chapter `Programmer guide'
       of forint.texi),

     - crash occurred in an external function,

     - crash was caused by arithmetic exception due to invalid arguments
       having been passed to an operator or function, GNU C-math-library
       handles with the situation and continues execution returning from
       incorrect operation non-number value -- it may be tested by functions
       like `isnan' or `isinf'.

     - crash was caused by stack overflow due to too big the number of
       recursive calls (see chapter `Programmer guide' of forint.texi).

  4. The program the forint is used by, please, take care of my time -- cut
     your program (if it's possible, check your case by the program `calc3'
     and if it gives the same result skip this point).

Alexey Filin.
