vexpr(3)

NAME
vexpr - expression parser

DESCRIPTION
vexpr 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 vexpr 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 vexpr 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.

Similar to the xvgraphics library, the vexpr defines the area of application with an identification number, or id. This id is of type long, and must be passed to all routines in vexpr. 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 vexpr 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 vexpr 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.

For an explanation of all the following routines in greater detail, with explanations of all arguments to each routine, see the section on vexpr in the Khoros Programmer's Manual, chapter 8, Libraries.

AVAILABLE ROUTINES

xve_eval_int()

This routine initializes internal structures and variables used by the vexpr library. It MUST be called prior to ANY other calls to the vexpr library. It has no parameters.

xve_eval_int()

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 error string.

The string passed in will indicate which function xve_eval_int() is to perform, and the integer value 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 value returned will be 10. Later, suppose xve_eval_int() is called again with the same id, with a string 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 value returned in this case would be 25.

int xve_eval_int(id, string, value, error)
long id;
char *string;
int *value;
char *error;

xve_eval_float()

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 error string.

The string passed in will indicate which function xve_eval_float() is to perform, and the float value 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 value returned will be 0.1. Then, xve_eval_float is called again with a string of "y = 0.9"; now the value returned is 0.9. Finally, suppose xve_eval_float() is with the with a string 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 value returned in this case would be 0.5.

int xve_eval_float(id, string, value, error)
long id;
char *string;
float *value;
char *error;

xve_eval_string()

This routine evaluates a string - at this point, this routine is still undeveloped and simply returns the string that was passed in.

int xve_eval_string(id, string, value, error)
long id;
char *string;
char *value;
char *error;

xve_list_variables()

This routine prints the current list of variables for a particular id into a file that has been opened for writing.

int xve_list_variables(id, file)
long id;
FILE *file;

xve_set_parent()

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.

int xve_set_parent(id, parent)
long id;
long parent;

xve_unset_parent()

This routine unsets the parent variable list previously specified by xve_set_parent(). The result of a call to this routine is that if a a variable is not found in the variable list associated with the vexpr identifier, then no other variable list will be checked. In short, this routine provides a method of forcing variables used to be "local".

int xve_unset_parent(id)
long id;

For more information on the use of these utilities available via the vexpr library, see the documentation on vexpr found in the Khoros Programming Manual.

AUTHORS
Mark Young

COPYRIGHT
Copyright 1990, University of New Mexico. All rights reserved.