Main Help → All Commands → Language Reference → Expression
You can define variables in command files and do calculations on variables with expressions. Any argument to a command can be a variable or an expression.
Variables are defined and used in the form #varname
. Although not required, it is recommended that all variables begin in a number sign. This character is used to color code variables in commands and a couple of commands that take variable name itself as input require a number sign (or use it to distinguish it from object names). Beside that recommendation, the rules for a valid variable name:
A variable is initially defined in an assignment statement such as:
#x=1
where the variable is set equal to the right side of the equals sign which can be any valid expression.
Any valid variable can be a variable array by following it with an expression in square brackets
#y[#j]=1
where
#z[#i][#j]
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^
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:
#varname
, #x[2]
, #z[#i][#j]
, etc.) and the value of the variable is used. The variable must have been previously defined.return
- inserts a line-ending return charactertab
- inserts a tab. When using tabs to write output from internal scripts, the output field has a large number of tab stops spaced by 96 points.quote
- inserts a double-quote character (")pi
- inserts numerical value of π[ATOMIC]
's text must be quoted.
([EXPRESSION])
and the value of the [ATOMIC]
is the value of the included expression.sin([EXPRESSION])
) and the value of the [ATOMIC]
is the value of the function applied to the value of the expression. The following numeric expression are supported (in both scripts and in user defined functions used in input command files):
sin(x)
- sine of x in radianscos(x)
- cosine of x in radianstan(x)
- tangent of x in radiansasin(x)
- inverse sine with result in radiansacos(x)
- inverse cosine with result in radiansatan(x)
- inverse tangent with result in radiansexp(x)
- exponentiallog(x)
- natural loglog10(x)
- log base 10sqrt(x)
- square rootabs(x)
- absolute valuesinh(x)
- hyperbolic sinecosh(x)
- hyperbolic cosinetanh(x)
- hyperbolic tangentint(x)
- integer partmod(x,y)
- returns remainder of x/y and allows non-integers. For remainder after integer divsion (e.g., "x % y" in C++), use int(mod(x,y)) where y is an integer.erf(x)
- error function.erfc(x)
- error function complement.ramp(A,x)
- 0 for x<0, Ax for 0≤x≤1, and A for x>1cosramp(A,x)
- 0 for x<0, (A/2)(1-cos(πx)) for 0≤x≤1, and A for x>1box(A,x)
- 0 for x<0, A for 0≤x≤1, and 0 for x>1sinbox(A,x)
- 0 for x<0, A sin(πx) for 0≤x≤1, and 0 for x>1tri(x)
- 1-|x| for -1 < x < 1, 0 otherwisesgn(x)
- -1 for x<0, 0 for x=0, and +1 for x>0sign(x)
- 1 if x
is greater than zero or 0 if x
is negative or equal to zero.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)
.length(str)
- number of characters in a string.words(str)
- number of words in a string.firstWord(str)
- first word in a string.lastWord(str)
- last word in a string.removeFirstWord(str)
- string with first word removed.removeLastWord(str)
- string with last word removed.trim(str)
- 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 [2], 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)
- returns 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 [2] 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 [2] to delete all occurrences of string s1
.round(sting)
- the string argument should be a number and an integer separated by a space. For example, if #nmbr=34.6745
and #digits=2
the function round(#nmbr&" "digits)
will round the number to the provided number of digits past the decimal point. Here it would return 34.67.upperCase()
- convert string to upper case.lowerCase()
- convert string to lower case.titleCase()
- convert to string with capitalized words.@
sign and containing specific items separated by periods, such as "@key.TopLeft.x
" to evaluate to the x value of the keypoint named "TopLeft":
@key.#kname.x
) and the contents of #kname
will replace that item in the expression. #n[3]
but not #n[#i]
). Hint: if you need to index an array, you can define simple variable first (e.g., #ni=#n[#i]
) and then use that in an expression (e.g., @key.#ni.y
).#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.
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)
).