(→Infix Expressions and Binary Operators) |
|||
| (100 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
FTM expressions are used in the following contexts | FTM expressions are used in the following contexts | ||
| − | * the FTM message box ... ''ftm.mess'' | + | * the FTM '''message box''' ... the [[Message Box | ''ftm.mess'']] external |
| − | * FTM definitions ... ''ftm.object'' | + | * FTM '''definitions''' ... the [[Object and Value Definitions | ''ftm.object'']] external |
| − | * the expr class/object | + | * FTM '''externals''' ... arguments of any other FTM external |
| + | * the [[expr demystified | expr class/object]] a class just like ''fmat'' or ''dict'' representing an expression | ||
| − | The syntax of FTM expressions | + | The syntax of FTM expressions is an extension of the Max list and message syntax known from the Max message box and externals. |
| − | The | + | The help patch of the [[Message Box | ''ftm.mess'']] external gives a complete overview of the use of FTM expressions in the FTM message box. |
== Single Values == | == Single Values == | ||
| Line 12: | Line 13: | ||
The values in FTM expressions can be int, float, symbol or references to FTM object. | The values in FTM expressions can be int, float, symbol or references to FTM object. | ||
Single values can be represended by the following items: | Single values can be represended by the following items: | ||
| − | * a '''''primitive''''' value (int, float, symbol) such as '1', '2.3' and ' | + | * a '''''primitive''''' value (int, float, symbol) such as '1', '2.3' and 'four' |
* a '''''named''''' value such as '$myobj' | * a '''''named''''' value such as '$myobj' | ||
* an '''''element''''' of an object such as '$myobj[7]' | * an '''''element''''' of an object such as '$myobj[7]' | ||
* a numbered '''''argument''''' such as '$1', '$2', etc. | * a numbered '''''argument''''' such as '$1', '$2', etc. | ||
* a '''''tuple''''' such as '{1 2.3 three $four}' | * a '''''tuple''''' such as '{1 2.3 three $four}' | ||
| − | * an expression | + | * an expression within '''''parentheses''''' such as '(1 + 2.3 / $4)' |
| − | Examples of | + | === Primitive Values === |
| + | Examples of ''primitive values'' are: | ||
* 1 ... an int | * 1 ... an int | ||
* -2 ... an int | * -2 ... an int | ||
| Line 30: | Line 32: | ||
* -thirteen ... a symbol | * -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 | * $x | ||
* $myobject | * $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 | ||
| − | An '''' | + | === 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] | * $myvec[0] | ||
* $mymat[0 0] | * $mymat[0 0] | ||
* $mydict[x] | * $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 == | == Lists == | ||
| − | + | Evidently single values can be concatenated to argument lists (in the message box ''lists'' or ''messages'') with spaces: | |
* 1 2.3 three | * 1 2.3 three | ||
* 4 + 5.5 / six (this is a list of 5 elements) | * 4 + 5.5 / six (this is a list of 5 elements) | ||
* $myobj set 7 9.8 ten | * $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 to''model'' | ||
| − | + | 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> ... ] ')' | ||
| − | .. | + | [[Category:FAQ]] [[Category:Expressions]] [[Category:ftm.mess]] [[Category:ftm.object]] [[Category:FTM Documentation]] |
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.
Contents
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> ... ] ')'