RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://pkg.go.dev/github.com/google/cel-go/cel below:

cel package - github.com/google/cel-go/cel - Go Packages

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.

package main

import (
	"fmt"
	"log"

	"github.com/google/cel-go/cel"
	"github.com/google/cel-go/common/types"
	"github.com/google/cel-go/common/types/ref"
)

func main() {
	// Create the CEL environment with declarations for the input attributes and the extension functions.
	// In many cases the desired functionality will be present in a built-in function.
	e, err := cel.NewEnv(
		// Variable identifiers used within this expression.
		cel.Variable("i", cel.StringType),
		cel.Variable("you", cel.StringType),
		// Function to generate a greeting from one person to another: i.greet(you)
		cel.Function("greet",
			cel.MemberOverload("string_greet_string", []*cel.Type{cel.StringType, cel.StringType}, cel.StringType,
				cel.BinaryBinding(func(lhs, rhs ref.Val) ref.Val {
					return types.String(fmt.Sprintf("Hello %s! Nice to meet you, I'm %s.\n", rhs, lhs))
				}),
			),
		),
	)
	if err != nil {
		log.Fatalf("environment creation error: %s\n", err)
	}

	// Compile the expression.
	ast, iss := e.Compile("i.greet(you)")
	if iss.Err() != nil {
		log.Fatalln(iss.Err())
	}

	// Create the program.
	prg, err := e.Program(ast)
	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]any{
		// 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.

package main

import (
	"fmt"
	"log"

	"github.com/google/cel-go/cel"
	"github.com/google/cel-go/common/types"
	"github.com/google/cel-go/common/types/ref"
)

func main() {
	// The GlobalOverload example demonstrates how to define global overload function.
	// 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.
	e, err := cel.NewEnv(
		// Identifiers used within this expression.
		cel.Variable("i", cel.StringType),
		cel.Variable("you", cel.StringType),
		// Function to generate shake_hands between two people.
		//    shake_hands(i,you)
		cel.Function("shake_hands",
			cel.Overload("shake_hands_string_string", []*cel.Type{cel.StringType, cel.StringType}, cel.StringType,
				cel.BinaryBinding(func(arg1, arg2 ref.Val) ref.Val {
					return types.String(fmt.Sprintf("%v and %v are shaking hands.\n", arg1, arg2))
				}),
			),
		),
	)
	if err != nil {
		log.Fatalf("environment creation error: %s\n", err)
	}

	// Compile the expression.
	ast, iss := e.Compile(`shake_hands(i,you)`)
	if iss.Err() != nil {
		log.Fatalln(iss.Err())
	}

	// Create the program.
	prg, err := e.Program(ast)
	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]any{
		"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.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/google/cel-go/cel"
	"github.com/google/cel-go/common/types"
	"github.com/google/cel-go/common/types/ref"
)

func main() {
	// makeFetch produces a consistent function signature with a different function
	// implementation depending on the provided context.
	makeFetch := func(ctx any) cel.EnvOption {
		fn := func(arg ref.Val) ref.Val {
			return types.NewErr("stateful context not bound")
		}
		if ctx != nil {
			fn = func(resource ref.Val) ref.Val {
				return types.DefaultTypeAdapter.NativeToValue(
					ctx.(context.Context).Value(contextString(string(resource.(types.String)))),
				)
			}
		}
		return cel.Function("fetch",
			cel.Overload("fetch_string",
				[]*cel.Type{cel.StringType}, cel.StringType,
				cel.UnaryBinding(fn),
			),
		)
	}

	// The base environment declares the fetch function with a dummy binding that errors
	// if it is invoked without being replaced by a subsequent call to `baseEnv.Extend`
	baseEnv, err := cel.NewEnv(
		// Identifiers used within this expression.
		cel.Variable("resource", cel.StringType),
		// Function to fetch a resource.
		//    fetch(resource)
		makeFetch(nil),
	)
	if err != nil {
		log.Fatalf("environment creation error: %s\n", err)
	}
	ast, iss := baseEnv.Compile("fetch('my-resource') == 'my-value'")
	if iss.Err() != nil {
		log.Fatalf("Compile() failed: %v", iss.Err())
	}

	// The runtime environment extends the base environment with a contextual binding for
	// the 'fetch' function.
	ctx := context.WithValue(context.TODO(), contextString("my-resource"), "my-value")
	runtimeEnv, err := baseEnv.Extend(makeFetch(ctx))
	if err != nil {
		log.Fatalf("baseEnv.Extend() failed with error: %s\n", err)
	}
	prg, err := runtimeEnv.Program(ast)
	if err != nil {
		log.Fatalf("runtimeEnv.Program() error: %s\n", err)
	}
	out, _, err := prg.Eval(cel.NoVars())
	if err != nil {
		log.Fatalf("runtime error: %s\n", err)
	}

	fmt.Println(out)
}

type contextString string

Output:

true

View Source

const (

	
	
	
	
	
	
	
	HomogeneousAggregateLiteralExemptFunctions = homogeneousValidatorName + ".exempt"
)

AlphaProtoAsValue converts between google.api.expr.v1alpha1.Value and ref.Val.

AstToCheckedExpr converts an Ast to an protobuf CheckedExpr value.

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

AstToParsedExpr converts an Ast to an protobuf ParsedExpr value.

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.

ExprToString converts an AST Expr node back to a string using macro call tracking metadata from source info if any macros are encountered within the expression.

FormatCELType formats a cel.Type value to a string representation.

The type formatting is identical to FormatType.

FormatType converts a type message into a string representation.

Deprecated: prefer FormatCELType

ProtoAsValue converts between cel.expr.Value and ref.Val.

RefValueToValue converts between ref.Val and google.api.expr.v1alpha1.Value. The result Value is the serialized proto form. The ref.Val must not be error or unknown.

TypeToExprType converts a CEL-native type representation to a protobuf CEL Type representation.

ValueAsAlphaProto converts between ref.Val and google.api.expr.v1alpha1.Value. The result Value is the serialized proto form. The ref.Val must not be error or unknown.

ValueAsProto converts between ref.Val and cel.expr.Value. The result Value is the serialized proto form. The ref.Val must not be error or unknown.

ValueToRefValue converts between google.api.expr.v1alpha1.Value and ref.Val.

ASTOptimizer applies an optimization over an AST and returns the optimized result.

NewConstantFoldingOptimizer creates an optimizer which inlines constant scalar an aggregate literal values within function calls and select statements with their evaluated result.

NewInliningOptimizer creates and optimizer which replaces variables with expression definitions.

If a variable occurs one time, the variable is replaced by the inline definition. If the variable occurs more than once, the variable occurences are replaced by a cel.bind() call.

ASTValidator defines a singleton interface for validating a type-checked Ast against an environment.

Note: the Issues argument is mutable in the sense that it is intended to collect errors which will be reported to the caller.

ValidateComprehensionNestingLimit ensures that comprehension nesting does not exceed the specified limit.

This validator can be useful for preventing arbitrarily nested comprehensions which can take high polynomial time to complete.

Note, this limit does not apply to comprehensions with an empty iteration range, as these comprehensions have no actual looping cost. The cel.bind() utilizes the comprehension structure to perform local variable assignments and supplies an empty iteration range, so they won't count against the nesting limit either.

ValidateDurationLiterals ensures that duration literal arguments are valid immediately after type-check.

ValidateHomogeneousAggregateLiterals checks that all list and map literals entries have the same types, i.e. no mixed list element types or mixed map key or map value types.

Note: the string format call relies on a mixed element type list for ease of use, so this check skips all literals which occur within string format calls.

ValidateRegexLiterals ensures that regex patterns are validated after type-check.

ValidateTimestampLiterals ensures that timestamp literal arguments are valid immediately after type-check.

ASTValidatorConfigurer indicates that this object, currently expected to be an ASTValidator, participates in validator configuration settings.

This interface may be split from the expectation of being an ASTValidator instance in the future.

ASTValidatorFactory creates an ASTValidator as configured by the input map

Activation used to resolve identifiers by name and references by id.

An Activation is the primary mechanism by which a caller supplies input into a CEL program.

ContextProtoVars uses the fields of the input proto.Messages as top-level variables within an Activation.

Consider using with `DeclareContextProto` to simplify variable type declarations and publishing when using protocol buffers.

NewActivation returns an activation based on a map-based binding where the map keys are expected to be qualified names used with ResolveName calls.

The input `bindings` may either be of type `Activation` or `map[string]any`.

Lazy bindings may be supplied within the map-based input in either of the following forms: - func() any - func() ref.Val

The output of the lazy binding will overwrite the variable reference in the internal map.

Values which are not represented as ref.Val types on input may be adapted to a ref.Val using the types.Adapter configured in the environment.

NoVars returns an empty Activation.

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

CheckedExprToAst converts a checked expression proto message to an Ast.

CheckedExprToAstWithSource converts a checked expression proto message to an Ast, using the provided Source as the textual contents.

In general the source is not necessary unless the AST has been modified between the `Parse` and `Check` calls as an `Ast` created from the `Parse` step will carry the source through future calls.

Prefer CheckedExprToAst if loading expressions from storage.

ParsedExprToAst converts a parsed expression proto message to an Ast.

ParsedExprToAstWithSource converts a parsed expression proto message to an Ast, using the provided Source as the textual contents.

In general you only need this if you need to recheck a previously checked expression, or if you need to separately check a subset of an expression.

Prefer ParsedExprToAst if loading expressions from storage.

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

Deprecated: prefer cel.AstToCheckedExpr() or cel.AstToParsedExpr() and call GetExpr() the result instead.

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

NativeRep converts the AST to a Go-native representation.

OutputType returns the output type of the expression if the Ast has been type-checked, else returns cel.DynType as the parse step cannot infer types.

ResultType returns the output type of the expression if the Ast has been type-checked, else returns chkdecls.Dyn as the parse step cannot infer the type.

Deprecated: use OutputType

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

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

AttributePatternType represents a top-level variable with an optional set of qualifier patterns.

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

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.

ConfigOptionFactory declares a signature which accepts a configuration element, e.g. env.Extension and optionally produces an EnvOption in response.

If there are multiple ConfigOptionFactory values which could apply to the same configuration node the first one that returns an EnvOption and a `true` response will be used, and the config node will not be passed along to any other option factory.

Only the *env.Extension type is provided at this time, but validators, optimizers, and other tuning parameters may be supported in the future.

type ConfigurableASTValidator interface {
	
	
	
	
	
	
	ToConfig() *env.Validator
}

ConfigurableASTValidator supports conversion of an object to an `env.Validator` instance used for YAML serialization.

type ConstantFoldingOption func(opt *constantFoldingOptimizer) (*constantFoldingOptimizer, error)

ConstantFoldingOption defines a functional option for configuring constant folding.

MaxConstantFoldIterations limits the number of times literals may be folding during optimization.

Defaults to 100 if not set.

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

NewCustomEnv creates a custom program environment which is not automatically configured with the standard library of functions and macros documented in the CEL spec.

The purpose for using a custom environment might be for subsetting the standard library produced by the cel.StdLib() function. Subsetting CEL is a core aspect of its design that allows users to limit the compute and memory impact of a CEL program by controlling the functions and macros that may appear in a given expression.

See the EnvOption helper functions for the options that can be used to configure the environment.

NewEnv creates a program environment configured with the standard library of CEL functions and macros. The Env value returned can parse and check any CEL program which builds upon the core features documented in the CEL specification.

See the EnvOption helper functions for the options that can be used to configure the environment.

CELTypeAdapter returns the `types.Adapter` configured for the environment.

CELTypeProvider returns the `types.Provider` configured for the environment.

Check performs type-checking on the input Ast and yields a checked Ast and/or set of Issues. If any `ASTValidators` are configured on the environment, they will be applied after a valid type-check result. If any issues are detected, the validators will provide them on the output Issues object.

Either checking or validation 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.

Compile combines the Parse and Check phases CEL program compilation to produce an Ast and associated issues.

If an error is encountered during parsing the Compile step will not continue with the Check phase. If non-error issues are encountered during Parse, they may be combined with any issues discovered during Check.

Note, for parse-only uses of CEL use Parse.

CompileSource combines the Parse and Check phases CEL program compilation to produce an Ast and associated issues.

If an error is encountered during parsing the CompileSource step will not continue with the Check phase. If non-error issues are encountered during Parse, they may be combined with any issues discovered during Check.

Note, for parse-only uses of CEL use Parse.

EstimateCost estimates the cost of a type checked CEL expression using the length estimates of input data and extension functions provided by estimator.

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

Note, the extended Env value should not share memory with the original. It is possible, however, that a CustomTypeAdapter or CustomTypeProvider options could provide values which are mutable. To ensure separation of state between extended environments either make sure the TypeAdapter and TypeProvider are immutable, or that their underlying implementations are based on the ref.TypeRegistry which provides a Copy method which will be invoked by this method.

Functions returns a shallow copy of the Functions, keyed by function name, that have been configured in the environment.

HasFeature checks whether the environment enables the given feature flag, as enumerated in options.go.

HasFunction returns whether a specific function has been configured in the environment

HasLibrary returns whether a specific SingletonLibrary has been configured in the environment.

HasValidator returns whether a specific ASTValidator has been configured in the environment.

Libraries returns a list of SingletonLibrary that have been configured in the environment.

Macros returns a shallow copy of macros associated with the environment.

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

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

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.

PartialVars returns a PartialActivation where all variables not in the input variable set, but which have been configured in the environment, are marked as unknown.

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

Note, this is equivalent to calling cel.PartialVars and manually configuring the set of unknown variables. For more advanced use cases of partial state where portions of an object graph, rather than top-level variables, are missing the PartialVars() method may be a more suitable choice.

Note, the PartialVars will behave the same as cel.NoVars() unless the PartialAttributes option is provided as a ProgramOption.

PlanProgram generates an evaluable instance of the AST in the go-native representation within the environment (Env).

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

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.

ToConfig produces a YAML-serializable env.Config object from the given environment.

The serialized configuration value is intended to represent a baseline set of config options which could be used as input to an EnvOption to configure the majority of the environment from a file.

Note: validators, features, flags, and safe-guard settings are not yet supported by the serialize method. Since optimizers are a separate construct from the environment and the standard expression components (parse, check, evalute), they are also not supported by the serialize method.

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

Deprecated: use CELTypeAdapter()

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

Deprecated: use CELTypeProvider()

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

Note, the UnknownVars will behave the same as an cel.NoVars() unless the PartialAttributes option is provided as a ProgramOption.

Validators returns the set of ASTValidators configured on the environment.

Variables returns a shallow copy of the variables associated with the environment.

EnvOption is a functional interface for configuring the environment.

ASTValidators configures a set of ASTValidator instances into the target environment.

Validators are applied in the order in which the are specified and are treated as singletons. The same ASTValidator with a given name will not be applied more than once.

Abbrevs configures a set of simple names as abbreviations for fully-qualified names.

An abbreviation (abbrev for short) is a simple name that expands to a fully-qualified name. Abbreviations can be useful when working with variables, functions, and especially types from multiple namespaces:

// CEL object construction
qual.pkg.version.ObjTypeName{
   field: alt.container.ver.FieldTypeName{value: ...}
}

Only one the qualified names above may be used as the CEL container, so at least one of these references must be a long qualified name within an otherwise short CEL program. Using the following abbreviations, the program becomes much simpler:

// CEL Go option
Abbrevs("qual.pkg.version.ObjTypeName", "alt.container.ver.FieldTypeName")
// Simplified Object construction
ObjTypeName{field: FieldTypeName{value: ...}}

There are a few rules for the qualified names and the simple abbreviations generated from them: - Qualified names must be dot-delimited, e.g. `package.subpkg.name`. - The last element in the qualified name is the abbreviation. - Abbreviations must not collide with each other. - The abbreviation must not collide with unqualified names in use.

Abbreviations are distinct from container-based references in the following important ways: - Abbreviations must expand to a fully-qualified name. - Expanded abbreviations do not participate in namespace resolution. - Abbreviation expansion is done instead of the container search for a matching identifier. - Containers follow C++ namespace resolution rules with searches from the most qualified name

to the least qualified name.

- Container references within the CEL program may be relative, and are resolved to fully

qualified names at either type-check time or program plan time, whichever comes first.

If there is ever a case where an identifier could be in both the container and as an abbreviation, the abbreviation wins as this will ensure that the meaning of a program is preserved between compilations even as the container evolves.

AlphaProtoAsDeclaration converts a v1alpha1.Decl value describing a variable or function into an 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.

Constant creates an instances of an identifier declaration with a variable name, type, and value.

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

CostEstimatorOptions configure type-check time options for estimating expression cost.

CrossTypeNumericComparisons makes it possible to compare across numeric types, e.g. double < int

CustomTypeAdapter swaps the default types.Adapter implementation with a custom one.

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

CustomTypeProvider replaces the types.Provider implementation with a custom one.

The `provider` variable type may either be types.Provider or ref.TypeProvider (deprecated)

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

Declarations option extends the declaration set configured in the environment.

Note: Declarations will by default be appended to the pre-existing declaration set configured for the environment. The NewEnv call builds on top of the standard CEL declarations. For a purely custom set of declarations use NewCustomEnv.

Deprecated: use FunctionDecls and VariableDecls or FromConfig instead.

DefaultUTCTimeZone ensures that time-based operations use the UTC timezone rather than the input time's local timezone.

EagerlyValidateDeclarations ensures that any collisions between configured declarations are caught at the time of the `NewEnv` call.

Eagerly validating declarations is also useful for bootstrapping a base `cel.Env` value. Calls to base `Env.Extend()` will be significantly faster when declarations are eagerly validated as declarations will be collision-checked at most once and only incrementally by way of `Extend`

Disabled by default as not all environments are used for type-checking.

EnableErrorOnBadPresenceTest enables error generation when a presence test or optional field selection is performed on a primitive type.

EnableHiddenAccumulatorName sets the parser to use the identifier '@result' for accumulators which is not normally accessible from CEL source.

func EnableIdentifierEscapeSyntax() EnvOption

EnableIdentifierEscapeSyntax enables identifier escaping (`) syntax for fields.

EnableMacroCallTracking ensures that call expressions which are replaced by macros are tracked in the `SourceInfo` of parsed and checked expressions.

ExprDeclToDeclaration converts a protobuf CEL declaration to a CEL-native declaration, either a Variable or Function.

ExtendedValidations collects a set of common AST validations which reduce the likelihood of runtime errors.

- Validate duration and timestamp literals - Ensure regex strings are valid - Disable mixed type list and map literals

FromConfig produces and applies a set of EnvOption values derived from an env.Config object.

For configuration elements which refer to features outside of the `cel` package, an optional set of ConfigOptionFactory values may be passed in to support the conversion from static configuration to configured cel.Env value.

Note: disabling the standard library will clear the EnvOptions values previously set for the environment with the exception of propagating types and adapters over to the new environment.

Note: to support custom types referenced in the configuration file, you must ensure that one of the following options appears before the FromConfig option: Types, TypeDescs, or CustomTypeProvider as the type provider configured at the time when the config is processed is the one used to derive type references from the configuration.

Function defines a function and overloads with optional singleton or per-overload bindings.

Using Function is roughly equivalent to calling Declarations() to declare the function signatures and Functions() to define the function bindings, if they have been defined. Specifying the same function name more than once will result in the aggregation of the function overloads. If any signatures conflict between the existing and new function definition an error will be raised. However, if the signatures are identical and the overload ids are the same, the redefinition will be considered a no-op.

One key difference with using Function() is that each FunctionDecl provided will handle dynamic dispatch based on the type-signatures of the overloads provided which means overload resolution at runtime is handled out of the box rather than via a custom binding for overload resolution via Functions():

- Overloads are searched in the order they are declared - Dynamic dispatch for lists and maps is limited by inspection of the list and map contents

at runtime. Empty lists and maps will result in a 'default dispatch'

- In the event that a default dispatch occurs, the first overload provided is the one invoked

If you intend to use overloads which differentiate based on the key or element type of a list or map, consider using a generic function instead: e.g. func(list(T)) or func(map(K, V)) as this will allow your implementation to determine how best to handle dispatch and the default behavior for empty lists and maps whose contents cannot be inspected.

For functions which use parameterized opaque types (abstract types), consider using a singleton function which is capable of inspecting the contents of the type and resolving the appropriate overload as CEL can only make inferences by type-name regarding such types.

FunctionDecls provides one or more fully formed function declarations to be added to the environment.

func HomogeneousAggregateLiterals() EnvOption

HomogeneousAggregateLiterals disables mixed type list and map literal values.

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.

Lib creates an EnvOption out of a Library, allowing libraries to be provided as functional args, and to be linked to each other.

Macros option extends the macro set configured in the environment.

Note: This option must be specified after ClearMacros if used together.

OptionalTypes enable support for optional syntax and types in CEL.

The optional value type makes it possible to express whether variables have been provided, whether a result has been computed, and in the future whether an object field path, map key value, or list index has a value.

Syntax Changes ¶

OptionalTypes are unlike other CEL extensions because they modify the CEL syntax itself, notably through the use of a `?` preceding a field name or index value.

## Field Selection

The optional syntax in field selection is denoted as `obj.?field`. In other words, if a field is set, return `optional.of(obj.field)“, else `optional.none()`. The optional field selection is viral in the sense that after the first optional selection all subsequent selections or indices are treated as optional, i.e. the following expressions are equivalent:

obj.?field.subfield
obj.?field.?subfield

## Indexing

Similar to field selection, the optional syntax can be used in index expressions on maps and lists:

list[?0]
map[?key]

## Optional Field Setting

When creating map or message literals, if a field may be optionally set based on its presence, then placing a `?` before the field name or key will ensure the type on the right-hand side must be optional(T) where T is the type of the field or key-value.

The following returns a map with the key expression set only if the subfield is present, otherwise an empty map is created:

{?key: obj.?field.subfield}

## Optional Element Setting

When creating list literals, an element in the list may be optionally added when the element expression is preceded by a `?`:

[a, ?b, ?c] // return a list with either [a], [a, b], [a, b, c], or [a, c]

Optional.Of ¶

Create an optional(T) value of a given value with type T.

optional.of(10)

Optional.OfNonZeroValue ¶

Create an optional(T) value of a given value with type T if it is not a zero-value. A zero-value the default empty value for any given CEL type, including empty protobuf message types. If the value is empty, the result of this call will be optional.none().

optional.ofNonZeroValue([1, 2, 3]) // optional(list(int))
optional.ofNonZeroValue([]) // optional.none()
optional.ofNonZeroValue(0)  // optional.none()
optional.ofNonZeroValue("") // optional.none()

Optional.None ¶

Create an empty optional value.

HasValue ¶

Determine whether the optional contains a value.

optional.of(b'hello').hasValue() // true
optional.ofNonZeroValue({}).hasValue() // false

Value ¶

Get the value contained by the optional. If the optional does not have a value, the result will be a CEL error.

optional.of(b'hello').value() // b'hello'
optional.ofNonZeroValue({}).value() // error

Or ¶

If the value on the left-hand side is optional.none(), the optional value on the right hand side is returned. If the value on the left-hand set is valued, then it is returned. This operation is short-circuiting and will only evaluate as many links in the `or` chain as are needed to return a non-empty optional value.

obj.?field.or(m[?key])
l[?index].or(obj.?field.subfield).or(obj.?other)

OrValue ¶

Either return the value contained within the optional on the left-hand side or return the alternative value on the right hand side.

m[?key].orValue("none")

OptMap ¶

Apply a transformation to the optional's underlying value if it is not empty and return an optional typed result based on the transformation. The transformation expression type must return a type T which is wrapped into an optional.

msg.?elements.optMap(e, e.size()).orValue(0)

OptFlatMap ¶

Introduced in version: 1

Apply a transformation to the optional's underlying value if it is not empty and return the result. The transform expression must return an optional(T) rather than type T. This can be useful when dealing with zero values and conditionally generating an empty or non-empty result in ways which cannot be expressed with `optMap`.

msg.?elements.optFlatMap(e, e[?0]) // return the first element if present.

First ¶

Introduced in version: 2

Returns an optional with the first value from the right hand list, or optional.None.

[1, 2, 3].first().value() == 1

Last ¶

Introduced in version: 2

Returns an optional with the last value from the right hand list, or optional.None.

[1, 2, 3].last().value() == 3

This is syntactic sugar for msg.elements[msg.elements.size()-1].

Unwrap / UnwrapOpt ¶

Introduced in version: 2

Returns a list of all the values that are not none in the input list of optional values. Can be used as optional.unwrap(List[T]) or with postfix notation: List[T].unwrapOpt()

optional.unwrap([optional.of(42), optional.none()]) == [42] [optional.of(42), optional.none()].unwrapOpt() == [42]

ParserExpressionSizeLimit adjusts the number of code points the expression parser is allowed to parse. Defaults defined in the parser package.

ParserRecursionLimit adjusts the AST depth the parser will tolerate. Defaults defined in the parser package.

ProtoAsDeclaration converts a canonical celpb.Decl value describing a variable or function into an EnvOption.

StdLib returns an EnvOption for the standard library of CEL functions and macros.

TypeDescs adds type declarations from any protoreflect.FileDescriptor, protoregistry.Files, google.protobuf.FileDescriptorProto or google.protobuf.FileDescriptorSet provided.

Note that messages instantiated from these descriptors will be *dynamicpb.Message values rather than the concrete message type.

TypeDescs are hermetic to a single Env object, but may be copied to other Env values via extension or by re-using the same EnvOption with another NewEnv() call.

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.

Variable creates an instance of a variable declaration with a variable name and type.

VariableDecls configures a set of fully defined cel.VariableDecl instances in the environment.

VariableWithDoc creates an instance of a variable declaration with a variable name, type, and doc string.

Error type which references an expression id, a location within source, and a message.

func ExistsMacroExpander ¶ added in v0.12.0

ExistsMacroExpander expands the input call arguments into a comprehension that returns true if any of the elements in the range match the predicate expressions: <iterRange>.exists(<iterVar>, <predicate>)

func ExistsOneMacroExpander ¶ added in v0.12.0

ExistsOneMacroExpander expands the input call arguments into a comprehension that returns true if exactly one of the elements in the range match the predicate expressions: <iterRange>.exists_one(<iterVar>, <predicate>)

func FilterMacroExpander ¶ added in v0.12.0

FilterMacroExpander expands the input call arguments into a comprehension which produces a list which contains only elements which match the provided predicate expression: <iterRange>.filter(<iterVar>, <predicate>)

func HasMacroExpander ¶ added in v0.12.0

HasMacroExpander expands the input call arguments into a presence test, e.g. has(<operand>.field)

func MapMacroExpander ¶ added in v0.12.0

MapMacroExpander expands the input call arguments into a comprehension that transforms each element in the input to produce an output list.

There are two call patterns supported by map:

<iterRange>.map(<iterVar>, <transform>)
<iterRange>.map(<iterVar>, <predicate>, <transform>)

In the second form only iterVar values which return true when provided to the predicate expression are transformed.

type EvalDetails struct {
	
}

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

ActualCost returns the tracked cost through the course of execution when `CostTracking` is enabled. Otherwise, returns nil if the cost was not enabled.

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

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

FunctionOpt defines a functional option for configuring a function declaration.

DisableDeclaration disables the function signatures, effectively removing them from the type-check environment while preserving the runtime bindings.

FunctionDocs provides a general usage documentation for the function.

Use OverloadExamples to provide example usage instructions for specific overloads.

MemberOverload defines a new receiver-style overload (or member function) with an overload id, argument types, and result type. Through the use of OverloadOpt options, the overload may also be configured with a binding, an operand trait, and to be non-strict.

Note: function bindings should be commonly configured with Overload instances whereas operand traits and strict-ness should be rare occurrences.

Overload defines a new global overload with an overload id, argument types, and result type. Through the use of OverloadOpt options, the overload may also be configured with a binding, an operand trait, and to be non-strict.

Note: function bindings should be commonly configured with Overload instances whereas operand traits and strict-ness should be rare occurrences.

SingletonBinaryBinding creates a singleton function definition to be used with all function overloads.