gocty

Documentation

Overview

Package gocty deals with converting between cty Values and native go values.

It operates under a similar principle to the encoding/json and encoding/xml packages in the standard library, using reflection to populate native Go data structures from cty values and vice-versa.

Index

• func FromCtyValue(val cty.Value, target interface{}) error
• func ImpliedType(gv interface{}) (cty.Type, error)
• func ToCtyValue(val interface{}, ty cty.Type) (cty.Value, error)

Functions

func FromCtyValue

func FromCtyValue(val cty.Value, target interface{}) error

FromCtyValue assigns a cty.Value to a reflect.Value, which must be a pointer, using a fixed set of conversion rules.

This function considers its audience to be the creator of the cty Value given, and thus the error messages it generates are (unlike with ToCtyValue) presented in cty terminology that is generally appropriate to return to end-users in applications where cty data structures are built from user-provided configuration. In particular this means that if incorrect target types are provided by the calling application the resulting error messages are likely to be confusing, since we assume that the given target type is correct and the cty.Value is where the error lies.

If an error is returned, the target data structure may have been partially populated, but the degree to which this is true is an implementation detail that the calling application should not rely on.

The function will panic if given a non-pointer as the Go value target, since that is considered to be a bug in the calling program.

func ImpliedType

func ImpliedType(gv interface{}) (cty.Type, error)

ImpliedType takes an arbitrary Go value (as an interface{}) and attempts to find a suitable cty.Type instance that could be used for a conversion with ToCtyValue.

This allows -- for simple situations at least -- types to be defined just once in Go and the cty types derived from the Go types, but in the process it makes some assumptions that may be undesirable so applications are encouraged to build their cty types directly if exacting control is required.

Not all Go types can be represented as cty types, so an error may be returned which is usually considered to be a bug in the calling program. In particular, ImpliedType will never use capsule types in its returned type, because it cannot know the capsule types supported by the calling program.

func ToCtyValue

func ToCtyValue(val interface{}, ty cty.Type) (cty.Value, error)

ToCtyValue produces a cty.Value from a Go value. The result will conform to the given type, or an error will be returned if this is not possible.

The target type serves as a hint to resolve ambiguities in the mapping. For example, the Go type set.Set tells us that the value is a set but does not describe the set's element type. This also allows for convenient conversions, such as populating a set from a slice rather than having to first explicitly instantiate a set.Set.

The audience of this function is assumed to be the developers of Go code that is integrating with cty, and thus the error messages it returns are presented from Go's perspective. These messages are thus not appropriate for display to end-users. An error returned from ToCtyValue represents a bug in the calling program, not user error.