typeexpr

Documentation

Overview

Package typeexpr is a fork of github.com/hashicorp/hcl/v2/ext/typeexpr which has additional experimental support for optional attributes.

This is here as part of the module_variable_optional_attrs experiment. If that experiment is successful, the changes here may be upstreamed into HCL itself or, if we deem it to be Durgaform-specific, we should at least update this documentation to reflect that this is now the primary Durgaform-specific type expression implementation, separate from the upstream HCL one.

Index

• Variables
• func Type(expr hcl.Expression) (cty.Type, hcl.Diagnostics)
• func TypeConstraint(expr hcl.Expression) (cty.Type, hcl.Diagnostics)
• func TypeConstraintFromVal(v cty.Value) cty.Type
• func TypeConstraintVal(ty cty.Type) cty.Value
• func TypeString(ty cty.Type) string
• type Defaults
  • func TypeConstraintWithDefaults(expr hcl.Expression) (cty.Type, *Defaults, hcl.Diagnostics)
  • func (d *Defaults) Apply(val cty.Value) cty.Value

Variables

var ConvertFunc function.Function

ConvertFunc is a cty function that implements type conversions.

Its signature is as follows:

convert(value, type_constraint)

...where type_constraint is a type constraint expression as defined by typeexpr.TypeConstraint.

It relies on HCL's customdecode extension and so it's not suitable for use in non-HCL contexts or if you are using a HCL syntax implementation that does not support customdecode for function arguments. However, it _is_ supported for function calls in the HCL native expression syntax.

var TypeConstraintType cty.Type

TypeConstraintType is a cty capsule type that allows cty type constraints to be used as values.

If TypeConstraintType is used in a context supporting the customdecode.CustomExpressionDecoder extension then it will implement expression decoding using the TypeConstraint function, thus allowing type expressions to be used in contexts where value expressions might normally be expected, such as in arguments to function calls.

Functions

func Type

func Type(expr hcl.Expression) (cty.Type, hcl.Diagnostics)

Type attempts to process the given expression as a type expression and, if successful, returns the resulting type. If unsuccessful, error diagnostics are returned.

func TypeConstraint

func TypeConstraint(expr hcl.Expression) (cty.Type, hcl.Diagnostics)

TypeConstraint attempts to parse the given expression as a type constraint and, if successful, returns the resulting type. If unsuccessful, error diagnostics are returned.

A type constraint has the same structure as a type, but it additionally allows the keyword "any" to represent cty.DynamicPseudoType, which is often used as a wildcard in type checking and type conversion operations.

func TypeConstraintFromVal

func TypeConstraintFromVal(v cty.Value) cty.Type

TypeConstraintFromVal extracts the type from a cty.Value of TypeConstraintType that was previously constructed using TypeConstraintVal.

If the given value isn't a known, non-null value of TypeConstraintType then this function will panic.

func TypeConstraintVal

func TypeConstraintVal(ty cty.Type) cty.Value

TypeConstraintVal constructs a cty.Value whose type is TypeConstraintType.

func TypeString

func TypeString(ty cty.Type) string

TypeString returns a string rendering of the given type as it would be expected to appear in the HCL native syntax.

This is primarily intended for showing types to the user in an application that uses typexpr, where the user can be assumed to be familiar with the type expression syntax. In applications that do not use typeexpr these results may be confusing to the user and so type.FriendlyName may be preferable, even though it's less precise.

TypeString produces reasonable results only for types like what would be produced by the Type and TypeConstraint functions. In particular, it cannot support capsule types.

Types

type Defaults

type Defaults struct {
	// Type of the node for which these defaults apply. This is necessary in
	// order to determine how to inspect the Defaults and Children collections.
	Type cty.Type

	// DefaultValues contains the default values for each object attribute,
	// indexed by attribute name.
	DefaultValues map[string]cty.Value

	// Children is a map of Defaults for elements contained in this type. This
	// only applies to structural and collection types.
	//
	// The map is indexed by string instead of cty.Value because cty.Number
	// instances are non-comparable, due to embedding a *big.Float.
	//
	// Collections have a single element type, which is stored at key "".
	Children map[string]*Defaults
}

Defaults represents a type tree which may contain default values for optional object attributes at any level. This is used to apply nested defaults to an input value before converting it to the concrete type.

func TypeConstraintWithDefaults

func TypeConstraintWithDefaults(expr hcl.Expression) (cty.Type, *Defaults, hcl.Diagnostics)

TypeConstraintWithDefaults attempts to parse the given expression as a type constraint which may include default values for object attributes. If successful both the resulting type and corresponding defaults are returned. If unsuccessful, error diagnostics are returned.

When using this function, defaults should be applied to the input value before type conversion, to ensure that objects with missing attributes have default values populated.

func (*Defaults) Apply

func (d *Defaults) Apply(val cty.Value) cty.Value

Apply walks the given value, applying specified defaults wherever optional attributes are missing. The input and output values may have different types, and the result may still require type conversion to the final desired type.

This function is permissive and does not report errors, assuming that the caller will have better context to report useful type conversion failure diagnostics.