package cel

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

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.

{
	// 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.
}

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.

Source Files ¶

cel.go env.go io.go options.go program.go