The scripting language allows expressions to do calculations with variables.
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]
- [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
- [ATOMIC] are the elements that are combined. The possible atomics are:
- An unsigned number (23, 2.234, 3e2, 4.56e-3, ...).2
- A variable (such as #varname, #x, #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 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).
- 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
- erf() - error function
- erfc() - error function complement
- exp() - exponential
- log() - natural log
- log10() - log base 10
- sqrt() - square root
- abs() - absolute value
- int() - integer part
- sign(x) - 1 if x is positive or 0 if it is negative
- sgn(x) - -1 if x <0, 0 if x=0, and +1 if x>0
- ramp(A,x) - 0 if x< 0, Ax if 0<x<1, A if x>1
- cosramp(A,x) - 0 if x< 0, (A/2)(1-cos(πx)) if 0<x<1, A if x>1
- box(A,x) - 0 if x< 0, A if 0<x<1, 0 if x>1
- sinbox(A,x) - 0 if x< 0, A sin(πx) if 0<x<1, 0 if x>1
- tri(x) - 1-|x| for -1 < x < 1, 0 otherwise
- rand(x) - a random number between 0 and x.
- cdfinv(x) - find inverse of the cumulative distribution function. For a random variable Z with mean m and standard deviation σ, the value of x such that the probability that Z<x is p is equal to x=m+σ*cdfinv(p).
Each string function takes a single string expression as an argument. Some functions embed sub-arguments delimited by back slashes within the evaluated single string expression. The following string functions are supported in both NairnFEAMPM and NairnFEAMPMViz:
- 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.
- trim() - string with leading and trailing white space removed.
- chars(c1\c2\string) - returns characters c1 to c2 (inclusive) of string (the first character is character 1). If omitted, c1 and c2 default to 1 and length of string, respectively. Thus char(c1\string) gets character 1 to the end and char(\c2\string) gets character 1 through c2. Either c1 or c2 can be <=0 to indicate character number relative to end of the string (e.g., 0 is last character, -1 is next to last, etc.)
- word(w1\string) - rreturns word w1 of string. If w1<=0, it specifies word number relative to end of the string (e.g., 0 is last word, -1 is next to last, etc.).
- 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)).
- 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.