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. In string expressions, all top-level [op]'s must be for concatenation (&), although any [ATOMIC] can be a numeric expression enclosed in parentheses.
• [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 numeric functions are supported in both NairnFEAMPM and NairnFEAMPMViz:

• 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
• sinh() - hyperbolic sine
• cosh() - hyperbolic cosine
• tanh() - hyperbolic tangent
• exp() - exponential
• log() - natural log
• log10() - log base 10
• sqrt() - square root
• abs() - absolute value
• int() - integer part
• sign() - 1 if argument is positive or 0 if it is negative
• rand() - a random number between 0 and the argument.

The following numeric functions are supported only in NairnFEAMPM:

• erf() - error function.
• erfc() - error function complement.

Each string function takes a single string expression as an argument. Some functions embed subarguments within the evaluated single string expression. The following string functions are supported only in NairnFEAMPM:

• 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 1) 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.

To omit first subargument in chars(), offset(), or replace(), start with a back slash (e.g., chars(\c2\string)). To omit second argument, you can either omit it and its backslash (e.g., chars(c1\string)), but if string might contain a backslash, it is better to just omit the subargument (e.g., chars(c1\\string)).

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.

2. Alert: In NairnFEAMPMViz, an unsigned number cannot use exponential form (e.g., 4.56e-3) unless the entire expression is that number (e.g., #x=4.56e-3 is OK, but #x=2*4.56e-3 is not).