Add package doc for tftypes

Author: Paddy Carver

tfprotov5/tftypes/doc.go

@@ -0,0 +1,53 @@
+// Package tftypes provides a type system for Terraform configuration and state
+// values.
+//
+// Terraform's configuration and state values are stored using a collection of
+// types. There are primitive types, such as strings, numbers, and booleans,
+// but there are also aggregate types such as lists, sets, tuples, maps, and
+// objects, which consist of multiple values of primitive types aggregated into
+// a single value. There is also a dynamic pseudo-type that represents an
+// unknown type. It is useful for indicating that any type of data is
+// acceptable.
+//
+// Terraform's values map neatly onto either primitives built into Go or types
+// in the Go standard library, with one exception. Terraform has the concept of
+// unknown values, values that may or may not be set at a future date. These
+// are distinct from null values, which indicate a value that is known to not
+// be set, and are mostly encountered when a user has interpolated a computed
+// field into another field; the field that is interpolated into has an unknown
+// value, because the field being interpolated won't have its value known until
+// apply time.
+//
+// To address this, the tftypes package wraps all values in a special Value
+// type. This Value type is capable of holding known and unknown values,
+// interrogating whether the value is known or not, and accessing the concrete
+// value that Terraform sent in the cases where the value is known. A common
+// pattern is to use the Value.IsKnown() method to confirm that a value is
+// known, then to use the Value.As() method to retrieve the underlying data for
+// use.
+//
+// When using the Value.As() method, certain types have built-in behavior to
+// support using them as destinations for converted data:
+//
+// * String values can be converted into strings
+// * Number values can be converted into *big.Floats
+// * Boolean values can be converted into bools
+// * List, Set, and Tuple values can be converted into a slice of Values
+// * Map and Object values can be converted into a map with string keys and
+//   Value values.
+//
+// These defaults were chosen because they're capable of losslessly
+// representing all possible values for their Terraform type, with the
+// exception of null values. Converting into pointer versions of any of these
+// types will correctly surface null values as well.
+//
+// Custom, provider-defined types can define their own conversion logic that
+// will be respected by Value.As(), as well, by implementing the
+// FromTerraform5Value method for that type. The FromTerraform5Value method
+// accepts a Value as an argument and returns an error. The Value passed in
+// will be the same Value that Value.As() was called on. The recommended
+// implementation of the FromTerraform5Value method is to call Value.As() on
+// the passed Value, converting it into one of the built-in types above, and
+// then performing whatever type casting or conversion logic is required to
+// assign the data to the provider-supplied type.
+package tftypes