cel

Documentation

Overview

Package cel defines the top-level interface for the Common Expression Language (CEL).

CEL is a non-Turing complete expression language designed to parse, check, and evaluate expressions against user-defined environments.

Example

// Create the CEL environment with declarations for the input attributes and
// the desired extension functions. In many cases the desired functionality will
// be present in a built-in function.
decls := Declarations(
	// Identifiers used within this expression.
	decls.NewIdent("i", decls.String, nil),
	decls.NewIdent("you", decls.String, nil),
	// Function to generate a greeting from one person to another.
	//    i.greet(you)
	decls.NewFunction("greet",
		decls.NewInstanceOverload("greet_string_string",
			[]*exprpb.Type{decls.String, decls.String},
			decls.String)))
e, err := NewEnv(decls)
if err != nil {
	log.Fatalf("environment creation error: %s\n", err)
}

// Parse and check the expression.
p, iss := e.Parse("i.greet(you)")
if iss != nil && iss.Err() != nil {
	log.Fatalln(iss.Err())
}
c, iss := e.Check(p)
if iss != nil && iss.Err() != nil {
	log.Fatalln(iss.Err())
}

// Create the program.
funcs := Functions(
	&functions.Overload{
		Operator: "greet",
		Binary: func(lhs ref.Val, rhs ref.Val) ref.Val {
			return types.String(
				fmt.Sprintf("Hello %s! Nice to meet you, I'm %s.\n", rhs, lhs))
		}})
prg, err := e.Program(c, funcs)
if err != nil {
	log.Fatalf("program creation error: %s\n", err)
}

// Evaluate the program against some inputs. Note: the details return is not used.
out, _, err := prg.Eval(Vars(map[string]interface{}{
	// Native values are converted to CEL values under the covers.
	"i": "CEL",
	// Values may also be lazily supplied.
	"you": func() ref.Val { return types.String("world") },
}))
if err != nil {
	log.Fatalf("runtime error: %s\n", err)
}

fmt.Println(out)

Output:

Hello world! Nice to meet you, I'm CEL.

Index

• func AstToCheckedExpr(a Ast) (*exprpb.CheckedExpr, error)
• func AstToParsedExpr(a Ast) (*exprpb.ParsedExpr, error)
• func NoVars() interpreter.Activation
• func Vars(vars map[string]interface{}) interpreter.Activation
• type Ast
  • func CheckedExprToAst(checkedExpr *exprpb.CheckedExpr) Ast
  • func ParsedExprToAst(parsedExpr *exprpb.ParsedExpr) Ast
• type Env
  • func NewEnv(opts ...EnvOption) (Env, error)
• type EnvOption
  • func ClearBuiltIns() EnvOption
  • func ClearMacros() EnvOption
  • func Container(pkg string) EnvOption
  • func CustomTypeProvider(provider ref.TypeProvider) EnvOption
  • func Declarations(decls ...*exprpb.Decl) EnvOption
  • func Macros(macros ...parser.Macro) EnvOption
  • func Types(addTypes ...interface{}) EnvOption
• type EvalDetails
• type EvalOption
• type Issues
• type Program
• type ProgramOption
  • func EvalOptions(opts ...EvalOption) ProgramOption
  • func Functions(funcs ...*functions.Overload) ProgramOption
  • func Globals(vars interpreter.Activation) ProgramOption
• type Source

Examples

• Package

Functions

func AstToCheckedExpr

func AstToCheckedExpr(a Ast) (*exprpb.CheckedExpr, error)

AstToCheckedExpr converts an Ast to an protobuf CheckedExpr value.

If the Ast.IsChecked() returns false, this conversion method will return an error.

func AstToParsedExpr

func AstToParsedExpr(a Ast) (*exprpb.ParsedExpr, error)

AstToParsedExpr converts an Ast to an protobuf ParsedExpr value.

func NoVars

func NoVars() interpreter.Activation

NoVars returns an empty Activation.

func Vars

func Vars(vars map[string]interface{}) interpreter.Activation

Vars takes an input map of variables and returns an Activation.

Types

type Ast

type Ast interface {
	// Expr returns the proto serializable instance of the parsed/checked expression.
	Expr() *exprpb.Expr

	// IsChecked returns whether the Ast value has been successfully type-checked.
	IsChecked() bool

	// ResultType returns the output type of the expression if the Ast has been type-checked,
	// else returns decls.Dyn as the parse step cannot infer the type.
	ResultType() *exprpb.Type

	// Source returns a view of the input used to create the Ast. This source may be complete or
	// constructed from the SourceInfo.
	Source() Source

	// SourceInfo returns character offset and newling position information about expression
	// elements.
	SourceInfo() *exprpb.SourceInfo
}

Ast interface representing the checked or unchecked expression, its source, and related metadata such as source position information.

func CheckedExprToAst

func CheckedExprToAst(checkedExpr *exprpb.CheckedExpr) Ast

CheckedExprToAst converts a checked expression proto message to an Ast.

func ParsedExprToAst

func ParsedExprToAst(parsedExpr *exprpb.ParsedExpr) Ast

ParsedExprToAst converts a parsed expression proto message to an Ast.

type Env

type Env interface {
	// Check performs type-checking on the input Ast and yields a checked Ast and/or set of Issues.
	//
	// Checking has failed if the returned Issues value and its Issues.Err() value is non-nil.
	// Issues should be inspected if they are non-nil, but may not represent a fatal error.
	//
	// It is possible to have both non-nil Ast and Issues values returned from this call: however,
	// the mere presence of an Ast does not imply that it is valid for use.
	Check(ast Ast) (Ast, Issues)

	// Parse parses the input expression value `txt` to a Ast and/or a set of Issues.
	//
	// Parsing has failed if the returned Issues value and its Issues.Err() value is non-nil.
	// Issues should be inspected if they are non-nil, but may not represent a fatal error.
	//
	// It is possible to have both non-nil Ast and Issues values returned from this call; however,
	// the mere presence of an Ast does not imply that it is valid for use.
	Parse(txt string) (Ast, Issues)

	// Program generates an evaluable instance of the Ast within the environment (Env).
	Program(ast Ast, opts ...ProgramOption) (Program, error)
}

Env defines functions for parsing and type-checking expressions against a set of user-defined constants, variables, and functions. The Env interface also defines a method for generating evaluable programs from parsed and checked Asts.

func NewEnv

func NewEnv(opts ...EnvOption) (Env, error)

NewEnv creates an Env instance suitable for parsing and checking expressions against a set of user-defined constants, variables, and functions. Macros and the standard built-ins are enabled by default.

See the EnvOptions for the options that can be used to configure the environment.

type EnvOption

type EnvOption func(e *env) (*env, error)

EnvOption is a functional interface for configuring the environment.

func ClearBuiltIns

func ClearBuiltIns() EnvOption

ClearBuiltIns option removes all standard types, operators, and macros from the environment.

Note: This option must be specified before Declarations and/or Macros if used together.

func ClearMacros

func ClearMacros() EnvOption

ClearMacros options clears all parser macros.

Clearing macros will ensure CEL expressions can only contain linear evaluation paths, as comprehensions such as `all` and `exists` are enabled only via macros.

Note: This option is a no-op when used with ClearBuiltIns, and must be used before Macros if used together.

func Container

func Container(pkg string) EnvOption

Container sets the container for resolving variable names. Defaults to an empty container.

If all references within an expression are relative to a protocol buffer package, then specifying a container of `google.type` would make it possible to write expressions such as `Expr{expression: 'a < b'}` instead of having to write `google.type.Expr{...}`.

func CustomTypeProvider

func CustomTypeProvider(provider ref.TypeProvider) EnvOption

CustomTypeProvider swaps the default ref.TypeProvider implementation with a custom one.

Note: This option must be specified before the Types option when used together.

func Declarations

func Declarations(decls ...*exprpb.Decl) EnvOption

Declarations option extends the declaration set configured in the environment.

Note: This option must be specified after ClearBuiltIns if both are used together.

func Macros

func Macros(macros ...parser.Macro) EnvOption

Macros option extends the macro set configured in the environment.

Note: This option must be specified after ClearBuiltIns and/or ClearMacros if used together.

func Types

func Types(addTypes ...interface{}) EnvOption

Types adds one or more type declarations to the environment, allowing for construction of type-literals whose definitions are included in the common expression built-in set.

The input types may either be instances of `proto.Message` or `ref.Type`. Any other type provided to this option will result in an error.

Well-known protobuf types within the `google.protobuf.*` package are included in the standard environment by default.

Note: This option must be specified after the CustomTypeProvider option when used together.

type EvalDetails

type EvalDetails interface {
	// State of the evaluation, non-nil if the OptTrackState or OptExhaustiveEval is specified
	// within EvalOptions.
	State() interpreter.EvalState
}

EvalDetails holds additional information observed during the Eval() call.

type EvalOption

type EvalOption int

EvalOption indicates an evaluation option that may affect the evaluation behavior or information in the output result.

const (
	// OptTrackState will cause the runtime to return an immutable EvalState value in the Result.
	OptTrackState EvalOption = 1 << iota

	// OptExhaustiveEval causes the runtime to disable short-circuits and track state.
	OptExhaustiveEval EvalOption = 1<<iota | OptTrackState

	// OptFoldConstants evaluates functions and operators with constants as arguments at program
	// creation time. This flag is useful when the expression will be evaluated repeatedly against
	// a series of different inputs.
	OptFoldConstants EvalOption = 1 << iota
)

type Issues

type Issues interface {
	fmt.Stringer

	// Err returns an error value if the issues list contains one or more errors.
	Err() error

	// Errors returns the collection of errors encountered in more granular detail.
	Errors() []common.Error
}

Issues defines methods for inspecting the error details of parse and check calls.

Note: in the future, non-fatal warnings and notices may be inspectable via the Issues interface.

type Program

type Program interface {
	// Eval returns the result of an evaluation of the Ast and environment against the input vars.
	//
	// If the evaluation is an error, the result will be nil with a non-nil error.
	//
	// If the OptTrackState or OptExhaustiveEval is used, the EvalDetails response will be non-nil.
	Eval(vars interpreter.Activation) (ref.Val, EvalDetails, error)
}

Program is an evaluable view of an Ast.

type ProgramOption

type ProgramOption func(p *prog) (*prog, error)

ProgramOption is a functional interface for configuring evaluation bindings and behaviors.

func EvalOptions

func EvalOptions(opts ...EvalOption) ProgramOption

EvalOptions sets one or more evaluation options which may affect the evaluation or Result.

func Functions

func Functions(funcs ...*functions.Overload) ProgramOption

Functions adds function overloads that extend or override the set of CEL built-ins.

func Globals

func Globals(vars interpreter.Activation) ProgramOption

Globals sets the global variable values for a given program. These values may be shadowed within the Activation value provided to the Eval() function.

type Source

type Source interface {
	common.Source
}

Source interface representing a user-provided expression.