checker

Documentation

Overview

Package checker defines functions to type-checked a parsed expression against a set of identifier and function declarations.

Index

• func Check(parsedExpr *exprpb.ParsedExpr, source common.Source, env *Env) (*exprpb.CheckedExpr, *common.Errors)
• func FormatCheckedType(t *exprpb.Type) string
• func Print(e *exprpb.Expr, checks *exprpb.CheckedExpr) string
• func StandardDeclarations() []*exprpb.Decl
• type AstNode
• type CallEstimate
• type CostEstimate
  • func Cost(checker *exprpb.CheckedExpr, estimator CostEstimator) CostEstimate
  • func (ce CostEstimate) Add(cost CostEstimate) CostEstimate
  • func (ce CostEstimate) Multiply(cost CostEstimate) CostEstimate
  • func (ce CostEstimate) MultiplyByCostFactor(costPerUnit float64) CostEstimate
  • func (ce CostEstimate) Union(size CostEstimate) CostEstimate
• type CostEstimator
• type Env
  • func NewEnv(container *containers.Container, provider ref.TypeProvider, opts ...Option) (*Env, error)
  • func (e *Env) Add(decls ...*exprpb.Decl) error
  • func (e *Env) LookupFunction(name string) *exprpb.Decl
  • func (e *Env) LookupIdent(name string) *exprpb.Decl
• type Option
  • func CrossTypeNumericComparisons(enabled bool) Option
  • func HomogeneousAggregateLiterals(enabled bool) Option
  • func ValidatedDeclarations(env *Env) Option
• type SizeEstimate
  • func (se SizeEstimate) Add(sizeEstimate SizeEstimate) SizeEstimate
  • func (se SizeEstimate) Multiply(sizeEstimate SizeEstimate) SizeEstimate
  • func (se SizeEstimate) MultiplyByCost(cost CostEstimate) CostEstimate
  • func (se SizeEstimate) MultiplyByCostFactor(costPerUnit float64) CostEstimate
  • func (se SizeEstimate) Union(size SizeEstimate) SizeEstimate

Functions

func Check

func Check(parsedExpr *exprpb.ParsedExpr,
	source common.Source,
	env *Env) (*exprpb.CheckedExpr, *common.Errors)

Check performs type checking, giving a typed AST. The input is a ParsedExpr proto and an env which encapsulates type binding of variables, declarations of built-in functions, descriptions of protocol buffers, and a registry for errors. Returns a CheckedExpr proto, which might not be usable if there are errors in the error registry.

func FormatCheckedType

func FormatCheckedType(t *exprpb.Type) string

FormatCheckedType converts a type message into a string representation.

func Print

func Print(e *exprpb.Expr, checks *exprpb.CheckedExpr) string

Print returns a string representation of the Expr message, annotated with types from the CheckedExpr. The Expr must be a sub-expression embedded in the CheckedExpr.

func StandardDeclarations

func StandardDeclarations() []*exprpb.Decl

StandardDeclarations returns the Decls for all functions and constants in the evaluator.

Types

type AstNode

type AstNode interface {
	// Path returns a field path through the provided type declarations to the type of the AstNode, or nil if the AstNode does not
	// represent type directly reachable from the provided type declarations.
	// The first path element is a variable. All subsequent path elements are one of: field name, '@items', '@keys', '@values'.
	Path() []string
	// Type returns the deduced type of the AstNode.
	Type() *exprpb.Type
	// Expr returns the expression of the AstNode.
	Expr() *exprpb.Expr
	// ComputedSize returns a size estimate of the AstNode derived from information available in the CEL expression.
	// For constants and inline list and map declarations, the exact size is returned. For concatenated list, strings
	// and bytes, the size is derived from the size estimates of the operands. nil is returned if there is no
	// computed size available.
	ComputedSize() *SizeEstimate
}

AstNode represents an AST node for the purpose of cost estimations.

type CallEstimate

type CallEstimate struct {
	CostEstimate
	ResultSize *SizeEstimate
}

CallEstimate includes a CostEstimate for the call, and an optional estimate of the result object size. The ResultSize should only be provided if the call results in a map, list, string or bytes.

type CostEstimate

type CostEstimate struct {
	Min, Max uint64
}

CostEstimate represents an estimated cost range and provides add and multiply operations that do not overflow.

func Cost

func Cost(checker *exprpb.CheckedExpr, estimator CostEstimator) CostEstimate

Cost estimates the cost of the parsed and type checked CEL expression.

func (CostEstimate) Add

func (ce CostEstimate) Add(cost CostEstimate) CostEstimate

Add adds the costs and returns the sum. If add would result in an uint64 overflow for the min or max, the value is set to math.MaxUint64.

func (CostEstimate) Multiply

func (ce CostEstimate) Multiply(cost CostEstimate) CostEstimate

Multiply multiplies by the cost and returns the product. If multiply would result in an uint64 overflow, the result is math.MaxUint64.

func (CostEstimate) MultiplyByCostFactor

func (ce CostEstimate) MultiplyByCostFactor(costPerUnit float64) CostEstimate

MultiplyByCostFactor multiplies a CostEstimate by a cost factor and returns the CostEstimate with the nearest integer of the result, rounded up.

func (CostEstimate) Union

func (ce CostEstimate) Union(size CostEstimate) CostEstimate

Union returns a CostEstimate that encompasses both input the CostEstimates.

type CostEstimator

type CostEstimator interface {
	// EstimateSize returns a SizeEstimate for the given AstNode, or nil if
	// the estimator has no estimate to provide. The size is equivalent to the result of the CEL `size()` function:
	// length of strings and bytes, number of map entries or number of list items.
	// EstimateSize is only called for AstNodes where
	// CEL does not know the size; EstimateSize is not called for values defined inline in CEL where the size
	// is already obvious to CEL.
	EstimateSize(element AstNode) *SizeEstimate
	// EstimateCallCost returns the estimated cost of an invocation, or nil if
	// the estimator has no estimate to provide.
	EstimateCallCost(function, overloadID string, target *AstNode, args []AstNode) *CallEstimate
}

CostEstimator estimates the sizes of variable length input data and the costs of functions.

type Env

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

Env is the environment for type checking.

The Env is comprised of a container, type provider, declarations, and other related objects which can be used to assist with type-checking.

func NewEnv

func NewEnv(container *containers.Container, provider ref.TypeProvider, opts ...Option) (*Env, error)

NewEnv returns a new *Env with the given parameters.

func (*Env) Add

func (e *Env) Add(decls ...*exprpb.Decl) error

Add adds new Decl protos to the Env. Returns an error for identifier redeclarations.

func (*Env) LookupFunction

func (e *Env) LookupFunction(name string) *exprpb.Decl

LookupFunction returns a Decl proto for typeName as a function in env. Returns nil if no such function is found in env.

func (*Env) LookupIdent

func (e *Env) LookupIdent(name string) *exprpb.Decl

LookupIdent returns a Decl proto for typeName as an identifier in the Env. Returns nil if no such identifier is found in the Env.

type Option

type Option func(*options) error

Option is a functional option for configuring the type-checker

func CrossTypeNumericComparisons

func CrossTypeNumericComparisons(enabled bool) Option

CrossTypeNumericComparisons toggles type-checker support for numeric comparisons across type See https://github.com/google/cel-spec/wiki/proposal-210 for more details.

func HomogeneousAggregateLiterals

func HomogeneousAggregateLiterals(enabled bool) Option

HomogeneousAggregateLiterals toggles support for constructing lists and maps whose elements all have the same type.

func ValidatedDeclarations

func ValidatedDeclarations(env *Env) Option

ValidatedDeclarations provides a references to validated declarations which will be copied into new checker instances.

type SizeEstimate

type SizeEstimate struct {
	Min, Max uint64
}

SizeEstimate represents an estimated size of a variable length string, bytes, map or list.

func (SizeEstimate) Add

func (se SizeEstimate) Add(sizeEstimate SizeEstimate) SizeEstimate

Add adds to another SizeEstimate and returns the sum. If add would result in an uint64 overflow, the result is math.MaxUint64.

func (SizeEstimate) Multiply

func (se SizeEstimate) Multiply(sizeEstimate SizeEstimate) SizeEstimate

Multiply multiplies by another SizeEstimate and returns the product. If multiply would result in an uint64 overflow, the result is math.MaxUint64.

func (SizeEstimate) MultiplyByCost

func (se SizeEstimate) MultiplyByCost(cost CostEstimate) CostEstimate

MultiplyByCost multiplies by the cost and returns the product. If multiply would result in an uint64 overflow, the result is math.MaxUint64.

func (SizeEstimate) MultiplyByCostFactor

func (se SizeEstimate) MultiplyByCostFactor(costPerUnit float64) CostEstimate

MultiplyByCostFactor multiplies a SizeEstimate by a cost factor and returns the CostEstimate with the nearest integer of the result, rounded up.

func (SizeEstimate) Union

func (se SizeEstimate) Union(size SizeEstimate) SizeEstimate

Union returns a SizeEstimate that encompasses both input the SizeEstimate.