decls

Documentation

Overview

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

Index

• func FunctionDeclToExprDecl(f *FunctionDecl) (*exprpb.Decl, error)
• func MaybeNoSuchOverload(funcName string, args ...ref.Val) ref.Val
• func VariableDeclToExprDecl(v *VariableDecl) (*exprpb.Decl, error)
• type FunctionDecl
  • func NewFunction(name string, opts ...FunctionOpt) (*FunctionDecl, error)
  • func (f *FunctionDecl) AddOverload(overload *OverloadDecl) error
  • func (f *FunctionDecl) Bindings() ([]*functions.Overload, error)
  • func (f *FunctionDecl) IsDeclarationDisabled() bool
  • func (f *FunctionDecl) Merge(other *FunctionDecl) (*FunctionDecl, error)
  • func (f *FunctionDecl) Name() string
  • func (f *FunctionDecl) OverloadDecls() []*OverloadDecl
• type FunctionOpt
  • func DisableDeclaration(value bool) FunctionOpt
  • func DisableTypeGuards(value bool) FunctionOpt
  • func MemberOverload(overloadID string, args []*types.Type, resultType *types.Type, ...) FunctionOpt
  • func Overload(overloadID string, args []*types.Type, resultType *types.Type, ...) FunctionOpt
  • func SingletonBinaryBinding(fn functions.BinaryOp, traits ...int) FunctionOpt
  • func SingletonFunctionBinding(fn functions.FunctionOp, traits ...int) FunctionOpt
  • func SingletonUnaryBinding(fn functions.UnaryOp, traits ...int) FunctionOpt
• type OverloadDecl
  • func (o *OverloadDecl) ArgTypes() []*types.Type
  • func (o *OverloadDecl) ID() string
  • func (o *OverloadDecl) IsMemberFunction() bool
  • func (o *OverloadDecl) IsNonStrict() bool
  • func (o *OverloadDecl) OperandTrait() int
  • func (o *OverloadDecl) ResultType() *types.Type
  • func (o *OverloadDecl) SignatureEquals(other *OverloadDecl) bool
  • func (o *OverloadDecl) SignatureOverlaps(other *OverloadDecl) bool
  • func (o *OverloadDecl) TypeParams() []string
• type OverloadOpt
  • func BinaryBinding(binding functions.BinaryOp) OverloadOpt
  • func FunctionBinding(binding functions.FunctionOp) OverloadOpt
  • func OverloadIsNonStrict() OverloadOpt
  • func OverloadOperandTrait(trait int) OverloadOpt
  • func UnaryBinding(binding functions.UnaryOp) OverloadOpt
• type VariableDecl
  • func NewConstant(name string, t *types.Type, v ref.Val) *VariableDecl
  • func NewVariable(name string, t *types.Type) *VariableDecl
  • func TypeVariable(t *types.Type) *VariableDecl
  • func (v *VariableDecl) DeclarationIsEquivalent(other *VariableDecl) bool
  • func (v *VariableDecl) Name() string
  • func (v *VariableDecl) Type() *types.Type
  • func (v *VariableDecl) Value() ref.Val

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) 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.

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 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 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) 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 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 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 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) 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.