package interpreter

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

Package interpreter provides functions to evaluate parsed expressions with the option to augment the evaluation with inputs and functions supplied at evaluation time.

Index

Functions

func PruneAst 

func PruneAst(expr *exprpb.Expr, state EvalState) *exprpb.Expr

PruneAst prunes the given AST based on the given EvalState and generates a new AST. Given AST is copied on write and a new AST is returned. Couple of typical use cases this interface would be:

A)

  1. Evaluate expr with some unknowns,
  2. If result is unknown: a) PruneAst b) Goto 1

Functional call results which are known would be effectively cached across iterations.

B)

  1. Compile the expression (maybe via a service and maybe after checking a compiled expression does not exists in local cache)
  2. Prepare the environment and the interpreter. Activation might be empty.
  3. Eval the expression. This might return unknown or error or a concrete value.
  4. PruneAst
  5. Maybe cache the expression

This is effectively constant folding the expression. How the environment is prepared in step 2 is flexible. For example, If the caller caches the compiled and constant folded expressions, but is not willing to constant fold(and thus cache results of) some external calls, then they can prepare the overloads accordingly.

Types

type Activation 

type Activation interface {
	// ResolveName returns a value from the activation by qualified name, or false if the name
	// could not be found.
	ResolveName(name string) (interface{}, 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
}

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.

func EmptyActivation 

func EmptyActivation() Activation

EmptyActivation returns a variable free activation.

func NewActivation 

func NewActivation(bindings interface{}) (Activation, error)

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

Lazy bindings may be supplied within the map-based input in either of the following forms: - func() interface{} - 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 ref.TypeAdapter configured in the environment.

func NewHierarchicalActivation 

func NewHierarchicalActivation(parent Activation, child Activation) Activation

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

type Attribute 

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 given the current Activation.
	Resolve(Activation) (interface{}, error)
}

Attribute values are a variable or value with an optional set of qualifiers, such as field, key, or index accesses.

type AttributeFactory 

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(id int64, 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(id int64, expr Interpretable, t, f Attribute) 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(id int64, name string) Attribute

	// RelativeAttribute creates an attribute whose value is a qualification of a dynamic
	// computation rather than a static variable reference.
	RelativeAttribute(id int64, operand Interpretable) 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 *exprpb.Type, qualID int64, val interface{}) (Qualifier, error)
}

AttributeFactory provides methods creating Attribute and Qualifier values.

func NewAttributeFactory 

func NewAttributeFactory(pkg packages.Packager,
	a ref.TypeAdapter,
	p ref.TypeProvider) AttributeFactory

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

func NewPartialAttributeFactory 

func NewPartialAttributeFactory(pkg packages.Packager,
	adapter ref.TypeAdapter,
	provider ref.TypeProvider) AttributeFactory

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

type AttributePattern 

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

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

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, if variable `c` appears in an expression whose container is `a.b`, the variable name supplied to the pattern must be `a.b.c`

The qualifier patterns for attribute matching must be one of the following:

Examples:

  1. ns.myvar["complex-value"]
  2. ns.myvar["complex-value"][0]
  3. ns.myvar["complex-value"].*.name

The first example is simple: match an attribute where the variable is 'ns.myvar' with a field access on 'complex-value'. The second example expands the match to indicate that only a specific index `0` should match. And lastly, the third example matches any indexed access that later selects the 'name' field.

func NewAttributePattern 

func NewAttributePattern(variable string) *AttributePattern

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

func (*AttributePattern) QualBool 

func (apat *AttributePattern) QualBool(pattern bool) *AttributePattern

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

func (*AttributePattern) QualInt 

func (apat *AttributePattern) QualInt(pattern int64) *AttributePattern

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

func (*AttributePattern) QualString 

func (apat *AttributePattern) QualString(pattern string) *AttributePattern

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

func (*AttributePattern) QualUint 

func (apat *AttributePattern) QualUint(pattern uint64) *AttributePattern

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

func (*AttributePattern) QualifierPatterns 

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

QualifierPatterns returns the set of AttributeQualifierPattern values on the AttributePattern.

func (*AttributePattern) VariableMatches 

func (apat *AttributePattern) VariableMatches(variable string) bool

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

func (*AttributePattern) Wildcard 

func (apat *AttributePattern) Wildcard() *AttributePattern

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

type AttributeQualifierPattern 

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

AttributeQualifierPattern holds a wilcard or valued qualifier pattern.

func (*AttributeQualifierPattern) Matches 

func (qpat *AttributeQualifierPattern) Matches(q Qualifier) bool

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

type Dispatcher 

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(overload string) (*functions.Overload, bool)

	// OverloadIds returns the set of all overload identifiers configured for dispatch.
	OverloadIds() []string
}

Dispatcher resolves function calls to their appropriate overload.

func ExtendDispatcher 

func ExtendDispatcher(parent Dispatcher) Dispatcher

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

func NewDispatcher 

func NewDispatcher() Dispatcher

NewDispatcher returns an empty Dispatcher instance.

type EvalState 

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()
}

EvalState tracks the values associated with expression ids during execution.

func NewEvalState 

func NewEvalState() EvalState

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

type Interpretable 

type Interpretable interface {
	// ID value corresponding to the expression node.
	ID() int64

	// Eval an Activation to produce an output.
	Eval(activation Activation) ref.Val
}

Interpretable can accept a given Activation and produce a value along with an accompanying EvalState which can be used to inspect whether additional data might be necessary to complete the evaluation.

type InterpretableDecorator 

type InterpretableDecorator func(Interpretable) (Interpretable, error)

InterpretableDecorator is a functional interface for decorating or replacing Interpretable expression nodes at construction time.

func ExhaustiveEval 

func ExhaustiveEval(state EvalState) InterpretableDecorator

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

func Optimize 

func Optimize() InterpretableDecorator

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

func TrackState 

func TrackState(state EvalState) InterpretableDecorator

TrackState decorates each expression node with an observer which records the value associated with the given expression id. EvalState must be provided to the decorator. This decorator is not thread-safe, and the EvalState must be reset between Eval() calls.

type Interpreter 

type Interpreter interface {
	// NewInterpretable creates an Interpretable from a checked expression and an
	// optional list of InterpretableDecorator values.
	NewInterpretable(checked *exprpb.CheckedExpr,
		decorators ...InterpretableDecorator) (Interpretable, error)

	// NewUncheckedInterpretable returns an Interpretable from a parsed expression
	// and an optional list of InterpretableDecorator values.
	NewUncheckedInterpretable(expr *exprpb.Expr,
		decorators ...InterpretableDecorator) (Interpretable, error)
}

Interpreter generates a new Interpretable from a checked or unchecked expression.

func NewInterpreter 

func NewInterpreter(dispatcher Dispatcher, packager packages.Packager,
	provider ref.TypeProvider,
	adapter ref.TypeAdapter,
	attrFactory AttributeFactory) Interpreter

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

func NewStandardInterpreter 

func NewStandardInterpreter(packager packages.Packager,
	provider ref.TypeProvider,
	adapter ref.TypeAdapter,
	resolver AttributeFactory) Interpreter

NewStandardInterpreter builds a Dispatcher and TypeProvider with support for all of the CEL builtins defined in the language definition.

type NamespacedAttribute 

type NamespacedAttribute interface {
	Attribute

	// CandidateVariableNames returns the possible namespaced variable names for this Attribute in
	// the CEL namespace resolution order.
	CandidateVariableNames() []string

	// HasQualifiers indicates whether the attribute has any qualifiers. An attribute without
	// qualifiers is just a variable.
	HasQualifiers() bool

	// TryResolve attempts to return the value of the attribute given the current Activation.
	// 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`,
	// `false`, `nil`.
	TryResolve(Activation) (interface{}, bool, error)
}

NamespacedAttribute values are a variable within a namespace, and an optional set of qualifiers such as field, key, or index accesses.

type PartialActivation 

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
}

PartialActivation extends the Activation interface with a set of UnknownAttributePatterns.

func NewPartialActivation 

func NewPartialActivation(bindings interface{},
	unknowns ...*AttributePattern) (PartialActivation, error)

NewPartialActivation returns an Activation which contains a list of AttributePattern values representing 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]interface{}.

type Qualifier 

type Qualifier interface {
	// ID where the qualifier appears within an expression.
	ID() int64

	// Qualify performs a qualification, e.g. field selection, on the input object and returns
	// the value or error that results.
	Qualify(vars Activation, obj interface{}) (interface{}, error)
}

Qualifier marker interface for designating different qualifier values and where they appear within field selections and index call expressions (`_[_]`).

Source Files

activation.go attribute_patterns.go attributes.go decorators.go dispatcher.go evalstate.go interpretable.go interpreter.go planner.go prune.go

Directories

PathSynopsis
interpreter/functionsPackage functions defines the standard builtin functions supported by the interpreter and as declared within the checker#StandardDeclarations.
Version
v0.5.0
Published
May 6, 2020
Platform
js/wasm
Imports
13 packages
Last checked
now –

Tools for package owners.