Reference Manual

This chapter defines CEL’s grammar, tokens, types, literals, operators, standard-library operations, collections, and closures.

Concept

CEL is an expression language. Use the tutorial chapters for worked examples.

Syntax

CEL uses strict LL(1) parsing.

expression = closure_expression | range_expression .
range_expression = ".." [ or_expression ]
                 | "..=" or_expression
                 | or_expression [ ".." [ or_expression ] | "..=" or_expression ] .
or_expression = and_expression { "||" and_expression } .
and_expression = comparison_expression { "&&" comparison_expression } .
comparison_expression = bitwise_or_expression
    [ comparison_operator bitwise_or_expression ] .
bitwise_or_expression = bitwise_xor_expression { "|" bitwise_xor_expression } .
bitwise_xor_expression = bitwise_and_expression { "^" bitwise_and_expression } .
bitwise_and_expression = bitwise_shift_expression { "&" bitwise_shift_expression } .
bitwise_shift_expression = additive_expression { ("<<" | ">>") additive_expression } .
additive_expression = multiplicative_expression { ("+" | "-") multiplicative_expression } .
multiplicative_expression = cast_expression { ("*" | "/" | "%") cast_expression } .
cast_expression = unary_expression { "as" identifier } .
unary_expression = ("-" | "!") unary_expression | postfix_expression .
postfix_expression = primary_expression { postfix_suffix } .
postfix_suffix = "(" [ argument_list ] ")" | "." (unsuffixed_integer | identifier) .
comparison_operator = "==" | "!=" | "<" | ">" | "<=" | ">=" .
argument_list = expression { "," expression } .
primary_expression = literal
                   | value_identifier [ record_fields ]
                   | tuple_or_group
                   | array_expression
                   | if_expression .
record_fields = "{"
    [ field_initializer { "," field_initializer } ] "}" .
field_initializer = identifier ":" expression .
tuple_or_group = "(" [ expression [ "," [ expression { "," expression } ] ] ] ")" .
array_expression = "[" [ expression { "," expression } ] "]"
                 [ ":" type_expr ] .
type_expr = identifier [ "(" [ type_expr { "," type_expr } ] ")" ]
          | "[" type_expr "]"
          | "(" [ type_expr [ "," [ type_expr { "," type_expr } ] ] ] ")" .
if_expression = "if" expression "{" expression "}"
              [ "else" ( "{" expression "}" | if_expression ) ] .
closure_expression = "||" expression
                   | "|" closure_param { "," closure_param } "|" expression .
closure_param = identifier ":" type_expr .

These productions encode precedence and left associativity directly. Comparisons and ranges do not chain; logical operators may combine separate comparisons. A closure is a complete expression, not a primary operand. Its body consumes the remaining expression inside its delimiter boundary. Group a closure before applying an operator or postfix suffix to it. Arguments and collection elements are complete expressions and accept bare closures. A call suffix directly after a named member dispatches that member. Parenthesize the member before the call suffix to call its result instead.

value_identifier excludes if, else, as, true, and false.

Worked examples

(1, 2).0
if ok && ready { [1, 2] } else { [3, 4] }
|pair: (i32, i32)| pair.0 + pair.1
1 + 2..=3 * 4
true as i32

Token table

Type table

Literal table

Operator precedence table

Operator rules table

Numeric call table

All functions in this table belong to the standard library and are available when the evaluation environment installs it. See Standard library for worked examples and fuller prose.

Both op(x, ...) and x.op(...) select these registered operations. Float calls retain Rust’s method semantics, including NaN and infinity; they do not introduce evaluation errors for mathematical domain violations.

Collection table

Closure table

Exact rules

• Calls accept zero or more comma-separated arguments and do not accept a trailing comma.
• Tuple indexing uses .N with an unsuffixed integer and may be chained.
• Unannotated arrays are non-empty and homogeneous. A complete type annotation permits an empty array and must match the element type exactly.
• Tuples and arrays are distinct forms and compose recursively, including registered leaves, source unit, and callable values.
• Rust interoperability uses Array<T>, source-ordered canonical lists (Nil/Cons witnesses), and Callable<Args, R> (FnOf witness). Array<Array<T>> converts to Vec<Array<T>>, not allocation-preserving deep native vectors. See collections.
• Arbitrary erased external values require complete shape checks. PreparedSegment and prepared_segment::PreparedRawSegment validate at preparation, not each invocation. Clone, equality, and formatting are explicit independent capabilities.
• Native Rust operations can serve interpreted CEL through typed adapters.
• Comparison expressions consume one comparison operator.
• Range forms do not chain.
• Closures require parentheses as operator operands, including range endpoints, cast inputs, and postfix receivers. Complete-expression positions, including call arguments, tuple elements, array elements, and branch bodies, accept bare closures.
• expr.name and expr.name() invoke the same host-provided unary operation. expr.name(a, b) passes the receiver first, followed by explicit arguments. Each operand evaluates once in source order. A value binding named name does not hide a dot operation, and the member label is not a variable reference.
• (expr.name)() calls the operation’s result normally; it fails if the result is not callable. Dot operations, ordinary calls, and tuple indexing share postfix precedence and may be chained.
• TypeName { field: expression, ... } constructs a host-registered record. Constructor names belong to the type namespace, separate from value names. Field labels are not variable references. Every schema field is required exactly once; unknown, duplicate, missing, and incorrectly typed fields are errors. Field expressions evaluate once in written order, independent of schema order. An empty schema permits TypeName {}. Field lists do not permit trailing commas.
• Field types match exactly: an f64 field accepts 1.0, not the i32 literal 1. The static checker uses installed record schemas and operation signatures; known custom types retain their identities instead of unifying with unrelated types. Unknown constructors are errors. Unresolved inputs and calls without metadata remain best-effort, but all their child expressions are still checked.
• Unparenthesized record constructors are forbidden throughout an if condition. Parentheses, call arguments, tuple elements, and array elements start unrestricted expression positions: write if (Sample { value: 3.0 }.value) > 0.0 { ... }. The restriction propagates through operators, ranges, and closure bodies.
• Members are reads/operations, not assignment targets. CEL has no member assignment.
• CEL does not use bracket postfix indexing such as expr[0].
• CEL does not define map literals, object literals, or a ternary operator.
• A closure body resolves its own parameters and does not capture free variables from the enclosing expression.
• A one-element tuple type requires (T,); (T) is grouping.

Edge cases

• Signed +, signed binary -, signed unary -, and signed * overflow report arithmetic overflow.
• Integer / and % failures report division by zero.
• Negative, too-large, or non-u32-fitting shift counts report shift overflow.
• a < b < c is not valid; write a < b && b < c.
• 1..2..3 is not valid.
• ..= is not valid without a right endpoint.
• [] is not valid.
• [(0, 1), (true, 2)] is not valid because element shapes differ.