cel-go

CEL Policy is a YAML-based format that extends the standard Common Expression Language (CEL). While standard CEL is limited to simple expressions without variables or modules, CEL Policy allows for expression composition, variable reuse, and nested rules. It is designed to be runtime-compatible with CEL, maintaining the same performance and safety guarantees, and is inspired by Kubernetes Admission Policy.

A policy consists of a named instance of a rule which contains conditional outputs and sub-rules. The default evaluation semantic is FIRST_MATCH (top-down).

To use CEL-Go, use cel.Compile() to create a program from an expression string. You must declare any variables used in the expression using cel.Variable(name, type). Once compiled, use prg.Eval(map[string]any) to execute the expression with a provided context of variables.

package main

import (
	"fmt"
	"log"

	"github.com/google/cel-go/cel"
)

func main() {
	prg, err := cel.Compile(`"Hello world! I'm " + name + "."`,
		cel.Variable("name", cel.StringType),
	)
	if err != nil {
		log.Fatalln(err)
	}
	out, _, err := prg.Eval(map[string]any{
		"name": "CEL",
	})
	if err != nil {
		log.Fatalln(err)
	}
	fmt.Println(out)
	// Output: Hello world! I'm CEL.
}

To use CEL, you must first create an environment that defines the variables and their types available to the expressions. Use cel.NewEnv and provide cel.Variable definitions for each expected variable.

import "github.com/google/cel-go/cel"

env, err := cel.NewEnv(
    cel.Variable("name", cel.StringType),
    cel.Variable("group", cel.StringType),
)

The CEL Codelab provides hands-on instructions for learning how to use cel-go. The codelab requires prior knowledge of Go and Protocol Buffers (Protobuf).

• Instructions: CEL Codelab Guide
• Reference Solutions: If you encounter difficulties, you can refer to the official solutions.

The CEL REPL is a command-line tool for experimenting with CEL expressions. By default, any input is interpreted as a CEL expression to evaluate. To modify the evaluation environment (variables, functions, options), use special commands prefixed with %.

$ cd ./repl/main
$ go run .
CEL REPL
%exit or EOF to quit.

cel-repl> %let x = 10
cel-repl> x + 5
15 : int

To run all the provided examples locally, use the following command:

go test -v ./examples/...```

CEL supports evaluation with partial state using commutative logical operators && and ||. If an error or unknown value is encountered on one side, the other side is evaluated to determine the outcome.

To track these unknowns, enable cel.OptTrackState via cel.EvalOptions. The details returned by Eval() can then be used with interpreter.Prune to generate a residual expression (an expression containing only the variables that were actually needed for the result).

The imports field allows you to use simple names for complex types (like protocol buffers) instead of fully qualified names within your CEL expressions.

Without imports:

rule:
  match:
    -   output: >
      dev.cel.example.ComplexDocument{
        title: "Example Document"
      }

With imports:

imports:
  -   name: dev.cel.example.ComplexDocument

rule:
  match:
    -   output: >
        ComplexDocument{
          title: "Example Document"
        }

To use the CEL REPL as a standalone binary, clone the repository, navigate to the REPL directory, and build it using Go. You can then move the resulting binary to a location in your $PATH to run it from anywhere.

$ git clone git@github.com:google/cel-go.git ./cel-go
$ cd ./cel-go/repl/main
$ go build -o repl .
# e.g. to your $PATH
$ mv ./repl <install location>

CEL supports explicit type casting using int(), uint(), double(), string(), bytes(), and dyn(). You can inspect types using the type(x) function.

prg, _ := cel.Compile(`type(42) == int`)
out, _, _ := prg.Eval(cel.NoVars())
fmt.Println(out) // true