Skip to main content

Writing Expressions

Basic Syntax​

Expressions are written in CEL and look similar to expressions in C, JavaScript, or Python. They can include variables, literals, and operators.

Variables​

Variables are used to refer to values. For example, identity might refer to a user object.

identity.age >= 18 // Checks if the user's age is 18 or more.

Supported Variables​

Here is a list of variable namespaces supported in expressions:

Literals​

CEL supports several literal types:

  • Boolean: true, false
  • Integer: 42, -7
  • String: "hello", 'world'
  • List: [1, 2, 3]
  • Map: {"key1": "value1", "key2": "value2"}

Operators​

CEL provides a rich set of operators for performing arithmetic, comparison, and logical operations:

  • Arithmetic: +, -, *, /, %
  • Comparison: ==, !=, <, <=, >, >=
  • Logical: &&, ||, !

Using Arithmetic​

5 * (3 - 1) // Evaluates to 10

Using Comparison and Logical Operators​

// Checks if the user is 18 or older and is in the US
identity.age >= 18 && identity.country == "US"

Working with Strings​

String Concatenation​

To combine strings, use the + operator:

"Hello, " + "world!" // Results in "Hello, world!"

String Functions​

CEL provides several built-in functions to work with strings, enabling you to perform transformations, query information, or compare strings.

size()​

Returns the number of characters in the string:

size("Hello") // Evaluates to 5

startsWith()​

Checks if the string starts with a specified substring:

"Hello, world".startsWith("Hello") // Evaluates to true

endsWith()​

Checks if the string ends with a specified substring:

"Hello, world".endsWith("world") // Evaluates to true

matches()​

Determines if the string matches a regular expression pattern:

"Hello, world".matches("H.*d") // Evaluates to true

contains()​

To check if a string contains another string:

"Hello, world!".contains("world") // Evaluates to true

Advanced String Manipulation​

Regular Expressions​

CEL's matches() function allows you to use regular expressions for pattern matching. This can be powerful for validation or extracting parts of strings:

// Evaluates to true for a valid email format
"user@example.com".matches("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$")

Concatenation and Interpolation​

While direct string interpolation isn't a feature in CEL, concatenation can be used to dynamically construct strings:

// Interpolates number to string
"Your order number is: " + string(order_number)

Working with Unicode​

Strings in CEL are Unicode and can handle a wide range of characters:

// Evaluates to 5, as there are 5 characters in this Japanese greeting
size("こんにちは")

String Comparison​

String comparison in CEL is case-sensitive and uses the standard comparison operators:

"apple" == "Apple" // Evaluates to false due to case difference
"apple" < "banana" // Alphabetically compares strings, evaluates to true

Working with Lists​

A list in CEL is an ordered collection of elements. You can perform various operations on lists, including checking if an item is contained within a list, accessing elements by their index, and iterating over elements.

Creating a List​

var my_list = [1, 2, 3, 4]

Checking for Membership​

To check if a value exists in a list, use the in operator:

2 in my_list; // Evaluates to true
5 in my_list; // Evaluates to false

Accessing Elements​

Access elements by their index (0-based):

// Accesses the second element, evaluates to 2
my_list[1];

Counting Elements​

Returns the number of elements in the list.

size(my_list) // Evaluates to 4

Iterating Over a List​

Use a comprehension to iterate over elements in a list and apply logic:

// Doubles each value in the list, resulting in [2, 4, 6, 8]
[value * 2 for value in my_list]

Filtering a List​

Filter a list to include only certain elements:

// Keeps only values greater than 2, resulting in [3, 4]
[value for value in my_list if value > 2]

Membership in Lists​

The in operator is versatile and can be used to check for membership in both lists:

// For maps (checks keys)
"apple" in { apple: 1, banana: 2 } // true

Working with Maps​

A map in CEL is a collection of key-value pairs. Keys are unique, and each key maps to exactly one value. You can check for the presence of keys, access values by their keys, and iterate over keys or values.

Creating a Map​

var my_map = { a: 1, b: 2, c: 3 }

Checking for Key Presence​

To check if a key is present in a map, use the in operator:

"a" in my_map; // Evaluates to true
"d" in my_map; // Evaluates to false

Accessing Values​

Access values by their keys:

// Accesses the value for the key "a", evaluates to 1
my_map["a"]

Counting Elements​

Returns the number of key-value pairs present in the map.

size(my_map) // Evaluates to 3

Iterating Over a Map​

You can iterate over the keys or values of a map using a comprehension:

// Extracts all keys, resulting in ["a", "b", "c"]
[key for key, value in my_map]

// Extracts all values, resulting in [1, 2, 3]
[value for key, value in my_map]

Checking for a Condition in a Map​

Use exists or all macros to check if any or all elements in a collection meet a condition:

// Checks if any key in the map starts with "a"
my_map.exists(key, key.startsWith("a")) // Evaluates to true

// Checks if all values in the map are greater than 0
my_map.all(value, value > 0) // Evaluates to true

Membership in Maps​

The in operator is versatile and can be used to check for membership in maps:

// For maps (checks keys)
"apple" in { apple: 1, banana: 2 } // true

Conditional Expressions​

CEL supports ternary conditional expressions, allowing for simple if-then-else logic:

identity.has_discount ? 0.2 : 0

Using Macros​

Macros provide syntactic sugar for common patterns, like looping through a collection:

// Returns true if any email ends with "@example.com"
identity.emails.exists(e, e.endsWith("@example.com"))

You can find the custom ngrok macros here: