Expressions

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)

FTM expressions provide the two assignment operators '=' and ':='. While '=' assigns single values to variables and elements of objects, the ':=' operator applies to the content of FTM object operands.

The operator ':=' copies the content of the right operand to the left operand. If the operands are of the same class the result of the operation are two identical objects, otherwise the left operand will represent as complete as possible the content of the right operand. The same effect can be obtained by a set message with a single argument.

In addition to the increment operator '+=', the operators '-=', '*=', and '/=' are provided. All four operators can be applied to variables and elements with primitive values as well as to objects (currently implemented for fmat only).

Note that (constant) named values cannot appear as left values of the simple assignement operand '=' while all other assignment operators can be applied so far the named value is an FTM object. Named primitive values cannot be left values of any assignment.