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("string_greet_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: "string_greet_string",
			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(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.

{
	// 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 shake_hands between two people.
		//    shake_hands(i,you)
		decls.NewFunction("shake_hands",
			decls.NewOverload("shake_hands_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(`shake_hands(i,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: "shake_hands_string_string",
			Binary: func(lhs ref.Val, rhs ref.Val) ref.Val {
				s1, ok := lhs.(types.String)
				if !ok {
					return types.ValOrErr(lhs, "unexpected type '%v' passed to shake_hands", lhs.Type())
				}
				s2, ok := rhs.(types.String)
				if !ok {
					return types.ValOrErr(rhs, "unexpected type '%v' passed to shake_hands", rhs.Type())
				}
				return types.String(
					fmt.Sprintf("%s and %s are shaking hands.\n", s1, s2))
			}})
	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(map[string]interface{}{
		"i":   "CEL",
		"you": func() ref.Val { return types.String("world") },
	})
	if err != nil {
		log.Fatalf("runtime error: %s\n", err)
	}

	fmt.Println(out)
	// Output:CEL and world are shaking hands.
}

CEL and world are shaking hands.

Index ¶

• func AstToCheckedExpr(a *Ast) (*exprpb.CheckedExpr, error)
• func AstToParsedExpr(a *Ast) (*exprpb.ParsedExpr, error)
• func AstToString(a *Ast) (string, error)
• func AttributePattern(varName string) *interpreter.AttributePattern
• func NoVars() interpreter.Activation
• func PartialVars(vars interface{}, unknowns ...*interpreter.AttributePattern) (interpreter.PartialActivation, error)
• type Ast
• func CheckedExprToAst(checkedExpr *exprpb.CheckedExpr) *Ast
• func ParsedExprToAst(parsedExpr *exprpb.ParsedExpr) *Ast
• func (ast *Ast) Expr() *exprpb.Expr
• func (ast *Ast) IsChecked() bool
• func (ast *Ast) ResultType() *exprpb.Type
• func (ast *Ast) Source() Source
• func (ast *Ast) SourceInfo() *exprpb.SourceInfo
• type Env
• func NewEnv(opts ...EnvOption) (*Env, error)
• func (e *Env) Check(ast *Ast) (*Ast, *Issues)
• func (e *Env) Extend(opts ...EnvOption) (*Env, error)
• func (e *Env) Parse(txt string) (*Ast, *Issues)
• func (e *Env) ParseSource(src common.Source) (*Ast, *Issues)
• func (e *Env) Program(ast *Ast, opts ...ProgramOption) (Program, error)
• func (e *Env) ResidualAst(a *Ast, details *EvalDetails) (*Ast, error)
• func (e *Env) TypeAdapter() ref.TypeAdapter
• func (e *Env) TypeProvider() ref.TypeProvider
• func (e *Env) UnknownVars() interpreter.PartialActivation
• type EnvOption
• func ClearBuiltIns() EnvOption
• func ClearMacros() EnvOption
• func Container(pkg string) EnvOption
• func CustomTypeAdapter(adapter ref.TypeAdapter) EnvOption
• func CustomTypeProvider(provider ref.TypeProvider) EnvOption
• func Declarations(decls ...*exprpb.Decl) EnvOption
• func HomogeneousAggregateLiterals() EnvOption
• func Macros(macros ...parser.Macro) EnvOption
• func TypeDescs(descs ...interface{}) EnvOption
• func Types(addTypes ...interface{}) EnvOption
• type EvalDetails
• func (ed *EvalDetails) State() interpreter.EvalState
• type EvalOption
• type Issues
• func NewIssues(errs *common.Errors) *Issues
• func (i *Issues) Append(other *Issues)
• func (i *Issues) Err() error
• func (i *Issues) Errors() []common.Error
• func (i *Issues) String() string
• type Program
• type ProgramOption
• func EvalOptions(opts ...EvalOption) ProgramOption
• func Functions(funcs ...*functions.Overload) ProgramOption
• func Globals(vars interface{}) ProgramOption
• type Source

Examples ¶

• package
• package (GlobalOverload)

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 AstToString ¶

func AstToString(a *Ast) (string, error)

AstToString converts an Ast back to a string if possible.

Note, the conversion may not be an exact replica of the original expression, but will produce a string that is semantically equivalent and whose textual representation is stable.

func AttributePattern ¶

func AttributePattern(varName string) *interpreter.AttributePattern

AttributePattern returns an AttributePattern that matches a top-level variable. The pattern is mutable, and its methods support the specification of one or more qualifier patterns.

For example, the AttributePattern(`a`).QualString(`b`) represents a variable access `a` with a string field or index qualification `b`. This pattern will match Attributes `a`, and `a.b`, but not `a.c`.

When using a CEL expression within a container, e.g. a package or namespace, the variable name in the pattern must match the qualified name produced during the variable namespace resolution. For example, when variable `a` is declared within an expression whose container is `ns.app`, the fully qualified variable name may be `ns.app.a`, `ns.a`, or `a` per the CEL namespace resolution rules. Pick the fully qualified variable name that makes sense within the container as the AttributePattern `varName` argument.

See the interpreter.AttributePattern and interpreter.AttributeQualifierPattern for more info about how to create and manipulate AttributePattern values.

func NoVars ¶

func NoVars() interpreter.Activation

NoVars returns an empty Activation.

func PartialVars ¶

func PartialVars(vars interface{},
	unknowns ...*interpreter.AttributePattern) (interpreter.PartialActivation, error)

PartialVars returns a PartialActivation which contains variables and a set of AttributePattern values that indicate variables or parts of variables whose value are not yet known.

The `vars` value may either be an interpreter.Activation or any valid input to the interpreter.NewActivation call.

Types ¶

type Ast ¶

type Ast struct {
	// contains filtered or unexported fields
}

Ast 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.

func (*Ast) Expr ¶

func (ast *Ast) Expr() *exprpb.Expr

Expr returns the proto serializable instance of the parsed/checked expression.

func (*Ast) IsChecked ¶

func (ast *Ast) IsChecked() bool

IsChecked returns whether the Ast value has been successfully type-checked.

func (*Ast) ResultType ¶

func (ast *Ast) ResultType() *exprpb.Type

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.

func (*Ast) Source ¶

func (ast *Ast) Source() Source

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

func (*Ast) SourceInfo ¶

func (ast *Ast) SourceInfo() *exprpb.SourceInfo

SourceInfo returns character offset and newling position information about expression elements.

type Env ¶

type Env struct {
	// contains filtered or unexported fields
}

Env encapsulates the context necessary to perform parsing, type checking, or generation of evaluable programs for different expressions.

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.

func (*Env) Check ¶

func (e *Env) Check(ast *Ast) (*Ast, *Issues)

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 are 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.

func (*Env) Extend ¶

func (e *Env) Extend(opts ...EnvOption) (*Env, error)

Extend the current environment with additional options to produce a new Env.

func (*Env) Parse ¶

func (e *Env) Parse(txt string) (*Ast, *Issues)

Parse parses the input expression value `txt` to a Ast and/or a set of Issues.

This form of Parse creates a common.Source value for the input `txt` and forwards to the ParseSource method.

func (*Env) ParseSource ¶

func (e *Env) ParseSource(src common.Source) (*Ast, *Issues)

ParseSource parses the input source to an Ast and/or 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.

func (*Env) Program ¶

func (e *Env) Program(ast *Ast, opts ...ProgramOption) (Program, error)

Program generates an evaluable instance of the Ast within the environment (Env).

func (*Env) ResidualAst ¶

func (e *Env) ResidualAst(a *Ast, details *EvalDetails) (*Ast, error)

ResidualAst takes an Ast and its EvalDetails to produce a new Ast which only contains the attribute references which are unknown.

Residual expressions are beneficial in a few scenarios:

- Optimizing constant expression evaluations away. - Indexing and pruning expressions based on known input arguments. - Surfacing additional requirements that are needed in order to complete an evaluation. - Sharing the evaluation of an expression across multiple machines/nodes.

For example, if an expression targets a 'resource' and 'request' attribute and the possible values for the resource are known, a PartialActivation could mark the 'request' as an unknown interpreter.AttributePattern and the resulting ResidualAst would be reduced to only the parts of the expression that reference the 'request'.

Note, the expression ids within the residual AST generated through this method have no correlation to the expression ids of the original AST.

See the PartialVars helper for how to construct a PartialActivation.

TODO: Consider adding an option to generate a Program.Residual to avoid round-tripping to an Ast format and then Program again.

func (*Env) TypeAdapter ¶

func (e *Env) TypeAdapter() ref.TypeAdapter

TypeAdapter returns the `ref.TypeAdapter` configured for the environment.

func (*Env) TypeProvider ¶

func (e *Env) TypeProvider() ref.TypeProvider

TypeProvider returns the `ref.TypeProvider` configured for the environment.

func (*Env) UnknownVars ¶

func (e *Env) UnknownVars() interpreter.PartialActivation

UnknownVars returns an interpreter.PartialActivation which marks all variables declared in the Env as unknown AttributePattern values.

Note, the UnknownVars will behave the same as an interpreter.EmptyActivation unless the PartialAttributes option is provided as a ProgramOption.

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 CustomTypeAdapter ¶

func CustomTypeAdapter(adapter ref.TypeAdapter) EnvOption

CustomTypeAdapter swaps the default ref.TypeAdapter implementation with a custom one.

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

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 and TypeDescs options 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 HomogeneousAggregateLiterals ¶

func HomogeneousAggregateLiterals() EnvOption

HomogeneousAggregateLiterals option ensures that list and map literal entry types must agree during type-checking.

Note, it is still possible to have heterogeneous aggregates when provided as variables to the expression, as well as via conversion of well-known dynamic types, or with unchecked expressions.

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 TypeDescs ¶

func TypeDescs(descs ...interface{}) EnvOption

TypeDescs adds type declarations for one or more protocol buffer FileDescriptorProtos or FileDescriptorSets. Note that types added via descriptor will not be able to instantiate messages, and so are only useful for Check() operations.

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 struct {
	// contains filtered or unexported fields
}

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

func (*EvalDetails) State ¶

func (ed *EvalDetails) State() interpreter.EvalState

State of the evaluation, non-nil if the OptTrackState or OptExhaustiveEval is specified within EvalOptions.

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

	// OptOptimize precomputes 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.
	OptOptimize EvalOption = 1 << iota

	// OptPartialEval enables the evaluation of a partial state where the input data that may be
	// known to be missing, either as top-level variables, or somewhere within a variable's object
	// member graph.
	//
	// By itself, OptPartialEval does not change evaluation behavior unless the input to the
	// Program Eval is an PartialVars.
	OptPartialEval EvalOption = 1 << iota
)

type Issues ¶

type Issues struct {
	// contains filtered or unexported fields
}

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 struct.

func NewIssues ¶

func NewIssues(errs *common.Errors) *Issues

NewIssues returns an Issues struct from a common.Errors object.

func (*Issues) Append ¶

func (i *Issues) Append(other *Issues)

Append collects the issues from another Issues struct into the current object.

func (*Issues) Err ¶

func (i *Issues) Err() error

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

func (*Issues) Errors ¶

func (i *Issues) Errors() []common.Error

Errors returns the collection of errors encountered in more granular detail.

func (*Issues) String ¶

func (i *Issues) String() string

String converts the issues to a suitable display string.

type Program ¶

type Program interface {
	// Eval returns the result of an evaluation of the Ast and environment against the input vars.
	//
	// The vars value may either be an `interpreter.Activation` or a `map[string]interface{}`.
	//
	// If the `OptTrackState` or `OptExhaustiveEval` flags are used, the `details` response will
	// be non-nil. Given this caveat on `details`, the return state from evaluation will be:
	//
	// *  `val`, `details`, `nil` - Successful evaluation of a non-error result.
	// *  `val`, `details`, `err` - Successful evaluation to an error result.
	// *  `nil`, `details`, `err` - Unsuccessful evaluation.
	//
	// An unsuccessful evaluation is typically the result of a series of incompatible `EnvOption`
	// or `ProgramOption` values used in the creation of the evaluation environment or executable
	// program.
	Eval(vars interface{}) (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 interface{}) ProgramOption

Globals sets the global variable values for a given program. These values may be shadowed by variables with the same name provided to the Eval() call.

The vars value may either be an `interpreter.Activation` instance or a `map[string]interface{}`.

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