expressions

Expressions apply operators to numeric and string operands, and return a result. They can be used in $[...] expression subs, the condition of /if and /while statements, the condition of /def -E, and as arguments to /return, /result, and /test commands.

Operands

• Integer constants like 42.
• Floating point constants ("floats", for short) containing a decimal point (12.3) or exponent (1e-2) or both (1.2e3).
• Time values of the form hours:minutes or hours:minutes:seconds (will be converted to integer seconds, and can be used anywhere integers are expected).
• Strings of characters, surrounded with quotes (", ', or `, with the same kind of quote on each end), like "hello world".
• Variable references (see below) like wrapsize.
• Variable substitutions (see below) like {wrapsize} and {1}.
• Macro substitutions like ${COMPRESS_SUFFIX}.
• Command substitutions like $(/listworlds -s).

Named variables may be accessed by simply using their name (with no leading '%'). This is called a variable reference, and is the preferred way of using a variable in an expression. The special substitutions (*, ?, #, n, Ln, Pn, R) may not be used this way.

Variable substitutions of the form "{selector}" and "{selector-default}" may be used. They follow the same rules as variable substitution in macros, except that there is no leading '%', and the '{' and '}' are required. The special substitutions (*, ?, #, n, Ln, Pn, R) are allowed.

Macro-style variable substitutions beginning with '%' may also be used, but are not recommended, since the multiple '%'s required in nested macros can quickly get confusing. It always easier to use one of the above methods.

Operators

(expression)

Parentheses, for grouping.

fn(args)

Perform function fn on args (see: functions).

!n

Boolean NOT (1 if n==0, otherwise 0).

+n

Unary positive (useful for converting a string to a number).

-n

Unary negative.

++v

Adds 1 to variable v and returns its new value.

--v

Subtracts 1 from variable v and returns its new value.

n * m

Numeric multiplication.

n / m

Numeric division.

n + m

Numeric addition.

n - m

Numeric subtraction.

n = m

Numeric equality.

n == m

Numeric equality.

n != m

Numeric inequality.

s =~ t

String equality (case sensitive).

s !~ t

String inequality (case sensitive).

s =/ t

String s matches glob pattern t.

s !/ t

String s does not match glob pattern t.

n < m

Numeric less than.

n <= m

Numeric less than or equal.

n > m

Numeric greater than.

n >= m

Numeric greater than or equal.

n & m

Boolean AND. m will be evaluated if and only if n is true.

n | m

Boolean OR. m will be evaluated if and only if n is false.

n ? a : b

n ? : b

Conditional. If n is nonzero, the result is the value of expression a; otherwise it is the value of expression b. If a is omitted, the value of n is used in its place.

v := s

Assignment. The identifier "v" refers to the variable in the nearest scope. If not found, a new variable is created at the global level, as if by /set.

a , b

Comma. Expressions a and b are evaluated; the result is the value of b. Only useful if a has some side effect.

The comparison operators return 0 for false, nonzero for true. The boolean operators (& and |) stop evaluating as soon as the value of the expression is known ("short-circuit"), and return the value of the last operand evaluated. This does not affect the value of the expression, but is important when the second operand performs side effects.

All operands will be automatically converted to the type expected by the operator.

• Integer to boolean: 0 is false, nonzero is true.
• Other to boolean: converted to integer, then to boolean.
• String to numeric: leading signs, digits, and exponents are interpreted as a numeric value; e.g., "12abc" becomes 12, "12.3junk" becomes 12.3, and "xyz" becomes 0.
• Integer to float: straightforward.
• Integer to string: straightforward.
• Float to integer: the fractional part is truncated.
• Float to string: decimal notation if the exponent is greater than -5 and less than 10, otherwise exponential notation.
• Enumerated variable to string: straightforward string value.
• Enumerated variable to integer: one integer stands for each of the allowed values. "Off" is always 0, "on" is always 1, etc. This makes (!visual) and (visual == 0) the same as (visual =~ 'off').
• Other (non-enumerated) variables are treated as strings, which are converted to another type if needed.

Examples

    /set X=5
    /set name=Hawkeye
    /set visual=1

    Expression		   Value   Comments
    ----		   -----   --------
    3 + X * 2		      13   3 + (5 * 2) = 13.
    "foo" =~ "bar"	       0   "foo" is not identical to "bar".
    name =/ 'hawk*'	       1   "Hawkeye" matches the glob "hawk*".
    X =~ "+5"		       0   X is interpreted as string "5".
    X == "+5"		       1   string "+5" is converted to integer 5.
    visual & (X > 0)	       1   visual is nonzero, AND %X is positive.

See: functions, /test, evaluation, patterns