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
- type CallContext
- type CallExpr
- type ConstExpr
- type CreateListExpr
- type CreateMapExpr
- type CreateObjectExpr
- type Dispatcher
- type EvalState
- type IdentExpr
- type Instruction
- type InstructionStepper
- type Interpretable
- type Interpreter
- type JumpInst
- type Metadata
- type MovInst
- type MutableEvalState
- type PopScopeInst
- type Program
- type PushScopeInst
- type SelectExpr
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PruneAst ¶
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)
- Evaluate expr with some unknowns,
- If result is unknown: a) PruneAst b) Goto 1
Functional call results which are known would be effectively cached across iterations.
B)
- Compile the expression (maybe via a service and maybe after checking a compiled expression does not exists in local cache)
- Prepare the environment and the interpreter. Activation might be empty.
- Eval the expression. This might return unknown or error or a concrete value.
- PruneAst
- 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 {
// ResolveReference returns a value from the activation by expression id,
// or false if the id-based reference could not be found.
ResolveReference(exprID int64) (ref.Value, bool)
// ResolveName returns a value from the activation by qualified name, or
// false if the name could not be found.
ResolveName(name string) (ref.Value, 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. TODO: supply references from checkedpb.proto.
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 CallContext ¶
type CallContext struct {
// contains filtered or unexported fields
}
CallContext provides a description of a function call invocation.
func (*CallContext) Args ¶
func (ctx *CallContext) Args() []ref.Value
Args to provide on the overload dispatch.
func (*CallContext) Function ¶
func (ctx *CallContext) Function() (string, string)
Function name to be invoked as it is written in an expression.
func (*CallContext) String ¶
func (ctx *CallContext) String() string
type CallExpr ¶
type CallExpr struct {
Function string
Args []int64
Overload string
Strict bool
// contains filtered or unexported fields
}
CallExpr is a call expression where the args are referenced by id.
func NewCallOverload ¶
NewCallOverload generates a CallExpr for overload calls.
type ConstExpr ¶
ConstExpr is a constant expression.
func NewLiteral ¶
NewLiteral generates a ConstExpr.
type CreateListExpr ¶
type CreateListExpr struct {
Elements []int64
// contains filtered or unexported fields
}
CreateListExpr will create a new list from the elements referened by their ids.
func NewList ¶
func NewList(exprID int64, elements []int64) *CreateListExpr
NewList generates a CreateListExpr.
func (CreateListExpr) GetID ¶
func (e CreateListExpr) GetID() int64
GetID returns the Expr id for the instruction.
func (*CreateListExpr) String ¶
func (e *CreateListExpr) String() string
String generates pseudo-assembly for the instruction.
type CreateMapExpr ¶
CreateMapExpr will create a map from the key value pairs where each key and value refers to an expression id.
func NewMap ¶
func NewMap(exprID int64, keyValues map[int64]int64) *CreateMapExpr
NewMap generates a CreateMapExpr.
func (CreateMapExpr) GetID ¶
func (e CreateMapExpr) GetID() int64
GetID returns the Expr id for the instruction.
func (*CreateMapExpr) String ¶
func (e *CreateMapExpr) String() string
String generates pseudo-assembly for the instruction.
type CreateObjectExpr ¶
type CreateObjectExpr struct {
Name string
FieldValues map[string]int64
// contains filtered or unexported fields
}
CreateObjectExpr generates a new typed object with field values referenced by id.
func NewObject ¶
func NewObject(exprID int64, name string, fieldValues map[string]int64) *CreateObjectExpr
NewObject generates a CreateObjectExpr.
func (CreateObjectExpr) GetID ¶
func (e CreateObjectExpr) GetID() int64
GetID returns the Expr id for the instruction.
func (*CreateObjectExpr) String ¶
func (e *CreateObjectExpr) String() string
String generates pseudo-assembly for the instruction.
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
// Dispatch a call to its appropriate Overload and return the result or
// error.
Dispatch(ctx *CallContext) ref.Value
// FindOverload returns an Overload definition matching the provided
// name.
FindOverload(overload string) (*functions.Overload, bool)
}
Dispatcher resolves function calls to their appropriate overload.
func NewDispatcher ¶
func NewDispatcher() Dispatcher
NewDispatcher returns an empty Dispatcher.
Typically this call would be used with functions#StandardOverloads:
dispatcher := NewDispatcher() dispatcher.add(functions.StandardOverloads())
type EvalState ¶
type EvalState interface {
// GetRuntimeExpressionID returns the runtime id corresponding to the
// expression id from the AST.
GetRuntimeExpressionID(exprID int64) int64
// OnlyValue returns the value in the eval state, if only one exists.
OnlyValue() (ref.Value, bool)
// Value of the given expression id, false if not found.
Value(int64) (ref.Value, bool)
}
EvalState tracks the values associated with expression ids during execution.
type IdentExpr ¶
type IdentExpr struct {
Name string
// contains filtered or unexported fields
}
IdentExpr is an identifier expression.
type Instruction ¶
Instruction represents a single step within a CEL program.
func WalkExpr ¶
func WalkExpr(expression *exprpb.Expr, metadata Metadata, dispatcher Dispatcher, state MutableEvalState, shortCircuit bool) []Instruction
WalkExpr produces a set of Instruction values from a CEL expression.
WalkExpr does a post-order traversal of a CEL syntax AST, which means expressions are evaluated in a bottom-up fashion just as they would be in a recursive execution pattern.
type InstructionStepper ¶
type InstructionStepper interface {
// Next returns the next instruction, or false if the end of the program
// has been reached.
Next() (Instruction, bool)
// JumpCount moves a relative count of instructions forward or back in the
// program and returns whether the jump was successful.
//
// A jump may be unsuccessful if the number of instructions to jump exceeds
// the beginning or end of the program.
JumpCount(count int) bool
}
InstructionStepper steps through program instructions and provides an option to jump a certain number of instructions forward or back.
type Interpretable ¶
type Interpretable interface {
// Eval an Activation to produce an output and EvalState.
Eval(activation Activation) (ref.Value, EvalState)
}
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 Interpreter ¶
type Interpreter interface {
// NewInterpretable returns an Interpretable from a Program.
NewInterpretable(program Program) Interpretable
}
Interpreter generates a new Interpretable from a Program.
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.
type JumpInst ¶
type JumpInst struct {
Count int
OnCondition func(EvalState) bool
// contains filtered or unexported fields
}
JumpInst represents an conditional jump to an instruction offset.
type Metadata ¶
type Metadata interface {
// IDOffset returns raw character offset of an expression within
// Source, or false if the expression cannot be found.
IDOffset(exprID int64) (int32, bool)
// IDLocation returns a common.Location for the given expression id,
// or false if one cannot be found. It behaves as the obvious
// composition of IdOffset() and OffsetLocation().
IDLocation(exprID int64) (common.Location, bool)
}
Metadata interface for accessing position information about expressions. TODO(jimlarson) Replace with common.Source.
type MovInst ¶
type MovInst struct {
ToExprID int64
// contains filtered or unexported fields
}
MovInst assigns the value of one expression id to another.
type MutableEvalState ¶
type MutableEvalState interface {
EvalState
// SetRuntimeExpressionID sets the runtime id for the given expr id.
SetRuntimeExpressionID(exprID int64, runtimeID int64)
// SetValue associates an expression id with a value.
SetValue(int64, ref.Value)
}
MutableEvalState permits the mutation of evaluation state for a given expression id.
func NewEvalState ¶
func NewEvalState(instructionCount int64) MutableEvalState
NewEvalState returns a MutableEvalState.
type PopScopeInst ¶
type PopScopeInst struct {
// contains filtered or unexported fields
}
PopScopeInst resets the current activation to the Activation#Parent() of the previous activation.
func NewPopScope ¶
func NewPopScope(exprID int64) *PopScopeInst
NewPopScope generates a PopScopeInst.
func (PopScopeInst) GetID ¶
func (e PopScopeInst) GetID() int64
GetID returns the Expr id for the instruction.
func (*PopScopeInst) String ¶
func (e *PopScopeInst) String() string
String generates pseudo-assembly for the instruction.
type Program ¶
type Program interface {
// Begin returns an InstructionStepper which iterates through the
// instructions. Each call to Begin() returns a stepper that starts
// from the first instructions.
//
// Note: Init() must be called prior to Begin().
Begin() InstructionStepper
// GetInstruction returns the instruction at the given runtime expression id.
GetInstruction(runtimeID int64) Instruction
// Init ensures that instructions have been properly initialized prior to
// beginning the execution of a program. The init step may optimize the
// instruction set.
Init(dispatcher Dispatcher, state MutableEvalState)
// MaxInstructionID returns the identifier of the last expression in the
// program.
MaxInstructionID() int64
// Metadata used to determine source locations of sub-expressions.
Metadata() Metadata
}
Program contains instructions and related metadata.
func NewCheckedProgram ¶
func NewCheckedProgram(c *exprpb.CheckedExpr) Program
NewCheckedProgram creates a Program from a checked CEL expression.
func NewExhaustiveProgram ¶
func NewExhaustiveProgram(expression *exprpb.Expr, info *exprpb.SourceInfo) Program
NewExhaustiveProgram creates a Program from a CEL expression and source information which force evaluating all branches of the expression.
func NewProgram ¶
func NewProgram(expression *exprpb.Expr, info *exprpb.SourceInfo) Program
NewProgram creates a Program from a CEL expression and source information.
type PushScopeInst ¶
type PushScopeInst struct {
Declarations map[string]int64
// contains filtered or unexported fields
}
PushScopeInst results in the generation of a new Activation containing the values of the associated declarations.
func NewPushScope ¶
func NewPushScope(exprID int64, declarations map[string]int64) *PushScopeInst
NewPushScope generates a PushScopeInst.
func (PushScopeInst) GetID ¶
func (e PushScopeInst) GetID() int64
GetID returns the Expr id for the instruction.
func (*PushScopeInst) String ¶
func (e *PushScopeInst) String() string
String generates pseudo-assembly for the instruction.
type SelectExpr ¶
SelectExpr is a select expression where the operand is represented by id.
func NewSelect ¶
func NewSelect(exprID int64, operandID int64, field string) *SelectExpr
NewSelect generates a SelectExpr.
func (SelectExpr) GetID ¶
func (e SelectExpr) GetID() int64
GetID returns the Expr id for the instruction.
func (*SelectExpr) String ¶
func (e *SelectExpr) String() string
String generates pseudo-assembly for the instruction.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package functions defines the standard builtin functions supported by the interpreter and as declared within the checker#StandardDeclarations.
|
Package functions defines the standard builtin functions supported by the interpreter and as declared within the checker#StandardDeclarations. |