function

package
v1.5.0 Latest Latest
Warning

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

 Go to latest Published: Jan 11, 2024 License: MPL-2.0 Imports: 7 Imported by: 8

Documentation

Overview

Package function contains all interfaces, request types, and response types for a Terraform Provider function implementation.

In Terraform, a function is a concept which enables provider developers to offer practitioners a pure function call in their configuration. Functions are defined by a function name, such as "parse_xyz", a definition representing the ordered list of parameters with associated data types and a result data type, and the function logic.

The main starting point for implementations in this package is the Function type which represents an instance of a function that has its own argument data when called. The Function implementations are referenced by a [provider.Provider] type Functions method, which enables the function for practitioner and testing usage.

Index

Constants

View Source 
const DefaultParameterName = "param"

DefaultParameterName is the name given to parameters which do not declare a name. Use this to prevent Terraform errors for missing names.

Variables

This section is empty.

Functions

This section is empty.

Types

type ArgumentsData 

type ArgumentsData struct {
	// contains filtered or unexported fields
}

ArgumentsData is the zero-based positional argument data sent by Terraform for a single function call. Use the Get method or GetArgument method in the Function type Run method to fetch the data.

This data is automatically populated by the framework based on the function definition. For unit testing, use the NewArgumentsData function to manually create the data.

func NewArgumentsData 

func NewArgumentsData(values []attr.Value) ArgumentsData

NewArgumentsData creates an ArgumentsData. This is only necessary for unit testing as the framework automatically creates this data.

func (ArgumentsData) Equal 

func (d ArgumentsData) Equal(o ArgumentsData) bool

Equal returns true if all the underlying values are equivalent.

func (ArgumentsData) Get 

func (d ArgumentsData) Get(ctx context.Context, targets ...any) diag.Diagnostics

Get retrieves all argument data and populates the targets with the values. All arguments must be present in the targets, including all parameters and an optional variadic parameter, otherwise an error diagnostic will be raised. Each target type must be acceptable for the data type in the parameter definition.

Variadic parameter argument data must be consumed by a types.List or Go slice type with an element type appropriate for the parameter definition ([]T). The framework automatically populates this list with elements matching the zero, one, or more arguments passed.

func (ArgumentsData) GetArgument 

func (d ArgumentsData) GetArgument(ctx context.Context, position int, target any) diag.Diagnostics

GetArgument retrieves the argument data found at the given zero-based position and populates the target with the value. The target type must be acceptable for the data type in the parameter definition.

Variadic parameter argument data must be consumed by a types.List or Go slice type with an element type appropriate for the parameter definition ([]T) at the position after all parameters. The framework automatically populates this list with elements matching the zero, one, or more arguments passed.

type BoolParameter 

type BoolParameter struct {
	// AllowNullValue when enabled denotes that a null argument value can be
	// passed to the function. When disabled, Terraform returns an error if the
	// argument value is null.
	//
	// Enabling this requires reading argument values as *bool or [types.Bool].
	AllowNullValue bool

	// AllowUnknownValues when enabled denotes that an unknown argument value
	// can be passed to the function. When disabled, Terraform skips the
	// function call entirely and assumes an unknown value result from the
	// function.
	//
	// Enabling this requires reading argument values as [types.Bool].
	AllowUnknownValues bool

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.BoolType]. When retrieving data, the
	// [basetypes.BoolValuable] implementation associated with this custom
	// type must be used in place of [types.Bool].
	CustomType basetypes.BoolTypable

	// Description is used in various tooling, like the language server, to
	// give practitioners more information about what this parameter is,
	// what it is for, and how it should be used. It should be written as
	// plain text, with no special formatting.
	Description string

	// MarkdownDescription is used in various tooling, like the
	// documentation generator, to give practitioners more information
	// about what this parameter is, what it is for, and how it should be
	// used. It should be formatted using Markdown.
	MarkdownDescription string

	// Name is a short usage name for the parameter, such as "data". This name
	// is used in documentation, such as generating a function signature,
	// however its usage may be extended in the future. If no name is provided,
	// this will default to "param".
	//
	// This must be a valid Terraform identifier, such as starting with an
	// alphabetical character and followed by alphanumeric or underscore
	// characters.
	Name string
}

BoolParameter represents a function parameter that is a boolean.

When retrieving the argument value for this parameter:

  • If CustomType is set, use its associated value type.
  • If AllowUnknownValues is enabled, you must use the [types.Bool] value type.
  • If AllowNullValue is enabled, you must use [types.Bool] or *bool value types.
  • Otherwise, use [types.Bool] or *bool, or bool value types.

Terraform configurations set this parameter's argument data using expressions that return a bool or directly via true/false keywords.

func (BoolParameter) GetAllowNullValue 

func (p BoolParameter) GetAllowNullValue() bool

GetAllowNullValue returns if the parameter accepts a null value.

func (BoolParameter) GetAllowUnknownValues 

func (p BoolParameter) GetAllowUnknownValues() bool

GetAllowUnknownValues returns if the parameter accepts an unknown value.

func (BoolParameter) GetDescription 

func (p BoolParameter) GetDescription() string

GetDescription returns the parameter plaintext description.

func (BoolParameter) GetMarkdownDescription 

func (p BoolParameter) GetMarkdownDescription() string

GetMarkdownDescription returns the parameter Markdown description.

func (BoolParameter) GetName 

func (p BoolParameter) GetName() string

GetName returns the parameter name.

func (BoolParameter) GetType 

func (p BoolParameter) GetType() attr.Type

GetType returns the parameter data type.

type BoolReturn 

type BoolReturn struct {
	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.BoolType]. When setting data, the
	// [basetypes.BoolValuable] implementation associated with this custom
	// type must be used in place of [types.Bool].
	CustomType basetypes.BoolTypable
}

BoolReturn represents a function return that is a boolean.

When setting the value for this return:

- If CustomType is set, use its associated value type. - Otherwise, use [types.Bool], *bool, or bool.

func (BoolReturn) GetType 

func (r BoolReturn) GetType() attr.Type

GetType returns the return data type.

func (BoolReturn) NewResultData 

func (r BoolReturn) NewResultData(ctx context.Context) (ResultData, diag.Diagnostics)

NewResultData returns a new result data based on the type.

type Definition 

type Definition struct {
	// Parameters is the ordered list of function parameters and their
	// associated data types.
	Parameters []Parameter

	// VariadicParameter is an optional final parameter which can accept zero or
	// more arguments when the function is called. The argument data is sent as
	// an ordered list of the associated data type.
	VariadicParameter Parameter

	// Return is the function call response data type.
	Return Return

	// Summary is a short description of the function, preferably a single
	// sentence. Use the Description field for longer documentation about the
	// function and its implementation.
	Summary string

	// Description is the longer documentation for usage, such as editor
	// integrations, to give practitioners more information about the purpose of
	// the function and how its logic is implemented. It should be plaintext
	// formatted.
	Description string

	// MarkdownDescription is the longer documentation for usage, such as a
	// registry, to give practitioners more information about the purpose of the
	// function and how its logic is implemented.
	MarkdownDescription string

	// DeprecationMessage defines warning diagnostic details to display when
	// practitioner configurations use this function. The warning diagnostic
	// summary is automatically set to "Function Deprecated" along with
	// configuration source file and line information.
	DeprecationMessage string
}

Definition is a function definition. Always set at least the Result field.

NOTE: Provider-defined function support is in technical preview and offered without compatibility promises until Terraform 1.8 is generally available.

func (Definition) Parameter 

func (d Definition) Parameter(ctx context.Context, position int) (Parameter, diag.Diagnostics)

Parameter returns the Parameter for a given argument position. This may be from the Parameters field or, if defined, the VariadicParameter field. An error diagnostic is raised if the position is outside the expected arguments.

func (Definition) ValidateImplementation 

func (d Definition) ValidateImplementation(ctx context.Context) diag.Diagnostics

ValidateImplementation contains logic for validating the provider-defined implementation of the definition to prevent unexpected errors or panics. This logic runs during the GetProviderSchema RPC, or via provider-defined unit testing, and should never include false positives.

type DefinitionRequest 

type DefinitionRequest struct{}

DefinitionRequest represents a request for the Function to return its definition, such as its ordered parameters and result. An instance of this request struct is supplied as an argument to the Function type Definition method.

type DefinitionResponse 

type DefinitionResponse struct {
	// Definition is the function definition.
	Definition Definition

	// Diagnostics report errors or warnings related to defining the function.
	// An empty slice indicates success, with no warnings or errors generated.
	Diagnostics diag.Diagnostics
}

DefinitionResponse represents a response to a DefinitionRequest. An instance of this response struct is supplied as an argument to the Function type Definition method. Always set at least the Definition field.

type Float64Parameter 

type Float64Parameter struct {
	// AllowNullValue when enabled denotes that a null argument value can be
	// passed to the function. When disabled, Terraform returns an error if the
	// argument value is null.
	AllowNullValue bool

	// AllowUnknownValues when enabled denotes that an unknown argument value
	// can be passed to the function. When disabled, Terraform skips the
	// function call entirely and assumes an unknown value result from the
	// function.
	AllowUnknownValues bool

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.Float64Type]. When retrieving data, the
	// [basetypes.Float64Valuable] implementation associated with this custom
	// type must be used in place of [types.Float64].
	CustomType basetypes.Float64Typable

	// Description is used in various tooling, like the language server, to
	// give practitioners more information about what this parameter is,
	// what it is for, and how it should be used. It should be written as
	// plain text, with no special formatting.
	Description string

	// MarkdownDescription is used in various tooling, like the
	// documentation generator, to give practitioners more information
	// about what this parameter is, what it is for, and how it should be
	// used. It should be formatted using Markdown.
	MarkdownDescription string

	// Name is a short usage name for the parameter, such as "data". This name
	// is used in documentation, such as generating a function signature,
	// however its usage may be extended in the future. If no name is provided,
	// this will default to "param".
	//
	// This must be a valid Terraform identifier, such as starting with an
	// alphabetical character and followed by alphanumeric or underscore
	// characters.
	Name string
}

Float64Parameter represents a function parameter that is a 64-bit floating point number.

When retrieving the argument value for this parameter:

  • If CustomType is set, use its associated value type.
  • If AllowUnknownValues is enabled, you must use the [types.Float64] value type.
  • If AllowNullValue is enabled, you must use [types.Float64] or *float64 value types.
  • Otherwise, use [types.Float64] or *float64, or float64 value types.

Terraform configurations set this parameter's argument data using expressions that return a number or directly via numeric syntax.

func (Float64Parameter) GetAllowNullValue 

func (p Float64Parameter) GetAllowNullValue() bool

GetAllowNullValue returns if the parameter accepts a null value.

func (Float64Parameter) GetAllowUnknownValues 

func (p Float64Parameter) GetAllowUnknownValues() bool

GetAllowUnknownValues returns if the parameter accepts an unknown value.

func (Float64Parameter) GetDescription 

func (p Float64Parameter) GetDescription() string

GetDescription returns the parameter plaintext description.

func (Float64Parameter) GetMarkdownDescription 

func (p Float64Parameter) GetMarkdownDescription() string

GetMarkdownDescription returns the parameter Markdown description.

func (Float64Parameter) GetName 

func (p Float64Parameter) GetName() string

GetName returns the parameter name.

func (Float64Parameter) GetType 

func (p Float64Parameter) GetType() attr.Type

GetType returns the parameter data type.

type Float64Return 

type Float64Return struct {
	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.Float64Type]. When setting data, the
	// [basetypes.Float64Valuable] implementation associated with this custom
	// type must be used in place of [types.Float64].
	CustomType basetypes.Float64Typable
}

Float64Return represents a function return that is a 64-bit floating point number.

When setting the value for this return:

- If CustomType is set, use its associated value type. - Otherwise, use [types.Float64], *float64, or float64.

func (Float64Return) GetType 

func (r Float64Return) GetType() attr.Type

GetType returns the return data type.

func (Float64Return) NewResultData 

func (r Float64Return) NewResultData(ctx context.Context) (ResultData, diag.Diagnostics)

NewResultData returns a new result data based on the type.

type Function 

type Function interface {
	// Metadata should return the name of the function, such as parse_xyz.
	Metadata(context.Context, MetadataRequest, *MetadataResponse)

	// Definition should return the definition for the function.
	Definition(context.Context, DefinitionRequest, *DefinitionResponse)

	// Run should return the result of the function logic. It is called when
	// Terraform reaches a function call in the configuration. Argument data
	// values should be read from the [RunRequest] and the result value set in
	// the [RunResponse].
	Run(context.Context, RunRequest, *RunResponse)
}

Function represents an instance of a function. This is the core interface that all functions must implement.

NOTE: Provider-defined function support is in technical preview and offered without compatibility promises until Terraform 1.8 is generally available.

type Int64Parameter 

type Int64Parameter struct {
	// AllowNullValue when enabled denotes that a null argument value can be
	// passed to the function. When disabled, Terraform returns an error if the
	// argument value is null.
	AllowNullValue bool

	// AllowUnknownValues when enabled denotes that an unknown argument value
	// can be passed to the function. When disabled, Terraform skips the
	// function call entirely and assumes an unknown value result from the
	// function.
	AllowUnknownValues bool

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.Int64Type]. When retrieving data, the
	// [basetypes.Int64Valuable] implementation associated with this custom
	// type must be used in place of [types.Int64].
	CustomType basetypes.Int64Typable

	// Description is used in various tooling, like the language server, to
	// give practitioners more information about what this parameter is,
	// what it is for, and how it should be used. It should be written as
	// plain text, with no special formatting.
	Description string

	// MarkdownDescription is used in various tooling, like the
	// documentation generator, to give practitioners more information
	// about what this parameter is, what it is for, and how it should be
	// used. It should be formatted using Markdown.
	MarkdownDescription string

	// Name is a short usage name for the parameter, such as "data". This name
	// is used in documentation, such as generating a function signature,
	// however its usage may be extended in the future. If no name is provided,
	// this will default to "param".
	//
	// This must be a valid Terraform identifier, such as starting with an
	// alphabetical character and followed by alphanumeric or underscore
	// characters.
	Name string
}

Int64Parameter represents a function parameter that is a 64-bit integer.

When retrieving the argument value for this parameter:

  • If CustomType is set, use its associated value type.
  • If AllowUnknownValues is enabled, you must use the [types.Int64] value type.
  • If AllowNullValue is enabled, you must use [types.Int64] or *int64 value types.
  • Otherwise, use [types.Int64] or *int64, or int64 value types.

Terraform configurations set this parameter's argument data using expressions that return a number or directly via numeric syntax.

func (Int64Parameter) GetAllowNullValue 

func (p Int64Parameter) GetAllowNullValue() bool

GetAllowNullValue returns if the parameter accepts a null value.

func (Int64Parameter) GetAllowUnknownValues 

func (p Int64Parameter) GetAllowUnknownValues() bool

GetAllowUnknownValues returns if the parameter accepts an unknown value.

func (Int64Parameter) GetDescription 

func (p Int64Parameter) GetDescription() string

GetDescription returns the parameter plaintext description.

func (Int64Parameter) GetMarkdownDescription 

func (p Int64Parameter) GetMarkdownDescription() string

GetMarkdownDescription returns the parameter Markdown description.

func (Int64Parameter) GetName 

func (p Int64Parameter) GetName() string

GetName returns the parameter name.

func (Int64Parameter) GetType 

func (p Int64Parameter) GetType() attr.Type

GetType returns the parameter data type.

type Int64Return 

type Int64Return struct {
	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.Int64Type]. When setting data, the
	// [basetypes.Int64Valuable] implementation associated with this custom
	// type must be used in place of [types.Int64].
	CustomType basetypes.Int64Typable
}

Int64Return represents a function return that is a 64-bit integer number.

When setting the value for this return:

- If CustomType is set, use its associated value type. - Otherwise, use [types.Int64], *int64, or int64.

func (Int64Return) GetType 

func (r Int64Return) GetType() attr.Type

GetType returns the return data type.

func (Int64Return) NewResultData 

func (r Int64Return) NewResultData(ctx context.Context) (ResultData, diag.Diagnostics)

NewResultData returns a new result data based on the type.

type ListParameter 

type ListParameter struct {
	// ElementType is the type for all elements of the list. This field must be
	// set.
	ElementType attr.Type

	// AllowNullValue when enabled denotes that a null argument value can be
	// passed to the function. When disabled, Terraform returns an error if the
	// argument value is null.
	AllowNullValue bool

	// AllowUnknownValues when enabled denotes that an unknown argument value
	// can be passed to the function. When disabled, Terraform skips the
	// function call entirely and assumes an unknown value result from the
	// function.
	AllowUnknownValues bool

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.ListType]. When retrieving data, the
	// [basetypes.ListValuable] implementation associated with this custom
	// type must be used in place of [types.List].
	CustomType basetypes.ListTypable

	// Description is used in various tooling, like the language server, to
	// give practitioners more information about what this parameter is,
	// what it is for, and how it should be used. It should be written as
	// plain text, with no special formatting.
	Description string

	// MarkdownDescription is used in various tooling, like the
	// documentation generator, to give practitioners more information
	// about what this parameter is, what it is for, and how it should be
	// used. It should be formatted using Markdown.
	MarkdownDescription string

	// Name is a short usage name for the parameter, such as "data". This name
	// is used in documentation, such as generating a function signature,
	// however its usage may be extended in the future. If no name is provided,
	// this will default to "param".
	//
	// This must be a valid Terraform identifier, such as starting with an
	// alphabetical character and followed by alphanumeric or underscore
	// characters.
	Name string
}

ListParameter represents a function parameter that is an ordered list of a single element type. Either the ElementType or CustomType field must be set.

When retrieving the argument value for this parameter:

  • If CustomType is set, use its associated value type.
  • If AllowUnknownValues is enabled, you must use the [types.List] value type.
  • Otherwise, use [types.List] or any Go slice value types compatible with the element type.

Terraform configurations set this parameter's argument data using expressions that return a list or directly via list ("[...]") syntax.

func (ListParameter) GetAllowNullValue 

func (p ListParameter) GetAllowNullValue() bool

GetAllowNullValue returns if the parameter accepts a null value.

func (ListParameter) GetAllowUnknownValues 

func (p ListParameter) GetAllowUnknownValues() bool

GetAllowUnknownValues returns if the parameter accepts an unknown value.

func (ListParameter) GetDescription 

func (p ListParameter) GetDescription() string

GetDescription returns the parameter plaintext description.

func (ListParameter) GetMarkdownDescription 

func (p ListParameter) GetMarkdownDescription() string

GetMarkdownDescription returns the parameter Markdown description.

func (ListParameter) GetName 

func (p ListParameter) GetName() string

GetName returns the parameter name.

func (ListParameter) GetType 

func (p ListParameter) GetType() attr.Type

GetType returns the parameter data type.

type ListReturn 

type ListReturn struct {
	// ElementType is the type for all elements of the list. This field must be
	// set.
	ElementType attr.Type

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.ListType]. When setting data, the
	// [basetypes.ListValuable] implementation associated with this custom
	// type must be used in place of [types.List].
	CustomType basetypes.ListTypable
}

ListReturn represents a function return that is an ordered collection of a single element type. Either the ElementType or CustomType field must be set.

When setting the value for this return:

  • If CustomType is set, use its associated value type.
  • Otherwise, use [types.List] or a Go slice value type compatible with the element type.

func (ListReturn) GetType 

func (r ListReturn) GetType() attr.Type

GetType returns the return data type.

func (ListReturn) NewResultData 

func (r ListReturn) NewResultData(ctx context.Context) (ResultData, diag.Diagnostics)

NewResultData returns a new result data based on the type.

type MapParameter 

type MapParameter struct {
	// ElementType is the type for all elements of the map. This field must be
	// set.
	ElementType attr.Type

	// AllowNullValue when enabled denotes that a null argument value can be
	// passed to the function. When disabled, Terraform returns an error if the
	// argument value is null.
	AllowNullValue bool

	// AllowUnknownValues when enabled denotes that an unknown argument value
	// can be passed to the function. When disabled, Terraform skips the
	// function call entirely and assumes an unknown value result from the
	// function.
	AllowUnknownValues bool

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.MapType]. When retrieving data, the
	// [basetypes.MapValuable] implementation associated with this custom
	// type must be used in place of [types.Map].
	CustomType basetypes.MapTypable

	// Description is used in various tooling, like the language server, to
	// give practitioners more information about what this parameter is,
	// what it is for, and how it should be used. It should be written as
	// plain text, with no special formatting.
	Description string

	// MarkdownDescription is used in various tooling, like the
	// documentation generator, to give practitioners more information
	// about what this parameter is, what it is for, and how it should be
	// used. It should be formatted using Markdown.
	MarkdownDescription string

	// Name is a short usage name for the parameter, such as "data". This name
	// is used in documentation, such as generating a function signature,
	// however its usage may be extended in the future. If no name is provided,
	// this will default to "param".
	//
	// This must be a valid Terraform identifier, such as starting with an
	// alphabetical character and followed by alphanumeric or underscore
	// characters.
	Name string
}

MapParameter represents a function parameter that is a mapping of a single element type. Either the ElementType or CustomType field must be set.

When retrieving the argument value for this parameter:

  • If CustomType is set, use its associated value type.
  • If AllowUnknownValues is enabled, you must use the [types.Map] value type.
  • Otherwise, use [types.Map] or any Go map value types compatible with the element type.

Terraform configurations set this parameter's argument data using expressions that return a map or directly via map ("{...}") syntax.

func (MapParameter) GetAllowNullValue 

func (p MapParameter) GetAllowNullValue() bool

GetAllowNullValue returns if the parameter accepts a null value.

func (MapParameter) GetAllowUnknownValues 

func (p MapParameter) GetAllowUnknownValues() bool

GetAllowUnknownValues returns if the parameter accepts an unknown value.

func (MapParameter) GetDescription 

func (p MapParameter) GetDescription() string

GetDescription returns the parameter plaintext description.

func (MapParameter) GetMarkdownDescription 

func (p MapParameter) GetMarkdownDescription() string

GetMarkdownDescription returns the parameter Markdown description.

func (MapParameter) GetName 

func (p MapParameter) GetName() string

GetName returns the parameter name.

func (MapParameter) GetType 

func (p MapParameter) GetType() attr.Type

GetType returns the parameter data type.

type MapReturn 

type MapReturn struct {
	// ElementType is the type for all elements of the map. This field must be
	// set.
	ElementType attr.Type

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.MapType]. When setting data, the
	// [basetypes.MapValuable] implementation associated with this custom
	// type must be used in place of [types.Map].
	CustomType basetypes.MapTypable
}

MapReturn represents a function return that is an ordered collect of a single element type. Either the ElementType or CustomType field must be set.

When setting the value for this return:

  • If CustomType is set, use its associated value type.
  • Otherwise, use [types.Map] or a Go map value type compatible with the element type.

func (MapReturn) GetType 

func (r MapReturn) GetType() attr.Type

GetType returns the return data type.

func (MapReturn) NewResultData 

func (r MapReturn) NewResultData(ctx context.Context) (ResultData, diag.Diagnostics)

NewResultData returns a new result data based on the type.

type MetadataRequest 

type MetadataRequest struct{}

MetadataRequest represents a request for the Function to return metadata, such as its name. An instance of this request struct is supplied as an argument to the Function type Metadata method.

type MetadataResponse 

type MetadataResponse struct {
	// Name should be the function name, such as parse_xyz. Unlike data sources
	// and managed resources, the provider name and an underscore should not be
	// included as the Terraform configuration syntax for provider function
	// calls already include the provider name.
	Name string
}

MetadataResponse represents a response to a MetadataRequest. An instance of this response struct is supplied as an argument to the Function type Metadata method.

type NumberParameter 

type NumberParameter struct {
	// AllowNullValue when enabled denotes that a null argument value can be
	// passed to the function. When disabled, Terraform returns an error if the
	// argument value is null.
	AllowNullValue bool

	// AllowUnknownValues when enabled denotes that an unknown argument value
	// can be passed to the function. When disabled, Terraform skips the
	// function call entirely and assumes an unknown value result from the
	// function.
	AllowUnknownValues bool

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.NumberType]. When retrieving data, the
	// [basetypes.NumberValuable] implementation associated with this custom
	// type must be used in place of [types.Number].
	CustomType basetypes.NumberTypable

	// Description is used in various tooling, like the language server, to
	// give practitioners more information about what this parameter is,
	// what it is for, and how it should be used. It should be written as
	// plain text, with no special formatting.
	Description string

	// MarkdownDescription is used in various tooling, like the
	// documentation generator, to give practitioners more information
	// about what this parameter is, what it is for, and how it should be
	// used. It should be formatted using Markdown.
	MarkdownDescription string

	// Name is a short usage name for the parameter, such as "data". This name
	// is used in documentation, such as generating a function signature,
	// however its usage may be extended in the future. If no name is provided,
	// this will default to "param".
	//
	// This must be a valid Terraform identifier, such as starting with an
	// alphabetical character and followed by alphanumeric or underscore
	// characters.
	Name string
}

NumberParameter represents a function parameter that is a 512-bit arbitrary precision number.

When retrieving the argument value for this parameter:

  • If CustomType is set, use its associated value type.
  • If AllowUnknownValues is enabled, you must use the [types.Number] value type.
  • Otherwise, use [types.Number] or *big.Float value types.

Terraform configurations set this parameter's argument data using expressions that return a number or directly via numeric syntax.

func (NumberParameter) GetAllowNullValue 

func (p NumberParameter) GetAllowNullValue() bool

GetAllowNullValue returns if the parameter accepts a null value.

func (NumberParameter) GetAllowUnknownValues 

func (p NumberParameter) GetAllowUnknownValues() bool

GetAllowUnknownValues returns if the parameter accepts an unknown value.

func (NumberParameter) GetDescription 

func (p NumberParameter) GetDescription() string

GetDescription returns the parameter plaintext description.

func (NumberParameter) GetMarkdownDescription 

func (p NumberParameter) GetMarkdownDescription() string

GetMarkdownDescription returns the parameter Markdown description.

func (NumberParameter) GetName 

func (p NumberParameter) GetName() string

GetName returns the parameter name.

func (NumberParameter) GetType 

func (p NumberParameter) GetType() attr.Type

GetType returns the parameter data type.

type NumberReturn 

type NumberReturn struct {
	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.NumberType]. When setting data, the
	// [basetypes.NumberValuable] implementation associated with this custom
	// type must be used in place of [types.Number].
	CustomType basetypes.NumberTypable
}

NumberReturn represents a function return that is a 512-bit arbitrary precision number.

When setting the value for this return:

- If CustomType is set, use its associated value type. - Otherwise, use [types.Number] or *big.Float.

func (NumberReturn) GetType 

func (r NumberReturn) GetType() attr.Type

GetType returns the return data type.

func (NumberReturn) NewResultData 

func (r NumberReturn) NewResultData(ctx context.Context) (ResultData, diag.Diagnostics)

NewResultData returns a new result data based on the type.

type ObjectParameter 

type ObjectParameter struct {
	// AttributeTypes is the mapping of underlying attribute names to attribute
	// types. This field must be set.
	AttributeTypes map[string]attr.Type

	// AllowNullValue when enabled denotes that a null argument value can be
	// passed to the function. When disabled, Terraform returns an error if the
	// argument value is null.
	AllowNullValue bool

	// AllowUnknownValues when enabled denotes that an unknown argument value
	// can be passed to the function. When disabled, Terraform skips the
	// function call entirely and assumes an unknown value result from the
	// function.
	AllowUnknownValues bool

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.ObjectType]. When retrieving data, the
	// [basetypes.ObjectValuable] implementation associated with this custom
	// type must be used in place of [types.Object].
	CustomType basetypes.ObjectTypable

	// Description is used in various tooling, like the language server, to
	// give practitioners more information about what this parameter is,
	// what it is for, and how it should be used. It should be written as
	// plain text, with no special formatting.
	Description string

	// MarkdownDescription is used in various tooling, like the
	// documentation generator, to give practitioners more information
	// about what this parameter is, what it is for, and how it should be
	// used. It should be formatted using Markdown.
	MarkdownDescription string

	// Name is a short usage name for the parameter, such as "data". This name
	// is used in documentation, such as generating a function signature,
	// however its usage may be extended in the future. If no name is provided,
	// this will default to "param".
	//
	// This must be a valid Terraform identifier, such as starting with an
	// alphabetical character and followed by alphanumeric or underscore
	// characters.
	Name string
}

ObjectParameter represents a function parameter that is a mapping of defined attribute names to values. Either the AttributeTypes or CustomType field must be set.

When retrieving the argument value for this parameter:

  • If CustomType is set, use its associated value type.
  • If AllowUnknownValues is enabled, you must use the [types.Object] value type.
  • If AllowNullValue is enabled, you must use the [types.Object] or a compatible Go *struct value type.
  • Otherwise, use [types.Object] or compatible *struct/struct value types.

Terraform configurations set this parameter's argument data using expressions that return an object or directly via object ("{...}") syntax.

func (ObjectParameter) GetAllowNullValue 

func (p ObjectParameter) GetAllowNullValue() bool

GetAllowNullValue returns if the parameter accepts a null value.

func (ObjectParameter) GetAllowUnknownValues 

func (p ObjectParameter) GetAllowUnknownValues() bool

GetAllowUnknownValues returns if the parameter accepts an unknown value.

func (ObjectParameter) GetDescription 

func (p ObjectParameter) GetDescription() string

GetDescription returns the parameter plaintext description.

func (ObjectParameter) GetMarkdownDescription 

func (p ObjectParameter) GetMarkdownDescription() string

GetMarkdownDescription returns the parameter Markdown description.

func (ObjectParameter) GetName 

func (p ObjectParameter) GetName() string

GetName returns the parameter name.

func (ObjectParameter) GetType 

func (p ObjectParameter) GetType() attr.Type

GetType returns the parameter data type.

type ObjectReturn 

type ObjectReturn struct {
	// AttributeTypes is the mapping of underlying attribute names to attribute
	// types. This field must be set.
	AttributeTypes map[string]attr.Type

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.ObjectType]. When setting data, the
	// [basetypes.ObjectValuable] implementation associated with this custom
	// type must be used in place of [types.Object].
	CustomType basetypes.ObjectTypable
}

ObjectReturn represents a function return that is mapping of defined attribute names to values. When setting the value for this return, use [types.Object] or a compatible Go struct as the value type unless the CustomType field is set. The AttributeTypes field must be set.

func (ObjectReturn) GetType 

func (r ObjectReturn) GetType() attr.Type

GetType returns the return data type.

func (ObjectReturn) NewResultData 

func (r ObjectReturn) NewResultData(ctx context.Context) (ResultData, diag.Diagnostics)

NewResultData returns a new result data based on the type.

type Parameter 

type Parameter interface {
	// GetAllowNullValue should return if the parameter accepts a null value.
	GetAllowNullValue() bool

	// GetAllowUnknownValues should return if the parameter accepts an unknown
	// value.
	GetAllowUnknownValues() bool

	// GetDescription should return the plaintext documentation for the
	// parameter.
	GetDescription() string

	// GetMarkdownDescription should return the Markdown documentation for the
	// parameter.
	GetMarkdownDescription() string

	// GetName should return a usage name for the parameter. Parameters are
	// positional, so this name has no meaning except documentation.
	GetName() string

	// GetType should return the data type for the parameter, which determines
	// what data type Terraform requires for configurations setting the argument
	// during a function call and the argument data type received by the
	// Function type Run method.
	GetType() attr.Type
}

Parameter is the interface for defining function parameters.

type ResultData 

type ResultData struct {
	// contains filtered or unexported fields
}

ResultData is the response data sent to Terraform for a single function call. Use the Set method in the Function type Run method to set the result data.

For unit testing, use the NewResultData function to manually create the data for comparison.

func NewResultData 

func NewResultData(value attr.Value) ResultData

NewResultData creates a ResultData. This is only necessary for unit testing as the framework automatically creates this data for the Function type Run method.

func (ResultData) Equal 

func (d ResultData) Equal(o ResultData) bool

Equal returns true if the value is equivalent.

func (*ResultData) Set 

func (d *ResultData) Set(ctx context.Context, value any) diag.Diagnostics

Set saves the result data. The value type must be acceptable for the data type in the result definition.

func (ResultData) Value 

func (d ResultData) Value() attr.Value

Value returns the saved value.

type Return 

type Return interface {
	// GetType should return the data type for the return, which determines
	// what data type Terraform requires for configurations receiving the
	// response of a function call and the return data type required from the
	// Function type Run method.
	GetType() attr.Type

	// NewResultData should return a new ResultData with an unknown value (or
	// best approximation of an invalid value) of the corresponding data type.
	// The Function type Run method is expected to overwrite the value before
	// returning.
	NewResultData(context.Context) (ResultData, diag.Diagnostics)
}

Return is the interface for defining function return data.

type RunRequest 

type RunRequest struct {
	// Arguments is the data sent from Terraform. Use the ArgumentsData type
	// GetArgument method to retrieve each positional argument.
	Arguments ArgumentsData
}

RunRequest represents a request for the Function to call its implementation logic. An instance of this request struct is supplied as an argument to the Function type Run method.

type RunResponse 

type RunResponse struct {
	// Diagnostics report errors or warnings related to defining the function.
	// An empty slice indicates success, with no warnings or errors generated.
	Diagnostics diag.Diagnostics

	// Result is the data to be returned to Terraform matching the function
	// result definition. This must be set or an error diagnostic is raised. Use
	// the ResultData type Set method to save the data.
	Result ResultData
}

RunResponse represents a response to a RunRequest. An instance of this response struct is supplied as an argument to the Function type Run method.

type SetParameter 

type SetParameter struct {
	// ElementType is the type for all elements of the set. This field must be
	// set.
	ElementType attr.Type

	// AllowNullValue when enabled denotes that a null argument value can be
	// passed to the function. When disabled, Terraform returns an error if the
	// argument value is null.
	AllowNullValue bool

	// AllowUnknownValues when enabled denotes that an unknown argument value
	// can be passed to the function. When disabled, Terraform skips the
	// function call entirely and assumes an unknown value result from the
	// function.
	AllowUnknownValues bool

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.SetType]. When retrieving data, the
	// [basetypes.SetValuable] implementation associated with this custom
	// type must be used in place of [types.Set].
	CustomType basetypes.SetTypable

	// Description is used in various tooling, like the language server, to
	// give practitioners more information about what this parameter is,
	// what it is for, and how it should be used. It should be written as
	// plain text, with no special formatting.
	Description string

	// MarkdownDescription is used in various tooling, like the
	// documentation generator, to give practitioners more information
	// about what this parameter is, what it is for, and how it should be
	// used. It should be formatted using Markdown.
	MarkdownDescription string

	// Name is a short usage name for the parameter, such as "data". This name
	// is used in documentation, such as generating a function signature,
	// however its usage may be extended in the future. If no name is provided,
	// this will default to "param".
	//
	// This must be a valid Terraform identifier, such as starting with an
	// alphabetical character and followed by alphanumeric or underscore
	// characters.
	Name string
}

SetParameter represents a function parameter that is an unordered set of a single element type. Either the ElementType or CustomType field must be set.

When retrieving the argument value for this parameter:

  • If CustomType is set, use its associated value type.
  • If AllowUnknownValues is enabled, you must use the [types.Set] value type.
  • Otherwise, use [types.Set] or any Go slice value types compatible with the element type.

Terraform configurations set this parameter's argument data using expressions that return a set or directly via set ("[...]") syntax.

func (SetParameter) GetAllowNullValue 

func (p SetParameter) GetAllowNullValue() bool

GetAllowNullValue returns if the parameter accepts a null value.

func (SetParameter) GetAllowUnknownValues 

func (p SetParameter) GetAllowUnknownValues() bool

GetAllowUnknownValues returns if the parameter accepts an unknown value.

func (SetParameter) GetDescription 

func (p SetParameter) GetDescription() string

GetDescription returns the parameter plaintext description.

func (SetParameter) GetMarkdownDescription 

func (p SetParameter) GetMarkdownDescription() string

GetMarkdownDescription returns the parameter Markdown description.

func (SetParameter) GetName 

func (p SetParameter) GetName() string

GetName returns the parameter name.

func (SetParameter) GetType 

func (p SetParameter) GetType() attr.Type

GetType returns the parameter data type.

type SetReturn 

type SetReturn struct {
	// ElementType is the type for all elements of the set. This field must be
	// set.
	ElementType attr.Type

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.SetType]. When setting data, the
	// [basetypes.SetValuable] implementation associated with this custom
	// type must be used in place of [types.Set].
	CustomType basetypes.SetTypable
}

SetReturn represents a function return that is an unordered collection of a single element type. Either the ElementType or CustomType field must be set.

When setting the value for this return:

  • If CustomType is set, use its associated value type.
  • Otherwise, use [types.Set] or a Go slice value type compatible with the element type.

func (SetReturn) GetType 

func (r SetReturn) GetType() attr.Type

GetType returns the return data type.

func (SetReturn) NewResultData 

func (r SetReturn) NewResultData(ctx context.Context) (ResultData, diag.Diagnostics)

NewResultData returns a new result data based on the type.

type StringParameter 

type StringParameter struct {
	// AllowNullValue when enabled denotes that a null argument value can be
	// passed to the function. When disabled, Terraform returns an error if the
	// argument value is null.
	AllowNullValue bool

	// AllowUnknownValues when enabled denotes that an unknown argument value
	// can be passed to the function. When disabled, Terraform skips the
	// function call entirely and assumes an unknown value result from the
	// function.
	AllowUnknownValues bool

	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.StringType]. When retrieving data, the
	// [basetypes.StringValuable] implementation associated with this custom
	// type must be used in place of [types.String].
	CustomType basetypes.StringTypable

	// Description is used in various tooling, like the language server, to
	// give practitioners more information about what this parameter is,
	// what it is for, and how it should be used. It should be written as
	// plain text, with no special formatting.
	Description string

	// MarkdownDescription is used in various tooling, like the
	// documentation generator, to give practitioners more information
	// about what this parameter is, what it is for, and how it should be
	// used. It should be formatted using Markdown.
	MarkdownDescription string

	// Name is a short usage name for the parameter, such as "data". This name
	// is used in documentation, such as generating a function signature,
	// however its usage may be extended in the future. If no name is provided,
	// this will default to "param".
	//
	// This must be a valid Terraform identifier, such as starting with an
	// alphabetical character and followed by alphanumeric or underscore
	// characters.
	Name string
}

StringParameter represents a function parameter that is a string.

When retrieving the argument value for this parameter:

  • If CustomType is set, use its associated value type.
  • If AllowUnknownValues is enabled, you must use the [types.String] value type.
  • If AllowNullValue is enabled, you must use [types.String] or *string value types.
  • Otherwise, use [types.String] or *string, or string value types.

Terraform configurations set this parameter's argument data using expressions that return a string or directly via double quote ("value") syntax.

func (StringParameter) GetAllowNullValue 

func (p StringParameter) GetAllowNullValue() bool

GetAllowNullValue returns if the parameter accepts a null value.

func (StringParameter) GetAllowUnknownValues 

func (p StringParameter) GetAllowUnknownValues() bool

GetAllowUnknownValues returns if the parameter accepts an unknown value.

func (StringParameter) GetDescription 

func (p StringParameter) GetDescription() string

GetDescription returns the parameter plaintext description.

func (StringParameter) GetMarkdownDescription 

func (p StringParameter) GetMarkdownDescription() string

GetMarkdownDescription returns the parameter Markdown description.

func (StringParameter) GetName 

func (p StringParameter) GetName() string

GetName returns the parameter name.

func (StringParameter) GetType 

func (p StringParameter) GetType() attr.Type

GetType returns the parameter data type.

type StringReturn 

type StringReturn struct {
	// CustomType enables the use of a custom data type in place of the
	// default [basetypes.StringType]. When setting data, the
	// [basetypes.StringValuable] implementation associated with this custom
	// type must be used in place of [types.String].
	CustomType basetypes.StringTypable
}

StringReturn represents a function return that is a string.

When setting the value for this return:

- If CustomType is set, use its associated value type. - Otherwise, use [types.String], *string, or string.

func (StringReturn) GetType 

func (r StringReturn) GetType() attr.Type

GetType returns the return data type.

func (StringReturn) NewResultData 

func (r StringReturn) NewResultData(ctx context.Context) (ResultData, diag.Diagnostics)

NewResultData returns a new result data based on the type.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.