Language: Boolean Expressions

Boolean expressions are expressions that evaluate to a boolean value from the result of a combination of one or more comparisons and logical operators. Boolean expressions form the basis of policy since policy can be broken down to a set of logical decisions that turn into true or false.

A single boolean expression is the body of a rule. Additionally, boolean expressions are used with conditionals, and more.

Order of Operations

The precedence of operators is shown below. Operators with higher precedence values (larger numbers) are evaluated first. Operators with the same precedence value are evaluated left-to-right.

Precedence    Operator
    6             *  /  %
    5             +  -
    4             else
    3             ==  !=  <  <=  >  >= "is" "is not" "matches" "contains" "in"
    2             and
    1             or  xor

Examples of this precedence are shown below:

4 * 5 / 5 // 4
4 * 5 + 2 // 22
4 + 5 * 2 // 14

Logical Operators

Logical operators are used to change or combine logical expressions. There are three binary operators and, or, and xor. There is a single unary operator not (which can also be specified as !).

The binary operators require two boolean operands and the unary operator requires a single boolean operand. In both case, the operands are values or expressions that are boolean types.

Below is a basic explanation of the logical operators directly from the specification:

and    conditional AND    p and q  is  "if p then q else false"
or     conditional OR     p or q   is  "if p then true else q"
xor    conditional XOR    p xor q  is  "if p and not q or not p and q then true"
!      NOT                !p       is  "not p"
not    NOT                !p       is  "not p"

Using parentheses to group boolean expressions, you can combine boolean expressions to become more complex or affect ordering:

(p and q) or r
p and (q or r)

Comparison Operators

Comparison operators compare two operands and yield a boolean value.

For any comparison, the two operands must be equivalent types. The one exception are integers and floats. When an integer is compared with a float, the integer is promoted to a floating point value.

The available comparison operators are:

==       equal
!=       not equal
<        less
<=       less or equal
>        greater
>=       greater or equal
"is"     equal
"is not" not equal

The behavior of is with == and is not with != is identical.

Example comparisons:

name is "Mitchell"
idnumber > 42
idnumber <= 12

Using the logical operators, these can be combined:

name is "Mitchell" and idnumber > 42

The language specification provides more detail on exactly how comparison behaves.

Set Operators

The set operators contains and in test for inclusion in a collection (a list or map).

Set operators may be negated by prefixing the operator with not, such as not contains and not in. This is equivalent to wrapping the expression in a unary not but results in a more readable form.

contains tests if the left-hand collection contains the right-hand value. in tests if the right-hand collection contains the left-hand value. For maps, "contains" looks at the keys, not the values.

Examples:

[1, 2, 3] contains 2            // true
[1, 2, 3] contains 5            // false
[1, 2, 3] contains "value"      // false
[1, 2, 3] not contains "value"  // true

{ "a": 1, "b": 2 } contains "a"     // true
{ "a": 1, "b": 2 } contains "c"     // false
{ "a": 1, "b": 2 } contains 2       // false
{ "a": 1, "b": 2 } not contains 2   // true

Matches Operator

The matches operator tests if a string matches a regular expression. The matches operator can be negated by prefixing the operator with not, such as not matches.

The left-hand value is the string to test. The right-hand value is a string value representing a regular expression. The syntax of the regular expression is the same general syntax used by Python, Ruby, and other languages. The precise syntax accepted is the syntax accepted by RE2.

Regular expressions are not anchored by default; any anchoring must be explicitly specified.

"test" matches "e"            // true
"test" matches "^e"           // false
"TEST" matches "test"         // false
"TEST" matches "(?i)test"     // true
"ABC123" matches "[A-Z]+\\d+" // true
"test" not matches "e"        // false

Any, All Expressions

any and all expressions allow testing that any or all elements of a collection match some boolean expression. The result of an any and all expression is a boolean.

any returns the boolean value true if any value in the collection expression results in the body expression evaluating to true. If the body expression evalutes to false for all values, the any expression returns false.

all returns the boolean true if all values in the collection expression result in the body expression evaluating to true. If any value in the collection expression result in the body expression evaluating to false, the all expression returns false.

For empty collections, any returns false and all returns true.

all group.tasks as t { t.driver is "vmware" }
any group.tasks as t { t.driver is "vmware" }

Since any and all expressions are themselves boolean expressions, they can be combined with other operators:

any ["a", "b"] as char { char is "a" } or
other_value is "another"

Emptiness Comparison

The expressions is empty and is not empty provide a convenience method for determining the emptiness of a value. It supports the same types as the built-in length, collections and strings.

[] is empty            // true
[] is not empty        // false
["foo"] is empty       // false
["foo"] is not empty   // true
undefined is empty     // undefined
undefined is not empty // undefined

Defined Comparison

The expressions is defined and is not defined provide a convenience method for determining if a value has been defined. In other words, any value other than undefined can be considered as defined.

[] is defined             // true
4 is defined              // true
true is defined           // true
{} is defined             // true
undefined is defined      // false
[] is not defined         // false
4 is not defined          // false
true is not defined       // false
undefined is not defined  // true