UCS::Expression - Compile and execute UCS expressions
use UCS::Expression;
$exp = new UCS::Expression $code; # compile UCS expression
@vars = $exp->needed; # variables needed to evaluate expression
$code = $exp->string; # retrieve sourcecode of UCS expression
$result = $exp->eval(@args); # evaluate UCS expression (argument list)
$result = $exp->eval($arghash); # named arguments (UCS variable names)
$exp = new UCS::Expression $code, "MU" => 10, ...; # expression with parameters
@params = $exp->params; # sorted list of parameter names
$value = $exp->param("MU"); # current value of parameter
$exp->set_param("MU", 1); # set parameter value
$exp2 = $exp->copy; # clone expression (e.g. when changing parameters)
$sub = $exp->code; # reference to compiled Perl expression
$result = $sub->(@args); # argument list is same as for eval()
$listref = $exp->evalloop($size, $arghash); # evaluate expression on full data set
$exp->evalloop(\@result, $size, $arghash); # directly writes to array @result
UCS expressions provide a convenient way to evaluate functions and conditions on the pair types in a data set. They consist of arbitrary Perl code with a syntax extension for direct access to data set variables: the character sequence %varname% (where varname is a legal UCS variable name) is replaced by the value of this variable (for the current pair type). See ucsexp for a more detailed description of UCS expressions and some cautionary remarks.
A UCS::Expression object represents a compiled UCS expression. The needed method returns a list of UCS variables that are required for evaluation of the expression. When derived variables are used in a UCS expression, they are automatically computed from the frequency signature.
The eval method is normally invoked with a (reference to a) hash of arguments, using UCS variable names as keys. It selects the variables needed to evaluate the UCS expression automatically from the hash, and ensures that all of them are present. Better performance is achieved by passing the required variables as an argument list in the correct order (as returned by needed).
The evalloop method greatly reduces overhead when a UCS expression is applied to a list of pair types (i.e. a full data set). It expects array references instead of simple variable values, and returns a reference to an array of the specified length. Optionally, evalloop can write directly to an existing array.
Compiles the UCS expression $code into a UCS::Expression object. If compilation fails for some reason, an undefined value is returned. Compiling a UCS expression involves the follwing steps:
@_.Since UCS::Expressions are comparatively small structures, it is usually not necessary to destroy them explicitly.
This form of the constructor defines a UCS expression with parameters, given as pairs of parameter name $param and default value $value. Parameters can be used like variables in the UCS expression. Their names are simple UCS identifiers, but must not be valid UCS variable names. The recommended convention is to write parameter names all in upper case.
Returns the names of all parameters in alphabetical order.
Returns the current value of parameter $name;
Set the parameter $name to the value $value. The new value will be used by all subsequent calls to the eval and evalloop methods.
Makes a clone of the UCS::Expression object $exp. Cloning is a fast operation and should always be used when changing the parameters of an expression shared between different modules (e.g. a registered association measure).
The needed methods returns a list of UCS variable names, corresponding to the data set variables needed to evaluate $exp.
Returns the original UCS expression represented by $exp as a string, and can be used to modify and recompile UCS expressions (especially those of built-in association measures). Note that $code is chomped, but may contain internal linebreaks (\n).
The eval method evaluates a compiled UCS expression on the data passed in $arghash, which must be a reference to a hash of variable names and the corresponding variable values. The necessary variables are extracted from $arghash by name, and the method dies with an error message unless all required variables are present. Unused variables are silently ignored.
The second form of the eval method avoids the overhead of variable name lookup and error checking. Here, the argument list @arg consists of the values of all required variables in the order defined by the needed method. The list @args is passed directly to the compiled Perl code, so that errors will usually go undetected.
The code method returns a code reference to the anonymous subroutine that resulted from compilation of the UCS expression. For an expression without parameters, the subroutine call
$result = $sub->(@args);
is equivalent to
$exp->eval(@args);
and further reduces overhead (by a small amount). It may be useful when the UCS expression is repeatedly applied, looping over a list of pair types. In most such cases, the evalloop method provides a better solution, though.
The evalloop method is used to apply $exp to an entire list of pair types (i.e. a data set) with a single call. Its invocation is similar to the firs form of the eval method. The additional parameter $size specifies the number of pair types to be processed. Each value in $arghash must be a reference to an array of length $size. The return value is a reference to an array of the same length.
The three-parameter form allows evalloop to write the results directly into an existing array, which may save a considerable amount of overhead when $size is large.
See the ucsexp manpage for an introduction to UCS expressions, as well as the UCS::SFunc and UCS::Expression::Func manpages for pre-defined functions that may be used in UCS expressions.
Copyright 2004 Stefan Evert.
This software is provided AS IS and the author makes no warranty as to its use and performance. You may use the software, redistribute and modify it under the same terms as Perl itself.