github.com/zclconf/go-cty

• convert: Will now produce correct type constraints when the input value is an empty collection and the target element type has optional attributes. In this case the conversion process must remove the optional attribute annotations because those are only for type conversion purposes and have no meaning when used in the type constraint for an empty collection. (#143)
• convert: Will now prefer to retain a concrete type in the input value when the input is either null or unknown and the target type is cty.DynamicPseudoType, which represents "any type". (#144)

• function: Each function can now have an English-language description summarizing its behavior. This is intended as a default string to use when an application wants to provide code hover tips or similar development aids. However, these descriptions are basic and only available in English, so applications may still prefer to provide their own descriptions and ignore those encoded in this module. (#137)

• convert: When running in "unsafe mode" (which allows additional conversions that can potentially fail with certain input values), we'll now allow converting from a map type to an object type with optional attributes as long as all of the present map elements are compatible with their corresponding optional attributes.

  It's still a dynamic error to convert a map whose element type is incompatible with any of the attributes that do have corresponding keys in the given map. (#139)

• convert: Will now produce correct type constraints when the input value is null and the target type has optional attributes. In this case the conversion process must remove the optional attribute annotations because those are only for type conversion purposes and have no meaning when used in the type constraint for a null or unknown value. (#140, #141)

• convert: Fix for error when converting empty sets and lists with nested optional attributes by explicitly removing optional attribute information from collections.

Upgrade Notes

This release contains some changes to some aspects of the API that are either legacy or de-facto internal (from before the Go toolchain had an explicit idea of that). Any external module using these will experience these as breaking changes, but we know of no such caller and so are admitting these without a major release in the interests of not creating churn for users of the main API.

• encoding/gob support utilities removed: we added these as a concession to HashiCorp who wanted to try to send cty values over some legacy protocols/formats used by legacy versions of HashiCorp Terraform. In the end those efforts were not successful for other reasons and so no Terraform release ever relied on this functionality.

  encoding/gob support has been burdensome due to how its unmarshaler interface is defined and so cty values and types are no longer automatically compatible with encoding/gob. Callers should instead use explicitly-implemented encodings, such as the built-in JSON and msgpack encodings or external libraries which use the public cty API to encode and decode.

• cty now requires Go 1.18: although the main API is not yet making any use of type parameters, we've begun to adopt it in the hope of improving the maintainability of some internal details, starting with the backing implementation of set types.

  Since type parameters are not supported by earlier versions of the Go compiler, callers must upgrade to Go 1.18 before using cty v1.11.0 or later.

Other changes in this release

• cty: Improved performance when comparing nonzero numbers to zero, by performing a relatively-cheap sign check on both numbers before falling back on the more expensive general equality implementation. (#125)
• cty: It's now possible to use capsule types in the elements of sets. Previously cty would panic if asked to construct a value of a set type whose element type either is or contains a capsule type, but there is now explicit support for storing encapsulated values in sets and optional (but recommended) support for a custom hashing function per type in order to improve performance for sets with a large number of elements.
• convert: Unify will no longer panic when asked to find a common base type for a tuple type and a list of unknown element type, and will instead just signal that such a unification is not possible. (#126)
• stdlib: FlattenFunc will no longer panic if it encounters a null value of a type that would normally be subject to flattening. Instead, it will treat it in the same way as a null value of any non-flattenable type. (#129)

• cty: The documented definition and comparison logic of cty.Number is now refined to acknowledge that its true range is limited only to values that have both a binary floating point and decimal representation, because cty values are primarily designed to traverse JSON serialization where numbers are always defined as decimal strings.

  In particular, that means that two cty.Number values now always compare as equal if their representation in JSON (under cty's own JSON encoder) would be equal, even though the decimal approximation we use for that conversion is slightly lossy. This pragmatic compromise avoids confusing situations where a round-trip through JSON serialization (or other serializations that use the same number format) may produce a value that doesn't compare equal to the original.

  This new definition of equals should not cause any significant behavior change for any integer in our in-memory storage range, but may cause some fractional values to compare equal where they didn't before if they differ only by a small fraction.

• cty: Don't panic in Value.Equals if comparing complex data structures with nested marked values. Instead, Equals will aggregate all of the marks on the resulting boolean value as we typically expect for operations that derived from marked values. (#112)

• cty: Value.AsBigFloat now properly isolates its result from the internal state of the associated value. It previously attempted to do this (so that modifying the result would not affect the supposedly-immutable cty.Number value) but ended up creating an object which still had some shared buffers. The result is now entirely separate from the internal state of the recieving value. (#114)

• function/stdlib: The FormatList function will now return an unknown value if any of the arguments have an unknown type, because in that case it can't tell whether that value will ultimately become a string or a list of strings, and thus it can't predict how many elements the result will have. (#115)

• cty: Don't panic in Value.Equals if comparing complex data structures with nested marked values. Instead, Equals will aggregate all of the marks on the resulting boolean value as we typically expect for operations that derived from marked values. (#112)
• cty: Value.AsBigFloat now properly isolates its result from the internal state of the associated value. It previously attempted to do this (so that modifying the result would not affect the supposedly-immutable cty.Number value) but ended up creating an object which still had some shared buffers. The result is now entirely separate from the internal state of the recieving value. (#114)
• function/stdlib: The FormatList function will now return an unknown value if any of the arguments have an unknown type, because in that case it can't tell whether that value will ultimately become a string or a list of strings, and thus it can't predict how many elements the result will have. (#115)

• cty: cty.Walk, cty.Transform, and cty.TransformWithTransformer now all correctly support marked values. Previously they would panic when encountering marked collections, because they would try to recurse into them without handling the markings.
• function/stdlib: The floor and ceil functions no longer lower the precision of arguments to what would fit inside a 64-bit float, instead preserving precision in a similar way as most other arithmetic functions. (#111)
• function/stdlib: The flatten function was incorrectly treating null values of an unknown type as if they were unknown values. Now it will treat them the same as any other non-list/non-tuple value, flattening them down into the result as-is. (#110)

• function/stdlib: The flatten function will now correctly return cty.DynamicVal if it encounters cty.DynamicVal anywhere in the given data structure, because it can't predict how many elements the result will have in that situation. (#106, #107)
• function/stdlib: The setproduct function will no longer panic when given a set containing unknown values, which would therefore be a set with an unknown length. (#109)

• function/stdlib: Fix a panic in SetproductFunc in situations where one of the input collections is empty. (#103)
• function/stdlib: Improvements to ElementFunc, ReverseListFunc, and SliceFunc to handle marked values more precisely (individual element vs. whole-collection marks). (#101)

• cty: Value.Mark will no longer incorrectly create nested markings when applied to a value that is already marked. Instead, it will unpack the reciever and use its underlying value directly, merging all of the marks into a new mark set. (#96)
• cty: Value.RawEquals will no longer panic if asked to compare two maps where at least one of them is marked. (#96)
• function/stdlib: Improvements to ChunklistFunc, ConcatFunc, FlattenFunc, KeysFunc, LengthFunc, LookupFunc, MergeFunc, SetproductFunc, ValuesFunc, and ZipmapFunc to handle marked values more precisely (individual element vs. whole-collection marks). (#94, #95, #96, #97, #98, #99, #100)