go-cty: github.com/zclconf/go-cty/cty/function Index | Files | Directories

package function

import "github.com/zclconf/go-cty/cty/function"

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

Package Files

argument.go doc.go error.go function.go unpredictable.go

func NewArgError Uses

func NewArgError(i int, err error) error

func NewArgErrorf Uses

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

type ArgError Uses

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 Uses

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

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

func New Uses

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 Uses

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 Uses

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) Params Uses

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 Uses

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 Uses

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 Uses

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 Uses

func (f Function) VarParam() *Parameter

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

type ImplFunc Uses

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 Uses

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 Uses

func (e PanicError) Error() string

type Parameter Uses

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

    // 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
}

Parameter represents a parameter to a function.

type ProxyFunc Uses

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

ProxyFunc the type returned by the method Function.Proxy.

type Spec Uses

type Spec struct {
    // 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

    // 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 Uses

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 Uses

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.

Directories

PathSynopsis
stdlibPackage stdlib is a collection of cty functions that are expected to be generally useful, and are thus factored out into this shared library in the hope that cty-using applications will have consistent behavior when using these functions.

Package function imports 3 packages (graph) and is imported by 51 packages. Updated 2019-09-12. Refresh now. Tools for package owners.