Expressions: Difference between revisions

From Planimate Knowledge Base
Jump to navigation Jump to search
m (1 revision(s))
No edit summary
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
'''<font face="Arial">Planimate Expression Language<br /> </font>'''<br /> Planimate supports numerical expressions. These can be entered in an Attribute Reference which has been configured as "Expression". They enable more complex mathematical and logical formulae to be expressed in an algebraic form rather than over multiple lines of routine code.
==== Planimate Expression Language ====


Previous versions of Planimate referenced data using a dialog based selector. This has been augmented with an underlying textual expression language which enables more straightforward mathematical, boolean and string manipulation.


The following mathematical and logical operators 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.
The following lists the operators and types available 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;"
|-
| 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
|-
| []
| Denotes an entire item table reference
|-
| function()
| Internal expression function
|-
| ref.func()
| Property function of a referenced datum
|-
| &nbsp;!
| Logical NOT,&nbsp;!1=0,&nbsp;!123=0,&nbsp;!0=1
|-
| /
| Arithmetic divide
|-
| &nbsp;%
| Arithmetic modulus
|-
| *
| Arithmetic multiply
|-
| +
| Arithmetic add
|-
| -
| Arithmetic subtract
|-
| &lt;
| Logical less than
|-
| &lt;=
| Logical less than or equal
|-
| &gt;
| Logical greater than
|-
| &gt;=
| Logical greater than or equal
|-
| ==
| Logical equal (values follow PL's equality check rules)
|-
| &nbsp;!=
| Logical not equal
|-
| ^
| Logical exclusive-or 0^0=0, 0^1=1, 1^0=1, 1^1=0
|-
| &amp;&amp;
| Logical AND
|-
| &#124;&#124;
| Logical OR
|-
| &amp;
| String concatenate
|-
| ,
| Comma separator for parameters to functions
|}


() Enforce precedence<br /> ! Not operator. Logical not of following value. !0 = 1, !1 = 0, !!3.5 = 1<br /> * / % Multiply, divide and remainder of values either side<br /> + - Add, subtract of values either side<br /> &lt; &lt;=<br /> &gt; &gt;= Arithmetic comparison of values, yields 1 for true, 0 for false<br /> == != Test for values being equal, not equal (following PL precision rules)<br /> ^ Logical (not bitwise) exclusive OR of 2 values, 1 ^ 0 = 1, 1 ^ 1 = 0. Any non zero value is 1<br /> &amp;&amp; Logical AND of 2 values. Any non zero value is considered 1.<br /> || Logical OR of 2 values. Any non zero value is considered 1.
<br>  


Brackets () can be used to force order, eg:&nbsp;&nbsp; (a + b) * c


Hence expressions follow BODMAS rules so a*b+c*d will evaluate as (a*b)+(c*d). Unneeded brackets are generally removed however brackets are placed around complex operations around &amp;&amp; and || to aid in legibility.
==== Functions  ====


As well as the operators above, a number of [[Functions|functions]] can be used. These can be nested and are particularly useful for complex math and string manipulation.


As well as the operators above, the following functions are available.
==== Data References  ====


The most useful ability of expressions is the ability to reference data within a Planimate model. Typically such a reference has a type letter, followed by a period then the datum's name.


sqrt(x) square root<br /> sqr(x) square (x * x)<br /> fabs() removes the sign of x so its always positive<br /> round(x) rounds x to closest integer<br /> trunc(x) removes fraction of x, leaving just integer part<br /> ceil(x) lowest integer which is &gt;= x<br /> floor(x) highest integer which is &lt;= x<br /> exp(x) e to the power of x<br /> ln(x) natural log of x<br /> log10(x) base 10 log of x<br /> pow10(x) 10 to the power of x<br /> pow2(x) 2 to the power of x
Most operations expect numeric data. Some expect entire table rows, tables, columns, label lists or text strings. In case where text is needed, Planimate will automatically translate values to their textual form following the format of the container of the value. The $= operation will translate text strings into the format of the container (as well it can) if its not a text format.<br>  


{| cellspacing="1" cellpadding="1" border="1" style="width: 621px; height: 339px;"
|-
! Example
! Type
! Context
! comments
|-
| i.attribute
| Value
| Item
| Attribute defined for an item class but uniquely settable for each
|-
| p.attribute
| Value / Text
| Subsystem
| Attribute defined and only visible within a subsystem and the portal/subsystems contained therein.
|-
| r.attribute
| Value / Text
| 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 / Text
| 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 / Text
| Subsystem
| References a table cell. 'c' can be a column label for the table, such as 'c.Origin' or an index.&nbsp;
|-
| t.tablename[]
| Table
| Subsystem
| Reference to an entire table
|-
| t.tablename[].Row(value)
| Row
| Subsystem
| Reference to an entire table row
|-
| t.tablename[].Column(value)
| Column
| Subsystem
| Reference to an entire table column
|-
|
t.tablename.


cos(x) <br /> sin(x) trig functions, x in radians<br /> tan(x)  
&nbsp;MatchedRow(keyc,key)  


| Row
| Subsystem
| Reference to an entire table row determined by search for a 'key' in column 'keyc'
|-
|
t.tablename[].


acos(x)<br /> asin(x) arc-trig functions, return radians<br /> atan(x)
&nbsp;MatchedCell(keyc,c,key)  


| Value / Text
| Subsystem
| Reference to a table cell determined by search for a 'key' in column 'keycl'. Once the row is found the cell is taken from column 'c'.
|-
|
t.tablename.


Attribute references:
&nbsp;MatchedIndex(keyc,key)


| Value
| Subsystem
| The row number determined by search for a 'key' in column 'keyc'
|-
| &nbsp;t.tablename[].Remap(x,yc)
| Value
| Subsystem
| Lookup and interpolation of value from column 'ycl' based on the row(s) which bound value 'x' in column 1 of the table.
|-
| &nbsp;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.
|-
| &nbsp;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.
|-
| &nbsp;t.tablename[].RowCount
| Value
| Subsystem
| References the number of rows in the table
|-
| &nbsp;t.tablename[].ColumnCount
| Value
| Subsystem
| References the number of columns in the table
|-
|
t.tablename[].ColumnIndex("label")


Expressions can also reference data in a Planimate model:<br /><br /><u>Attributes:</u>
| Value
| Subsystem
| Resolves the index of column 'label' in the table.
|-
|
i.itemtablename[]


| Table
| Item
| Enables access to an [[Item Table References|item table reference]] which can be dynamically associated with a table in the model and carried to another part of the model by the item, where that table may not be in scope.
|-
| &nbsp;l.labellistname["label"]<br>
| Value<br>
| Subsystem<br>
| Resolves the numerical index associated with text 'label' in the label list 'labellistname'.<br>
|-
| &nbsp;l.labellistname[value]<br>
| Value<br>
| Subsystem<br>
| Resolves the numerical index associated with a label in 'labellistname' where 'value' counts labels starting at 1 for the first.<br>
|-
| &nbsp;l.labellistname
| LabelList
| Subsystem
| Enables a reference to an entire label list where such a reference is required. Note that any other reference involving a label list, either explicitly (like l._colors["black"]) or implicitly, (like p.portalatt where portalatt is formatted for a label list) can be used where a list reference is expected.
|-
| &nbsp;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(ind,name)
| Value
| Item
| References an attribue 'name' on an item being carried by the current item. 'ind' 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.
|-
| &nbsp; (ref).ObjectProperty
| Value
| Object
| Interprets the value of 'ref' 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'.
|}


i.attname item attribute<br /> p.attname portal attribute<br /> r.attname routine attribute<br /> s.attname system attribute<br />
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 so update older models accordingly.


If "attname" contains spaces or non alphabetic/numeric symbols, it must be quoted, otherwise the<br /> quotes can be left out.
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 not verified until runtime.&nbsp;


 
[[Category:Attribute]] [[Category:Labellist]] [[Category:Routine]] [[Category:Table]]
eg:
 
 
p.attribute<br /> i."next location"<br /> s.clock<br /> s."run number"<br /><br /><u>Tables:</u>
 
 
Table cells can be referenced as follows:
 
 
t.tablename[rowindex][columnindex]
 
 
tablename must be quoted, as for attname above.<br /> rowindex and columnindex can be any valid expression.<br /> In addition, if columnindex is quoted, it is treated as a column label.
 
 
eg:
 
 
t.mytable[i.whichrow][3]<br /> t.mytable[i.whichrow + 1]["Destination"]<br /> t."Table With Spaces In Name"[i.location][t.mappingtable[i.location]["MapColumns"]]<br /><br /><br /><u>Labels</u>
 
 
The index of a label can be read as follows
 
 
l.labellistname["label text"]
 
 
or the index of a specified member in a label list can be read as follows
 
 
l.labellistname[whichlabel]
 
 
where whichlabel is an expression giving a number from 1 to the number of labels in the list.
 
 
eg:<br /> l._boolean["True"] - yields 1<br /> l._boolean[2] - also yields 1 because "True" is the second member in this list <br />
 
 
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.<br /><br />
----
[[Category:Attribute]]
[[Category:Labellist]]
[[Category:Routine]]
[[Category:String]]
[[Category:Table]]
[[Category:Expression]]
[[Category:Release Note]]
<font size="2">idkbase note 316</font>

Latest revision as of 19:04, 22 April 2010

Planimate Expression Language

Previous versions of Planimate referenced data using a dialog based selector. This has been augmented with an underlying textual expression language which enables more straightforward mathematical, boolean and string manipulation.

The following lists the operators and types available 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
[] Denotes an entire item table reference
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.

Data References

The most useful ability of expressions is the ability to reference data within 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 text strings. In case where text is needed, Planimate will automatically translate values to their textual form following the format of the container of the value. The $= operation will translate text strings into the format of the container (as well it can) if its not a text format.

Example Type Context comments
i.attribute Value Item Attribute defined for an item class but uniquely settable for each
p.attribute Value / Text Subsystem Attribute defined and only visible within a subsystem and the portal/subsystems contained therein.
r.attribute Value / Text 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 / Text 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 / Text Subsystem References a table cell. 'c' can be a column label for the table, such as 'c.Origin' or an index. 
t.tablename[] Table Subsystem Reference to an entire table
t.tablename[].Row(value) Row Subsystem Reference to an entire table row
t.tablename[].Column(value) Column Subsystem Reference to an entire table column

t.tablename.

 MatchedRow(keyc,key)

Row Subsystem Reference to an entire table row determined by search for a 'key' in column 'keyc'

t.tablename[].

 MatchedCell(keyc,c,key)

Value / Text Subsystem Reference to a table cell determined by search for a 'key' in column 'keycl'. Once the row is found the cell is taken from column 'c'.

t.tablename.

 MatchedIndex(keyc,key)

Value Subsystem The row number determined by search for a 'key' in column 'keyc'
 t.tablename[].Remap(x,yc) Value Subsystem Lookup and interpolation of value from column 'ycl' based on the row(s) which bound value 'x' in column 1 of the table.
 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

t.tablename[].ColumnIndex("label")

Value Subsystem Resolves the index of column 'label' in the table.

i.itemtablename[]

Table Item Enables access to an item table reference which can be dynamically associated with a table in the model and carried to another part of the model by the item, where that table may not be in scope.
 l.labellistname["label"]
Value
Subsystem
Resolves the numerical index associated with text 'label' in the label list 'labellistname'.
 l.labellistname[value]
Value
Subsystem
Resolves the numerical index associated with a label in 'labellistname' where 'value' counts labels starting at 1 for the first.
 l.labellistname LabelList Subsystem Enables a reference to an entire label list where such a reference is required. Note that any other reference involving a label list, either explicitly (like l._colors["black"]) or implicitly, (like p.portalatt where portalatt is formatted for a label list) can be used where a list reference is expected.
 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(ind,name) Value Item References an attribue 'name' on an item being carried by the current item. 'ind' 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.
  (ref).ObjectProperty Value Object Interprets the value of 'ref' 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 so update older models accordingly.

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 not verified until runtime.