Mesmerizer Command Reference, Expressions

Expressions may only occur in a few places (currently just two, but this list may grow):

• The first parameter to executeif, that specifies the condition
• the second parameter to setvarex, that specifies the value to be assigned. 

Apart from these specific places, all other parameter positions are treated as simple strings (which may include variable expansions).  So unless you use those specific commands, the only reason to read further in this post is if you're having trouble sleeping.

Expressions are written using Reverse Polish Notation (RPN).  Any expression consists of a mix of values and operators; in RPN the values are written ahead of the operator that uses those values.  In a conventional expression, the way you'd indicate adding two values a, b and then multiplying by third value c would look like this:  "(a + b) * c".  In RPN, the same expression would be written as "a b + c *".  The main advantage of RPN is that it eliminates the need for both brackets and rules to determine the precedence of operators.

In the Mesmerizer's implementation of RPN, operators are named with words.  The following operators are currently defined:

Operator	Example use	Description
gt	x y gt	x > y
lt	x y lt	x < y
ge	x y ge	x ≥ y
le	x y le	x ≤ y
eq	x y eq	x = y (as integers)
streq	x y streq	x = y (as strings)
ne	x y ne	x ≠ y (as integers)
strne	x y strne	x ≠ y (as strings)
plus	x y plus	x + y
minus	x y minus	x - y
and	x y and	x ∧ y
or	x y or	x ∨ y
csv2l	x csv2l	convert comma-separated values to colon-demarked list
l2csv	x l2csv	convert colon-demarked list to comma-separated values
contains	x y contains	true if y is an element of colon-demarked list x
toseconds	x toseconds	convert interval x to integer number of seconds
asbool	x asbool	convert x to boolean (truth) value
asinteger	x asinteger	convert x to integer value
asinterval	x asinterval	convert x to a canonical interval
istrue	x istrue	synonym for asbool
isfalse	x isfalse	complement of istrue
isdefined	x isdefined	true if x is the name of a defined variable.  Note that 'x' should not include a leading "$" symbol - the name of the variable is needed, not its value
rand	x rand	return a random integer between 1 and x inclusive
select	aN .. a3 a2 a1 x y select	returns ax, in other words the xth a-value.  y is the total number of parameters to select, not counting y itself - in other words y must be N+1

select is an example of a vararg operator - one that takes a variable number of arguments.  Vararg operators will always take, as their nearest parameter, an integer specifying how many other parameters there are.  So in the case of select, if there are N alternatives to select from, and one more parameter to specify which should be selected, the total number of additional parameters is N+1, and this value must be specified as the final (nearest) parameter.

Some examples of RPN expressions and their meanings follow:

• "$x 1 gt" - true if the value of x is greater than 1.
• "$x 1 minus 0 gt" - true if "x-1 > 0", or the same as the previous example.
• "'$forbidden' '$sim' contains" - true if the current sim is in forbidden (assumed to be a list).  Note the use of single-quotes around the string variable expansions to keep them grouped as two single objects, even if their expansion(s) contain spaces.
• "$x 0 ge $x 5 le and" - true if (x >=0) && (x <= 5)
• "three two one 3 rand 4 select" - will return one of "one", "two" or "three"; the choice is random

Variables and expressions are expanded or evaluated as strings.  However, some contexts require particular types of values.  For example, the first parameter of the executeif command will be interpreted as a boolean value.  The strings "true" and "false" are the canonical boolean values.  Some other strings will be interpreted as "true":  "yes", "t", and non-zero integer;  all other strings will be considered to be "false".  

A colon-demarked list is simply a string representation of a list, where the elements are separated by colon characters (":"), and a colon also appears at the start and end of the string.   So a list containing "red", "green" and "blue" would be represented as: ":red:green:blue:".  The advantage of this format is that searching for an element within the list simply involves searching for a substring that is the desired element with a colon at either end.  So to search for "blue" in the above list, you would check to see whether the colon-demarked form contains ":blue:"  (and it does).