The language

cel-lite runs a subset of CEL, the Common Expression Language. An expression means what CEL's language definition says it means. What cel-lite doesn't implement it refuses, by name, when the expression is compiled: an expression that compiles never means something other than it would in CEL.

cel-go, CEL's reference implementation, is the oracle. The tests in oracle/ run the same expressions through both engines and compare types, values, errors and unknowns: a corpus of corner cases, thousands of generated expressions on random variables, and two fuzz targets. Where cel-go strays from the definition, cel-lite follows the definition, and the difference is listed below.

Types

Every expression is type-checked when it compiles. A value of type dyn is checked when the expression runs instead: dyn(x) makes any value dyn, and a variable declared dyn holds anything.

Literals

42  -7  0x1F            int
42u  0x1Fu              uint
1.5  1e3  .5  1.e3      double
'single'  "double"      string, with \n \t \\ \' \" \xHH \uHHHH escapes
'''triple'''  """too""" string, across lines
r'raw \n'               string, no escapes
b'bytes\xff'            bytes
true  false  null
[1, 2, 3]  {'a': 1}     list, map; a trailing comma is allowed

Operators

From the loosest to the tightest:

• Arithmetic takes two values of one type: 1 + 1u is a type error. Overflow in int or uint is an error when the expression runs, and so is dividing an integer by zero. double follows IEEE 754: 1.0 / 0.0 is infinity, and NaN equals nothing, itself included. Integer division truncates toward zero: -5 / 3 is -1, and -5 % 3 is -2.
• + also concatenates strings, bytes and lists.
• Equality and order take two values of one type when their types are known: 1 == 1u is a type error, as in cel-go. Values of type dyn compare across the numeric types by their value: dyn(1) == 1u and dyn(1) < 1.5 hold. Lists and maps are equal when their elements are. Strings order by code point, bytes by byte, and false < true.
• in is membership: an element of a list, or a key of a map.
• c ? a : b evaluates only the branch it takes.

Names and fields

• A variable is declared by your program, with its type. Its name may be qualified: a variable declared as pane.id is what pane.id reads, even where pane is a variable too. A leading dot, .pane.id, names it from the root.
• a.f is a struct's field, or a map's value at the key 'f'. a[k] is a list's element (at an int) or a map's value. A missing key or an index out of range is an error when the expression runs.
• has(a.f) is whether the map a holds the key 'f'.
• The words CEL reserves (in, if, null, true, package, …) can't name a variable or a helper, but a field may have one: x.if. cellite.ReservedWords() lists them.
• A variable may take the name of a type (list, int, type), and the name then reads the variable. Without such a variable, a type's name in an expression is a type value, which cel-lite refuses.

Functions

A conversion that doesn't fit, int(1e19) or int('ten'), is an error when the expression runs. So is one whose argument isn't of the type Check gave it, as untyped data can give a variable: int(s) with s a string variable given an int, as in cel-go. Your program can add functions of its own: helpers.

Errors and unknowns

An expression that compiles can still fail as it runs: a division by zero, an overflow, a missing key, a variable the activation doesn't have. A variable can also be unknown: its value isn't there yet, as in partial evaluation.

An error or an unknown is the result of whatever depends on it, except that && and || look at both sides, in either order:

• false && x and x && false are false, and true || x and x || true are true, whatever x is: an error, an unknown, or a value.
• When neither side decides, an unknown wins over an error: with x unknown, x && 1 / 0 == 1 is unknown.
• c ? a : b is unknown or an error when c is.

What cel-lite refuses

Each of these is refused when the expression compiles, with an *cellite.Error whose Kind is Unsupported and whose Name names the feature:

The macros are all, exists, exists_one, map and filter. The last row is explained below.

A dyn can hide a struct from the checker: x == y with both dyn, or has(x.f). When the values turn out to be structs, the refusal comes as the expression runs, as an *EvalError that says it is not supported, unless the answer doesn't depend on it: [x, 1] == [y, 2] is false, and 'a' in [x, 'a'] is true.

Where cel-lite and cel-go differ

Where cel-go strays from the language definition, cel-lite follows the definition, or refuses by name. The comparison with cel-go leaves out each of these cases by name.

• Inferred types. cel-go types a value read with [] from a dyn (x['k'], or an element of an empty literal) with a type parameter that its first use binds: -x['k'] is a double there, [x['k'], 'a'] a list(string), -x['k'] + 1 is refused, and int(x['k']) takes only an int when it runs. In the definition the value is dyn. cel-lite refuses such a use (inferred type); x.k or dyn(x['k']) keeps the value dyn.
• Map keys. A map's keys are bool, int, uint or string, as the definition says. A map literal whose dyn key turns out a double, a list or a map is an error when it runs; cel-go builds the map, where a NaN key is never found and two NaN keys are two entries.
• A variable named after a type, absent. When a variable named list or int is declared but the activation doesn't have it, cel-go reads the type instead, a value the expression's checked type doesn't allow: list declared a bool gives the type list. cel-lite reports the variable missing, as for any other name.
• [] on a struct. cel-go reads a struct's field by its name with [] when a dyn hides the struct: dyn(item)['title']. In the definition [] reads a list or a map, and a field is read with .; cel-lite gives an error (no such overload).
• A bytes key. x in m with x bytes, as untyped data can give a variable declared a string, is false on any map: bytes are never a key. cel-go fails on a map literal, which can't hash them, and says false on a Go map.
• Limits. cel-lite reads shorter and shallower expressions than cel-go: see Limits.

Error messages are cel-lite's own. Type errors read as cel-go's do (found no matching overload for '_+_' applied to '(string, int)'), and so do undeclared names; syntax errors are worded differently (syntax error: unexpected end of input).