vendor/github.com/zclconf/go-cty/cty/convert/public.go

   1 package convert
   2
   3 import (
   4         "errors"
   5
   6         "github.com/zclconf/go-cty/cty"
   7 )
   8
   9 // This file contains the public interface of this package, which is intended
  10 // to be a small, convenient interface designed for easy integration into
  11 // a hypothetical language type checker and interpreter.
  12
  13 // Conversion is a named function type representing a conversion from a
  14 // value of one type to a value of another type.
  15 //
  16 // The source type for a conversion is always the source type given to
  17 // the function that returned the Conversion, but there is no way to recover
  18 // that from a Conversion value itself. If a Conversion is given a value
  19 // that is not of its expected type (with the exception of DynamicPseudoType,
  20 // which is always supported) then the function may panic or produce undefined
  21 // results.
  22 type Conversion func(in cty.Value) (out cty.Value, err error)
  23
  24 // GetConversion returns a Conversion between the given in and out Types if
  25 // a safe one is available, or returns nil otherwise.
  26 func GetConversion(in cty.Type, out cty.Type) Conversion {
  27         return retConversion(getConversion(in, out, false))
  28 }
  29
  30 // GetConversionUnsafe returns a Conversion between the given in and out Types
  31 // if either a safe or unsafe one is available, or returns nil otherwise.
  32 func GetConversionUnsafe(in cty.Type, out cty.Type) Conversion {
  33         return retConversion(getConversion(in, out, true))
  34 }
  35
  36 // Convert returns the result of converting the given value to the given type
  37 // if an safe or unsafe conversion is available, or returns an error if such a
  38 // conversion is impossible.
  39 //
  40 // This is a convenience wrapper around calling GetConversionUnsafe and then
  41 // immediately passing the given value to the resulting function.
  42 func Convert(in cty.Value, want cty.Type) (cty.Value, error) {
  43         if in.Type().Equals(want) {
  44                 return in, nil
  45         }
  46
  47         conv := GetConversionUnsafe(in.Type(), want)
  48         if conv == nil {
  49                 return cty.NilVal, errors.New(MismatchMessage(in.Type(), want))
  50         }
  51         return conv(in)
  52 }
  53
  54 // Unify attempts to find the most general type that can be converted from
  55 // all of the given types. If this is possible, that type is returned along
  56 // with a slice of necessary conversions for some of the given types.
  57 //
  58 // If no common supertype can be found, this function returns cty.NilType and
  59 // a nil slice.
  60 //
  61 // If a common supertype *can* be found, the returned slice will always be
  62 // non-nil and will contain a non-nil conversion for each given type that
  63 // needs to be converted, with indices corresponding to the input slice.
  64 // Any given type that does *not* need conversion (because it is already of
  65 // the appropriate type) will have a nil Conversion.
  66 //
  67 // cty.DynamicPseudoType is, as usual, a special case. If the given type list
  68 // contains a mixture of dynamic and non-dynamic types, the dynamic types are
  69 // disregarded for type selection and a conversion is returned for them that
  70 // will attempt a late conversion of the given value to the target type,
  71 // failing with a conversion error if the eventual concrete type is not
  72 // compatible. If *all* given types are DynamicPseudoType, or in the
  73 // degenerate case of an empty slice of types, the returned type is itself
  74 // cty.DynamicPseudoType and no conversions are attempted.
  75 func Unify(types []cty.Type) (cty.Type, []Conversion) {
  76         return unify(types, false)
  77 }
  78
  79 // UnifyUnsafe is the same as Unify except that it may return unsafe
  80 // conversions in situations where a safe conversion isn't also available.
  81 func UnifyUnsafe(types []cty.Type) (cty.Type, []Conversion) {
  82         return unify(types, true)
  83 }