lang

Documentation

Overview

Package lang deals with the runtime aspects of Terraform's configuration language, with concerns such as expression evaluation. It is closely related to sibling package "configs", which is responsible for configuration parsing and static validation.

Index

• func References(parseRef ParseRef, traversals []hcl.Traversal) ([]*addrs.Reference, tfdiags.Diagnostics)
• func ReferencesInBlock(parseRef ParseRef, body hcl.Body, schema *configschema.Block) ([]*addrs.Reference, tfdiags.Diagnostics)
• func ReferencesInExpr(parseRef ParseRef, expr hcl.Expression) ([]*addrs.Reference, tfdiags.Diagnostics)
• type Data
• type ParseRef
• type Scope
  • func (s *Scope) EvalBlock(body hcl.Body, schema *configschema.Block) (cty.Value, tfdiags.Diagnostics)
  • func (s *Scope) EvalContext(refs []*addrs.Reference) (*hcl.EvalContext, tfdiags.Diagnostics)
  • func (s *Scope) EvalExpr(expr hcl.Expression, wantType cty.Type) (cty.Value, tfdiags.Diagnostics)
  • func (s *Scope) EvalReference(ref *addrs.Reference, wantType cty.Type) (cty.Value, tfdiags.Diagnostics)
  • func (s *Scope) EvalSelfBlock(body hcl.Body, self cty.Value, schema *configschema.Block, ...) (cty.Value, tfdiags.Diagnostics)
  • func (s *Scope) ExpandBlock(body hcl.Body, schema *configschema.Block) (hcl.Body, tfdiags.Diagnostics)
  • func (s *Scope) Functions() map[string]function.Function
  • func (s *Scope) SetActiveExperiments(active experiments.Set)

Functions

func References

func References(parseRef ParseRef, traversals []hcl.Traversal) ([]*addrs.Reference, tfdiags.Diagnostics)

References finds all of the references in the given set of traversals, returning diagnostics if any of the traversals cannot be interpreted as a reference.

This function does not do any de-duplication of references, since references have source location information embedded in them and so any invalid references that are duplicated should have errors reported for each occurence.

If the returned diagnostics contains errors then the result may be incomplete or invalid. Otherwise, the returned slice has one reference per given traversal, though it is not guaranteed that the references will appear in the same order as the given traversals.

func ReferencesInBlock

func ReferencesInBlock(parseRef ParseRef, body hcl.Body, schema *configschema.Block) ([]*addrs.Reference, tfdiags.Diagnostics)

ReferencesInBlock is a helper wrapper around References that first searches the given body for traversals, before converting those traversals to references.

A block schema must be provided so that this function can determine where in the body variables are expected.

func ReferencesInExpr

func ReferencesInExpr(parseRef ParseRef, expr hcl.Expression) ([]*addrs.Reference, tfdiags.Diagnostics)

ReferencesInExpr is a helper wrapper around References that first searches the given expression for traversals, before converting those traversals to references.

Types

type Data

type Data interface {
	StaticValidateReferences(refs []*addrs.Reference, self addrs.Referenceable, source addrs.Referenceable) tfdiags.Diagnostics

	GetCountAttr(addrs.CountAttr, tfdiags.SourceRange) (cty.Value, tfdiags.Diagnostics)
	GetForEachAttr(addrs.ForEachAttr, tfdiags.SourceRange) (cty.Value, tfdiags.Diagnostics)
	GetResource(addrs.Resource, tfdiags.SourceRange) (cty.Value, tfdiags.Diagnostics)
	GetLocalValue(addrs.LocalValue, tfdiags.SourceRange) (cty.Value, tfdiags.Diagnostics)
	GetModule(addrs.ModuleCall, tfdiags.SourceRange) (cty.Value, tfdiags.Diagnostics)
	GetPathAttr(addrs.PathAttr, tfdiags.SourceRange) (cty.Value, tfdiags.Diagnostics)
	GetTerraformAttr(addrs.TerraformAttr, tfdiags.SourceRange) (cty.Value, tfdiags.Diagnostics)
	GetInputVariable(addrs.InputVariable, tfdiags.SourceRange) (cty.Value, tfdiags.Diagnostics)
	GetOutput(addrs.OutputValue, tfdiags.SourceRange) (cty.Value, tfdiags.Diagnostics)
	GetCheckBlock(addrs.Check, tfdiags.SourceRange) (cty.Value, tfdiags.Diagnostics)
}

Data is an interface whose implementations can provide cty.Value representations of objects identified by referenceable addresses from the addrs package.

This interface will grow each time a new type of reference is added, and so implementations outside of the Terraform codebases are not advised.

Each method returns a suitable value and optionally some diagnostics. If the returned diagnostics contains errors then the type of the returned value is used to construct an unknown value of the same type which is then used in place of the requested object so that type checking can still proceed. In cases where it's not possible to even determine a suitable result type, cty.DynamicVal is returned along with errors describing the problem.

type ParseRef

type ParseRef func(traversal hcl.Traversal) (*addrs.Reference, tfdiags.Diagnostics)

type Scope

type Scope struct {
	// Data is used to resolve references in expressions.
	Data Data

	// ParseRef is a function that the scope uses to extract references from
	// a hcl.Traversal. This controls the type of references the scope currently
	// supports. As an example, the testing scope can reference outputs directly
	// while the main Terraform context scope can not. This means that this
	// function for the testing scope will happily return outputs, while the
	// main context scope would fail if a user attempts to reference an output.
	ParseRef ParseRef

	// SelfAddr is the address that the "self" object should be an alias of,
	// or nil if the "self" object should not be available at all.
	SelfAddr addrs.Referenceable

	// SourceAddr is the address of the source item for the scope. This will
	// affect any scoped resources that can be accessed from within this scope.
	//
	// If nil, access is assumed to be at the module level. So, in practice this
	// only needs to be set for items that should be able to access something
	// hidden in their own scope.
	SourceAddr addrs.Referenceable

	// BaseDir is the base directory used by any interpolation functions that
	// accept filesystem paths as arguments.
	BaseDir string

	// PureOnly can be set to true to request that any non-pure functions
	// produce unknown value results rather than actually executing. This is
	// important during a plan phase to avoid generating results that could
	// then differ during apply.
	PureOnly bool

	// ConsoleMode can be set to true to request any console-only functions are
	// included in this scope.
	ConsoleMode bool

	// PlanTimestamp is a timestamp representing when the plan was made. It will
	// either have been generated during this operation or read from the plan.
	PlanTimestamp time.Time
	// contains filtered or unexported fields
}

Scope is the main type in this package, allowing dynamic evaluation of blocks and expressions based on some contextual information that informs which variables and functions will be available.

func (*Scope) EvalBlock

func (s *Scope) EvalBlock(body hcl.Body, schema *configschema.Block) (cty.Value, tfdiags.Diagnostics)

EvalBlock evaluates the given body using the given block schema and returns a cty object value representing its contents. The type of the result conforms to the implied type of the given schema.

This function does not automatically expand "dynamic" blocks within the body. If that is desired, first call the ExpandBlock method to obtain an expanded body to pass to this method.

If the returned diagnostics contains errors then the result may be incomplete or invalid.

func (*Scope) EvalContext

func (s *Scope) EvalContext(refs []*addrs.Reference) (*hcl.EvalContext, tfdiags.Diagnostics)

EvalContext constructs a HCL expression evaluation context whose variable scope contains sufficient values to satisfy the given set of references.

Most callers should prefer to use the evaluation helper methods that this type offers, but this is here for less common situations where the caller will handle the evaluation calls itself.

func (*Scope) EvalExpr

func (s *Scope) EvalExpr(expr hcl.Expression, wantType cty.Type) (cty.Value, tfdiags.Diagnostics)

EvalExpr evaluates a single expression in the receiving context and returns the resulting value. The value will be converted to the given type before it is returned if possible, or else an error diagnostic will be produced describing the conversion error.

Pass an expected type of cty.DynamicPseudoType to skip automatic conversion and just obtain the returned value directly.

If the returned diagnostics contains errors then the result may be incomplete, but will always be of the requested type.

func (*Scope) EvalReference

func (s *Scope) EvalReference(ref *addrs.Reference, wantType cty.Type) (cty.Value, tfdiags.Diagnostics)

EvalReference evaluates the given reference in the receiving scope and returns the resulting value. The value will be converted to the given type before it is returned if possible, or else an error diagnostic will be produced describing the conversion error.

Pass an expected type of cty.DynamicPseudoType to skip automatic conversion and just obtain the returned value directly.

If the returned diagnostics contains errors then the result may be incomplete, but will always be of the requested type.

func (*Scope) EvalSelfBlock

func (s *Scope) EvalSelfBlock(body hcl.Body, self cty.Value, schema *configschema.Block, keyData instances.RepetitionData) (cty.Value, tfdiags.Diagnostics)

EvalSelfBlock evaluates the given body only within the scope of the provided object and instance key data. References to the object must use self, and the key data will only contain count.index or each.key. The static values for terraform and path will also be available in this context.

func (*Scope) ExpandBlock

func (s *Scope) ExpandBlock(body hcl.Body, schema *configschema.Block) (hcl.Body, tfdiags.Diagnostics)

ExpandBlock expands any "dynamic" blocks present in the given body. The result is a body with those blocks expanded, ready to be evaluated with EvalBlock.

If the returned diagnostics contains errors then the result may be incomplete or invalid.

func (*Scope) Functions

func (s *Scope) Functions() map[string]function.Function

Functions returns the set of functions that should be used to when evaluating expressions in the receiving scope.

func (*Scope) SetActiveExperiments

func (s *Scope) SetActiveExperiments(active experiments.Set)

SetActiveExperiments allows a caller to declare that a set of experiments is active for the module that the receiving Scope belongs to, which might then cause the scope to activate some additional experimental behaviors.