Difference between revisions of "Expressions"

Revision as of 16:54, 9 September 2007

The following documentation is fully valid from FTM 2.2.

FTM expressions are used in the following contexts

• the FTM message box ... the ftm.mess external
• FTM definitions ... the ftm.object external
• FTM externals ... arguments of any other FTM external
• the expr class/object ... a class just like fmat or dict representing an expression

The syntax of FTM expressions is an extension of the Max list and message syntax known from the Max message box and externals.

Single Values

The values in FTM expressions can be int, float, symbol or references to FTM object. Single values can be represended by the following items:

• a primitive value (int, float, symbol) such as '1', '2.3' and 'four'
• a named value such as '$myobj'
• an element of an object such as '$myobj[7]'
• a numbered argument such as '$1', '$2', etc.
• a tuple such as '{1 2.3 three $four}'
• an expression within parentheses such as '(1 + 2.3 / $4)'

Primitive values

Examples of primitive values are:

• 1 ... an int
• -2 ... an int
• 2.3 ... a float
• -4. ... a float
• 5.67e-4 ... a float
• .89 ... a float
• ten ... a symbol
• 11-12 ... a symbol (because no space!)
• -thirteen ... a symbol

Named values & variables

Named values and variables, always representing a single value, are used in expressions with a leading dollar ('$'), as for example:

• $x
• $myobject

Constant named values are defined by FTM definitions using ftm.object and one should think of them as constants that don't change in runtime but allow that a patch can be easily reconfigured for different parameters using FTM's initialization propagation mechanism.

In addition, there are two kinds of variables that use the same $-syntax in expressions as names values:

• declared variables (defined by FTM definitions using ftm.object)
• private properties of the expression (defined in the inspector of ftm.mess)

Even if a named value $mydict and a variable $myvar use the same $-syntax, they behave very differnet in some situations.

• named values cannot be used as left values of assignments (see below)
• objects and externals listen to named values

Elements and properties of objects

An element or a property of an object can be accessed with FTM expressions using brackets ('[ ]'), as for example:

• $myvec[0]
• $mymat[0 0]
• $mydict[x]
• {0 1 2.3 $four}[$1]
• $mysccob[pitch]

Numbered arguments

Numbered arguments ('$1', '$2', '$3' etc) are especially useful in the FTM message box and can be used in the expr object. In expressions of FTM definitions with ftm.object they don't make sense and generate an error.

Tuples

A tuple is an FTM object pretty much like an fmat or a dict and can show up in expressions with braces ('{ }'). The elements of a tuple are single values separated by blancs. The single value is a reference to a tuple. Since tuples are immutable objects (they don't have any methods that allow changing their size or thier values) they can be used in a similar way as lists, giving the possibilty to create tuples that contain tuples). Example of tuples are:

• {1 2.3 three $four}
• {1 2 3 {4 5 6} 7}
• {1 + 2 + 3 + 4} (7 elements!)

Lists

Evidently single values can be concatenated to argument lists (in the message box lists or messages) with spaces:

• 1 2.3 three
• 4 + 5.5 / six (this is a list of 5 elements)
• $myobj set 7 9.8 ten

Parentheses

Parentheses in FTM expressions – '(' and ')' – always will (try to) evaluate the contained sub-expressions to a single value.

Inside parentheses the following expressions are allowed:

• a value such as '(1)' or '($x)' or '($mydict[x])' (in which case the parentheses are useless)
• an infix expression using binary operators such as '(4 + 5.5 / $six)'
• an assignement such as '($x = 7)' or '($mydict[0] = zero)'
• an increment such as '($x += 0.5)' or '($myfmat[0 0] += 0.1)' (also '-=', '*=' and '/=')
• a function call such as '(random -90 0)'
• a method call such as '($myobj set 7 9.8 ten)'

Infix expressions (binary operators)

Binary operators such as '+' and '*' are evaluated in infix expressions within parentheses. The following operators are provided:

• ($1 + $2 - $3 * $4 / $5) ... basic artimetic operators (division has always floating-point result)
• ($1 % $2) ... modulo operator (integer and floating-point)
• ($1 ^ $2) ... power operator
• ($1 > $2) ($1 < $2) ($1 >= $2) ($1 <= $2) ($1 == $2) ($1 != $2) ... comparisons operators (result is 0 or 1)
• ($1 && $2) ($1 || $2) ... logical operators (AND and OR) applying to integer values (non-0 is true and 0 is false, result is 0 or 1)
• ($1 & $2) ($1 | $2) ... bitwise logical operators (AND and OR) applying to integer values
• ($1 << $2) ($1 >> $2) ... bitshift operators (LEFT and RIGHT) applying to integer values

Operators can be chained in which case the usual (C) precedence rules are applied.

Assignments, Increments, etc

The "=" can appear in the following operations:

• ($x = 42) ... assignment of a value to a variable
• ($mydict[two] = zwei) ... assignment of a value to an element of an object
• ($myfmat := $yourfmat) ... assignment of the content of an object from another
• ($x += 1) ... increment of a variable value
• ($myfmat[0 0] += 0.1) ... increment of an element of an object
• ($myfmat += $yourfmat) ... increment of an object by a value or an object (currently implemented for fmat only)

Variables are either very local to the FTM messages box (ftm.mess) or declared by FTM definitions (ftm.object) like other objects. One should think of a variable in the same way as an object with a single element that can be accessed simply by '$x' instead of '$x[0]'. Everything that can be done with an element of an object (e.g. mat or dict) can be also done with a variable.

While '=' assigns single values - including (references to) objects -to variables and elements, the ':=' operator applies to the content of the left operand assigning (or copying) all values of one object to another in the same way as the message set with a single argument.

Function calls

Method calls