Documentation
¶
Overview ¶
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.
Index ¶
- Constants
- Variables
- func ValidateValue(t Type, val interface{}) error
- func Walk(val Value, cb func(*AttributePath, Value) (bool, error)) error
- type AttributeName
- type AttributePath
- func (a *AttributePath) Equal(o *AttributePath) bool
- func (a *AttributePath) LastStep() AttributePathStep
- func (a *AttributePath) NewError(err error) error
- func (a *AttributePath) NewErrorf(f string, args ...interface{}) error
- func (a *AttributePath) NextStep() AttributePathStep
- func (a *AttributePath) Steps() []AttributePathStep
- func (a *AttributePath) String() string
- func (a *AttributePath) WithAttributeName(name string) *AttributePath
- func (a *AttributePath) WithElementKeyInt(key int) *AttributePath
- func (a *AttributePath) WithElementKeyString(key string) *AttributePath
- func (a *AttributePath) WithElementKeyValue(key Value) *AttributePath
- func (a *AttributePath) WithoutLastStep() *AttributePath
- type AttributePathError
- type AttributePathStep
- type AttributePathStepper
- type ElementKeyInt
- type ElementKeyString
- type ElementKeyValue
- type List
- type Map
- type Object
- type Set
- type Tuple
- type Type
- type Value
- func NewValue(t Type, val interface{}) Value
- func Transform(val Value, cb func(*AttributePath, Value) (Value, error)) (Value, error)
- func ValueFromJSON(data []byte, typ Type) (Value, error)deprecated
- func ValueFromJSONWithOpts(data []byte, typ Type, opts ValueFromJSONOpts) (Value, error)
- func ValueFromMsgPack(data []byte, typ Type) (Value, error)deprecated
- func (val Value) ApplyTerraform5AttributePathStep(step AttributePathStep) (interface{}, error)
- func (val Value) As(dst interface{}) error
- func (val Value) Copy() Value
- func (val1 Value) Diff(val2 Value) ([]ValueDiff, error)
- func (val Value) Equal(o Value) bool
- func (val Value) IsFullyKnown() bool
- func (val Value) IsKnown() bool
- func (val Value) IsNull() bool
- func (val Value) MarshalMsgPack(t Type) ([]byte, error)deprecated
- func (val Value) String() string
- func (val Value) Type() Type
- type ValueConverter
- type ValueCreator
- type ValueDiff
- type ValueFromJSONOpts
Examples ¶
Constants ¶
const ( // UnknownValue represents a value that is not yet known. It can be the // value of any type. UnknownValue = unknown(0) )
Variables ¶
var ( // ErrNotAttributePathStepper is returned when a type that doesn't full // the AttributePathStepper interface is passed to WalkAttributePath. ErrNotAttributePathStepper = errors.New("doesn't fill tftypes.AttributePathStepper interface") // ErrInvalidStep is returned when an AttributePath has the wrong kind // of AttributePathStep for the type that WalkAttributePath is // operating on. ErrInvalidStep = errors.New("step cannot be applied to this value") )
var ( // DynamicPseudoType is a pseudo-type in Terraform's type system that // is used as a wildcard type. It indicates that any Terraform type can // be used. DynamicPseudoType = primitive{/* contains filtered or unexported fields */} // String is a primitive type in Terraform that represents a UTF-8 // string of bytes. String = primitive{/* contains filtered or unexported fields */} // Number is a primitive type in Terraform that represents a real // number. Number = primitive{/* contains filtered or unexported fields */} // Bool is a primitive type in Terraform that represents a true or // false boolean value. Bool = primitive{/* contains filtered or unexported fields */} )
Functions ¶
func ValidateValue ¶
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.
func Walk ¶
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.
Types ¶
type AttributeName ¶
type AttributeName string
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.
func (AttributeName) Equal ¶ added in v0.5.0
func (a AttributeName) Equal(other AttributePathStep) bool
Equal returns true if the other AttributePathStep is an AttributeName and has the same value.
type AttributePath ¶
type AttributePath struct {
// contains filtered or unexported fields
}
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.
func NewAttributePath ¶
func NewAttributePath() *AttributePath
NewAttributePath returns an empty AttributePath, ready to have steps added to it using WithElementKeyString, WithElementKeyInt, WithElementKeyValue, or WithAttributeName.
func NewAttributePathWithSteps ¶
func NewAttributePathWithSteps(steps []AttributePathStep) *AttributePath
NewAttributePathWithSteps returns an AttributePath populated with the passed AttributePathSteps.
func WalkAttributePath ¶
func WalkAttributePath(in interface{}, path *AttributePath) (interface{}, *AttributePath, error)
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.
func (*AttributePath) Equal ¶
func (a *AttributePath) Equal(o *AttributePath) bool
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.
func (*AttributePath) LastStep ¶ added in v0.5.0
func (a *AttributePath) LastStep() AttributePathStep
LastStep returns the last step in the path. If the path is nil or empty, nil is returned.
func (*AttributePath) NewError ¶
func (a *AttributePath) NewError(err error) error
NewError returns an error that associates `err` with the value indicated by `a`.
func (*AttributePath) NewErrorf ¶
func (a *AttributePath) NewErrorf(f string, args ...interface{}) error
NewErrorf returns an error associated with the value indicated by `a`. This is equivalent to calling a.NewError(fmt.Errorf(f, args...)).
func (*AttributePath) NextStep ¶ added in v0.18.0
func (a *AttributePath) NextStep() AttributePathStep
NextStep returns the next step in the path. If the path is nil or empty, nil is returned.
func (*AttributePath) Steps ¶
func (a *AttributePath) Steps() []AttributePathStep
Steps returns the AttributePathSteps that make up an AttributePath.
func (*AttributePath) String ¶
func (a *AttributePath) String() string
func (*AttributePath) WithAttributeName ¶
func (a *AttributePath) WithAttributeName(name string) *AttributePath
WithAttributeName adds an AttributeName step to `a`, using `name` as the attribute's name. `a` is copied, not modified.
func (*AttributePath) WithElementKeyInt ¶
func (a *AttributePath) WithElementKeyInt(key int) *AttributePath
WithElementKeyInt adds an ElementKeyInt step to `a`, using `key` as the element's key. `a` is copied, not modified.
func (*AttributePath) WithElementKeyString ¶
func (a *AttributePath) WithElementKeyString(key string) *AttributePath
WithElementKeyString adds an ElementKeyString step to `a`, using `key` as the element's key. `a` is copied, not modified.
func (*AttributePath) WithElementKeyValue ¶
func (a *AttributePath) WithElementKeyValue(key Value) *AttributePath
WithElementKeyValue adds an ElementKeyValue to `a`, using `key` as the element's key. `a` is copied, not modified.
func (*AttributePath) WithoutLastStep ¶
func (a *AttributePath) WithoutLastStep() *AttributePath
WithoutLastStep removes the last step, whatever kind of step it was, from `a`. `a` is copied, not modified.
type AttributePathError ¶
type AttributePathError struct {
Path *AttributePath
// contains filtered or unexported fields
}
AttributePathError represents an error associated with part of a tftypes.Value, indicated by the Path property.
func (AttributePathError) Equal ¶ added in v0.4.0
func (a AttributePathError) Equal(o AttributePathError) bool
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.
func (AttributePathError) Error ¶
func (a AttributePathError) Error() string
func (AttributePathError) Unwrap ¶
func (a AttributePathError) Unwrap() error
type AttributePathStep ¶
type AttributePathStep interface {
// Equal returns true if the AttributePathStep is equal to the other.
Equal(AttributePathStep) bool
// contains filtered or unexported methods
}
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 ¶
type AttributePathStepper interface {
// Return the attribute or element the AttributePathStep is referring
// to, or an error if the AttributePathStep is referring to an
// attribute or element that doesn't exist.
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.
type ElementKeyInt ¶
type ElementKeyInt int64
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.
func (ElementKeyInt) Equal ¶ added in v0.5.0
func (e ElementKeyInt) Equal(other AttributePathStep) bool
Equal returns true if the other AttributePathStep is an ElementKeyInt and has the same value.
type ElementKeyString ¶
type ElementKeyString string
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.
func (ElementKeyString) Equal ¶ added in v0.5.0
func (e ElementKeyString) Equal(other AttributePathStep) bool
Equal returns true if the other AttributePathStep is an ElementKeyString and has the same value.
type ElementKeyValue ¶
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.
func (ElementKeyValue) Equal ¶ added in v0.5.0
func (e ElementKeyValue) Equal(other AttributePathStep) bool
Equal returns true if the other AttributePathStep is an ElementKeyValue and has the same value.
type List ¶
type List struct {
ElementType Type
// contains filtered or unexported fields
}
List is a Terraform type representing an ordered collection of elements, all of the same type.
func (List) ApplyTerraform5AttributePathStep ¶ added in v0.9.0
func (l List) ApplyTerraform5AttributePathStep(step AttributePathStep) (interface{}, error)
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.
func (List) Equal ¶
Equal returns true if the two Lists are exactly equal. Unlike Is, passing in a List with no ElementType will always return false.
func (List) Is ¶
Is returns whether `t` is a List type or not. It does not perform any ElementType checks.
func (List) MarshalJSON
deprecated
type Map ¶
type Map struct {
ElementType Type
// contains filtered or unexported fields
}
Map is a Terraform type representing an unordered collection of elements, all of the same type, each identifiable with a unique string key.
func (Map) ApplyTerraform5AttributePathStep ¶ added in v0.9.0
func (m Map) ApplyTerraform5AttributePathStep(step AttributePathStep) (interface{}, error)
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.
func (Map) Equal ¶
Equal returns true if the two Maps are exactly equal. Unlike Is, passing in a Map with no ElementType will always return false.
func (Map) Is ¶
Is returns whether `t` is a Map type or not. It does not perform any ElementType checks.
func (Map) MarshalJSON
deprecated
type Object ¶
type Object struct {
// AttributeTypes is a map of attributes to their types. The key should
// be the name of the attribute, and the value should be the type of
// the attribute.
AttributeTypes map[string]Type
// OptionalAttributes is a set of attributes that are optional. This
// allows values of this object type to include or not include those
// attributes without changing the type of the value; other attributes
// are considered part of the type signature, and their absence means a
// value is no longer of that type.
//
// OptionalAttributes is only valid when declaring a type constraint
// (e.g. Schema) and should not be used as part of a Type when creating
// a Value (e.g. NewValue()). When creating a Value, all OptionalAttributes
// must still be defined in the Object by setting each attribute to a null
// or known value for its attribute type.
//
// The key of OptionalAttributes should be the name of the attribute
// that is optional. The value should be an empty struct, used only to
// indicate presence.
//
// OptionalAttributes must also be listed in the AttributeTypes
// property, indicating their types.
OptionalAttributes map[string]struct{}
// contains filtered or unexported fields
}
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.
func (Object) ApplyTerraform5AttributePathStep ¶ added in v0.9.0
func (o Object) ApplyTerraform5AttributePathStep(step AttributePathStep) (interface{}, error)
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.
func (Object) Equal ¶
Equal returns true if the two Objects are exactly equal. Unlike Is, passing in an Object with no AttributeTypes will always return false.
func (Object) Is ¶
Is returns whether `t` is an Object type or not. It does not perform any AttributeTypes checks.
func (Object) MarshalJSON
deprecated
func (Object) UsableAs ¶ added in v0.4.0
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 ¶
type Set struct {
ElementType Type
// contains filtered or unexported fields
}
Set is a Terraform type representing an unordered collection of unique elements, all of the same type.
func (Set) ApplyTerraform5AttributePathStep ¶ added in v0.9.0
func (s Set) ApplyTerraform5AttributePathStep(step AttributePathStep) (interface{}, error)
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.
func (Set) Equal ¶
Equal returns true if the two Sets are exactly equal. Unlike Is, passing in a Set with no ElementType will always return false.
func (Set) Is ¶
Is returns whether `t` is a Set type or not. It does not perform any ElementType checks.
func (Set) MarshalJSON
deprecated
type Tuple ¶
type Tuple struct {
ElementTypes []Type
// contains filtered or unexported fields
}
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.
func (Tuple) ApplyTerraform5AttributePathStep ¶ added in v0.9.0
func (tu Tuple) ApplyTerraform5AttributePathStep(step AttributePathStep) (interface{}, error)
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.
func (Tuple) Equal ¶
Equal returns true if the two Tuples are exactly equal. Unlike Is, passing in a Tuple with no ElementTypes will always return false.
func (Tuple) Is ¶
Is returns whether `t` is a Tuple type or not. It does not perform any ElementTypes checks.
func (Tuple) MarshalJSON
deprecated
func (Tuple) UsableAs ¶ added in v0.4.0
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 Type ¶
type Type interface {
// AttributePathStepper requires each Type to implement the
// ApplyTerraform5AttributePathStep method, so Type is compatible with
// WalkAttributePath. The method should return the Type found at that
// AttributePath within the Type or ErrInvalidStep.
AttributePathStepper
// Is performs shallow type equality checks, in that the root type is
// compared, but underlying attribute/element types are not.
Is(Type) bool
// Equal performs deep type equality checks, including attribute/element
// types and whether attributes are optional or not.
Equal(Type) bool
// UsableAs performs type conformance checks. This primarily checks if the
// target implements DynamicPsuedoType in a compatible manner.
UsableAs(Type) bool
// String returns a string representation of the Type's name.
String() string
// MarshalJSON returns a JSON representation of the Type's signature.
// It is modeled based on Terraform's requirements for type signature
// JSON representations, and may change over time to match Terraform's
// formatting. The error return should always be nil.
//
// Deprecated: this is not meant to be called by third-party code.
MarshalJSON() ([]byte, error)
// contains filtered or unexported methods
}
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.
func ParseJSONType
deprecated
func TypeFromElements ¶
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.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
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.
func NewValue ¶
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:
- String: string, *string
- Number: *big.Float, int64, *int64, int32, *int32, int16, *int16, int8, *int8, int, *int, uint64, *uint64, uint32, *uint32, uint16, *uint16, uint8, *uint8, uint, *uint, float64, *float64
- Bool: bool, *bool
- Map and Object: map[string]Value
- Tuple, List, and Set: []Value
func Transform ¶
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.
func ValueFromJSON
deprecated
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.
func ValueFromJSONWithOpts ¶ added in v0.13.0
func ValueFromJSONWithOpts(data []byte, typ Type, opts ValueFromJSONOpts) (Value, error)
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.
func ValueFromMsgPack
deprecated
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.
func (Value) ApplyTerraform5AttributePathStep ¶
func (val Value) ApplyTerraform5AttributePathStep(step AttributePathStep) (interface{}, error)
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.
func (Value) As ¶
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.
Example (Interface) ¶
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>
Example (String) ¶
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
Example (StringNull) ¶
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>
func (Value) Copy ¶
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.
func (Value) Diff ¶
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.
func (Value) Equal ¶
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.
func (Value) IsFullyKnown ¶
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.
func (Value) IsKnown ¶
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.
func (Value) MarshalMsgPack
deprecated
type ValueConverter ¶
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 ¶
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.
type ValueDiff ¶
type ValueDiff struct {
// The Path these different subsets are located at in the original
// Values.
Path *AttributePath
// The subset of the first Value passed to Diff found at the
// AttributePath indicated by Path.
Value1 *Value
// The subset of the second Value passed to Diff found at the
// AttributePath indicated by Path.
Value2 *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.
type ValueFromJSONOpts ¶ added in v0.13.0
type ValueFromJSONOpts struct {
// IgnoreUndefinedAttributes is used to ignore any attributes which appear in the
// JSON but do not have a corresponding entry in the schema. For example, raw state
// where an attribute has been removed from the schema.
IgnoreUndefinedAttributes bool
}
ValueFromJSONOpts contains options that can be used to modify the behaviour when unmarshalling JSON.
Source Files