The author of this extension makes no claims concerning the
fitness of this extension for any purpose whatsoever, and makes
no gurantees, written or implied, of its level of security and
safety to authors or to end users in any respect. You agree to
use this extension at your own risk and to hold the author
harmless in any event.

The
Basics

The Expression Evalutor Object works very much like the
Multimedia Fusion's own Expression Evaluator. It takes an
expression, such as sin(log(12*54+16)+1.5)/16, and evaluates it.
This object supports both functions and operators. A list of all
of the functions and operators is provided below.

Numbers:Numbers are numbers (-12, 16, 3.5, 0.6,
-2,34e-012,6.022e+023 etc.). There are two sub-types of numbers:
integers and floats. Integers are numbers without decimal parts.
They have a limited range (same range as a signed long in C++).
Floats are numbers decimal parts and have a much larger range
(same range as signed double in C++). Certain operations act
differently on integers than on floats. If an operator does, it
will be noted in the operator's description.Strings:Strings are enclosed by the string
indicator character that you set. For our purposes here, we
will use " as the string indicator character.
Examples of strings are "Hi", "Matt", "I
aM kEwL". Using \ followed by the string indicator
will allow you to use the string indicator character in
a string. For example, "Hi, \"Matt\", how are
you?" is a completely acceptable string. A backslash plus
another character is known as an escape sequence. Other
meaningful escape sequences are \\ (backslash character), \a
(alarm character), \b (backspace character), \f (form feed
character), \n (newline character), \r (return character), \t
(tab character), and \v (vertical tab character). Any other
sequence evaluates to the second character. For example, \c is c.
These escape sequences are really only useful when converting an
ExpEval string to an MMF string.Lists:Lists are enclosed in {} with elements
separated by commas: {1,2,3,7.8,-5} or
{"Hi","Yo","word","I love
you!!!"}. While you can mix numbers and string in a list,
it's not a good idea. It limits what operations you can perfrom
on the list.

Variables,
Functions, and Operators

Variables: Variables can be defined using the assignment
operator (=) or the defintion operator (:=). Variables have no
restrictions on type. The same variable can store Numbers,
Strings, and Lists at various times throughout it's life-span.
Variables are subject to a form of scope, which I call Function
Scope. Variables defined inside a user-defined function or inside
a user-defined operation are only available to that function.
These are called local variables. If that function/operation
calls another function or operation, the local variables of the
calling function/operation are NOT available to the called
function/operation. When a function/operation returns, its local
variables are deleted. Global variables are those variables
defined outside of any functions or operations. These variables
are available to all functions and operations. A local variable
can be defined with the same name as a global variable without
affecting the global variable. This does, however, make the
global variable of that name inaccessible while the local
variable exists.Functions: Functions are processes that may or may or may
not take data (in the form of parameters) and manipulate it to
get some result. Functions follow the format function_name(parameters),
where the parameters are in the form (p1, p2, p3, etc.).
You may define your own user-defined functions. There are two
types of user-defined functions: normal functions and MMF
functions. Normal functions are simply expressions that the
object will evaluate when the function is called. MMF functions
allow you to use MMF events to manipulate the parameters and
return a value.Operators: Operators are processes that take data (in the
form of parameters) and manipulate it to get some result.
Operations follow the format p1 operator p2. You
may define your own user-defined operators. There are two types
of user-defined operators: normal operators and MMF operators.
Normal operators are simply expressions that the object will
evaluate when the operator is used. MMF operators allow you to
use MMF events to manipulate the parameters and return a value.

Conditions

On Function
This condition is used to denote an event that will be executed
when the specified function is called from an expression.

On Operation
This condition is used to denote an event that will be executed
when the specified operator is used in an expression

First IterationThis condition returns true if the current MMF function
or operator is in it's first iteration, that is, if no Iterate
action has been used yet.

On Error (immediate)This condition will return true if an error has occured.
Events with this condition will be executed as soon as an error
occurs in an expression evaluated in an action. The events are
executed even before the erroneous expression returns. For
expressions evaluated in an expression, the events will be
executed at the end of the current program loop.

Error Has Occured (not immediate)This condition will return true if an error has occured.
It will return true until errors are cleared.

Actions

Define a Function
This action allows you to define you own function. In the
expression for the function, the parameters are p1, p2, p3,
etc. When you call your function, using the usual format function_name(parameters),
it will evaluate your function using your parameters in your
expression.

Define an OperatorThis action allows you to define you own operator. In
the expression for the operation, the parameters are p1
and p2. When you use your operator, using the usual
format p1 operator p2, it will evaluate your operation
using the parameters in your expression.

Define an MMF Function
This action allows you to define you own MMF function. The
"Evaluate Parameters?" option allows you to have the
object evaluate the parameters. If you choose not to do this,
your parameters may be expressions, variable names, etc. The
parameters are stored in the local variables p1, p2,
p3, etc. When you call your function, using the usual format
function_name(parameters), MMF will execute all
events with the proper On Function condition. The value returned
in the Return Value action will be the return value of your
function.

Define an MMF OperatorThis action allows you to define you own MMF operator.
The "Evaluate Parameters?" option allows you to have
the object evaluate the parameters. If you choose not to do this,
your parameters may be expressions, variable names, etc. The
parameters are stored in the local variables p1 and p2.
When you call your operation, using the usual format p1
operator p2, MMF will execute all events with the proper On
Operation condition. The value returned in the Return Value
action will be the return value of your operation

Iterate Current MMF Function or Operator
This action tells the object to run through the current
function's or operator's events again after finishing the current
iteration.

Redraw FrameThis action forces MMF to immediately redraw the frame.
This action allows you to update the screen while inside an MMF
function or operator loop.

Return a ValueThis action sets the return value of the current MMF
function or operation to the specified value. It all also ends
the current MMF function or operation, so no more events for that
function or operation will be executed.

Generate an ErrorThis action generates an error with the specified
message. It is designed to be used in MMF functions and
operations. It all also ends the current MMF function or
operation, so no more events for that function or operation will
be executed.

Set String Indicator
This action allows you to set the string indicator character. If
you pass a string, the action will take just teh first character
of that string. If you pass an empty string, the string indicator
character will not be changed. While you can set the string
indicator character to anything, you should bear in mind that if
you set it to something like 7, you won't be able to use it as a
number, and any operations or functions that return a number that
contains a 7 will cause you problems. You're best bet is to stick
with either ' or " as the string indicator character.

Clear Errors
This action clears errors. It resets the Last Error Message, and
makes any Error Has Occured (not immediate) conditions return
false.

Expressions

Evaluate ExpressionEvaluate$( "Expression Evaluator Object",
Expression )
This expression returns the result of an expression. The result
is always returned as an MMF string. MMF Functions and MMF
operators cannot be used in this expression.

Convert Integer to String of So Many DigitsStrDigits$( "Expression Evaluator Object",
Number to Convert, Number of Digits)
This expression returns the Number to Convert as a
string of at least Number of Digits digits.

Convert ExpEval String to MMF StringConvertString$( "Expression Evaluator
Object", ExpEval String )
This expression takes an ExpEval style string (using string
indicator characters and whatnot) and converts it to an MMF style
string for direct use in other MMF objects by stripping the
opening and closing string indicators and by evaluating any
escape sequences.

Get Last Error MessageCurrentLoopIndex( "Expression Evaluator Object" )
The expression returns the last error message generated.

Find in ExpressionFindInExpression( "Expression Evaluator
Object", Expression, Substring, Starting Point, Ending
Point)This expression returns the starting location of the
specified substring in the specified expression,
starting at the starting location and ending at the ending
location. If the ending location is less than the starting
location, this will search to the end of the expression.
It will not search inside lists or strings. If the substring is
not found, the function returns -1. The first location in the
string is 0 (the first character).