The Expression Evaluator Object
By Matt Galanto

Download the Console Program (v 1.01) (It's out-dated, but I figured I'd leave it up anyway.)

Index

Disclaimer

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.

Built-in Functions
Built-in Operators

Data Types

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 Iteration
This 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 Operator
This 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 Operator
This 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 Frame
This 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 Value
This 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 Error
This 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 Expression
Evaluate$( "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 Digits
StrDigits$( "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 String
ConvertString$( "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 Message
CurrentLoopIndex( "Expression Evaluator Object" )
The expression returns the last error message generated.

Get String Indicator
StringIndicator$( "Expression Evaluator Object" )
This expression returns the current string indicator character.

Convert Expression to Lowercase
LowerCase$( "Expression Evaluator Object", Expression )
This expression converts all letters outside of strings to lowercase letters.

Remove Whitespace from an Expression
RemoveWhiteSpace$( "Expression Evaluator Object", Expression )
This expression removes all whitespace (spaces, tabs, line breaks, etc.) outside of strings.

Find in Expression
FindInExpression( "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).