cel-go

README

Common Expression Language - Go Toolchain

This repo contains the Go toolchain for the Common Expression Language (CEL). CEL is a non-Turing complete language designed to be portable and fast. It is best suited to applications where sandboxing a full-fledged language like JavaScript or Lua would be too resource intensive, but side-effect free dynamic computations are strongly desired.

Want to learn more?

• See the CEL Spec for more details about the language.
• Ask for support on the CEL Go Discuss Google group.

Want to integrate CEL?

• See GoDoc to learn how to integrate CEL into services written in Go.
• See the CEL C++ toolchain (under development) for information about how to integrate CEL evaluation into other environments.

Want to contribute?

• See CONTRIBUTING.md to get started.
• Use GitHub Issues to request features or report bugs.

How does CEL work?

Write an expression in the CEL syntax, then parse, check, and interpret.

Step	Description
Parse	Parses a string expression to a protocol buffer representation.
Check	Type-checks a parsed expression against a given environment.
Interpret	Evaluates parsed expressions against a set of inputs.

Type-checking an expression in an optional, but strongly encouraged step that can be used to reject some expressions as semantically invalid using static analysis. Additionally, the type-check produces some additional metadata related to function overload resolution and object field selection which may be used by the interpret step to speed up execution.

Example

The following example shows the parse, check, and intepretation of a simple program. After the parse and type-check steps, the service checks whether there are any errors that need to be reported.

import(
	"fmt"
	"log"

	"github.com/google/cel-go/cel",
	"github.com/google/cel-go/checker/decls"
)

func main() {
	// Variables used within this expression environment.
	decls := cel.Declarations(
		decls.NewIdent("i", decls.String, nil),
		decls.NewIdent("you", decls.String, nil))
	env, err := cel.NewEnv(decls)
	if err != nil {
		log.Fatalf("environment creation error: %s\n", err)
	}

	// Parse and type-check the expression.
	//
	// Detailed information about which issues/errors were encountered may be
	// found within the `iss`, but a non-nil `iss.Err()` value will contain a
	// detailed error string in human-readable form.
	p, iss := env.Parse(`"Hello " + you + "! I'm " + i + "."`)
	if iss != nil && iss.Err() != nil {
		log.Fatalln(iss.Err())
	}
	c, iss := env.Check(p)
	if iss != nil && iss.Err() != nil {
		log.Fatalln(iss.Err())
	}

	// Create the program, and evaluate it against some input.
	prg, err := env.Program(c)
	if err != nil {
		log.Fatalf("program creation error: %s\n", err)
	}

	// Note, the second result, the EvalDetails will be non-nil when using
	// either cel.OptTrackState or cel.OptExhaustiveEval (not shown). The
	// details value holds information about the evaluation, rather than the
	// output of the evaluation itself.
	out, _, err := prg.Eval(cel.Vars(map[string]interface{}{
		"i": "CEL",
		"you": "world"}))
	if err != nil {
		log.Fatalf("runtime error: %s\n", err)
	}

	// Hello world! I'm CEL.
	fmt.Println(out)
}

More examples like these can be found within the unit tests which can be run using Bazel:

bazel test ...

License

Released under the Apache License.

Disclaimer: This is not an official Google product.