func CostTrackerFactory(factory func() (*CostTracker,error)) costTrackPlanOption

func EvalStateFactory(factory func()EvalState) evalStateOption

func PruneAst(exprast.Expr, macroCalls map[int64]ast.Expr, stateEvalState) *ast.AST

type Activation interface {// ResolveName returns a value from the activation by qualified name, or false if the name// could not be found.ResolveName(namestring) (any,bool)// Parent returns the parent of the current activation, may be nil.// If non-nil, the parent will be searched during resolve calls.Parent()Activation}

funcEmptyActivation¶added inv0.2.0

func EmptyActivation()Activation

EmptyActivation returns a variable-free activation.

funcNewActivation¶

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.

funcNewHierarchicalActivation¶

func NewHierarchicalActivation(parentActivation, childActivation)Activation

NewHierarchicalActivation takes two activations and produces a new one which prioritizesresolution in the child first and parent(s) second.

type ActualCostEstimator interface {CallCost(function, overloadIDstring, args []ref.Val, resultref.Val) *uint64}

type AttrFactoryOption func(*attrFactory) *attrFactory

funcEnableErrorOnBadPresenceTest¶added inv0.21.0

func EnableErrorOnBadPresenceTest(valuebool)AttrFactoryOption

EnableErrorOnBadPresenceTest error generation when a presence test or optional field selectionis performed on a primitive type.

type Attribute interface {Qualifier// AddQualifier adds a qualifier on the Attribute or error if the qualification is not a valid qualifier type.AddQualifier(Qualifier) (Attribute,error)// Resolve returns the value of the Attribute and whether it was present given an Activation.// For objects which support safe traversal, the value may be non-nil and the presence flag be false.//// If an error is encountered during attribute resolution, it will be returned immediately.// If the attribute cannot be resolved within the Activation, the result must be: `nil`, `error`// with the error indicating which variable was missing.Resolve(Activation) (any,error)}

type AttributeFactory interface {// AbsoluteAttribute creates an attribute that refers to a top-level variable name.//// Checked expressions generate absolute attribute with a single name.// Parse-only expressions may have more than one possible absolute identifier when the// expression is created within a container, e.g. package or namespace.//// When there is more than one name supplied to the AbsoluteAttribute call, the names// must be in CEL's namespace resolution order. The name arguments provided here are// returned in the same order as they were provided by the NamespacedAttribute// CandidateVariableNames method.AbsoluteAttribute(idint64, names ...string)NamespacedAttribute// ConditionalAttribute creates an attribute with two Attribute branches, where the Attribute// that is resolved depends on the boolean evaluation of the input 'expr'.ConditionalAttribute(idint64, exprInterpretable, t, fAttribute)Attribute// MaybeAttribute creates an attribute that refers to either a field selection or a namespaced// variable name.//// Only expressions which have not been type-checked may generate oneof attributes.MaybeAttribute(idint64, namestring)Attribute// RelativeAttribute creates an attribute whose value is a qualification of a dynamic// computation rather than a static variable reference.RelativeAttribute(idint64, operandInterpretable)Attribute// NewQualifier creates a qualifier on the target object with a given value.//// The 'val' may be an Attribute or any proto-supported map key type: bool, int, string, uint.//// The qualifier may consider the object type being qualified, if present. If absent, the// qualification should be considered dynamic and the qualification should still work, though// it may be sub-optimal.NewQualifier(objType *types.Type, qualIDint64, valany, optbool) (Qualifier,error)}

funcNewAttributeFactory¶added inv0.4.0

func NewAttributeFactory(cont *containers.Container, atypes.Adapter, ptypes.Provider, opts ...AttrFactoryOption)AttributeFactory

NewAttributeFactory returns a default AttributeFactory which is produces Attribute valuescapable of resolving types by simple names and qualify the values using the supported qualifiertypes: bool, int, string, and uint.

funcNewPartialAttributeFactory¶added inv0.4.0

func NewPartialAttributeFactory(container *containers.Container, adaptertypes.Adapter, providertypes.Provider, opts ...AttrFactoryOption)AttributeFactory

NewPartialAttributeFactory returns an AttributeFactory implementation capable of performingAttributePattern matches with PartialActivation inputs.

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

funcNewAttributePattern¶added inv0.4.0

func NewAttributePattern(variablestring) *AttributePattern

NewAttributePattern produces a new mutable AttributePattern based on a variable name.

func (*AttributePattern)QualBool¶added inv0.4.0

func (apat *AttributePattern) QualBool(patternbool) *AttributePattern

QualBool adds a bool qualifier pattern for a map index operation to the AttributePattern.

func (*AttributePattern)QualInt¶added inv0.4.0

func (apat *AttributePattern) QualInt(patternint64) *AttributePattern

QualInt adds an int qualifier pattern to the AttributePattern. The index may be either a map orlist index.

func (*AttributePattern)QualString¶added inv0.4.0

func (apat *AttributePattern) QualString(patternstring) *AttributePattern

QualString adds a string qualifier pattern to the AttributePattern. The string may be a valididentifier, or string map key including empty string.

func (*AttributePattern)QualUint¶added inv0.4.0

func (apat *AttributePattern) QualUint(patternuint64) *AttributePattern

QualUint adds an uint qualifier pattern for a map index operation to the AttributePattern.

func (*AttributePattern)QualifierPatterns¶added inv0.4.0

func (apat *AttributePattern) QualifierPatterns() []*AttributeQualifierPattern

QualifierPatterns returns the set of AttributeQualifierPattern values on the AttributePattern.

func (*AttributePattern)VariableMatches¶added inv0.4.0

func (apat *AttributePattern) VariableMatches(variablestring)bool

VariableMatches returns true if the fully qualified variable matches the AttributePatternfully qualified variable name.

func (*AttributePattern)Wildcard¶added inv0.4.0

func (apat *AttributePattern) Wildcard() *AttributePattern

Wildcard adds a special sentinel qualifier pattern that will match any single qualifier.

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

func (*AttributeQualifierPattern)Matches¶added inv0.4.0

func (qpat *AttributeQualifierPattern) Matches(qQualifier)bool

Matches returns true if the qualifier pattern is a wildcard, or the Qualifier implements thequalifierValueEquator interface and its IsValueEqualTo returns true for the qualifier pattern.

type CancellationCauseint

type ConstantQualifier interface {Qualifier// Value returns the constant value associated with the qualifier.Value()ref.Val}

type CostTracker struct {EstimatorActualCostEstimatorLimit *uint64// contains filtered or unexported fields}

funcNewCostTracker¶added inv0.16.0

func NewCostTracker(estimatorActualCostEstimator, opts ...CostTrackerOption) (*CostTracker,error)

NewCostTracker creates a new CostTracker with a given estimator and a set of functional CostTrackerOption values.

func (*CostTracker)ActualCost¶added inv0.10.0

func (c *CostTracker) ActualCost()uint64

ActualCost returns the runtime cost

type CostTrackerOption func(*CostTracker)error

funcCostTrackerLimit¶added inv0.16.0

func CostTrackerLimit(limituint64)CostTrackerOption

CostTrackerLimit sets the runtime limit on the evaluation cost during execution and will terminate the expressionevaluation if the limit is exceeded.

funcOverloadCostTracker¶added inv0.17.7

func OverloadCostTracker(overloadIDstring, fnTrackerFunctionTracker)CostTrackerOption

OverloadCostTracker binds an overload ID to a runtime FunctionTracker implementation.

OverloadCostTracker instances augment or override ActualCostEstimator decisions, allowing for versioned and/oroptional cost tracking changes.

funcPresenceTestHasCost¶added inv0.16.0

func PresenceTestHasCost(hasCostbool)CostTrackerOption

PresenceTestHasCost determines whether presence testing has a cost of one or zero.Defaults to presence test has a cost of one.

type Dispatcher interface {// Add one or more overloads, returning an error if any Overload has the same Overload#Name.Add(overloads ...*functions.Overload)error// FindOverload returns an Overload definition matching the provided name.FindOverload(overloadstring) (*functions.Overload,bool)// OverloadIds returns the set of all overload identifiers configured for dispatch.OverloadIds() []string}

funcExtendDispatcher¶

func ExtendDispatcher(parentDispatcher)Dispatcher

ExtendDispatcher returns a Dispatcher which inherits the overloads of its parent, andprovides an isolation layer between built-ins and extension functions which is usefulfor forward compatibility.

funcNewDispatcher¶

func NewDispatcher()Dispatcher

NewDispatcher returns an empty Dispatcher instance.

type EvalCancelledError struct {Messagestring// Type identifies the cause of the cancellation.CauseCancellationCause}

func (EvalCancelledError)Error¶added inv0.10.0

func (eEvalCancelledError) Error()string

type EvalObserver func(varsActivation, idint64, programStepany, valueref.Val)

type EvalState interface {// IDs returns the list of ids with recorded values.IDs() []int64// Value returns the observed value of the given expression id if found, and a nil false// result if not.Value(int64) (ref.Val,bool)// SetValue sets the observed value of the expression id.SetValue(int64,ref.Val)// Reset clears the previously recorded expression values.Reset()}

funcNewEvalState¶

func NewEvalState()EvalState

NewEvalState returns an EvalState instanced used to observe the intermediateevaluations of an expression.

type FunctionTracker func(args []ref.Val, resultref.Val) *uint64

type Interpretable interface {// ID value corresponding to the expression node.ID()int64// Eval an Activation to produce an output.Eval(activationActivation)ref.Val}

type InterpretableAttribute interface {Interpretable// Attr returns the Attribute value.Attr()Attribute// Adapter returns the type adapter to be used for adapting resolved Attribute values.Adapter()types.Adapter// AddQualifier proxies the Attribute.AddQualifier method.//// Note, this method may mutate the current attribute state. If the desire is to clone the// Attribute, the Attribute should first be copied before adding the qualifier. Attributes// are not copyable by default, so this is a capable that would need to be added to the// AttributeFactory or specifically to the underlying Attribute implementation.AddQualifier(Qualifier) (Attribute,error)// Qualify replicates the Attribute.Qualify method to permit extension and interception// of object qualification.Qualify(varsActivation, objany) (any,error)// QualifyIfPresent qualifies the object if the qualifier is declared or defined on the object.// The 'presenceOnly' flag indicates that the value is not necessary, just a boolean status as// to whether the qualifier is present.QualifyIfPresent(varsActivation, objany, presenceOnlybool) (any,bool,error)// IsOptional indicates whether the resulting value is an optional type.IsOptional()bool// Resolve returns the value of the Attribute given the current Activation.Resolve(Activation) (any,error)}

type InterpretableCall interface {Interpretable// Function returns the function name as it appears in text or mangled operator name as it// appears in the operators.go file.Function()string// OverloadID returns the overload id associated with the function specialization.// Overload ids are stable across language boundaries and can be treated as synonymous with a// unique function signature.OverloadID()string// Args returns the normalized arguments to the function overload.// For receiver-style functions, the receiver target is arg 0.Args() []Interpretable}

funcNewCall¶added inv0.10.0

func NewCall(idint64, function, overloadstring, args []Interpretable, implfunctions.FunctionOp)InterpretableCall

NewCall creates a new call Interpretable.

type InterpretableConst interface {Interpretable// Value returns the constant value of the instruction.Value()ref.Val}

funcNewConstValue¶added inv0.6.0

func NewConstValue(idint64, valref.Val)InterpretableConst

NewConstValue creates a new constant valued Interpretable.

type InterpretableConstructor interface {Interpretable// InitVals returns all the list elements, map key and values or struct field values.InitVals() []Interpretable// Type returns the type constructed.Type()ref.Type}

type InterpretableDecorator func(Interpretable) (Interpretable,error)

type Interpreter interface {// NewInterpretable creates an Interpretable from a checked expression and an// optional list of PlannerOption values.NewInterpretable(exprAST *ast.AST, opts ...PlannerOption) (Interpretable,error)}

funcNewInterpreter¶

func NewInterpreter(dispatcherDispatcher,container *containers.Container,providertypes.Provider,adaptertypes.Adapter,attrFactoryAttributeFactory)Interpreter

NewInterpreter builds an Interpreter from a Dispatcher and TypeProvider which will be usedthroughout the Eval of all Interpretable instances generated from it.

type NamespacedAttribute interface {Attribute// CandidateVariableNames returns the possible namespaced variable names for this Attribute in// the CEL namespace resolution order.CandidateVariableNames() []string// Qualifiers returns the list of qualifiers associated with the Attribute.Qualifiers() []Qualifier}

type ObservableInterpretable struct {Interpretable// contains filtered or unexported fields}

func (*ObservableInterpretable)Eval¶added inv0.25.0

func (oi *ObservableInterpretable) Eval(varsActivation)ref.Val

Eval proxies to the ObserveEval method while invoking a no-op callback to report the observations.

func (*ObservableInterpretable)ID¶added inv0.25.0

func (oi *ObservableInterpretable) ID()int64

ID implements the Interpretable method to get the expression id associated with the step.

func (*ObservableInterpretable)ObserveEval¶added inv0.25.0

func (oi *ObservableInterpretable) ObserveEval(varsActivation, observer func(any))ref.Val

ObserveEval evaluates an interpretable and performs per-evaluation state-tracking.

This method is concurrency safe and the expectation is that the observer function will usea switch statement to determine the type of the state which has been reported back from the call.

type PartialActivation interface {Activation// UnknownAttributePaths returns a set of AttributePattern values which match Attribute// expressions for data accesses whose values are not yet known.UnknownAttributePatterns() []*AttributePattern}

funcAsPartialActivation¶added inv0.24.0

func AsPartialActivation(varsActivation) (PartialActivation,bool)

AsPartialActivation walks the activation hierarchy and returns the first PartialActivation, if found.

funcNewPartialActivation¶added inv0.4.0

func NewPartialActivation(bindingsany,unknowns ...*AttributePattern) (PartialActivation,error)

NewPartialActivation returns an Activation which contains a list of AttributePattern valuesrepresenting field and index operations that should result in a 'types.Unknown' result.

The `bindings` value may be any value type supported by the interpreter.NewActivation call,but is typically either an existing Activation or map[string]any.

type PlannerOption func(*planner) (*planner,error)

funcCompileRegexConstants¶added inv0.10.0

func CompileRegexConstants(regexOptimizations ...*RegexOptimization)PlannerOption

CompileRegexConstants compiles regex pattern string constants at program creation time and reports any regex patterncompile errors.

funcCostObserver¶added inv0.10.0

func CostObserver(opts ...costTrackPlanOption)PlannerOption

CostObserver provides an observer that tracks runtime cost.

funcCustomDecorator¶added inv0.25.0

func CustomDecorator(decInterpretableDecorator)PlannerOption

CustomDecorator configures a custom interpretable decorator for the program.

funcEvalStateObserver¶added inv0.10.0

func EvalStateObserver(opts ...evalStateOption)PlannerOption

EvalStateObserver provides an observer which records the value associated with the given expression id.EvalState must be provided to the observer.

funcExhaustiveEval¶

func ExhaustiveEval()PlannerOption

ExhaustiveEval replaces operations that short-circuit with versions that evaluateexpressions and couples this behavior with the TrackState() decorator to provideinsight into the evaluation state of the entire expression. EvalState must beprovided to the decorator. This decorator is not thread-safe, and the EvalStatemust be reset between Eval() calls.

funcInterruptableEval¶added inv0.10.0

func InterruptableEval()PlannerOption

InterruptableEval annotates comprehension loops with information that indicates theyshould check the `#interrupted` state within a custom Activation.

The custom activation is currently managed higher up in the stack within the 'cel' packageand should not require any custom support on behalf of callers.

funcOptimize¶added inv0.3.0

func Optimize()PlannerOption

Optimize will pre-compute operations such as list and map construction and optimizecall arguments to set membership tests. The set of optimizations will increase over time.

type Qualifier interface {// ID where the qualifier appears within an expression.ID()int64// IsOptional specifies whether the qualifier is optional.// Instead of a direct qualification, an optional qualifier will be resolved via QualifyIfPresent// rather than Qualify. A non-optional qualifier may also be resolved through QualifyIfPresent if// the object to qualify is itself optional.IsOptional()bool// Qualify performs a qualification, e.g. field selection, on the input object and returns// the value of the access and whether the value was set. A non-nil value with a false presence// test result indicates that the value being returned is the default value.Qualify(varsActivation, objany) (any,error)// QualifyIfPresent qualifies the object if the qualifier is declared or defined on the object.// The 'presenceOnly' flag indicates that the value is not necessary, just a boolean status as// to whether the qualifier is present.QualifyIfPresent(varsActivation, objany, presenceOnlybool) (any,bool,error)}

type RegexOptimization struct {// Function is the name of the function to optimize.Functionstring// OverloadID is the ID of the overload to optimize.OverloadIDstring// RegexIndex is the index position of the regex pattern argument. Only calls to the function where this argument is// a string constant will be delegated to this optimizer.RegexIndexint// Factory constructs a replacement InterpretableCall node that optimizes the regex function call. Factory is// provided with the unoptimized regex call and the string constant at the RegexIndex argument.// The Factory may compile the regex for use across all invocations of the call, return any errors and// return an interpreter.NewCall with the desired regex optimized function impl.Factory func(callInterpretableCall, regexPatternstring) (InterpretableCall,error)}

type StatefulObserver interface {// InitState configures stateful metadata on the activation.InitState(Activation) (Activation,error)// GetState retrieves the stateful metadata from the activation.GetState(Activation)any// Observe passes the activation and relevant evaluation metadata to the observer.// The observe method is expected to do the equivalent of GetState(vars) in order// to find the metadata that needs to be updated upon invocation.Observe(varsActivation, idint64, programStepany, valueref.Val)}