.\" 
.\" Copyright 2003 Michael B. Allen <mba2000 ioplex.com>
.\" 
.TH eval 3m "Apr 29, 2005" "libmba-0.9.1" "MBA Library Functions"
.SH NAME
eval \- evaluate simple arithmetic expressions
.SH SYNOPSIS
.nf
.B #include <mba/eval.h>
.sp
.BI "struct eval *eval_new(symlook_fn " symlook ", void *context);
.br
.BI "void eval_del(void *" eval ");
.br
.BI "int eval_expression(struct eval *" eval ", const tchar *" expr ", const tchar *" elim ", unsigned long *" result ");
.br

.fi
.SH DESCRIPTION
The
.BR "eval" (3m)
module will evaluate simple arithmentic expressions consisting of integers, symbols for which the provided
.B symlook_fn
returns an integer, and any of the operators
.IR "|&^+-*/()" .Operator Precedence
.sp
Operator precedence is roughly the same as the C language.
.PP
.RS
.nf
.ta 4n 19n 31n

 ( )  higher
 * /
 + -
^ & | lower

.ta
.fi
.RE
.PP
Prefixing integer tokens with minus
.I '-'
to indicate a negative value is currently not supported.
.PP
.TP
.B new
The
.B eval_new
function creates and returns a new context object for evaluating expressions. The
.I symlook
parameter is defined as follows:
.PP
.RS
.nf
.ta 4n 19n 31n

typedef int (*symlook_fn)(const tchar *name, unsigned long *val, void *context);

.ta
.fi
.RE
.PP
The
.I symlook_fn
function will be called to resolve any non-numeric symbols and should place the value identified by
.I name
into
.I val
and return 0. If the symbol is not found -1 should be returned.
.sp
The
.B eval_new
function can be used repeatedly to evaluate any number of expressions before being destroyed with the
.B eval_del
function. The
.I context
parameter is passed uninterpreted to the
.I symlook_fn
(e.g. a map perhaps).
.TP
.B del
The
.B eval_del
function deletes the context object
.I eval
freeing any memory allocated with
.I eval_new
or during the evaluation of expressions.
.TP
.B eval_expression
The
.B eval_expression
function evaluates an infix expression like
.IR "'(5 + 3) * N'" ,
converts it into a stack of tokens in postfix orientation, and reduces it with a simple translation matrix to produce a single integer value. The
.I eval
parameter is a context object created with
.IR "eval_new" .
The expression at
.I expr
is evaluated up to, but not including, the memory at
.IR "elim" ,
and writes the resulting value in the memory at
.IR "result" .
.SH RETURNS
.TP
.B eval_expression
The
.B eval_expression
function returns 0 if the expression was successfully reduced or -1 if an error occured in which case
.I errno
will be set appropriately (e.g.
.I ENOENT
if the
.I symlook_fn
could not resolve a symbol).