Expressions and Mathematical Functions

Expression Evaluation

There are a number of commands that expect an expression as an argument, and evaluate it later in time. In these commands, expressions are typically provided in curly braces. Examples of such commands are the control structures, such as foreach, for, while, and if (see Section Control Structures).

Alternatively, expressions can be directly evaluated. That is, the expression is evaluated, and, after the evaluation took place, the expression is replaced with the result of the expression. This is done by providing the expression inside of round braces: (...), which trigger an expression substitution.

Here is an example that contains both kinds of expression evaluation. In the example a while loop, which prints ten lines of the form x is 0, x is 1, ..., is defined.

set x 0
while {$x < 10} {
    puts "x is $x"
    set x ($x + 1)
}

In the expression argument of while, the expression is given in curly braces, because while does not need to evaluate the expression directly, but must evaluate the expression multiple times. If we would have used while ($x < 10) ... instead, while would receive the value of the expression, at the point in time when while is reached in the control flow (which is true in this example). Hence, the loop would run forever. But instead we use while {$x < 10} ..., which passes the expression code block: "$x < 10" to the while command. The while command then can evaluate the expression for every iteration of the while loop.

In the second expression in the while body, $x + 1, we require direct evaluation of the expression, because the result of the expression must be written into the variable x. Hence round braces are used for evaluating the second expression.

Expression Operators

Frag offers the usual expression operators, as they can be found in many other languages, such as Java or C.

There are the following unary operators:

Unary Minus: -
Unary Plus: +
Unary Not: !
Bitwise Not: ~

There are the following binary operators (in order of precedence groups, from high precedence to low precedence):

Multiply: *
Divide: /
Modulo: %

Plus: +
Minus: -

Bitshift Left: <<
Bitshift Right: >>

Less: <
Less Equal: <=
Greater: >
Greater Equal: >=

Equal: =
Not Equal: !=

Bitwise And: &

Bitwise Xor: ^

Bitwise Or: |

And: &&

Or: ||

An operator with higher precedence has greater binding power. For example, the expression

set x (1 - 1 * 19)

is equivalent to:

set x (1 - (1 * 19))

because "*" has a higher precedence than "-".

As usual (round) braces can be used to control the precedence of operators. For instance, the expression:

set x ((1 - 1) * 19)

evaluates the "-" operator first.

Substitutions in Expressions

Inside of an expression, code substitution, escape (backslash) substitution, and variable substitution are supported. Here is an example:

set z 3
set x ($z + [get z])

Usable Data Types in Expressions

In expressions, all kinds of data types can be used. However, not all operators are defined for all data types. Almost all operators are applicable for numbers, but some operators do not support double values as operands. Also boolean values are not always supported. If a data type is unknown, its string value is used. Strings can be used inside of an expression, but only the operators "==" and "!=" work for strings. If a wrong data type is chosen, an exception is raised.

Mathematical Functions: The Math Command

The predefined math command contains all kinds of mathematical functions that can be used in Frag invocations and in expressions through code substitution. For instance, the following code uses math sqrt in an expression:

set x (2 + [math sqrt 2.0])

The general syntax of math is:

math <math function name> ?args ...?

Below you find a complete reference of the mathematical functions provided by math.