Expression Syntax

The scripting language allows expressions to do calculations with variables.

Expression Definition

An expression combines any number of numbers, strings, variables, and functions with operators. An expression evaluates to a numeric or string value. The general, recursive definition of an expression is:

[EXPRESSION] = [sign] [ATOMIC] [op] [ATOMIC] [op] [ATOMIC] ... [op] [ATOMIC]

where

• [sign] is an optional leading sign of + or -
• [op] are operators that determine how the [ATOMIC]'s are combined. The options are:
  • + for addition
  • - for subtraction
  • * for multiplication
  • / for division
  • ^ for raising to a power
  • & for string concatenation
  When there are multiple operators, the operations are combined with the usual operator precedence of ^ followed by * and / followed by + and -. When there are multiple operators of the same precedence, they are evaluated left to right.
• [ATOMIC] are the elements that are combined. The possible atomics are:
  • An unsigned number (23, 2.234, 3e2, 4.56e-3, ...)
  • A variable (such as #varname, #x[2], #z[#i][#j], etc.) and the value of the variable is used. The variable must have been previously defined.
  • Text in quotes ("some text") and the value is the text after the quotes are removed.
  • Unquoted text and the value is all the text between the operators after all spaces have been removed. To include spaces in text [ATOMIC]'s, the text must be quoted.
  • Another expression in parenthesis or ([EXPRESSION]) and the value of the [ATOMIC] is the value of the included expression.
  • A function of an expression (such as sin([EXPRESSION])) and the value of the [ATOMIC] is the value of the function applied to the value of the expression. The allowed functions are listed below.
  • An "at" expression beginning in an @ sign and containing specific items separated by periods, such as "@key.TopLeft.x" to evaluate to the x value of the keypoint named TopLeft.
    • The available "at" expressions are defined elsewhere (for example, see Keypoint Command and Path Command).
    • Any of the period-delimited items can be a variable (such as @key.#kname.x) and the contents of #kname will replace that item in the expression.
    • Variables used as items can only be a single variable and not an expression. They also cannot be an array variable with a variable index (e.g., it can be#n[3] but cannot be #n[#i]). Hint: if you need to index an array with a variable, you can define simple variable first (e.g., #ni=#n[#i]) and then use that in an expression (e.g., @key.#ni.y).

Supported Functions

The following functions are supported. The argument if each function can be any expression.

• sin() - sine of argument in radians
• cos() - cosine of argument in radians
• tan() - tangent of argument in radians
• asin() - inverse sine with result in radians
• acos() - inverse cosine with result in radians
• atan() - inverse tangent with result in radians
• exp() - exponential
• log() - natural log
• log10() - log base 10
• sqrt() - square root
• abs() - absolute value
• sinh() - hyperbolic sine
• cosh() - hyperbolic cosine
• tanh() - hyperbolic tangent
• int() - integer part
• sign() - 1 if argument is positive or 0 if it is negative
• rand() - a random number between 0 and the argument.
• erf() - error function.
• erfc() - error function complement.
• length() - number of characters in a string.
• words() - number of words in a string.
• firstWord() - first word in a string.
• lastWord() - last word in a string.
• removeFirstWord() - string with first word removed.
• removeLastWord() - string with last word removed.
• chars(c1\c2\string) - returns characters c1 to c2 of string (the first character is character 1). c1 defaults to 1 if omitted (or less than 0) and c2 defaults to length of string (if omitted or larger). Thus char(c1\string) gets character 1 to the end and char(\c2\string) gets character 1 through c2.
• word(w1\string) - returns word w1 of string. If w1 is less than 1 or greater then number of words in string, an empty string is returned.
• offset(s1\c1\string) - returns offset of string s1 in string at or after character c1 (the first character is character 1) or returns 0 if string s1 is not found. c1 can be omitted to find s1 any place in string. The search is case insensitive.
• replace(s1\s2\string) - returns string where all occurrences of string s1 in string are replaced with string s2. s2 may be omitted to delete all occurrences of string s1.
• upperCase() - convert string to upper case.
• lowerCase() - convert string to lower case.
• titleCase() - convert to string with capitalized words.

Notes

1. An assignment command can be combined with an operator as in

   #x [op] = [EXPRESSION]
   

   which is equivalent to

   #x = #x [op] ([EXPRESSION])
   

   provided the variable is already a defined variable. It is an error if the variable has not previously been defined.