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

You can find the ngrok supported variables here:

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.20 : 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: