function

Documentation

Overview

Package function builds on the functionality of cty by modeling functions that operate on cty Values.

Functions are, at their core, Go anonymous functions. However, this package wraps around them utility functions for parameter type checking, etc.

Index

• func NewArgError(i int, err error) error
• func NewArgErrorf(i int, f string, args ...interface{}) error
• type ArgError
• type Function
  • func New(spec *Spec) Function
  • func Unpredictable(f Function) Function
  • func (f Function) Call(args []cty.Value) (val cty.Value, err error)
  • func (f Function) Description() string
  • func (f Function) Params() []Parameter
  • func (f Function) Proxy() ProxyFunc
  • func (f Function) ReturnType(argTypes []cty.Type) (cty.Type, error)
  • func (f Function) ReturnTypeForValues(args []cty.Value) (ty cty.Type, err error)
  • func (f Function) VarParam() *Parameter
  • func (f Function) WithNewDescriptions(funcDesc string, paramDescs []string) Function
• type ImplFunc
• type PanicError
  • func (e PanicError) Error() string
• type Parameter
• type ProxyFunc
• type Spec
• type TypeFunc
  • func StaticReturnType(ty cty.Type) TypeFunc

Functions

func NewArgError

func NewArgError(i int, err error) error

func NewArgErrorf

func NewArgErrorf(i int, f string, args ...interface{}) error

Types

type ArgError

type ArgError struct {
	Index int
	// contains filtered or unexported fields
}

ArgError represents an error with one of the arguments in a call. The attribute Index represents the zero-based index of the argument in question.

Its error *may* be a cty.PathError, in which case the error actually pertains to a nested value within the data structure passed as the argument.

type Function

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

Function represents a function. This is the main type in this package.

func New

func New(spec *Spec) Function

New creates a new function with the given specification.

After passing a Spec to this function, the caller must no longer read from or mutate it.

func Unpredictable

func Unpredictable(f Function) Function

Unpredictable wraps a given function such that it retains the same arguments and type checking behavior but will return an unknown value when called.

It is recommended that most functions be "pure", which is to say that they will always produce the same value given particular input. However, sometimes it is necessary to offer functions whose behavior depends on some external state, such as reading a file or determining the current time. In such cases, an unpredictable wrapper might be used to stand in for the function during some sort of prior "checking" phase in order to delay the actual effect until later.

While Unpredictable can support a function that isn't pure in its implementation, it still expects a function to be pure in its type checking behavior, except for the special case of returning cty.DynamicPseudoType if it is not yet able to predict its return value based on current argument information.

func (Function) Call

func (f Function) Call(args []cty.Value) (val cty.Value, err error)

Call actually calls the function with the given arguments, which must conform to the function's parameter specification or an error will be returned.

func (Function) Description

func (f Function) Description() string

Description returns a human-readable description of the function.

func (Function) Params

func (f Function) Params() []Parameter

Params returns information about the function's fixed positional parameters. This does not include information about any variadic arguments accepted; for that, call VarParam.

func (Function) Proxy

func (f Function) Proxy() ProxyFunc

Proxy returns a function that can be called with cty.Value arguments to run the function. This is provided as a convenience for when using a function directly within Go code.

func (Function) ReturnType

func (f Function) ReturnType(argTypes []cty.Type) (cty.Type, error)

ReturnType returns the return type of a function given a set of candidate argument types, or returns an error if the given types are unacceptable.

If the caller already knows values for at least some of the arguments it can be better to call ReturnTypeForValues, since certain functions may determine their return types from their values and return DynamicVal if the values are unknown.

func (Function) ReturnTypeForValues

func (f Function) ReturnTypeForValues(args []cty.Value) (ty cty.Type, err error)

ReturnTypeForValues is similar to ReturnType but can be used if the caller already knows the values of some or all of the arguments, in which case the function may be able to determine a more definite result if its return type depends on the argument *values*.

For any arguments whose values are not known, pass an Unknown value of the appropriate type.

func (Function) VarParam

func (f Function) VarParam() *Parameter

VarParam returns information about the variadic arguments the function expects, or nil if the function is not variadic.

func (Function) WithNewDescriptions

func (f Function) WithNewDescriptions(funcDesc string, paramDescs []string) Function

WithNewDescriptions returns a new function that has the same signature and implementation as the receiver but has the function description and the parameter descriptions replaced with those given in the arguments.

All descriptions may be given as an empty string to specify that there should be no description at all.

The paramDescs argument must match the number of parameters the reciever expects, or this function will panic. If the function has a VarParam then that counts as one parameter for the sake of this rule. The given descriptions will be assigned in order starting with the positional arguments in their declared order, followed by the variadic parameter if any.

As a special case, WithNewDescriptions will accept a paramDescs which does not cover the reciever's variadic parameter (if any), so that it's possible to add a variadic parameter to a function which didn't previously have one without that being a breaking change for an existing caller using WithNewDescriptions against that function. In this case the base description of the variadic parameter will be preserved.

type ImplFunc

type ImplFunc func(args []cty.Value, retType cty.Type) (cty.Value, error)

ImplFunc is a callback type for the main implementation of a function.

"args" are the values for the arguments, and this slice will always be at least as long as the argument definition slice for the function.

"retType" is the type returned from the Type callback, included as a convenience to avoid the need to re-compute the return type for generic functions whose return type is a function of the arguments.

type PanicError

type PanicError struct {
	Value interface{}
	Stack []byte
}

PanicError indicates that a panic occurred while executing either a function's type or implementation function. This is captured and wrapped into a normal error so that callers (expected to be language runtimes) are freed from having to deal with panics in buggy functions.

func (PanicError) Error

func (e PanicError) Error() string

type Parameter

type Parameter struct {
	// Name is an optional name for the argument. This package ignores this
	// value, but callers may use it for documentation, etc.
	Name string

	// Description is an optional description for the argument.
	Description string

	// A type that any argument for this parameter must conform to.
	// cty.DynamicPseudoType can be used, either at top-level or nested
	// in a parameterized type, to indicate that any type should be
	// permitted, to allow the definition of type-generic functions.
	Type cty.Type

	// If AllowNull is set then null values may be passed into this
	// argument's slot in both the type-check function and the implementation
	// function. If not set, such values are rejected by the built-in
	// checking rules.
	AllowNull bool

	// If AllowUnknown is set then unknown values may be passed into this
	// argument's slot in the implementation function. If not set, any
	// unknown values will cause the function to immediately return
	// an unkonwn value without calling the implementation function, thus
	// freeing the function implementer from dealing with this case.
	AllowUnknown bool

	// If AllowDynamicType is set then DynamicVal may be passed into this
	// argument's slot in the implementation function. If not set, any
	// dynamic values will cause the function to immediately return
	// DynamicVal value without calling the implementation function, thus
	// freeing the function implementer from dealing with this case.
	//
	// Note that DynamicVal is also unknown, so in order to receive dynamic
	// *values* it is also necessary to set AllowUnknown.
	//
	// However, it is valid to set AllowDynamicType without AllowUnknown, in
	// which case a dynamic value may be passed to the type checking function
	// but will not make it to the *implementation* function. Instead, an
	// unknown value of the type returned by the type-check function will be
	// returned. This is suggested for functions that have a static return
	// type since it allows the return value to be typed even if the input
	// values are not, thus improving the type-check accuracy of derived
	// values.
	AllowDynamicType bool

	// If AllowMarked is set then marked values may be passed into this
	// argument's slot in the implementation function. If not set, any
	// marked value will be unmarked before calling and then the markings
	// from that value will be applied automatically to the function result,
	// ensuring that the marks get propagated in a simplistic way even if
	// a function is unable to handle them.
	//
	// For any argument whose parameter has AllowMarked set, it's the
	// function implementation's responsibility to Unmark the given value
	// and propagate the marks appropriatedly to the result in order to
	// avoid losing the marks. Application-specific functions might use
	// special rules to selectively propagate particular marks.
	//
	// The automatic unmarking of values applies only to the main
	// implementation function. In an application that uses marked values,
	// the Type implementation for a function must always be prepared to accept
	// marked values, which is easy to achieve by consulting only the type
	// and ignoring the value itself.
	AllowMarked bool
}

Parameter represents a parameter to a function.

type ProxyFunc

type ProxyFunc func(args ...cty.Value) (cty.Value, error)

ProxyFunc the type returned by the method Function.Proxy.

type Spec

type Spec struct {
	// Description is an optional description for the function specification.
	Description string

	// Params is a description of the positional parameters for the function.
	// The standard checking logic rejects any calls that do not provide
	// arguments conforming to this definition, freeing the function
	// implementer from dealing with such inconsistencies.
	Params []Parameter

	// VarParam is an optional specification of additional "varargs" the
	// function accepts. If this is non-nil then callers may provide an
	// arbitrary number of additional arguments (after those matching with
	// the fixed parameters in Params) that conform to the given specification,
	// which will appear as additional values in the slices of values
	// provided to the type and implementation functions.
	VarParam *Parameter

	// Type is the TypeFunc that decides the return type of the function
	// given its arguments, which may be Unknown. See the documentation
	// of TypeFunc for more information.
	//
	// Use StaticReturnType if the function's return type does not vary
	// depending on its arguments.
	Type TypeFunc

	// RefineResult is an optional callback for describing additional
	// refinements for the result value beyond what can be described using
	// a type constraint.
	//
	// A refinement callback should always return the same builder it was
	// given, typically after modifying it using the methods of
	// [cty.RefinementBuilder].
	//
	// Any refinements described by this callback must hold for the entire
	// range of results from the function. For refinements that only apply
	// to certain results, use direct refinement within [Impl] instead.
	RefineResult func(*cty.RefinementBuilder) *cty.RefinementBuilder

	// Impl is the ImplFunc that implements the function's behavior.
	//
	// Functions are expected to behave as pure functions, and not create
	// any visible side-effects.
	//
	// If a TypeFunc is also provided, the value returned from Impl *must*
	// conform to the type it returns, or a call to the function will panic.
	Impl ImplFunc
}

Spec is the specification of a function, used to instantiate a new Function.

type TypeFunc

type TypeFunc func(args []cty.Value) (cty.Type, error)

TypeFunc is a callback type for determining the return type of a function given its arguments.

Any of the values passed to this function may be unknown, even if the parameters are not configured to accept unknowns.

If any of the given values are *not* unknown, the TypeFunc may use the values for pre-validation and for choosing the return type. For example, a hypothetical JSON-unmarshalling function could return cty.DynamicPseudoType if the given JSON string is unknown, but return a concrete type based on the JSON structure if the JSON string is already known.

func StaticReturnType

func StaticReturnType(ty cty.Type) TypeFunc

StaticReturnType returns a TypeFunc that always returns the given type.

This is provided as a convenience for defining a function whose return type does not depend on the argument types.