Difference between revisions of "Expressions"

Revision as of 14:10, 28 July 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

Named values are defined by FTM definitions using ftm.object. The names, always representing a single value, are used in expressions with a leading dollar ('$'), as for example:

• $x
• $myobject

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 elements to a single value.

Inside parentheses the following (sub-)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)'
• the definition of a variable local to the expression such as '(x := $1 * 3.14159)'
• 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.

Variables

Using the ':=' operator, variables can be defined that are strictly local to the expresssion such as '(x := $1 / 180.)'. Once a variable is defined it can be used referenced in the same way as other named values using the $-syntax ('$x').

A defined variable can be arbitrarily redefined using the ':=' operator.

Assignments

Using the '=' operator the following assignments are possible:

• ($myfmat = $yourfmat = $hisfmat - $herfmat * 0.5)
• ($myvar = $1 * 3.14159)

The assignment '($left = $right)' copies the content of the object named right into the object named left. In the case that both objects are of the same class the result is that both objects have identical values (although still different references). The left value of an assignment has to be an object (and cannot be a number nor a symbol).

These assignment are implemented using the method for 'set' with a single argument so that the expresssion '($left = $right)' is equvalent to the expression '($left set $right)'.

In the case that the left value of the assigment is a variable (e.g. defined with 'var 33' using ftm.object giving the name myvar) the assignment '($myvar = $1)' simply sets the value of the variable to the right value.

Increments & Co

Similar to the assignments

Function calls

Method calls