                       Mathomatic Symbolic Math Library
                       --------------------------------

This directory contains the API (Application Programming Interface) and
test/example program for the Mathomatic symbolic math library.  The API in
"lib.c" can be used to link your C compatible programs with the Mathomatic
symbolic math engine.  This simple API provides for passing C text strings
containing equations and commands to the Mathomatic engine.  If successful, a
text string containing the resulting equation is returned, otherwise an error
message is returned.

This symbolic math library is at least able to be run anywhere the main
Mathomatic application can be run, and does not require an operating system
beyond the ability to allocate memory with malloc().  The symbolic math
library is not re-entrant, meaning it cannot successfully be called until the
last call to it completes.  This is due to the fact that most data storage
areas in it are global and static.

Compile and link *.c and ../*.c with -DLIBRARY on the C compiler command
line, to compile Mathomatic in library mode, and to create the test/example
application which uses this API.  This is automatically done with the GNU
make utility and its input file "makefile".  To compile the library and test
program, type "make" while in this "lib" directory.

This will create the API test executable named "mathomatic" and the static
library "libmathomatic.a".  To run the test executable, type "./mathomatic".
To do a system install of the development library "libmathomatic.a" and C
header file "mathomatic.h", type:

	sudo make install

Just include the file "mathomatic.h" and call the functions in "lib.c" to use
this library.  Link your program with "libmathomatic.a" by using
"-lmathomatic -lm" at the end of the ld linker command line.
"libmathomatic.a" is not required on the target system, since it is a static
library, meaning it is included in the resulting executable.

The following code provides a quick test of the library:

    char *output;
    matho_init();
    matho_process("x^2=4", &output);
    matho_process("solve x", &output);
    printf("%s\n", output);

Remember to free(output) on each successful call to matho_process() and
matho_parse() to return the memory used by the output string when you are
finished using it, otherwise there will be a memory leak.  Here is the above
code fixed so it doesn't leak:

    char *output;
    matho_init();
    if (matho_process("x^2=4", &output) && output)
        free(output);
    if (matho_process("solve x", &output)) {
        if (output) {
            printf("%s\n", output);
            free(output);
	}
    } else if (output) {
        printf("%s\n", output);
    }

The following Mathomatic commands are omitted in this library: calculate,
edit, "factor number", plot, push, quit, and tally.  GNU readline
functionality is not used in the library.

Recently, the "nintegrate" and "integrate definite" commands are allowed; the
bounds of integration are specified in the two equation spaces following the
current equation.  cur_equation+1 is the lower bound, and cur_equation+2 is
the upper bound.  Of course, the integrate and nintegrate commands operate on
the current equation, specified by the global "cur_equation" variable (origin
0).  The equation number displayed is always origin 1, making it 1 greater
than "cur_equation", so keep that in mind.

Please define the C preprocessor name "HANDHELD" when compiling for handheld
devices like the iPhone, for reduced memory usage.

Many bugs, ugliness's, and inconsistencies in the symbolic math library have
recently been fixed; it is best to always use a recent version of Mathomatic,
when used as a library.  The most recent version can always be found on the
Mathomatic website http://mathomatic.org
