package decls

import "github.com/google/cel-go/common/decls"

Package decls contains function and variable declaration structs and helper methods.

Index

Functions

func FunctionDeclToExprDecl 

func FunctionDeclToExprDecl(f *FunctionDecl) (*exprpb.Decl, error)

FunctionDeclToExprDecl converts a go-native function declaration into a protobuf-typed function declaration.

func MaybeNoSuchOverload 

func MaybeNoSuchOverload(funcName string, args ...ref.Val) ref.Val

MaybeNoSuchOverload determines whether to propagate an error if one is provided as an argument, or to return an unknown set, or to produce a new error for a missing function signature.

func VariableDeclToExprDecl 

func VariableDeclToExprDecl(v *VariableDecl) (*exprpb.Decl, error)

VariableDeclToExprDecl converts a go-native variable declaration into a protobuf-type variable declaration.

Types

type FunctionDecl 

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

FunctionDecl defines a function name, overload set, and optionally a singleton definition for all overload instances.

func NewFunction 

func NewFunction(name string, opts ...FunctionOpt) (*FunctionDecl, error)

NewFunction creates a new function declaration with a set of function options to configure overloads and function definitions (implementations).

Functions are checked for name collisions and singleton redefinition.

func (*FunctionDecl) AddOverload 

func (f *FunctionDecl) AddOverload(overload *OverloadDecl) error

AddOverload ensures that the new overload does not collide with an existing overload signature; however, if the function signatures are identical, the implementation may be rewritten as its difficult to compare functions by object identity.

func (*FunctionDecl) Bindings 

func (f *FunctionDecl) Bindings() ([]*functions.Overload, error)

Bindings produces a set of function bindings, if any are defined.

func (*FunctionDecl) Description 

func (f *FunctionDecl) Description() string

Description provides an overview of the function's purpose.

Usage examples should be included on specific overloads.

func (*FunctionDecl) Documentation 

func (f *FunctionDecl) Documentation() *common.Doc

Documentation generates documentation about the Function and its overloads as a common.Doc object.

func (*FunctionDecl) HasLateBinding 

func (f *FunctionDecl) HasLateBinding() bool

Returns true if the function has late bindings. A function cannot mix late bindings with other bindings.

func (*FunctionDecl) IsDeclarationDisabled 

func (f *FunctionDecl) IsDeclarationDisabled() bool

IsDeclarationDisabled indicates that the function implementation should be added to the dispatcher, but the declaration should not be exposed for use in expressions.

func (*FunctionDecl) Merge 

func (f *FunctionDecl) Merge(other *FunctionDecl) (*FunctionDecl, error)

Merge combines an existing function declaration with another.

If a function is extended, by say adding new overloads to an existing function, then it is merged with the prior definition of the function at which point its overloads must not collide with pre-existing overloads and its bindings (singleton, or per-overload) must not conflict with previous definitions either.

func (*FunctionDecl) Name 

func (f *FunctionDecl) Name() string

Name returns the function name in human-readable terms, e.g. 'contains' of 'math.least'

func (*FunctionDecl) OverloadDecls 

func (f *FunctionDecl) OverloadDecls() []*OverloadDecl

OverloadDecls returns the overload declarations in the order in which they were declared.

func (*FunctionDecl) Subset 

func (f *FunctionDecl) Subset(selector OverloadSelector) *FunctionDecl

Subset returns a new function declaration which contains only the overloads with the specified IDs. If the subset function contains no overloads, then nil is returned to indicate the function is not functional.

type FunctionOpt 

type FunctionOpt func(*FunctionDecl) (*FunctionDecl, error)

FunctionOpt defines a functional option for mutating a function declaration.

func DisableDeclaration 

func DisableDeclaration(value bool) FunctionOpt

DisableDeclaration indicates that the function declaration should be disabled, but the runtime function binding should be provided. Marking a function as runtime-only is a safe way to manage deprecations of function declarations while still preserving the runtime behavior for previously compiled expressions.

func DisableTypeGuards 

func DisableTypeGuards(value bool) FunctionOpt

DisableTypeGuards disables automatically generated function invocation guards on direct overload calls. Type guards remain on during dynamic dispatch for parsed-only expressions.

func FunctionDocs 

func FunctionDocs(docs ...string) FunctionOpt

FunctionDocs configures documentation from a list of strings separated by newlines.

func MemberOverload 

func MemberOverload(overloadID string,
	args []*types.Type, resultType *types.Type,
	opts ...OverloadOpt) FunctionOpt

MemberOverload defines a new receiver-style overload (or member function) with an overload id, argument types, and result type. Through the use of OverloadOpt options, the overload may also be configured with a binding, an operand trait, and to be non-strict.

Note: function bindings should be commonly configured with Overload instances whereas operand traits and strict-ness should be rare occurrences.

func Overload 

func Overload(overloadID string,
	args []*types.Type, resultType *types.Type,
	opts ...OverloadOpt) FunctionOpt

Overload defines a new global overload with an overload id, argument types, and result type. Through the use of OverloadOpt options, the overload may also be configured with a binding, an operand trait, and to be non-strict.

Note: function bindings should be commonly configured with Overload instances whereas operand traits and strict-ness should be rare occurrences.

func SingletonBinaryBinding 

func SingletonBinaryBinding(fn functions.BinaryOp, traits ...int) FunctionOpt

SingletonBinaryBinding creates a singleton function definition to be used with all function overloads.

Note, this approach works well if operand is expected to have a specific trait which it implements, e.g. traits.ContainerType. Otherwise, prefer per-overload function bindings.

func SingletonFunctionBinding 

func SingletonFunctionBinding(fn functions.FunctionOp, traits ...int) FunctionOpt

SingletonFunctionBinding creates a singleton function definition to be used with all function overloads.

Note, this approach works well if operand is expected to have a specific trait which it implements, e.g. traits.ContainerType. Otherwise, prefer per-overload function bindings.

func SingletonUnaryBinding 

func SingletonUnaryBinding(fn functions.UnaryOp, traits ...int) FunctionOpt

SingletonUnaryBinding creates a singleton function definition to be used for all function overloads.

Note, this approach works well if operand is expected to have a specific trait which it implements, e.g. traits.ContainerType. Otherwise, prefer per-overload function bindings.

type FunctionSubsetter 

type FunctionSubsetter func(fn *FunctionDecl) (*FunctionDecl, bool)

FunctionSubsetter subsets a function declaration or returns nil and false if the function subset was empty.

type OverloadDecl 

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

OverloadDecl contains the definition of a single overload id with a specific signature, and an optional implementation.

func (*OverloadDecl) ArgTypes 

func (o *OverloadDecl) ArgTypes() []*types.Type

ArgTypes contains the set of argument types expected by the overload.

For member functions ArgTypes[0] represents the member operand type.

func (*OverloadDecl) Examples 

func (o *OverloadDecl) Examples() []string

Examples returns a list of string examples for the overload.

func (*OverloadDecl) HasLateBinding 

func (o *OverloadDecl) HasLateBinding() bool

HasLateBinding returns whether the overload has a binding which is not known at compile time.

func (*OverloadDecl) ID 

func (o *OverloadDecl) ID() string

ID mirrors the overload signature and provides a unique id which may be referenced within the type-checker and interpreter to optimize performance.

The ID format is usually one of two styles: global: <functionName>_<argType>_<argTypeN> member: <memberType>_<functionName>_<argType>_<argTypeN>

func (*OverloadDecl) IsMemberFunction 

func (o *OverloadDecl) IsMemberFunction() bool

IsMemberFunction indicates whether the overload is a member function

func (*OverloadDecl) IsNonStrict 

func (o *OverloadDecl) IsNonStrict() bool

IsNonStrict returns whether the overload accepts errors and unknown values as arguments.

func (*OverloadDecl) OperandTrait 

func (o *OverloadDecl) OperandTrait() int

OperandTrait returns the trait mask of the first operand to the overload call, e.g. `traits.Indexer`

func (*OverloadDecl) ResultType 

func (o *OverloadDecl) ResultType() *types.Type

ResultType indicates the output type from calling the function.

func (*OverloadDecl) SignatureEquals 

func (o *OverloadDecl) SignatureEquals(other *OverloadDecl) bool

SignatureEquals determines whether the incoming overload declaration signature is equal to the current signature.

Result type, operand trait, and strict-ness are not considered as part of signature equality.

func (*OverloadDecl) SignatureOverlaps 

func (o *OverloadDecl) SignatureOverlaps(other *OverloadDecl) bool

SignatureOverlaps indicates whether two functions have non-equal, but overloapping function signatures.

For example, list(dyn) collides with list(string) since the 'dyn' type can contain a 'string' type.

func (*OverloadDecl) TypeParams 

func (o *OverloadDecl) TypeParams() []string

TypeParams returns the type parameter names associated with the overload.

type OverloadOpt 

type OverloadOpt func(*OverloadDecl) (*OverloadDecl, error)

OverloadOpt is a functional option for configuring a function overload.

func BinaryBinding 

func BinaryBinding(binding functions.BinaryOp) OverloadOpt

BinaryBinding provides the implementation of a binary overload. The provided function is protected by a runtime type-guard which ensures runtime type agreement between the overload signature and runtime argument types.

func FunctionBinding 

func FunctionBinding(binding functions.FunctionOp) OverloadOpt

FunctionBinding provides the implementation of a variadic overload. The provided function is protected by a runtime type-guard which ensures runtime type agreement between the overload signature and runtime argument types.

func LateFunctionBinding 

func LateFunctionBinding() OverloadOpt

LateFunctionBinding indicates that the function has a binding which is not known at compile time. This is useful for functions which have side-effects or are not deterministically computable.

func OverloadExamples 

func OverloadExamples(examples ...string) OverloadOpt

OverloadExamples configures example expressions for the overload.

func OverloadIsNonStrict 

func OverloadIsNonStrict() OverloadOpt

OverloadIsNonStrict enables the function to be called with error and unknown argument values.

Note: do not use this option unless absoluately necessary as it should be an uncommon feature.

func OverloadOperandTrait 

func OverloadOperandTrait(trait int) OverloadOpt

OverloadOperandTrait configures a set of traits which the first argument to the overload must implement in order to be successfully invoked.

func UnaryBinding 

func UnaryBinding(binding functions.UnaryOp) OverloadOpt

UnaryBinding provides the implementation of a unary overload. The provided function is protected by a runtime type-guard which ensures runtime type agreement between the overload signature and runtime argument types.

type OverloadSelector 

type OverloadSelector func(overload *OverloadDecl) bool

OverloadSelector selects an overload associated with a given function when it returns true.

Used in combination with the Subset method.

func ExcludeOverloads 

func ExcludeOverloads(overloadIDs ...string) OverloadSelector

ExcludeOverloads defines an OverloadSelector which deny-lists a set of overloads by their ids.

func IncludeOverloads 

func IncludeOverloads(overloadIDs ...string) OverloadSelector

IncludeOverloads defines an OverloadSelector which allow-lists a set of overloads by their ids.

type VariableDecl 

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

VariableDecl defines a variable declaration which may optionally have a constant value.

func NewConstant 

func NewConstant(name string, t *types.Type, v ref.Val) *VariableDecl

NewConstant creates a new constant declaration.

func NewVariable 

func NewVariable(name string, t *types.Type) *VariableDecl

NewVariable creates a new variable declaration.

func NewVariableWithDoc 

func NewVariableWithDoc(name string, t *types.Type, doc string) *VariableDecl

NewVariableWithDoc creates a new variable declaration with usage documentation.

func TypeVariable 

func TypeVariable(t *types.Type) *VariableDecl

TypeVariable creates a new type identifier for use within a types.Provider

func (*VariableDecl) DeclarationIsEquivalent 

func (v *VariableDecl) DeclarationIsEquivalent(other *VariableDecl) bool

DeclarationIsEquivalent returns true if one variable declaration has the same name and same type as the input.

func (*VariableDecl) Description 

func (v *VariableDecl) Description() string

Description returns the usage documentation for the variable, if set.

Good usage instructions provide information about the valid formats, ranges, sizes for the variable type.

func (*VariableDecl) Documentation 

func (v *VariableDecl) Documentation() *common.Doc

Documentation returns name, type, and description for the variable.

func (*VariableDecl) Name 

func (v *VariableDecl) Name() string

Name returns the fully-qualified variable name

func (*VariableDecl) Type 

func (v *VariableDecl) Type() *types.Type

Type returns the types.Type value associated with the variable.

func (*VariableDecl) Value 

func (v *VariableDecl) Value() ref.Val

Value returns the constant value associated with the declaration.

Source Files

decls.go

Version
v0.25.0 (latest)
Published
Apr 22, 2025
Platform
linux/amd64
Imports
9 packages
Last checked
1 hour ago –

Tools for package owners.