convert

Documentation

Overview

Package convert contains some routines for converting between cty types. The intent of providing this package is to encourage applications using cty to have consistent type conversion behavior for maximal interoperability when Values pass from one application to another.

The conversions are categorized into two categories. "Safe" conversions are ones that are guaranteed to succeed if given a non-null value of the appropriate source type. "Unsafe" conversions, on the other hand, are valid for only a subset of input values, and thus may fail with an error when called for values outside of that valid subset.

The functions whose names end in Unsafe support all of the conversions that are supported by the corresponding functions whose names do not have that suffix, and then additional unsafe conversions as well.

Index

• func Convert(in cty.Value, want cty.Type) (cty.Value, error)
• func MismatchMessage(got, want cty.Type) string
• type Conversion
  • func GetConversion(in cty.Type, out cty.Type) Conversion
  • func GetConversionUnsafe(in cty.Type, out cty.Type) Conversion
  • func Unify(types []cty.Type) (cty.Type, []Conversion)
  • func UnifyUnsafe(types []cty.Type) (cty.Type, []Conversion)

Functions

func Convert

func Convert(in cty.Value, want cty.Type) (cty.Value, error)

Convert returns the result of converting the given value to the given type if an safe or unsafe conversion is available, or returns an error if such a conversion is impossible.

This is a convenience wrapper around calling GetConversionUnsafe and then immediately passing the given value to the resulting function.

func MismatchMessage

func MismatchMessage(got, want cty.Type) string

MismatchMessage is a helper to return an English-language description of the differences between got and want, phrased as a reason why got does not conform to want.

This function does not itself attempt conversion, and so it should generally be used only after a conversion has failed, to report the conversion failure to an English-speaking user. The result will be confusing got is actually conforming to or convertable to want.

The shorthand helper function Convert uses this function internally to produce its error messages, so callers of that function do not need to also use MismatchMessage.

This function is similar to Type.TestConformance, but it is tailored to describing conversion failures and so the messages it generates relate specifically to the conversion rules implemented in this package.

Types

type Conversion

type Conversion func(in cty.Value) (out cty.Value, err error)

Conversion is a named function type representing a conversion from a value of one type to a value of another type.

The source type for a conversion is always the source type given to the function that returned the Conversion, but there is no way to recover that from a Conversion value itself. If a Conversion is given a value that is not of its expected type (with the exception of DynamicPseudoType, which is always supported) then the function may panic or produce undefined results.

func GetConversion

func GetConversion(in cty.Type, out cty.Type) Conversion

GetConversion returns a Conversion between the given in and out Types if a safe one is available, or returns nil otherwise.

func GetConversionUnsafe

func GetConversionUnsafe(in cty.Type, out cty.Type) Conversion

GetConversionUnsafe returns a Conversion between the given in and out Types if either a safe or unsafe one is available, or returns nil otherwise.

func Unify

func Unify(types []cty.Type) (cty.Type, []Conversion)

Unify attempts to find the most general type that can be converted from all of the given types. If this is possible, that type is returned along with a slice of necessary conversions for some of the given types.

If no common supertype can be found, this function returns cty.NilType and a nil slice.

If a common supertype *can* be found, the returned slice will always be non-nil and will contain a non-nil conversion for each given type that needs to be converted, with indices corresponding to the input slice. Any given type that does *not* need conversion (because it is already of the appropriate type) will have a nil Conversion.

cty.DynamicPseudoType is, as usual, a special case. If the given type list contains a mixture of dynamic and non-dynamic types, the dynamic types are disregarded for type selection and a conversion is returned for them that will attempt a late conversion of the given value to the target type, failing with a conversion error if the eventual concrete type is not compatible. If *all* given types are DynamicPseudoType, or in the degenerate case of an empty slice of types, the returned type is itself cty.DynamicPseudoType and no conversions are attempted.

func UnifyUnsafe

func UnifyUnsafe(types []cty.Type) (cty.Type, []Conversion)

UnifyUnsafe is the same as Unify except that it may return unsafe conversions in situations where a safe conversion isn't also available.