NAME
Math::Expression - Evaluate arithmetic/string expressions
SYNOPSIS
use strict;
use Math::Expression;
my $ArithEnv = new Math::Expression;
# Some/all of these read from a config file:
my $tree1 = $ArithEnv->Parse('ConfVar := 42');
my $tree2 = $ArithEnv->Parse('ConfVar * 3');
...
$ArithEnv->Eval($tree1);
my $ConfValue = $ArithEnv->EvalToScalar($tree2);
DESCRIPTION
This solves the problem of evaluating expressions read from config/... files without the use of eval
. String and arithmetic operators are supported, as are: conditions, arrays and functions. The name-space is managed (for security), user provided functions may be specified to set/get variable values. Error messages may be via a user provided function. This is not designed for high computation use.
DESCRIPTION
An expression needs to be first compiled (parsed) and the resulting tree may be run (evaluated) many times. The result of an evaluation is an array. You might also want to take computation results from stored variables.
For further examples of use please see the test program for the module.
Package functions
- new
-
This must be used before anything else to obtain a handle that can be used in calling other functions.
- SetOpt
-
The items following may be set. In many cases you will want to set a function to extend what the standard one does.
- PrintErrFunc
-
This is a printf style function that will be called in the event of an error, the error text will not have a trailing newline. The default is
printf STDERR
. - VarHash
-
The argument is a hash that will be used to store variables. If this is called several times it is possible to manage distinct name spaces. The name
EmptyList
should, by convention, exist and be an empty array; this may be used to assign an empty value to a variable. - VarGetFun
-
This specifies the that function returns the value of a variable as an array. The arguments are: 0 - the value returned by
new
; 1 - the name of the variable wanted. If no value is available you may return the empty array. - VarIsDefFun
-
This should return
1
if the variable is defined,0
if it is not defined. The arguments are the same as forVarGetFun
. - VarSetFun
-
This sets the value of a variable as an array. The arguments are: 0 - the value returned by
new
; 1 - the name of the variable to be set; 2 - the value to set as an array. The return value should be the variable value. - VarSetScalar
-
This sets the value of a variable as a simple scalar (ie one value). The arguments are: 0 - the value returned by
new
; 1 - the name of the variable to be set; 2 - the value to set as a scalar. The return value should be the variable value. - FuncEval
-
This will evaluate functions. The arguments are: 0 - the value returned by
new
; 1 - the name of the function to be evaluated; 2... - an array of function arguments. This should return the value of the function: scalar or array. - AutoInit
-
If true automatically initialise undefined values, to the empty string or '0' depending on use. The default is that undefined values cause an error, except that concatentation (
.
) always results in the empty string being assumed.Example:
my %Vars = ( EmptyList => [()], ); $ArithEnv->SetOpt('VarHash' => \%Vars, 'VarGetFun' => \&VarValue, 'VarIsDefFun' => \&VarIsDef, 'PrintErrFunc' => \&MyPrintError, 'AutoInit' => 1, );
- ParseString
-
This parses an expression string and returns a tree that may be evaluated later. The arguments are: 0 - the value returned by
new
; 1 - the string to parse. If there is an error a complaint will be made viaPrintErrFunc
and the undefined value returned. - CheckTree
-
This checks a parsed tree. The arguments are: 0 - the value returned by
new
; 1 - the tree to check. The input tree is returned. If there is an error a complaint will be made viaPrintErrFunc
and the undefined value returned. - Parse
-
This combines
ParseString
andCheckTree
. - VarSetFun
-
This sets a variable, see the description in &SetOpt.
- VarSetScalar
-
This sets a variable, see the description in &SetOpt.
- FuncValue
-
This evaluates a function, see the description in &SetOpt.
- EvalTree
-
Evaluate a tree. The result is an array, if you are expecting a single value it is the last (probably $#'th) element. The arguments are: 0 - the value returned by
new
; 1 - tree to evaluate; 2 - true if a variable name is to be returned rather than it's value (don't set this). You should not use this, use &Eval or &EvalToScalar instead. - Eval
-
Evaluate a tree. The result is an array, if you are expecting a single value it is the last (probably $#'th) element. The arguments are: 0 - the value returned by
new
; 1 - tree to evaluate. - EvalToScalar
-
Evaluate a tree. The result is a scalar (simple variable). The arguments are: 0 - the value returned by
new
; 1 - tree to evaluate.
Functions that may be used in expressions
The following functions may be used in expressions, if you want more than this write your own function evaluator and set it with &SetOpt; The POSIX package is used to provide some of the functions.
- int
-
Returns the integer part of an expression.
- round
-
Adds 0.5 to input and returns the integer part.
- split
-
Perl
split
, the 0th argument is the RE to split on, the last argument what will be split. - join
-
Joins arguments 1..$#, separating elements with the 0th argument.
- printf
-
The standard perl
printf
, returns the formatted result. - mktime
-
Passes all the arguments to
mktime
, returns the result. - strftime
-
Passes all the arguments to
strftime
, returns the result. - localtime
-
Returns the result of applying
localtime
to the last argument. - defined
-
Applies the
VarIsDefFun
to the last argument. - aindex
-
Searches the arguments for the last argument and returns the index. Return -1 if it is not found. Eg the following will return 1:
months := 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' aindex(months, 'Feb')
Variables
Variables can 3 three forms, there is no difference in usage between any of them. A variable name is either alphanumeric (starting with alpha), numeric (with a leading $
or ${
, or any non white space between {}
or one non white space after a $
:
Variable
$Variable
${Variable}
$123
${123}
$#
${###=##}
Literals
Literals may be: integers, floating point in the form nn.nn, strings bounded by matching singe or double quotes. Escapes are not looked for in literal strings.
Operators and precedence
The operators should not surprise any Perl/C programmer, with the exception that assignemnt is :=
. Operators associate left to right except for :=
which associates right to left. Precedence may be overridden with parenthesis. Unary +
and -
do not exist. <> is the same as !=
.
* / %
+ -
. String concatenation
> < >= <= == != <>
lt gt le ge eq ne
&&
||
? :
,
:=
Arrays
Variables are implemented as arrays, if a simple scalar value is wanted (eg you want to go +
) the last element of the array is used. Arrays may be built using the comma operator, arrays may be joined using ,
eg:
a1 := (1, 2, 3, 4)
a2 := (9, 8, 7, 6)
a1 , a2
yeilds:
1, 2, 3, 4, 9, 8, 7, 6
And:
a2 + 10
yeilds:
16
Arrays may be used to assign multiple values, eg:
(v1, v2, v3) := (42, 44, 48)
If there are too many values the last variable receives the remainder. If there are not enough values the last ones are unchanged.
Conditions
Conditional assignment may be done by use of the ternary operator:
a > b ? ( c := 3 ) : 0
Variables may be the result of a conditional, so below one of aa
or bb
is assigned a value:
a > b ? aa : bb := 124
AUTHOR
Alain D D Williams <addw@phcomp.co.uk>
Copyright and Version
Version "1.14", this is available as: $Math::Expression::Version.
Copyright (c) 2003 Parliament Hill Computers Ltd/Alain D D Williams. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Please see the module source for the full copyright.