.ds f. vexpr.sec
.NH 1 "VEXPR LIBRARY"
.XS
\s12\*(SN  VEXPR LIBRARY\s0
.XE
.sp 2
.NH 2 "INTRODUCTION TO THE VEXPR LIBRARY"
.XS
      \*(SN  INTRODUCTION
.XE
.sp 2
.PP
\fIvexpr\fP is the Khoros Library which contains routines 
to set variables defined by the user, to parse mathematical expressions input
by the user utilizing variables that have been previously set, and evaluate
these expressions.  It is used mainly by cantata to implement the control
loops available in the visual language; however, it is available for other
applications - for example, an application that implements interactive 
mathematical computation might find the \fIvexpr\fP library useful.  In such
an application, the user might want to define a variable i with some integer 
value, a variable j with another integer value, and then ask for the value 
of i*2+j.  The \fIvexpr\fP library provides functionality of this type.
Variables may be defined, set, and reset;  expressions using those variables
may be evaluated;  a list of the current variables and their values may be
obtained.
.PP
Note that the \fIvexpr\fP library is NOT the same as the \fIxvparser\fP 
library used to parse functions by the xprism2 and xprism3 plotting packages - 
the \fIxvparser\fP library is not documented here, as it is private to xprism2 
and xprism3 only, and is not available for outside use.
.PP
Similar to the \fIxvgraphics\fP library, the \fIvexpr\fP defines the area of
application with an \fIidentification number,\fP or \fIid\fP.  This id is of 
type long, and must be passed to all routines in \fIvexpr\fP.  It is defined 
by the application program to be any number that is deemed suitable.  
The value of the id itself is not important;  the key issue is that it be
used consistently.  The id number, when used properly by the application 
program, defines the domain of variables set and used.  For instance, if 
all variables set by the user are to be considered global, the application 
program would use the same id for all calls to the \fIvexpr\fP library.  
However, if a set of variable definitions and expression evaluations were 
to be local to a particular module, a different id must be used for calls
to the \fIvexpr\fP library in that module.   For instance, the same variables 
with different values might be employed by the user in three different areas 
of the application, provided that the application used
a different identification number in each of the three areas.
.sp 3
.NH 2 " xve_init()"
.XS
      \*(SN   xve_init()
.XE
.sp
.LP
This routine initializes internal structures and variables used by the
\fIvexpr\fP library.  It MUST be called prior to ANY other calls to the
\fIvexpr\fP library.  It has no parameters. 
.sp
.LP
=====================================================================
.sp 3
.NH 2 " xve_eval_int()"
.XS
      \*(SN   xve_eval_int()
.XE
.sp
.LP
This routine performs two functions: it sets integer variables and
evaluates integer expressions.  It will return TRUE (1) on success, FALSE (0)
on failure.  If the routine fails for some reason, an error message will be
passed back in the \fIerror\fP string.
.LP
The \fIstring\fP passed in will indicate which function 
xve_eval_int() is to perform, and the integer \fIvalue\fP returned 
will reflect this. 
Let us illustrate with an example.  Suppose a string of "i = 10" is passed
to xve_eval_int(). This indicates that the variable i is to be defined and
assigned the value of 10; the \fIvalue\fP returned will be 10.  Later, suppose
xve_eval_int() is called again with the same \fIid\fP, with a \fIstring\fP of
"i*2+5".  Now, xve_eval_int() will evaluate the expression, using the value
of i defined by the previous call - [10*2+5].  The \fIvalue\fP returned 
in this case would be 25.
.sp
.B
.sp
int xve_eval_int(id, string, value, error)
.br
long	id;
.br
char    *string;
.br
int	*value;
.br
char    *error;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP id: 10
The \fIvexpr\fP identifier
.sp
.IP string:
The string to be evaluated.
.IP value:
The integer value returned.  
.IP error:
If the xve_eval_int() routine fails for some reason, the reason for failure
will be printed into this error string. It MUST be allocated by the caller,
and should be at least 1024 bytes long. The application may print out this
error message to correct the user.
.sp
.LP
=====================================================================
.bp
.sp 3
.NH 2 " xve_eval_float()"
.XS
      \*(SN   xve_eval_float()
.XE
.sp
.LP
This routine performs two functions: it sets floating point variables and
evaluates floating point expressions.  It will return TRUE (1) on success, 
FALSE (0) on failure.  If the routine fails for some reason, an error 
message will be passed back in the \fIerror\fP string.
.LP
The \fIstring\fP passed in will indicate which function 
xve_eval_float() is to perform, and the float \fIvalue\fP returned 
will reflect this. 
Let us illustrate with an example.  Suppose a string of "x = 0.1" is passed
to xve_eval_float(). This indicates that the variable x is to be defined and
assigned the value of 0.1; the \fIvalue\fP returned will be 0.1.  Then,
xve_eval_float is called again with a \fIstring\fP of "y = 0.9"; now the
\fIvalue\fP returned is 0.9. Finally, suppose xve_eval_float() is with the 
with a \fIstring\fP of "(x+y)/2".  Now, xve_eval_float() will evaluate the 
expression, using the values of x and y defined by the previous call : 
[(0.1 + 0.9) / 2].  The \fIvalue\fP returned in this case would be 0.5.
.sp
.B
.sp
int xve_eval_float(id, string, value, error)
.br
long	id;
.br
char    *string;
.br
float	*value;
.br
char    *error;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP id: 10
The \fIvexpr\fP identifier
.sp
.IP string:
The string to be evaluated.
.IP value:
The float value returned.  
.IP error:
If the xve_eval_float() routine fails for some reason, the reason for failure
will be printed into this error string. It MUST be allocated by the caller,
and should be at least 1024 bytes long. The application may print out this
error message to correct the user.
.sp
.LP
=====================================================================
.bp
.sp 3
.NH 2 " xve_eval_string()"
.XS
      \*(SN   xve_eval_string()
.XE
.sp
.LP
This routine evaluates a string - at this point, this routine is still
undeveloped and simply returns the string that was passed in.
.sp
.B
.sp
int xve_eval_string(id, string, value, error)
.br
long	id;
.br
char    *string;
.br
float	*value;
.br
char    *error;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP id: 10
The \fIvexpr\fP identifier
.sp
.IP string:
The string to be evaluated.
.IP value:
The string value returned.  
.IP error:
If the xve_eval_string() routine fails for some reason, the reason for failure
will be printed into this error string. It MUST be allocated by the caller,
and should be at least 1024 bytes long. The application may print out this
error message to correct the user.
.sp
.LP
=====================================================================
.bp
.sp 3
.NH 2 " xve_list_variables()"
.XS
      \*(SN   xve_list_variables()
.XE
.sp
.LP
This routine prints the current list of variables for a particular \fIid\fP
into a file that has been opened for writing. 
.sp
.B
.sp
int xve_list_variables(id, file)
.br
long	id;
.br
FILE    *file;
.sp
.R
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP id: 10
The \fIvexpr\fP identifier
.sp
.IP file:
The open stream to the file to which the variable list is to be written.
The calling routine must open the file for writing before the call to
xve_list_variables(), and close it afterwards.  If the variable list is
to be written to standard out or standard error, "stdout" or "stderr" may
be passed in directly.
.bp
.sp 3
.NH 2 " xve_set_parent()"
.XS
      \*(SN   xve_set_parent()
.XE
.sp
.LP
This routine sets the child alternate variable list specified by the parent id.
This variable list will be searched when a variable is not found in the
current variable list.  If the parent's variable list "parent" is set, then
the procedure is repeated until either the variable is found or no more
variable lists are available to search.  In short, this routine provides
a method of expanding the scope of variables used.
.sp
.B
.sp
int xve_set_parent(id, parent)
.br
long	id;
.br
long    parent;
.br
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP id: 10
The \fIvexpr\fP identifier associated with the child variable list.
.sp
.IP parent:
The \fIvexpr\fP identifier associated with the parent variable list.
.sp
.LP
=====================================================================
.bp
.sp 3
.NH 2 " xve_unset_parent()"
.XS
      \*(SN   xve_unset_parent()
.XE
.sp
.LP
This routine unsets the parent variable list previously specified by
\fIxve_set_parent()\fP.  The result of a call to this routine is that if a 
a variable is not found in the variable list associated with the \fIvexpr\fP 
identifier, then no other variable list will be checked. In short, this 
routine provides a method of forcing variables used to be "local".
.sp
.B
.sp
int xve_unset_parent(id)
.br
long	id;
.br
.LP
-- -- -- -- -- -- -- -- -- -- -- -- -- -- --  explanation of arguments  -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
.sp
.IP id: 10
The \fIvexpr\fP identifier associated with the variable list.
.sp
.LP
=====================================================================
