func AlphaProtoAsValue(adaptertypes.Adapter, v *exprpb.Value) (ref.Val,error)

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

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

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

func ExprToString(east.Expr, info *ast.SourceInfo) (string,error)

func ExprValueAsAlphaProto(resref.Val) (*exprpb.ExprValue,error)

func ExprValueAsProto(resref.Val) (*celpb.ExprValue,error)

func FormatCELType(t *Type)string

func ProtoAsValue(adaptertypes.Adapter, v *celpb.Value) (ref.Val,error)

func RefValToExprValue(resref.Val) (*exprpb.ExprValue,error)

func RefValueToValue(resref.Val) (*exprpb.Value,error)

func TypeToExprType(t *Type) (*exprpb.Type,error)

func ValueAsAlphaProto(resref.Val) (*exprpb.Value,error)

func ValueAsProto(resref.Val) (*celpb.Value,error)

func ValueToRefValue(adaptertypes.Adapter, v *exprpb.Value) (ref.Val,error)

type ASTOptimizer interface {// Optimize optimizes a type-checked AST within an Environment and accumulates any issues.Optimize(*OptimizerContext, *ast.AST) *ast.AST}

funcNewConstantFoldingOptimizer¶added inv0.18.0

func NewConstantFoldingOptimizer(opts ...ConstantFoldingOption) (ASTOptimizer,error)

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

funcNewInliningOptimizer¶added inv0.18.0

func NewInliningOptimizer(inlineVars ...*InlineVariable)ASTOptimizer

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 thevariable occurs more than once, the variable occurences are replaced by a cel.bind() call.

type ASTValidator interface {// Name returns the name of the validator. Names must be unique.Name()string// Validate validates a given Ast within an Environment and collects a set of potential issues.//// The ValidatorConfig is generated from the set of ASTValidatorConfigurer instances prior to// the invocation of the Validate call. The expectation is that the validator configuration// is created in sequence and immutable once provided to the Validate call.//// See individual validators for more information on their configuration keys and configuration// properties.Validate(*Env,ValidatorConfig, *ast.AST, *Issues)}

funcValidateComprehensionNestingLimit¶added inv0.17.0

func ValidateComprehensionNestingLimit(limitint)ASTValidator

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 polynomialtime to complete.

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

funcValidateDurationLiterals¶added inv0.17.0

func ValidateDurationLiterals()ASTValidator

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

funcValidateHomogeneousAggregateLiterals¶added inv0.17.0

func ValidateHomogeneousAggregateLiterals()ASTValidator

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 allliterals which occur within string format calls.

funcValidateRegexLiterals¶added inv0.17.0

func ValidateRegexLiterals()ASTValidator

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

funcValidateTimestampLiterals¶added inv0.17.0

func ValidateTimestampLiterals()ASTValidator

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

type ASTValidatorConfigurer interface {Configure(MutableValidatorConfig)error}

type ASTValidatorFactory func(*env.Validator) (ASTValidator,error)

type Activation =interpreter.Activation

funcContextProtoVars¶added inv0.17.0

func ContextProtoVars(ctxproto.Message) (Activation,error)

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 usingprotocol buffers.

funcNewActivation¶added inv0.24.0

func NewActivation(bindingsany) (Activation,error)

NewActivation returns an activation based on a map-based binding where the map keys areexpected 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 usingthe types.Adapter configured in the environment.

funcNoVars¶

func NoVars()Activation

NoVars returns an empty Activation.

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

funcCheckedExprToAst¶

func CheckedExprToAst(checkedExpr *exprpb.CheckedExpr) *Ast

CheckedExprToAst converts a checked expression proto message to an Ast.

funcCheckedExprToAstWithSource¶added inv0.9.0

func CheckedExprToAstWithSource(checkedExpr *exprpb.CheckedExpr, srcSource) (*Ast,error)

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 sourcethrough future calls.

Prefer CheckedExprToAst if loading expressions from storage.

funcParsedExprToAst¶

func ParsedExprToAst(parsedExpr *exprpb.ParsedExpr) *Ast

ParsedExprToAst converts a parsed expression proto message to an Ast.

funcParsedExprToAstWithSource¶added inv0.9.0

func ParsedExprToAstWithSource(parsedExpr *exprpb.ParsedExpr, srcSource) *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 checkedexpression, or if you need to separately check a subset of an expression.

Prefer ParsedExprToAst if loading expressions from storage.

func (*Ast)IsChecked¶

func (ast *Ast) IsChecked()bool

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

func (*Ast)NativeRep¶added inv0.18.2

func (ast *Ast) NativeRep() *celast.AST

NativeRep converts the AST to a Go-native representation.

func (*Ast)OutputType¶added inv0.12.0

func (ast *Ast) OutputType() *Type

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

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 orconstructed from the SourceInfo.

func (*Ast)SourceInfo¶

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

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

type AttributePatternType =interpreter.AttributePattern

funcAttributePattern¶added inv0.4.0

func AttributePattern(varNamestring) *AttributePatternType

AttributePattern returns an AttributePattern that matches a top-level variable. The pattern ismutable, 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 astring 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 namein 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`, thefully qualified variable name may be `ns.app.a`, `ns.a`, or `a` per the CEL namespace resolutionrules. Pick the fully qualified variable name that makes sense within the container as theAttributePattern `varName` argument.

type ConfigOptionFactory func(any) (EnvOption,bool)

type ConfigurableASTValidator interface {// ToConfig converts the internal configuration of an ASTValidator into an env.Validator instance// which minimally must include the validator name, but may also include a map[string]any config// object to be serialized to YAML. The string keys represent the configuration parameter name,// and the any value must mirror the internally supported type associated with the config key.//// Note: only primitive CEL types are supported by CEL validators at this time.ToConfig() *env.Validator}

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

funcFoldKnownValues¶added inv0.25.1

func FoldKnownValues(knownValuesActivation)ConstantFoldingOption

FoldKnownValues adds an Activation which provides known values for the folding evaluator

Any values the activation provides will be used by the constant folder and turned intoliterals in the AST.

Defaults to the NoVars() Activation

funcMaxConstantFoldIterations¶added inv0.18.0

func MaxConstantFoldIterations(limitint)ConstantFoldingOption

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

Defaults to 100 if not set.

type Env struct {Container *containers.Container// contains filtered or unexported fields}

funcNewCustomEnv¶added inv0.4.0

func NewCustomEnv(opts ...EnvOption) (*Env,error)

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

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

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

funcNewEnv¶

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

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

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

func (*Env)CELTypeAdapter¶added inv0.17.0

func (e *Env) CELTypeAdapter()types.Adapter

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

func (*Env)CELTypeProvider¶added inv0.17.0

func (e *Env) CELTypeProvider()types.Provider

CELTypeProvider returns the `types.Provider` configured for 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.If any `ASTValidators` are configured on the environment, they will be applied after a validtype-check result. If any issues are detected, the validators will provide them on theoutput 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 afatal 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)Compile¶added inv0.4.0

func (e *Env) Compile(txtstring) (*Ast, *Issues)

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

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

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

func (*Env)CompileSource¶added inv0.4.0

func (e *Env) CompileSource(srcSource) (*Ast, *Issues)

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

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

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

func (*Env)EstimateCost¶added inv0.10.0

func (e *Env) EstimateCost(ast *Ast, estimatorchecker.CostEstimator, opts ...checker.CostOption) (checker.CostEstimate,error)

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

func (*Env)Extend¶added inv0.3.2

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

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 andTypeProvider are immutable, or that their underlying implementations are based on theref.TypeRegistry which provides a Copy method which will be invoked by this method.

func (*Env)Functions¶added inv0.21.0

func (e *Env) Functions() map[string]*decls.FunctionDecl

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

func (*Env)HasFeature¶added inv0.5.1

func (e *Env) HasFeature(flagint)bool

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

func (*Env)HasFunction¶added inv0.21.0

func (e *Env) HasFunction(functionNamestring)bool

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

func (*Env)HasLibrary¶added inv0.13.0

func (e *Env) HasLibrary(libNamestring)bool

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

func (*Env)HasValidator¶added inv0.17.0

func (e *Env) HasValidator(namestring)bool

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

func (*Env)Libraries¶added inv0.17.5

func (e *Env) Libraries() []string

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

func (*Env)Macros¶added inv0.25.0

func (e *Env) Macros() []Macro

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

func (*Env)Parse¶

func (e *Env) Parse(txtstring) (*Ast, *Issues)

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 theParseSource method.

func (*Env)ParseSource¶added inv0.4.0

func (e *Env) ParseSource(srcSource) (*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)PartialVars¶added inv0.17.0

func (e *Env) PartialVars(varsany) (PartialActivation,error)

PartialVars returns a PartialActivation where all variables not in the input variableset, 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 unknownvariables. For more advanced use cases of partial state where portions of an object graph, ratherthan 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 PartialAttributesoption is provided as a ProgramOption.

func (*Env)PlanProgram¶added inv0.22.0

func (e *Env) PlanProgram(a *celast.AST, opts ...ProgramOption) (Program,error)

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

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¶added inv0.4.0

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 theattribute 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 possiblevalues for the resource are known, a PartialActivation could mark the 'request' as an unknowninterpreter.AttributePattern and the resulting ResidualAst would be reduced to only the partsof the expression that reference the 'request'.

Note, the expression ids within the residual AST generated through this method have nocorrelation 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 anAst format and then Program again.

func (*Env)ToConfig¶added inv0.24.0

func (e *Env) ToConfig(namestring) (*env.Config,error)

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

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

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

func (*Env)UnknownVars¶added inv0.4.0

func (e *Env) UnknownVars()PartialActivation

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

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

func (*Env)Validators¶added inv0.24.0

func (e *Env) Validators() []ASTValidator

Validators returns the set of ASTValidators configured on the environment.

func (*Env)Variables¶added inv0.24.0

func (e *Env) Variables() []*decls.VariableDecl

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

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

funcASTValidators¶added inv0.17.0

func ASTValidators(validators ...ASTValidator)EnvOption

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.

funcAbbrevs¶added inv0.6.0

func Abbrevs(qualifiedNames ...string)EnvOption

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 frommultiple namespaces:

// CEL object constructionqual.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 thesereferences must be a long qualified name within an otherwise short CEL program. Using thefollowing abbreviations, the program becomes much simpler:

// CEL Go optionAbbrevs("qual.pkg.version.ObjTypeName", "alt.container.ver.FieldTypeName")// Simplified Object constructionObjTypeName{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 anabbreviation, the abbreviation wins as this will ensure that the meaning of a program ispreserved between compilations even as the container evolves.

funcAlphaProtoAsDeclaration¶added inv0.22.0

func AlphaProtoAsDeclaration(d *exprpb.Decl) (EnvOption,error)

AlphaProtoAsDeclaration converts a v1alpha1.Decl value describing a variable or function into an EnvOption.

funcClearMacros¶

func ClearMacros()EnvOption

ClearMacros options clears all parser macros.

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

funcConstant¶added inv0.17.0

func Constant(namestring, t *Type, vref.Val)EnvOption

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

funcContainer¶

func Container(namestring)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, thenspecifying 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{...}`.

funcCostEstimatorOptions¶added inv0.17.7

func CostEstimatorOptions(costOpts ...checker.CostOption)EnvOption

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

funcCrossTypeNumericComparisons¶added inv0.10.0

func CrossTypeNumericComparisons(enabledbool)EnvOption

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

funcCustomTypeAdapter¶added inv0.2.0

func CustomTypeAdapter(adaptertypes.Adapter)EnvOption

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.

funcCustomTypeProvider¶

func CustomTypeProvider(providerany)EnvOption

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.

funcDeclareContextProto¶added inv0.8.0

func DeclareContextProto(descriptorprotoreflect.MessageDescriptor)EnvOption

DeclareContextProto returns an option to extend CEL environment with declarations from the given context proto.Each field of the proto defines a variable of the same name in the environment.https://github.com/google/cel-spec/blob/master/doc/langdef.md#evaluation-environment

funcDefaultUTCTimeZone¶added inv0.12.0

func DefaultUTCTimeZone(enabledbool)EnvOption

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

funcEagerlyValidateDeclarations¶added inv0.11.1

func EagerlyValidateDeclarations(enabledbool)EnvOption

EagerlyValidateDeclarations ensures that any collisions between configured declarations are caughtat 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 validatedas 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.

funcEnableErrorOnBadPresenceTest¶added inv0.21.0

func EnableErrorOnBadPresenceTest(valuebool)EnvOption

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

funcEnableHiddenAccumulatorName¶added inv0.23.0

func EnableHiddenAccumulatorName(enabledbool)EnvOption

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

funcEnableIdentifierEscapeSyntax¶added inv0.23.0

func EnableIdentifierEscapeSyntax()EnvOption

EnableIdentifierEscapeSyntax enables identifier escaping (`) syntax forfields.

funcEnableMacroCallTracking¶added inv0.10.0

func EnableMacroCallTracking()EnvOption

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

funcExprDeclToDeclaration¶added inv0.12.0

func ExprDeclToDeclaration(d *exprpb.Decl) (EnvOption,error)

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

funcExtendedValidations¶added inv0.17.0

func ExtendedValidations()EnvOption

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

funcFromConfig¶added inv0.24.0

func FromConfig(config *env.Config, optFactories ...ConfigOptionFactory)EnvOption

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 ofConfigOptionFactory values may be passed in to support the conversion from static configuration toconfigured cel.Env value.

Note: disabling the standard library will clear the EnvOptions values previously set for theenvironment 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 ofthe following options appears before the FromConfig option: Types, TypeDescs, or CustomTypeProvideras the type provider configured at the time when the config is processed is the one used to derivetype references from the configuration.

funcFunction¶added inv0.12.0

func Function(namestring, opts ...FunctionOpt)EnvOption

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 signaturesand Functions() to define the function bindings, if they have been defined. Specifying thesame function name more than once will result in the aggregation of the function overloads. If anysignatures 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 willbe considered a no-op.

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

- 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 ormap, consider using a generic function instead: e.g. func(list(T)) or func(map(K, V)) as thiswill allow your implementation to determine how best to handle dispatch and the default behaviorfor empty lists and maps whose contents cannot be inspected.

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

funcFunctionDecls¶added inv0.24.0

func FunctionDecls(funcs ...*decls.FunctionDecl)EnvOption

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

funcHomogeneousAggregateLiterals¶added inv0.2.0

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 theexpression, as well as via conversion of well-known dynamic types, or with uncheckedexpressions.

funcLib¶added inv0.4.0

func Lib(lLibrary)EnvOption

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

funcMacros¶

func Macros(macros ...Macro)EnvOption

Macros option extends the macro set configured in the environment.

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

funcOptionalTypes¶added inv0.13.0

func OptionalTypes(opts ...OptionalTypesOption)EnvOption

OptionalTypes enable support for optional syntax and types in CEL.

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

Syntax Changes¶

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

## Field Selection

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

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

## Indexing

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

list[?0]map[?key]

## Optional Field Setting

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

The following returns a map with the key expression set only if thesubfield 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 addedwhen 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 azero-value. A zero-value the default empty value for any given CEL type,including empty protobuf message types. If the value is empty, the resultof 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() // trueoptional.ofNonZeroValue({}).hasValue() // false

Value¶

Get the value contained by the optional. If the optional does not have avalue, 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 valueon the right hand side is returned. If the value on the left-hand set isvalued, then it is returned. This operation is short-circuiting and willonly evaluate as many links in the `or` chain as are needed to return anon-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 sideor 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 emptyand return an optional typed result based on the transformation. Thetransformation expression type must return a type T which is wrapped intoan 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 emptyand return the result. The transform expression must return an optional(T)rather than type T. This can be useful when dealing with zero values andconditionally generating an empty or non-empty result in ways which cannotbe 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, oroptional.None.

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

Last¶

Introduced in version: 2

Returns an optional with the last value from the right hand list, oroptional.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]

funcParserExpressionSizeLimit¶added inv0.16.0

func ParserExpressionSizeLimit(limitint)EnvOption

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

funcParserRecursionLimit¶added inv0.13.0

func ParserRecursionLimit(limitint)EnvOption

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

funcProtoAsDeclaration¶added inv0.22.0

func ProtoAsDeclaration(d *celpb.Decl) (EnvOption,error)

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

funcStdLib¶added inv0.4.0

func StdLib(opts ...StdLibOption)EnvOption

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

funcTypeDescs¶added inv0.2.0

func TypeDescs(descs ...any)EnvOption

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 valuesrather than the concrete message type.

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

funcTypes¶

func Types(addTypes ...any)EnvOption

Types adds one or more type declarations to the environment, allowing for construction oftype-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 typeprovided to this option will result in an error.

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

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

funcVariable¶added inv0.12.0

func Variable(namestring, t *Type)EnvOption

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

funcVariableDecls¶added inv0.24.0

func VariableDecls(vars ...*decls.VariableDecl)EnvOption

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

funcVariableWithDoc¶added inv0.25.0

func VariableWithDoc(namestring, t *Type, docstring)EnvOption

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

type Error =common.Error

funcExistsMacroExpander¶added inv0.12.0

func ExistsMacroExpander(mehMacroExprHelper, target *exprpb.Expr, args []*exprpb.Expr) (*exprpb.Expr, *Error)

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

funcExistsOneMacroExpander¶added inv0.12.0

func ExistsOneMacroExpander(mehMacroExprHelper, target *exprpb.Expr, args []*exprpb.Expr) (*exprpb.Expr, *Error)

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

funcFilterMacroExpander¶added inv0.12.0

func FilterMacroExpander(mehMacroExprHelper, target *exprpb.Expr, args []*exprpb.Expr) (*exprpb.Expr, *Error)

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

funcHasMacroExpander¶added inv0.12.0

func HasMacroExpander(mehMacroExprHelper, target *exprpb.Expr, args []*exprpb.Expr) (*exprpb.Expr, *Error)

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

funcMapMacroExpander¶added inv0.12.0

func MapMacroExpander(mehMacroExprHelper, target *exprpb.Expr, args []*exprpb.Expr) (*exprpb.Expr, *Error)

MapMacroExpander expands the input call arguments into a comprehension that transforms each element in theinput 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 expressionare transformed.

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

func (*EvalDetails)ActualCost¶added inv0.10.0

func (ed *EvalDetails) ActualCost() *uint64

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

func (*EvalDetails)State¶

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

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

type EvalOptionint

type FunctionOpt =decls.FunctionOpt

funcDisableDeclaration¶added inv0.17.0

func DisableDeclaration(valuebool)FunctionOpt

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

funcFunctionDocs¶added inv0.25.0

func FunctionDocs(docs ...string)FunctionOpt

FunctionDocs provides a general usage documentation for the function.

Use OverloadExamples to provide example usage instructions for specific overloads.

funcMemberOverload¶added inv0.12.0

func MemberOverload(overloadIDstring, args []*Type, resultType *Type, opts ...OverloadOpt)FunctionOpt

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 andstrict-ness should be rare occurrences.

funcOverload¶added inv0.12.0

func Overload(overloadIDstring, args []*Type, resultType *Type, opts ...OverloadOpt)FunctionOpt

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

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

funcSingletonBinaryBinding¶added inv0.13.0

func SingletonBinaryBinding(fnfunctions.BinaryOp, traits ...int)FunctionOpt

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

Note, this approach works well if operand is expected to have a specific trait which it implements,e.g. traits.ContainerType. Otherwise, prefer per-overload function bindings.

funcSingletonFunctionBinding¶added inv0.13.0

func SingletonFunctionBinding(fnfunctions.FunctionOp, traits ...int)FunctionOpt

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

Note, this approach works well if operand is expected to have a specific trait which it implements,e.g. traits.ContainerType. Otherwise, prefer per-overload function bindings.

funcSingletonUnaryBinding¶added inv0.12.0

func SingletonUnaryBinding(fnfunctions.UnaryOp, traits ...int)FunctionOpt

SingletonUnaryBinding creates a singleton function definition to be used for all function overloads.

Note, this approach works well if operand is expected to have a specific trait which it implements,e.g. traits.ContainerType. Otherwise, prefer per-overload function bindings.

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

funcNewInlineVariable¶added inv0.18.0

func NewInlineVariable(namestring, definition *Ast) *InlineVariable

NewInlineVariable declares a variable name to be replaced by a checked expression.

funcNewInlineVariableWithAlias¶added inv0.18.0

func NewInlineVariableWithAlias(name, aliasstring, definition *Ast) *InlineVariable

NewInlineVariableWithAlias declares a variable name to be replaced by a checked expression.If the variable occurs more than once, the provided alias will be used to replace the expressionswhere the variable name occurs.

func (*InlineVariable)Alias¶added inv0.18.0

func (v *InlineVariable) Alias()string

Alias returns the alias to use when performing cel.bind() calls during inlining.

func (*InlineVariable)Expr¶added inv0.18.0

func (v *InlineVariable) Expr()ast.Expr

Expr returns the inlined expression value.

func (*InlineVariable)Name¶added inv0.18.0

func (v *InlineVariable) Name()string

Name returns the qualified variable or field selection to replace.

func (*InlineVariable)Type¶added inv0.18.0

func (v *InlineVariable) Type() *Type

Type indicates the inlined expression type.

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

funcNewIssues¶added inv0.4.0

func NewIssues(errs *common.Errors) *Issues

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

funcNewIssuesWithSourceInfo¶added inv0.17.0

func NewIssuesWithSourceInfo(errs *common.Errors, info *celast.SourceInfo) *Issues

NewIssuesWithSourceInfo returns an Issues struct from a common.Errors object with SourceInfo metatatawhich can be used with the `ReportErrorAtID` method for additional error reports within the contextinformation that's inferred from an expression id.

func (*Issues)Append¶added inv0.4.0

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

Append collects the issues from another Issues struct into a new Issues 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() []*Error

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

func (*Issues)ReportErrorAtID¶added inv0.17.0

func (i *Issues) ReportErrorAtID(idint64, messagestring, args ...any)

ReportErrorAtID reports an error message with an optional set of formatting arguments.

The source metadata for the expression at `id`, if present, is attached to the error report.To ensure that source metadata is attached to error reports, use NewIssuesWithSourceInfo.

func (*Issues)String¶added inv0.4.0

func (i *Issues) String()string

String converts the issues to a suitable display string.

type Kind =types.Kind

type Library interface {// CompileOptions returns a collection of functional options for configuring the Parse / Check// environment.CompileOptions() []EnvOption// ProgramOptions returns a collection of functional options which should be included in every// Program generated from the Env.Program() call.ProgramOptions() []ProgramOption}

type LibraryAliaser interface {LibraryAlias()string}

type LibrarySubsetter interface {LibrarySubset() *env.LibrarySubset}

type LibraryVersioner interface {LibraryVersion()uint32}

type Macro =parser.Macro

funcGlobalMacro¶added inv0.17.2

func GlobalMacro(functionstring, argCountint, factoryMacroFactory, opts ...MacroOpt)Macro

GlobalMacro creates a Macro for a global function with the specified arg count.

funcGlobalVarArgMacro¶added inv0.17.2

func GlobalVarArgMacro(functionstring, factoryMacroFactory, opts ...MacroOpt)Macro

GlobalVarArgMacro creates a Macro for a global function with a variable arg count.

funcReceiverMacro¶added inv0.17.2

func ReceiverMacro(functionstring, argCountint, factoryMacroFactory, opts ...MacroOpt)Macro

ReceiverMacro creates a Macro for a receiver function matching the specified arg count.

funcReceiverVarArgMacro¶added inv0.17.2

func ReceiverVarArgMacro(functionstring, factoryMacroFactory, opts ...MacroOpt)Macro

ReceiverVarArgMacro creates a Macro for a receiver function matching a variable arg count.

type MacroExpander func(ehMacroExprHelper, target *exprpb.Expr, args []*exprpb.Expr) (*exprpb.Expr, *Error)

type MacroExprFactory =parser.ExprHelper

type MacroExprHelper interface {// Copy the input expression with a brand new set of identifiers.Copy(*exprpb.Expr) *exprpb.Expr// LiteralBool creates an Expr value for a bool literal.LiteralBool(valuebool) *exprpb.Expr// LiteralBytes creates an Expr value for a byte literal.LiteralBytes(value []byte) *exprpb.Expr// LiteralDouble creates an Expr value for double literal.LiteralDouble(valuefloat64) *exprpb.Expr// LiteralInt creates an Expr value for an int literal.LiteralInt(valueint64) *exprpb.Expr// LiteralString creates am Expr value for a string literal.LiteralString(valuestring) *exprpb.Expr// LiteralUint creates an Expr value for a uint literal.LiteralUint(valueuint64) *exprpb.Expr// NewList creates a CreateList instruction where the list is comprised of the optional set// of elements provided as arguments.NewList(elems ...*exprpb.Expr) *exprpb.Expr// NewMap creates a CreateStruct instruction for a map where the map is comprised of the// optional set of key, value entries.NewMap(entries ...*exprpb.Expr_CreateStruct_Entry) *exprpb.Expr// NewMapEntry creates a Map Entry for the key, value pair.NewMapEntry(key *exprpb.Expr, val *exprpb.Expr, optionalbool) *exprpb.Expr_CreateStruct_Entry// NewObject creates a CreateStruct instruction for an object with a given type name and// optional set of field initializers.NewObject(typeNamestring, fieldInits ...*exprpb.Expr_CreateStruct_Entry) *exprpb.Expr// NewObjectFieldInit creates a new Object field initializer from the field name and value.NewObjectFieldInit(fieldstring, init *exprpb.Expr, optionalbool) *exprpb.Expr_CreateStruct_Entry// Fold creates a fold comprehension instruction.//// - iterVar is the iteration variable name.// - iterRange represents the expression that resolves to a list or map where the elements or//   keys (respectively) will be iterated over.// - accuVar is the accumulation variable name, typically parser.AccumulatorName.// - accuInit is the initial expression whose value will be set for the accuVar prior to//   folding.// - condition is the expression to test to determine whether to continue folding.// - step is the expression to evaluation at the conclusion of a single fold iteration.// - result is the computation to evaluate at the conclusion of the fold.//// The accuVar should not shadow variable names that you would like to reference within the// environment in the step and condition expressions. Presently, the name __result__ is commonly// used by built-in macros but this may change in the future.Fold(iterVarstring,iterRange *exprpb.Expr,accuVarstring,accuInit *exprpb.Expr,condition *exprpb.Expr,step *exprpb.Expr,result *exprpb.Expr) *exprpb.Expr// Ident creates an identifier Expr value.Ident(namestring) *exprpb.Expr// AccuIdent returns an accumulator identifier for use with comprehension results.AccuIdent() *exprpb.Expr// GlobalCall creates a function call Expr value for a global (free) function.GlobalCall(functionstring, args ...*exprpb.Expr) *exprpb.Expr// ReceiverCall creates a function call Expr value for a receiver-style function.ReceiverCall(functionstring, target *exprpb.Expr, args ...*exprpb.Expr) *exprpb.Expr// PresenceTest creates a Select TestOnly Expr value for modelling has() semantics.PresenceTest(operand *exprpb.Expr, fieldstring) *exprpb.Expr// Select create a field traversal Expr value.Select(operand *exprpb.Expr, fieldstring) *exprpb.Expr// OffsetLocation returns the Location of the expression identifier.OffsetLocation(exprIDint64)common.Location// NewError associates an error message with a given expression id.NewError(exprIDint64, messagestring) *Error}

type MacroFactory =parser.MacroExpander

type MacroOpt =parser.MacroOpt

funcMacroDocs¶added inv0.25.0

func MacroDocs(docs ...string)MacroOpt

MacroDocs configures a list of strings into a multiline description for the macro.

funcMacroExamples¶added inv0.25.0

func MacroExamples(examples ...string)MacroOpt

MacroExamples configures a list of examples, either as a string or common.MultilineString,into an example set to be provided with the macro Documentation() call.

type MutableValidatorConfig interface {ValidatorConfigSet(namestring, valueany)error}

type OptimizerContext struct {*Env*Issues// contains filtered or unexported fields}

func (OptimizerContext)ClearMacroCall¶added inv0.20.1

func (opt OptimizerContext) ClearMacroCall(idint64)

ClearMacroCall clears the macro at the given expression id.

func (OptimizerContext)CopyAST¶added inv0.18.2

func (opt OptimizerContext) CopyAST(a *ast.AST) (ast.Expr, *ast.SourceInfo)

CopyAST creates a renumbered copy of `Expr` and `SourceInfo` values of the input AST, where therenumbering uses the same scheme as the core optimizer logic ensuring there are no collisionsbetween copies.

Use this method before attempting to merge the expression from AST into another.

func (OptimizerContext)CopyASTAndMetadata¶added inv0.20.1

func (opt OptimizerContext) CopyASTAndMetadata(a *ast.AST)ast.Expr

CopyASTAndMetadata copies the input AST and propagates the macro metadata into the AST beingoptimized.

func (*OptimizerContext)ExtendEnv¶added inv0.22.0

func (opt *OptimizerContext) ExtendEnv(opts ...EnvOption)error

ExtendEnv auguments the context's environment with the additional options.

func (OptimizerContext)MacroCalls¶added inv0.21.0

func (opt OptimizerContext) MacroCalls() map[int64]ast.Expr

MacroCalls returns the map of macro calls currently in the context.

func (OptimizerContext)NewAST¶added inv0.20.1

func (opt OptimizerContext) NewAST(exprast.Expr) *ast.AST

NewAST creates an AST from the current expression using the tracked source info whichis modified and managed by the OptimizerContext.

func (OptimizerContext)NewBindMacro¶added inv0.18.0

func (opt OptimizerContext) NewBindMacro(macroIDint64, varNamestring, varInit, remainingast.Expr) (astExpr, macroExprast.Expr)

NewBindMacro creates an AST expression representing the expanded bind() macro, and a macro expressionrepresenting the unexpanded call signature to be inserted into the source info macro call metadata.

func (OptimizerContext)NewCall¶added inv0.18.0

func (opt OptimizerContext) NewCall(functionstring, args ...ast.Expr)ast.Expr

NewCall creates a global function call invocation expression.

Example:

countByField(list, fieldName)- function: countByField- args: [list, fieldName]

func (OptimizerContext)NewHasMacro¶added inv0.18.2

func (opt OptimizerContext) NewHasMacro(macroIDint64, sast.Expr) (astExpr, macroExprast.Expr)

NewHasMacro generates a test-only select expression to be included within an AST and an unexpandedhas() macro call signature to be inserted into the source info macro call metadata.

func (OptimizerContext)NewIdent¶added inv0.18.0

func (opt OptimizerContext) NewIdent(namestring)ast.Expr

NewIdent creates a new identifier expression.

Examples:

- simple_var_name- qualified.subpackage.var_name

func (OptimizerContext)NewList¶added inv0.18.0

func (opt OptimizerContext) NewList(elems []ast.Expr, optIndices []int32)ast.Expr

NewList creates a list expression with a set of optional indices.

Examples:

[a, b]- elems: [a, b]- optIndices: []

[a, ?b, ?c]- elems: [a, b, c]- optIndices: [1, 2]

func (OptimizerContext)NewLiteral¶added inv0.18.0

func (opt OptimizerContext) NewLiteral(valueref.Val)ast.Expr

NewLiteral creates a new literal expression value.

The range of valid values for a literal generated during optimization is different than for expressionsgenerated via parsing / type-checking, as the ref.Val may be _any_ CEL value so long as the value canbe converted back to a literal-like form.

func (OptimizerContext)NewMap¶added inv0.18.0

func (opt OptimizerContext) NewMap(entries []ast.EntryExpr)ast.Expr

NewMap creates a map from a set of entry expressions which contain a key and value expression.

func (OptimizerContext)NewMapEntry¶added inv0.18.0

func (opt OptimizerContext) NewMapEntry(key, valueast.Expr, isOptionalbool)ast.EntryExpr

NewMapEntry creates a map entry with a key and value expression and a flag to indicate whether theentry is optional.

Examples:

{a: b}- key: a- value: b- optional: false

{?a: ?b}- key: a- value: b- optional: true

func (OptimizerContext)NewMemberCall¶added inv0.18.0

func (opt OptimizerContext) NewMemberCall(functionstring, targetast.Expr, args ...ast.Expr)ast.Expr

NewMemberCall creates a member function call invocation expression where 'target' is the receiver of the call.

Example:

list.countByField(fieldName)- function: countByField- target: list- args: [fieldName]

func (OptimizerContext)NewSelect¶added inv0.18.0

func (opt OptimizerContext) NewSelect(operandast.Expr, fieldstring)ast.Expr

NewSelect creates a select expression where a field value is selected from an operand.

Example:

msg.field_name- operand: msg- field: field_name

func (OptimizerContext)NewStruct¶added inv0.18.0

func (opt OptimizerContext) NewStruct(typeNamestring, fields []ast.EntryExpr)ast.Expr

NewStruct creates a new typed struct value with an set of field initializations.

Example:

pkg.TypeName{field: value}- typeName: pkg.TypeName- fields: [{field: value}]

func (OptimizerContext)NewStructField¶added inv0.18.0

func (opt OptimizerContext) NewStructField(fieldstring, valueast.Expr, isOptionalbool)ast.EntryExpr

NewStructField creates a struct field initialization.

Examples:

{count: 3u}- field: count- value: 3u- optional: false

{?count: x}- field: count- value: x- optional: true

func (OptimizerContext)SetMacroCall¶added inv0.20.1

func (opt OptimizerContext) SetMacroCall(idint64, exprast.Expr)

SetMacroCall sets the macro call metadata for the given macro id within the tracked source infometadata.

func (OptimizerContext)UpdateExpr¶added inv0.18.2

func (opt OptimizerContext) UpdateExpr(target, updatedast.Expr)

UpdateExpr updates the target expression with the updated content while preserving macro metadata.

There are four scenarios during the update to consider:1. target is not macro, updated is not macro2. target is macro, updated is not macro3. target is macro, updated is macro4. target is not macro, updated is macro

When the target is a macro already, it may either be updated to a new macro functionbody if the update is also a macro, or it may be removed altogether if the update isa macro.

When the update is a macro, then the target references within other macros must beupdated to point to the new updated macro. Otherwise, other macros which pointed tothe target body must be replaced with copies of the updated expression body.

type OptionalTypesOption func(*optionalLib) *optionalLib

funcOptionalTypesVersion¶added inv0.17.0

func OptionalTypesVersion(versionuint32)OptionalTypesOption

OptionalTypesVersion configures the version of the optional type library.

The version limits which functions are available. Only functions introducedbelow or equal to the given version included in the library. If this optionis not set, all functions are available.

See the library documentation to determine which version a function was introduced.If the documentation does not state which version a function was introduced, it canbe assumed to be introduced at version 0, when the library was first created.

type OverloadOpt =decls.OverloadOpt

funcBinaryBinding¶added inv0.12.0

func BinaryBinding(bindingfunctions.BinaryOp)OverloadOpt

BinaryBinding provides the implementation of a binary overload. The provided function is protected by a runtimetype-guard which ensures runtime type agreement between the overload signature and runtime argument types.

funcFunctionBinding¶added inv0.12.0

func FunctionBinding(bindingfunctions.FunctionOp)OverloadOpt

FunctionBinding provides the implementation of a variadic overload. The provided function is protected by a runtimetype-guard which ensures runtime type agreement between the overload signature and runtime argument types.

funcLateFunctionBinding¶added inv0.25.0

func LateFunctionBinding()OverloadOpt

LateFunctionBinding indicates that the function has a binding which is not known at compile time.This is useful for functions which have side-effects or are not deterministically computable.

funcOverloadExamples¶added inv0.25.0

func OverloadExamples(docs ...string)OverloadOpt

OverloadExamples configures an example of how to invoke the overload.

funcOverloadIsNonStrict¶added inv0.12.0

func OverloadIsNonStrict()OverloadOpt

OverloadIsNonStrict enables the function to be called with error and unknown argument values.

Note: do not use this option unless absoluately necessary as it should be an uncommon feature.

funcOverloadOperandTrait¶added inv0.12.0

func OverloadOperandTrait(traitint)OverloadOpt

OverloadOperandTrait configures a set of traits which the first argument to the overload must implement in order to besuccessfully invoked.

funcUnaryBinding¶added inv0.12.0

func UnaryBinding(bindingfunctions.UnaryOp)OverloadOpt

UnaryBinding provides the implementation of a unary overload. The provided function is protected by a runtimetype-guard which ensures runtime type agreement between the overload signature and runtime argument types.

type OverloadSelector =decls.OverloadSelector

funcExcludeOverloads¶added inv0.24.0

func ExcludeOverloads(overloadIDs ...string)OverloadSelector

ExcludeOverloads defines an OverloadSelector which deny-lists a set of overloads by their ids.

funcIncludeOverloads¶added inv0.24.0

func IncludeOverloads(overloadIDs ...string)OverloadSelector

IncludeOverloads defines an OverloadSelector which allow-lists a set of overloads by their ids.

type PartialActivation =interpreter.PartialActivation

funcPartialVars¶added inv0.4.0

func PartialVars(varsany,unknowns ...*AttributePatternType) (PartialActivation,error)

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

This method relies on manually configured sets of missing attribute patterns. For a method whichinfers the missing variables from the input and the configured environment, use Env.PartialVars().

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

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 `Activation` or a `map[string]any`.//// If the `OptTrackState`, `OptTrackCost` 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(any) (ref.Val, *EvalDetails,error)// ContextEval evaluates the program with a set of input variables and a context object in order// to support cancellation and timeouts. This method must be used in conjunction with the// InterruptCheckFrequency() option for cancellation interrupts to be impact evaluation.//// The vars value may either be an `Activation` or `map[string]any`.//// The output contract for `ContextEval` is otherwise identical to the `Eval` method.ContextEval(context.Context,any) (ref.Val, *EvalDetails,error)}

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

funcCostLimit¶added inv0.10.0

func CostLimit(costLimituint64)ProgramOption

CostLimit enables cost tracking and sets configures program evaluation to exit early with a"runtime cost limit exceeded" error if the runtime cost exceeds the costLimit.The CostLimit is a metric that corresponds to the number and estimated expense of operationsperformed while evaluating an expression. It is indicative of CPU usage, not memory usage.

funcCostTrackerOptions¶added inv0.17.7

func CostTrackerOptions(costOpts ...interpreter.CostTrackerOption)ProgramOption

CostTrackerOptions configures a set of options for cost-tracking.

Note, CostTrackerOptions is a no-op unless CostTracking is also enabled.

funcCostTracking¶added inv0.10.0

func CostTracking(costEstimatorinterpreter.ActualCostEstimator)ProgramOption

CostTracking enables cost tracking and registers a ActualCostEstimator that can optionally provide a runtime cost estimate for any function calls.

funcCustomDecorator¶added inv0.6.0

func CustomDecorator(decinterpreter.InterpretableDecorator)ProgramOption

CustomDecorator appends an InterpreterDecorator to the program.

InterpretableDecorators can be used to inspect, alter, or replace the Program plan.

funcEvalOptions¶

func EvalOptions(opts ...EvalOption)ProgramOption

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

funcGlobals¶

func Globals(varsany)ProgramOption

Globals sets the global variable values for a given program. These values may be shadowed byvariables with the same name provided to the Eval() call. If Globals is used in a Library witha Lib EnvOption, vars may shadow variables provided by previously added libraries.

The vars value may either be an `cel.Activation` instance or a `map[string]any`.

funcInterruptCheckFrequency¶added inv0.10.0

func InterruptCheckFrequency(checkFrequencyuint)ProgramOption

InterruptCheckFrequency configures the number of iterations within a comprehension to evaluatebefore checking whether the function evaluation has been interrupted.

funcOptimizeRegex¶added inv0.10.0

func OptimizeRegex(regexOptimizations ...*interpreter.RegexOptimization)ProgramOption

OptimizeRegex provides a way to replace the InterpretableCall for regex functions. This can be usedto compile regex string constants at program creation time and report any errors and then use thecompiled regex for all regex function invocations.

type Prompt struct {// Persona indicates something about the kind of user making the requestPersonastring// FormatRules indicate how the LLM should generate its outputFormatRulesstring// GeneralUsage specifies additional context on how CEL should be used.GeneralUsagestring// contains filtered or unexported fields}

funcAuthoringPrompt¶added inv0.25.0

func AuthoringPrompt(env *Env) (*Prompt,error)

AuthoringPrompt creates a prompt template from a CEL environment for the purpose of AI-assisted authoring.

func (*Prompt)Render¶added inv0.25.0

func (p *Prompt) Render(userPromptstring)string

Render renders the user prompt with the associated context from the prompt templatefor use with LLM generators.

type SingletonLibrary interface {Library// LibraryName provides a namespaced name which is used to check whether the library has already// been configured in the environment.LibraryName()string}

type Source =common.Source

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

funcNewStaticOptimizer¶added inv0.18.0

func NewStaticOptimizer(optimizers ...ASTOptimizer) *StaticOptimizer

NewStaticOptimizer creates a StaticOptimizer with a sequence of ASTOptimizer's to be appliedto a checked expression.

func (*StaticOptimizer)Optimize¶added inv0.18.0

func (opt *StaticOptimizer) Optimize(env *Env, a *Ast) (*Ast, *Issues)

Optimize applies a sequence of optimizations to an Ast within a given environment.

If issues are encountered, the Issues.Err() return value will be non-nil.

type StdLibOption func(*stdLibrary) *stdLibrary

funcStdLibSubset¶added inv0.24.0

func StdLibSubset(subset *env.LibrarySubset)StdLibOption

StdLibSubset configures the standard library to use a subset of its functions and macros.

Since the StdLib is a singleton library, only the first instance of the StdLib() environment optionswill be configured on the environment which means only the StdLibSubset() initially configured withthe library will be used.

type Type =types.Type

funcExprTypeToType¶added inv0.12.0

func ExprTypeToType(t *exprpb.Type) (*Type,error)

ExprTypeToType converts a protobuf CEL type representation to a CEL-native type representation.

type ValidatorConfig interface {GetOrDefault(namestring, valueany)any}