Expressions: Difference between revisions
No edit summary |
No edit summary |
||
Line 1: | Line 1: | ||
==== Planimate Expression Language ==== | |||
Originally Planimate referenced data using a dialog. This has been augmented with an underlying textual expression language which enables more straightforward mathematical, boolean and string manipulation. | |||
An INI file default specifies whether references are specified using the text or dialog. You can switch between the two on the fly. | |||
The following operators and types can be used in an expression. They are listed in order of precedence - the higher ones in the list will evaluate before the lower ones (BODMAS rules are followed). | |||
{| cellspacing="1" cellpadding="1" border="1" style="width: 621px; height: 339px;" | {| cellspacing="1" cellpadding="1" border="1" style="width: 621px; height: 339px;" | ||
Line 122: | Line 126: | ||
| System provided access to properties and settings of the runtime environment | | System provided access to properties and settings of the runtime environment | ||
|- | |- | ||
| b.name | | b.name | ||
| Value | | Value | ||
| Global | | Global | ||
| Enables a labelled constant to be used instead of 0 or 1. 'name' can be FALSE, NO or OFF for 0 and TRUE, YES or ON for 1. This can help make code intent clearer without any impact on performance in looking up a normal attribute or label value. | | Enables a labelled constant to be used instead of 0 or 1. 'name' can be FALSE, NO or OFF for 0 and TRUE, YES or ON for 1. This can help make code intent clearer without any impact on performance in looking up a normal attribute or label value. | ||
|- | |- | ||
Line 130: | Line 134: | ||
| Value / String | | Value / String | ||
| Subsystem | | Subsystem | ||
| References a table cell. 'c' can be a column label for the table. | | References a table cell. 'c' can be a column label for the table. | ||
|- | |- | ||
| t.tablename | | t.tablename | ||
Line 148: | Line 152: | ||
|- | |- | ||
| | | | ||
t.tablename. | t.tablename. | ||
MatchedRow(value) | MatchedRow(value) | ||
| Table Row | | Table Row | ||
Line 157: | Line 161: | ||
|- | |- | ||
| | | | ||
t.tablename. | t.tablename. | ||
MatchedCell(keycol,col,key) | MatchedCell(keycol,col,key) | ||
| Value / String | | Value / String | ||
Line 166: | Line 170: | ||
|- | |- | ||
| | | | ||
t.tablename. | t.tablename. | ||
MatchedIndex(keycol,key) | MatchedIndex(keycol,key) | ||
| Value | | Value | ||
Line 189: | Line 193: | ||
| References a column of CDF variables for the distribution generator when it is in CDF mode | | References a column of CDF variables for the distribution generator when it is in CDF mode | ||
|- | |- | ||
| t.table[r][c].Block | | t.table[r][c].Block | ||
| Cell | | Cell | ||
| Subsystem | | Subsystem | ||
| Converts a cell reference at [r][c] so it can be used to specify the top left cell in a block operation. This operation is due for review and replacement. | | Converts a cell reference at [r][c] so it can be used to specify the top left cell in a block operation. This operation is due for review and replacement. | ||
|- | |- | ||
| t.table[r][c].Property | | t.table[r][c].Property | ||
| Value | | Value | ||
| Subsystem | | Subsystem | ||
| Converts a cell reference at [r][c] so it references the cell colour property data which enables the cells background and foreground colours to be individually set. | | Converts a cell reference at [r][c] so it references the cell colour property data which enables the cells background and foreground colours to be individually set. | ||
|- | |- | ||
| t.Dynamic(usename) | | t.Dynamic(usename) | ||
| Table | | Table | ||
| Subsystem | | Subsystem | ||
| Enables a table to be referenced by name dynamically. 'usename' is interpreted as a string to name the table. Note that matched references cannot be used with this kind of table reference. | | Enables a table to be referenced by name dynamically. 'usename' is interpreted as a string to name the table. Note that matched references cannot be used with this kind of table reference. | ||
|- | |- | ||
| t.tablename.RowCount | | t.tablename.RowCount | ||
| Value | | Value | ||
| Subsystem | | Subsystem | ||
| References the number of rows in the table | | References the number of rows in the table | ||
|- | |- | ||
| t.tablename.ColumnCount | | t.tablename.ColumnCount | ||
| Value | | Value | ||
| Subsystem | | Subsystem | ||
| References the number of columns in the table | | References the number of columns in the table | ||
|- | |- | ||
| s.item | | s.item | ||
| Entire item | | Entire item | ||
| Item | | Item | ||
| References an entire item. Normally items are implicit and do not need to be referenced for an interaction but this is provided for special item properties. | | References an entire item. Normally items are implicit and do not need to be referenced for an interaction but this is provided for special item properties. | ||
|- | |- | ||
| s.item.Carried(index,name) | | s.item.Carried(index,name) | ||
| Value | | Value | ||
| Item | | Item | ||
| References an attribue 'name' on an item being carried by the current item. 'index' specifies which item, it can be a number like 1 for the first item, s.ItemsCarried uses the system attribute to get the last item picked up or i.CARRYINDEX enables use of a modeller created attribute which must be named CARRYINDEX to determine which carried item the reference will refer to. | | References an attribue 'name' on an item being carried by the current item. 'index' specifies which item, it can be a number like 1 for the first item, s.ItemsCarried uses the system attribute to get the last item picked up or i.CARRYINDEX enables use of a modeller created attribute which must be named CARRYINDEX to determine which carried item the reference will refer to. | ||
|- | |- | ||
| (reference).objectproperty | | (reference).objectproperty | ||
| Value | | Value | ||
| Object | | Object | ||
| Interprets the value of 'reference' as an object index and returns | | Interprets the value of 'reference' as an object index and returns object property 'objectproperty' for that object, eg: p.fromportal.ObjectXPosition would retrieve the co-ordinate for the portal object referenced by a portal attribute 'fromportal'. | ||
|} | |} | ||
Notes: | Notes: | ||
Attribute/table/list names must be quoted if they contain spaces or characters apart from letters, numbers and underscore. Future versions will remove support for names with characters needing quotes. | Attribute/table/list names must be quoted if they contain spaces or characters apart from letters, numbers and underscore. Future versions will remove support for names with characters needing quotes. | ||
<br> | |||
l.labellistname["label text"] | l.labellistname["label text"] | ||
l.labellistname[whichlabel] | l.labellistname[whichlabel] | ||
where whichlabel is an expression giving a number from 1 to the number of labels in the list. | where whichlabel is an expression giving a number from 1 to the number of labels in the list. |
Revision as of 22:24, 31 July 2009
Planimate Expression Language
Originally Planimate referenced data using a dialog. This has been augmented with an underlying textual expression language which enables more straightforward mathematical, boolean and string manipulation.
An INI file default specifies whether references are specified using the text or dialog. You can switch between the two on the fly.
The following operators and types can be used in an expression. They are listed in order of precedence - the higher ones in the list will evaluate before the lower ones (BODMAS rules are followed).
number | Numeric constant |
reference | Attribute/cell/row/column/label reference, references data in a model |
"string" | Quoted text string |
'x' | Single ASCII character |
ref.prop | Property of a referenced datum |
[] | Index property for tables and lists |
function() | Internal expression function |
ref.func() | Property function of a referenced datum |
! | Logical NOT, !1=0, !123=0, !0=1 |
/ | Arithmetic divide |
% | Arithmetic modulus |
* | Arithmetic multiply |
+ | Arithmetic add |
- | Arithmetic subtract |
< | Logical less than |
<= | Logical less than or equal |
> | Logical greater than |
>= | Logical greater than or equal |
== | Logical equal (values follow PL's equality check rules) |
!= | Logical not equal |
^ | Logical exclusive-or 0^0=0, 0^1=1, 1^0=1, 1^1=0 |
&& | Logical AND |
|| | Logical OR |
& | String concatenate |
, | Comma separator for parameters to functions |
Brackets () can be used to force order, eg: (a + b) * c
Functions
As well as the operators above, a number of functions can be used. These can be nested and are particularly useful for complex math and string manipulation.
References
The most useful ability of expressions is the ability to reference multiple pieces of data in a Planimate model. Typically such a reference has a type letter, followed by a period then the datum's name.
Most operations expect numeric data. Some expect entire table rows, tables, columns, label lists or strings. In case where a string is needed, Planimate will automatically translate values to a string, following the format of the container of the value.
Example | Type | Context | comments |
---|---|---|---|
i.attribute | Value | Item | Attribute defined for an item class but uniquely settable for each |
p.attribute | Value / String | Subsystem | Attribute defined and only visible within a subsystem and the portal/subsystems contained therein. |
r.attribute | Value / String | Routine (Change) | Attribute defined within a routine (or subroutine). String attributes are not recursive within subroutines that call themselves but values are. |
s.attname | Value / String | System wide | System provided access to properties and settings of the runtime environment |
b.name | Value | Global | Enables a labelled constant to be used instead of 0 or 1. 'name' can be FALSE, NO or OFF for 0 and TRUE, YES or ON for 1. This can help make code intent clearer without any impact on performance in looking up a normal attribute or label value. |
t.tablename[r][c] | Value / String | Subsystem | References a table cell. 'c' can be a column label for the table. |
t.tablename | Table | Subsystem | Reference to an entire table |
t.tablename.Row(value) | Table Row | Subsystem | Reference to an entire table row |
t.tablename.Column(value) | Table Row | Subsystem | Reference to an entire table column |
t.tablename. MatchedRow(value) |
Table Row | Subsystem | Reference to an entire table row determined by search for a 'key' in a 'column' |
t.tablename. MatchedCell(keycol,col,key) |
Value / String | Subsystem | Reference to a table cell determined by search for a 'key' in a 'keycol'. The cell is taken from column 'col'. |
t.tablename. MatchedIndex(keycol,key) |
Value | Subsystem | The row number determined by search for a 'key' in a 'keycol' |
t.tablename.Remap(x,ycol) | Value | Subsystem | Lookup and interpolation of value from 'ycol' based on the row(s) which bound value 'x' in column 1 of the table. |
t.tablename.PDF(colindex) | Column | Subsystem | References a column of PDF variables for the distribution generator when it is in PDF mode |
t.tablename.CDF(colindex) | Column | Subsystem | References a column of CDF variables for the distribution generator when it is in CDF mode |
t.table[r][c].Block | Cell | Subsystem | Converts a cell reference at [r][c] so it can be used to specify the top left cell in a block operation. This operation is due for review and replacement. |
t.table[r][c].Property | Value | Subsystem | Converts a cell reference at [r][c] so it references the cell colour property data which enables the cells background and foreground colours to be individually set. |
t.Dynamic(usename) | Table | Subsystem | Enables a table to be referenced by name dynamically. 'usename' is interpreted as a string to name the table. Note that matched references cannot be used with this kind of table reference. |
t.tablename.RowCount | Value | Subsystem | References the number of rows in the table |
t.tablename.ColumnCount | Value | Subsystem | References the number of columns in the table |
s.item | Entire item | Item | References an entire item. Normally items are implicit and do not need to be referenced for an interaction but this is provided for special item properties. |
s.item.Carried(index,name) | Value | Item | References an attribue 'name' on an item being carried by the current item. 'index' specifies which item, it can be a number like 1 for the first item, s.ItemsCarried uses the system attribute to get the last item picked up or i.CARRYINDEX enables use of a modeller created attribute which must be named CARRYINDEX to determine which carried item the reference will refer to. |
(reference).objectproperty | Value | Object | Interprets the value of 'reference' as an object index and returns object property 'objectproperty' for that object, eg: p.fromportal.ObjectXPosition would retrieve the co-ordinate for the portal object referenced by a portal attribute 'fromportal'. |
Notes:
Attribute/table/list names must be quoted if they contain spaces or characters apart from letters, numbers and underscore. Future versions will remove support for names with characters needing quotes.
l.labellistname["label text"] l.labellistname[whichlabel]
where whichlabel is an expression giving a number from 1 to the number of labels in the list.
eg:
l._boolean["True"] - yields 1
l._boolean[2] - also yields 1 because "True" is the second member in this list
Expressions are "parsed" when OK is clicked so any syntax errors will be picked up during editing. However attribute names, table columns and label lookups are currently not determined until runtime. Future versions will see this optimised.