interpreter

Documentation

Overview

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

Index

• func PruneAst(expr *exprpb.Expr, state EvalState) *exprpb.Expr
• type Activation
  • func NewActivation(bindings map[string]interface{}) Activation
  • func NewHierarchicalActivation(parent Activation, child Activation) Activation
• type Dispatcher
  • func ExtendDispatcher(parent Dispatcher) Dispatcher
  • func NewDispatcher() Dispatcher
• type EvalState
  • func NewEvalState() EvalState
• type Interpretable
• type InterpretableDecorator
  • func ExhaustiveEval(state EvalState) InterpretableDecorator
  • func FoldConstants() InterpretableDecorator
  • func TrackState(state EvalState) InterpretableDecorator
• type Interpreter
  • func NewInterpreter(dispatcher Dispatcher, packager packages.Packager, ...) Interpreter
  • func NewStandardInterpreter(packager packages.Packager, typeProvider ref.TypeProvider) Interpreter

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
4. 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) (ref.Val, 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 NewActivation

func NewActivation(bindings map[string]interface{}) Activation

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

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 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 {
	// 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 expresssion 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 FoldConstants

func FoldConstants() InterpretableDecorator

FoldConstants will pre-compute list and map literals comprised entirely of constant entries. This optimization will increase the set of constant fold operations 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,
	typeProvider ref.TypeProvider) 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,
	typeProvider ref.TypeProvider) Interpreter

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