Difference between revisions of "Expressions"

Latest revision as of 18:38, 21 April 2012

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.

The help patch of the ftm.mess external gives a complete overview of the use of FTM expressions in the FTM message box.

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.

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 the var keyword in 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 and 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) ... power operator
• ($1 % $2) ... modulo operator (integer and floating-point)
• ($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) ($1 ^ $2) ... bitwise logical operators (AND, OR, XOR) 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.

Function & Method Calls

Functions and FTM object methods are called by prefix expressions within parenthesis such as:

• (random) ... call the function random returning a floating-point random value between 0 and 1
• (sin ($phi * 3.141593)) ... call the function sin with the result of the given multiplication
• (cat $1 + $2) ... concatenate the two arguments to a single symbol with '+' in the middle
• (new fmat 7 7) ... call the new-function creating a new fmat with the given instantiation arguments
• (info functions) ... call the info system function printing a list of the available functions to the console

• ($myfmat set 0 0 1. 0.5 0.25 0.125) ... call the method set of an fmat with the given arguments (returns the fmat itself)
• ($myfmat iget 1.5 2.2) ... call the method iget of an fmat with the given arguments (returns an interpolated value)
• ((new fmat 7 7) fill 7) ... call fill method on a newly created fmat
• ($model[coeffs] random) ... call the random method of an fmat stored as element coeffs in the dict bound tomodel

If the first value within parenthesis is a symbol and the second (if any) is not an operator, the sub-expression is evaluated to the result of a function call interpreting the symbol as function name and the following (optional) values as function arguments. Note that the first argument of a function cannot be an operator since an expression such as '(random + 42)' would be evaluated as infix expression.

Similar to a function call, a method call of an FTM objects starts with the object followed by a symbol, the method name, and the optional arguments passed to the method.

The syntax of function and method calls can be summarized as follows:

• '(' <function name> [<function arguments> ... ] ')'
• '(' <object reference> <method name> [<method arguments> ... ] ')'