attr

Documentation

Overview

Package attr contains type and value interfaces for core framework and provider-defined data types. The underlying xattr package contains additional interfaces for advanced type functionality.

Index

• Constants
• type Type
• type TypeWithAttributeTypes
• type TypeWithElementType
• type TypeWithElementTypes
• type TypeWithMarkdownDescription
• type TypeWithPlaintextDescription
• type Value
• type ValueState
  • func (s ValueState) String() string

Constants

const (
	// UnknownValueString should be returned by Value.String() implementations,
	// when Value.IsUnknown() returns true.
	UnknownValueString = "<unknown>"

	// NullValueString should be returned by Value.String() implementations
	// when Value.IsNull() returns true.
	NullValueString = "<null>"
)

Types

type Type

type Type interface {
	// TerraformType returns the tftypes.Type that should be used to
	// represent this type. This constrains what user input will be
	// accepted and what kind of data can be set in state. The framework
	// will use this to translate the Type to something Terraform can
	// understand.
	TerraformType(context.Context) tftypes.Type

	// ValueFromTerraform returns a Value given a tftypes.Value. This is
	// meant to convert the tftypes.Value into a more convenient Go type
	// for the provider to consume the data with.
	ValueFromTerraform(context.Context, tftypes.Value) (Value, error)

	// ValueType should return the attr.Value type returned by
	// ValueFromTerraform. The returned attr.Value can be any null, unknown,
	// or known value for the type, as this is intended for type detection
	// and improving error diagnostics.
	ValueType(context.Context) Value

	// Equal should return true if the Type is considered equivalent to the
	// Type passed as an argument.
	//
	// Most types should verify the associated Type is exactly equal to prevent
	// potential data consistency issues. For example:
	//
	//  - basetypes.Number is inequal to basetypes.Int64 or basetypes.Float64
	//  - basetypes.String is inequal to a custom Go type that embeds it
	//
	Equal(Type) bool

	// String should return a human-friendly version of the Type.
	String() string

	tftypes.AttributePathStepper
}

Type defines an interface for describing a kind of attribute. Types are collections of constraints and behaviors such that they can be reused on multiple attributes easily.

Refer also to the xattr package, which contains additional extensions for Type, such as validation.

type TypeWithAttributeTypes

type TypeWithAttributeTypes interface {
	Type

	// WithAttributeTypes returns a new copy of the type with its
	// attribute types set.
	WithAttributeTypes(map[string]Type) TypeWithAttributeTypes

	// AttributeTypes returns the object's attribute types.
	AttributeTypes() map[string]Type
}

TypeWithAttributeTypes extends the Type interface to include information about attribute types. Attribute types are part of the definition of an object type.

type TypeWithElementType

type TypeWithElementType interface {
	Type

	// WithElementType returns a new copy of the type with its element type
	// set.
	WithElementType(Type) TypeWithElementType

	// ElementType returns the type's element type.
	ElementType() Type
}

TypeWithElementType extends the Type interface to include information about the type all elements will share. Element types are part of the definition of a list, set, or map type.

type TypeWithElementTypes

type TypeWithElementTypes interface {
	Type

	// WithElementTypes returns a new copy of the type with its elements'
	// types set.
	WithElementTypes([]Type) TypeWithElementTypes

	// ElementTypes returns the type's elements' types.
	ElementTypes() []Type
}

TypeWithElementTypes extends the Type interface to include information about the types of each element. Element types are part of the definition of a tuple type.

type TypeWithMarkdownDescription

type TypeWithMarkdownDescription interface {
	Type

	// MarkdownDescription returns a practitioner-friendly explanation of
	// the type and the constraints of the data it accepts and returns. It
	// will be combined with the MarkdownDescription associated with the
	// Attribute.
	MarkdownDescription(context.Context) string
}

TypeWithMarkdownDescription extends the Type interface to include a MarkdownDescription method, used to bundle extra information to include in attribute descriptions with the Type. It expects the description to be formatted for display with Markdown.

type TypeWithPlaintextDescription

type TypeWithPlaintextDescription interface {
	Type

	// Description returns a practitioner-friendly explanation of the type
	// and the constraints of the data it accepts and returns. It will be
	// combined with the Description associated with the Attribute.
	Description(context.Context) string
}

TypeWithPlaintextDescription extends the Type interface to include a Description method, used to bundle extra information to include in attribute descriptions with the Type. It expects the description to be written as plain text, with no special formatting.

type Value

type Value interface {
	// Type returns the Type that created the Value.
	Type(context.Context) Type

	// ToTerraformValue returns the data contained in the Value as
	// a tftypes.Value.
	ToTerraformValue(context.Context) (tftypes.Value, error)

	// Equal should return true if the Value is considered type and data
	// value equivalent to the Value passed as an argument.
	//
	// Most types should verify the associated Type is exactly equal to prevent
	// potential data consistency issues. For example:
	//
	//  - basetypes.Number is inequal to basetypes.Int64 or basetypes.Float64
	//  - basetypes.String is inequal to a custom Go type that embeds it
	//
	// Additionally, most types should verify that known values are compared
	// to comply with Terraform's data consistency rules. For example:
	//
	//  - In a list, element order is significant
	//  - In a string, runes are compared byte-wise (e.g. whitespace is
	//    significant in JSON-encoded strings)
	//
	Equal(Value) bool

	// IsNull returns true if the Value is not set, or is explicitly set to null.
	IsNull() bool

	// IsUnknown returns true if the value is not yet known.
	IsUnknown() bool

	// String returns a summary representation of either the underlying Value,
	// or UnknownValueString (`<unknown>`) when IsUnknown() returns true,
	// or NullValueString (`<null>`) when IsNull() return true.
	//
	// This is an intentionally lossy representation, that are best suited for
	// logging and error reporting, as they are not protected by
	// compatibility guarantees within the framework.
	String() string
}

Value defines an interface for describing data associated with an attribute. Values allow provider developers to specify data in a convenient format, and have it transparently be converted to formats Terraform understands.

type ValueState

type ValueState uint8

const (
	// ValueStateNull represents a value which is null.
	//
	// This value is 0 so it is the zero-value for types implementations.
	ValueStateNull ValueState = 0

	// ValueStateUnknown represents a value which is unknown.
	ValueStateUnknown ValueState = 1

	// ValueStateKnown represents a value which is known (not null or unknown).
	ValueStateKnown ValueState = 2
)

func (ValueState) String

func (s ValueState) String() string