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.
var (
ErrNotAttributePathStepper = errors.New("doesn't fill tftypes.AttributePathStepper interface")
ErrInvalidStep = errors.New("step cannot be applied to this value")
)View Source
var (
DynamicPseudoType = primitive{}
String = primitive{}
Number = primitive{}
Bool = primitive{}
)
func ValidateValue(t Type, val interface{}) error
ValidateValue checks that the Go type passed as `val` can be used as a value for the Type passed as `t`. A nil error response indicates that the value is valid for the type.
Walk traverses a Value, calling the passed function for every element and attribute in the Value. The AttributePath passed to the callback function will identify which attribute or element is currently being surfaced by the Walk, and the passed Value will be the element or attribute at that AttributePath. Returning true from the callback function will indicate that any attributes or elements of the surfaced Value should be walked, too; returning false short-circuits the walk at that element or attribute, and does not visit any of its descendants. The return value of the callback does not matter when the Value that has been surfaced has no elements or attributes. Walk uses a depth-first traversal.
AttributeName is an AttributePathStep implementation that indicates the next step in the AttributePath is to select an attribute. The value of the AttributeName is the name of the attribute to be selected.
Equal returns true if the other AttributePathStep is an AttributeName and has the same value.
type AttributePath struct {
}
AttributePath is a type that can point to a specific value within an aggregate Terraform value. It consists of steps, each identifying one element or attribute of the current value, and making that the current value. This allows referring to arbitrarily precise values.
NewAttributePath returns an empty AttributePath, ready to have steps added to it using WithElementKeyString, WithElementKeyInt, WithElementKeyValue, or WithAttributeName.
NewAttributePathWithSteps returns an AttributePath populated with the passed AttributePathSteps.
WalkAttributePath will return the Type or Value that `path` is pointing to, using `in` as the root. If an error is returned, the AttributePath returned will indicate the steps that remained to be applied when the error was encountered.
map[string]interface{} and []interface{} types have built-in support. Other types need to use the AttributePathStepper interface to tell WalkAttributePath how to traverse themselves.
Equal returns true if two AttributePaths should be considered equal. AttributePaths are considered equal if they have the same number of steps, the steps are all the same types, and the steps have all the same values.
LastStep returns the last step in the path. If the path is nil or empty, nil is returned.
NewError returns an error that associates `err` with the value indicated by `a`.
NewErrorf returns an error associated with the value indicated by `a`. This is equivalent to calling a.NewError(fmt.Errorf(f, args...)).
NextStep returns the next step in the path. If the path is nil or empty, nil is returned.
Steps returns the AttributePathSteps that make up an AttributePath.
WithAttributeName adds an AttributeName step to `a`, using `name` as the attribute's name. `a` is copied, not modified.
WithElementKeyInt adds an ElementKeyInt step to `a`, using `key` as the element's key. `a` is copied, not modified.
WithElementKeyString adds an ElementKeyString step to `a`, using `key` as the element's key. `a` is copied, not modified.
WithElementKeyValue adds an ElementKeyValue to `a`, using `key` as the element's key. `a` is copied, not modified.
WithoutLastStep removes the last step, whatever kind of step it was, from `a`. `a` is copied, not modified.
AttributePathError represents an error associated with part of a tftypes.Value, indicated by the Path property.
Equal returns true if two AttributePathErrors are semantically equal. To be considered equal, they must have the same path and if errors are set, the strings returned by their `Error()` methods must match.
AttributePathStep is an intentionally unimplementable interface that functions as an enum, allowing us to use different strongly-typed step types as a generic "step" type.
An AttributePathStep is meant to indicate a single step in an AttributePath, indicating a specific attribute or element that is the next value in the path.
type AttributePathStepper interface {
ApplyTerraform5AttributePathStep(AttributePathStep) (interface{}, error)
}
AttributePathStepper is an interface that types can implement to make them traversable by WalkAttributePath, allowing providers to retrieve the specific value an AttributePath is pointing to.
ElementKeyInt is an AttributePathStep implementation that indicates the next step in the AttributePath is to select an element using an int64 key. The value of the ElementKeyInt is the key of the element to select.
Equal returns true if the other AttributePathStep is an ElementKeyInt and has the same value.
ElementKeyString is an AttributePathStep implementation that indicates the next step in the AttributePath is to select an element using a string key. The value of the ElementKeyString is the key of the element to select.
Equal returns true if the other AttributePathStep is an ElementKeyString and has the same value.
type ElementKeyValue Value
ElementKeyValue is an AttributePathStep implementation that indicates the next step in the AttributePath is to select an element using the element itself as a key. The value of the ElementKeyValue is the key of the element to select.
Equal returns true if the other AttributePathStep is an ElementKeyValue and has the same value.
type List struct {
ElementType Type
}
List is a Terraform type representing an ordered collection of elements, all of the same type.
ApplyTerraform5AttributePathStep applies an AttributePathStep to a List, returning the Type found at that AttributePath within the List. If the AttributePathStep cannot be applied to the List, an ErrInvalidStep error will be returned.
Equal returns true if the two Lists are exactly equal. Unlike Is, passing in a List with no ElementType will always return false.
Is returns whether `t` is a List type or not. It does not perform any ElementType checks.
MarshalJSON returns a JSON representation of the full type signature of `l`, including its ElementType.
Deprecated: this is not meant to be called by third-party code.
UsableAs returns whether the two Lists are type compatible.
If the other type is DynamicPseudoType, it will return true. If the other type is not a List, it will return false. If the other List does not have a type compatible ElementType, it will return false.
type Map struct {
ElementType Type
}
Map is a Terraform type representing an unordered collection of elements, all of the same type, each identifiable with a unique string key.
ApplyTerraform5AttributePathStep applies an AttributePathStep to a Map, returning the Type found at that AttributePath within the Map. If the AttributePathStep cannot be applied to the Map, an ErrInvalidStep error will be returned.
Equal returns true if the two Maps are exactly equal. Unlike Is, passing in a Map with no ElementType will always return false.
Is returns whether `t` is a Map type or not. It does not perform any ElementType checks.
MarshalJSON returns a JSON representation of the full type signature of `m`, including its ElementType.
Deprecated: this is not meant to be called by third-party code.
UsableAs returns whether the two Maps are type compatible.
If the other type is DynamicPseudoType, it will return true. If the other type is not a Map, it will return false. If the other Map does not have a type compatible ElementType, it will return false.
type Object struct {
AttributeTypes map[string]Type
OptionalAttributes map[string]struct{}
}
Object is a Terraform type representing an unordered collection of attributes, potentially of differing types, each identifiable with a unique string name. The number of attributes, their names, and their types are part of the type signature for the Object, and so two Objects with different attribute names or types are considered to be distinct types.
ApplyTerraform5AttributePathStep applies an AttributePathStep to an Object, returning the Type found at that AttributePath within the Object. If the AttributePathStep cannot be applied to the Object, an ErrInvalidStep error will be returned.
Equal returns true if the two Objects are exactly equal. Unlike Is, passing in an Object with no AttributeTypes will always return false.
Is returns whether `t` is an Object type or not. It does not perform any AttributeTypes checks.
MarshalJSON returns a JSON representation of the full type signature of `o`, including the AttributeTypes and, if present, OptionalAttributes.
Deprecated: this is not meant to be called by third-party code.
UsableAs returns whether the two Objects are type compatible.
If the other type is DynamicPseudoType, it will return true. If the other type is not a Object, it will return false. If the other Object does not have matching AttributeTypes length, it will return false. If the other Object does not have a type compatible ElementType for every nested attribute, it will return false.
If the current type contains OptionalAttributes, it will panic.
type Set struct {
ElementType Type
}
Set is a Terraform type representing an unordered collection of unique elements, all of the same type.
ApplyTerraform5AttributePathStep applies an AttributePathStep to a Set, returning the Type found at that AttributePath within the Set. If the AttributePathStep cannot be applied to the Set, an ErrInvalidStep error will be returned.
Equal returns true if the two Sets are exactly equal. Unlike Is, passing in a Set with no ElementType will always return false.
Is returns whether `t` is a Set type or not. It does not perform any ElementType checks.
MarshalJSON returns a JSON representation of the full type signature of `s`, including its ElementType.
Deprecated: this is not meant to be called by third-party code.
UsableAs returns whether the two Sets are type compatible.
If the other type is DynamicPseudoType, it will return true. If the other type is not a Set, it will return false. If the other Set does not have a type compatible ElementType, it will return false.
type Tuple struct {
ElementTypes []Type
}
Tuple is a Terraform type representing an ordered collection of elements, potentially of differing types. The number of elements and their types are part of the type signature for the Tuple, and so two Tuples with different numbers or types of elements are considered to be distinct types.
ApplyTerraform5AttributePathStep applies an AttributePathStep to a Tuple, returning the Type found at that AttributePath within the Tuple. If the AttributePathStep cannot be applied to the Tuple, an ErrInvalidStep error will be returned.
Equal returns true if the two Tuples are exactly equal. Unlike Is, passing in a Tuple with no ElementTypes will always return false.
Is returns whether `t` is a Tuple type or not. It does not perform any ElementTypes checks.
MarshalJSON returns a JSON representation of the full type signature of `tu`, including the ElementTypes.
Deprecated: this is not meant to be called by third-party code.
UsableAs returns whether the two Tuples are type compatible.
If the other type is DynamicPseudoType, it will return true. If the other type is not a Tuple, it will return false. If the other Tuple does not have matching ElementTypes length, it will return false. If the other Tuple does not have type compatible ElementTypes in each position, it will return false.
Type is an interface representing a Terraform type. It is only meant to be implemented by the tftypes package. Types define the shape and characteristics of data coming from or being sent to Terraform.
ParseJSONType returns a Type from its JSON representation. The JSON representation should come from Terraform or from MarshalJSON as the format is not part of this package's API guarantees.
Deprecated: this is not meant to be called by third-party code.
TypeFromElements returns the common type that the passed elements all have in common. An error will be returned if the passed elements are not of the same type.
Value is a piece of data from Terraform or being returned to Terraform. It has a Type associated with it, defining its shape and characteristics, and a Go representation of that Type containing the data itself. Values are a special type and are not represented as pure Go values beause they can contain UnknownValues, which cannot be losslessly represented in Go's type system.
The recommended usage of a Value is to check that it is known, using Value.IsKnown, then to convert it to a Go type, using Value.As. The Go type can then be manipulated.
NewValue returns a Value constructed using the specified Type and stores the passed value in it.
The passed value should be in one of the builtin Value representations or implement the ValueCreator interface.
If the passed value is not a valid value for the passed type, NewValue will panic. Any value and type combination that does not return an error from ValidateValue is guaranteed to not panic. When calling NewValue with user input with a type not known at compile time, it is recommended to call ValidateValue before calling NewValue, to allow graceful handling of the error.
The builtin Value representations are:
Transform uses a callback to mutate a Value. Each element or attribute will be visited in turn, with the AttributePath and Value surfaced to the callback, as in Walk. Unlike in Walk, the callback returns a Value instead of a boolean; this is the Value that will be stored at that AttributePath. The callback must return the passed Value unmodified if it wishes to not mutate a Value. Elements and attributes of a Value will be passed to the callback prior to the Value they belong to being passed to the callback, which means a callback can overwrite its own modifications. Values passed to the callback will always reflect the results of earlier callback calls.
ValueFromJSON returns a Value from the JSON-encoded bytes, using the provided Type to determine what shape the Value should be. DynamicPseudoTypes will be transparently parsed into the types they represent.
Deprecated: this function is exported for internal use in terraform-plugin-go. Third parties should not use it, and its behavior is not covered under the API compatibility guarantees. Don't use this.
ValueFromJSONWithOpts is identical to ValueFromJSON with the exception that it accepts ValueFromJSONOpts which can be used to modify the unmarshalling behaviour, such as ignoring undefined attributes, for instance. This can occur when the JSON being unmarshalled does not have a corresponding attribute in the schema.
ValueFromMsgPack returns a Value from the MsgPack-encoded bytes, using the provided Type to determine what shape the Value should be. DynamicPseudoTypes will be transparently parsed into the types they represent.
Deprecated: this function is exported for internal use in terraform-plugin-go. Third parties should not use it, and its behavior is not covered under the API compatibility guarantees. Don't use this.
ApplyTerraform5AttributePathStep applies an AttributePathStep to a Value, returning the Value found at that AttributePath within the Value. It fulfills that AttributePathStepper interface, allowing Values to be passed to WalkAttributePath. This allows retrieving a subset of a Value using an AttributePath. If the AttributePathStep can't be applied to the Value, either because it is the wrong type or because no Value exists at that AttributePathStep, an ErrInvalidStep error will be returned.
As converts a Value into a Go value. `dst` must be set to a pointer to a value of a supported type for the Value's type or an implementation of the ValueConverter interface.
For Strings, `dst` must be a pointer to a string or a pointer to a pointer to a string. If it's a pointer to a pointer to a string, if the Value is null, the pointer to the string will be set to nil. If it's a pointer to a string, if the Value is null, the string will be set to the empty value.
For Numbers, `dst` must be a poitner to a big.Float or a pointer to a pointer to a big.Float. If it's a pointer to a pointer to a big.Float, if the Value is null, the pointer to the big.Float will be set to nil. If it's a pointer to a big.Float, if the Value is null, the big.Float will be set to 0.
For Bools, `dst` must be a pointer to a bool or a pointer to a pointer to a bool. If it's a pointer to a pointer to a bool, if the Value is null, the pointer to the bool will be set to nil. If it's a pointer to a bool, if the Value is null, the bool will be set to false.
For Maps and Objects, `dst` must be a pointer to a map[string]Value or a pointer to a pointer to a map[string]Value. If it's a pointer to a pointer to a map[string]Value, if the Value is null, the pointer to the map[string]Value will be set to nil. If it's a pointer to a map[string]Value, if the Value is null, the map[string]Value will be set to an empty map.
For Lists, Sets, and Tuples, `dst` must be a pointer to a []Value or a pointer to a pointer to a []Value. If it's a pointer to a pointer to a []Value, if the Value is null, the poitner to []Value will be set to nil. If it's a pointer to a []Value, if the Value is null, the []Value will be set to an empty slice.
Future builtin conversions may be added over time.
If `val` is unknown, an error will be returned, as unknown values can't be represented in Go's type system. Providers should check Value.IsKnown before calling Value.As.
package main
import (
"fmt"
"github.com/hashicorp/terraform-plugin-go/tftypes"
)
type exampleResource struct {
name string
suppliedName *bool
}
// fill the tftypes.ValueConverter interface to control how As works
// we want a pointer to exampleResource so we can change the properties
func (e *exampleResource) FromTerraform5Value(val tftypes.Value) error {
v := map[string]tftypes.Value{}
err := val.As(&v)
if err != nil {
return err
}
err = v["name"].As(&e.name)
if err != nil {
return err
}
err = v["supplied_name"].As(&e.suppliedName)
if err != nil {
return err
}
return nil
}
func main() {
// our tftypes.Value would usually come over the wire as a
// DynamicValue, but for simplicity, let's just declare one inline here
val := tftypes.NewValue(tftypes.Object{
AttributeTypes: map[string]tftypes.Type{
"name": tftypes.String,
"supplied_name": tftypes.Bool,
},
}, map[string]tftypes.Value{
"name": tftypes.NewValue(tftypes.String, "ozymandias"),
"supplied_name": tftypes.NewValue(tftypes.Bool, nil),
})
// exampleResource has FromTerraform5Value method defined on it, see
// value_example_test.go for implementation details. We'd put the
// function and type inline here, but apparently Go can't have methods
// defined on types defined inside a function
var res exampleResource
// call As as usual
err := val.As(&res)
if err != nil {
panic(err)
}
fmt.Println(res.name)
fmt.Println(res.suppliedName)
}
Output: ozymandias <nil>
package main
import (
"fmt"
"github.com/hashicorp/terraform-plugin-go/tftypes"
)
func main() {
// Values come over the wire, usually from a DynamicValue for this
// example, we're just building one inline
val := tftypes.NewValue(tftypes.String, "hello, world")
var salutation string
// we need to use a pointer so we can modify the value, just like
// json.Unmarshal
err := val.As(&salutation)
if err != nil {
panic(err)
}
fmt.Println(salutation)
}
Output: hello, world
package main
import (
"fmt"
"github.com/hashicorp/terraform-plugin-go/tftypes"
)
func main() {
type exampleResource struct {
salutation string
nullableSalutation *string
}
// let's see what happens when we have a null value
val := tftypes.NewValue(tftypes.String, nil)
var res exampleResource
// we can use a pointer to a variable, but the variable can't hold nil,
// so we'll get the empty value. You can use this if you don't care
// about null, and consider it equivalent to the empty value.
err := val.As(&res.salutation)
if err != nil {
panic(err)
}
// we can use a pointer to a pointer to a variable, which can hold nil,
// so we'll be able to distinguish between a null and an empty string
err = val.As(&res.nullableSalutation)
if err != nil {
panic(err)
}
fmt.Println(res.salutation)
fmt.Println(res.nullableSalutation)
}
Output: <nil>
Copy returns a defensively-copied clone of Value that shares no underlying data structures with the original Value and can be mutated without accidentally mutating the original.
Diff computes the differences between `val1` and `val2` and surfaces them as a slice of ValueDiffs. The ValueDiffs in the struct will use `val1`'s values as Value1 and `val2`'s values as Value2. An empty or nil slice means the two Values can be considered equal. Values must be the same type when passed to Diff; passing in Values of two different types will result in an error. If both Values are empty, they are considered equal. If one Value is missing type, it will result in an error. val1.Type().Is(val2.Type()) is a safe way to check that Values can be compared with Diff.
Equal returns true if two Values should be considered equal. Values are considered equal if their types are considered equal and if they represent data that is considered equal.
IsFullyKnown returns true if `val` is known. If `val` is an aggregate type, IsFullyKnown only returns true if all elements and attributes are known, as well.
IsKnown returns true if `val` is known. If `val` is an aggregate type, only the top level of the aggregate type is checked; elements and attributes are not checked.
IsNull returns true if the Value is null.
MarshalMsgPack returns a msgpack representation of the Value. This is used for constructing tfprotov5.DynamicValues.
Deprecated: this is not meant to be called by third parties. Don't use it.
Type returns the Type of the Value.
type ValueConverter interface {
FromTerraform5Value(Value) error
}
ValueConverter is an interface that provider-defined types can implement to control how Value.As will convert a Value into that type. The passed Value is the Value that Value.As is being called on. The intended usage is to call Value.As on the passed Value, converting it into a builtin type, and then converting or casting that builtin type to the provider-defined type.
type ValueCreator interface {
ToTerraform5Value() (interface{}, error)
}
ValueCreator is an interface that provider-defined types can implement to control how NewValue will convert that type into a Value. The returned interface should return one of the builtin Value representations that should be used for that Value.
ValueDiff expresses a subset of a Value that is different between two Values. The Path property indicates where the subset is located within the Value, and Value1 and Value2 indicate what the subset is in each of the Values. If the Value does not contain a subset at that AttributePath, its Value will be nil. This is distinct from a Value with a nil in it (a "null" value), which is present in the Value.
Equal returns whether two ValueDiffs should be considered equal or not. ValueDiffs are consisdered equal when their Path, Value1, and Value2 properties are considered equal.
type ValueFromJSONOpts struct {
IgnoreUndefinedAttributes bool
}
ValueFromJSONOpts contains options that can be used to modify the behaviour when unmarshalling JSON.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4