tftypes

package
Version: v0.9.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 12, 2022 License: MPL-2.0 Imports: 11 Imported by: 23

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

Examples

Constants

View Source
const (
	// UnknownValue represents a value that is not yet known. It can be the
	// value of any type.
	UnknownValue = unknown(0)
)

Variables

View Source
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")
)
View Source
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

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.

func Walk

func Walk(val Value, cb func(*AttributePath, Value) (bool, error)) error

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 was 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) 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

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

func (l List) Equal(o Type) bool

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

func (l List) Is(t Type) bool

Is returns whether `t` is a List type or not. It does not perform any ElementType checks.

func (List) MarshalJSON deprecated

func (l List) MarshalJSON() ([]byte, error)

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.

func (List) String

func (l List) String() string

func (List) UsableAs added in v0.4.0

func (l List) UsableAs(o Type) bool

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

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

func (m Map) Equal(o Type) bool

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

func (m Map) Is(t Type) bool

Is returns whether `t` is a Map type or not. It does not perform any ElementType checks.

func (Map) MarshalJSON deprecated

func (m Map) MarshalJSON() ([]byte, error)

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.

func (Map) String

func (m Map) String() string

func (Map) UsableAs added in v0.4.0

func (m Map) UsableAs(o Type) bool

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

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

func (o Object) Equal(other Type) bool

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

func (o Object) Is(t Type) bool

Is returns whether `t` is an Object type or not. It does not perform any AttributeTypes checks.

func (Object) MarshalJSON deprecated

func (o Object) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON representation of the full type signature of `o`, including the AttributeTypes.

Deprecated: this is not meant to be called by third-party code.

func (Object) String

func (o Object) String() string

func (Object) UsableAs added in v0.4.0

func (o Object) UsableAs(other Type) bool

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

func (s Set) Equal(o Type) bool

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

func (s Set) Is(t Type) bool

Is returns whether `t` is a Set type or not. It does not perform any ElementType checks.

func (Set) MarshalJSON deprecated

func (s Set) MarshalJSON() ([]byte, error)

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.

func (Set) String

func (s Set) String() string

func (Set) UsableAs added in v0.4.0

func (s Set) UsableAs(o Type) bool

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

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

func (tu Tuple) Equal(o Type) bool

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

func (tu Tuple) Is(t Type) bool

Is returns whether `t` is a Tuple type or not. It does not perform any ElementTypes checks.

func (Tuple) MarshalJSON deprecated

func (tu Tuple) MarshalJSON() ([]byte, error)

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.

func (Tuple) String

func (tu Tuple) String() string

func (Tuple) UsableAs added in v0.4.0

func (tu Tuple) UsableAs(o Type) bool

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.
	//
	// 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 ParseJSONType(buf []byte) (Type, error)

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.

func TypeFromElements

func TypeFromElements(elements []Value) (Type, error)

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

func NewValue(t Type, val interface{}) Value

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

func Transform(val Value, cb func(*AttributePath, Value) (Value, error)) (Value, error)

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

func ValueFromJSON(data []byte, typ Type) (Value, error)

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 ValueFromMsgPack deprecated

func ValueFromMsgPack(data []byte, typ Type) (Value, error)

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

func (val Value) As(dst interface{}) error

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

func (val Value) Copy() Value

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

func (val1 Value) Diff(val2 Value) ([]ValueDiff, error)

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

func (val Value) Equal(o Value) bool

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

func (val Value) IsFullyKnown() bool

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

func (val Value) IsKnown() bool

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) IsNull

func (val Value) IsNull() bool

IsNull returns true if the Value is null.

func (Value) MarshalMsgPack deprecated

func (val Value) MarshalMsgPack(t Type) ([]byte, error)

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.

func (Value) String

func (val Value) String() string

func (Value) Type

func (val Value) Type() Type

Type returns the Type of the Value.

type ValueConverter

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

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.

func (ValueDiff) Equal

func (v ValueDiff) Equal(o ValueDiff) bool

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.

func (ValueDiff) String

func (v ValueDiff) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL