github.com/terramate-io/tf@v0.0.0-20230830114523-fce866b4dfcd/lang/scope.go (about)

     1  // Copyright (c) HashiCorp, Inc.
     2  // SPDX-License-Identifier: MPL-2.0
     3  
     4  package lang
     5  
     6  import (
     7  	"sync"
     8  	"time"
     9  
    10  	"github.com/hashicorp/hcl/v2"
    11  	"github.com/zclconf/go-cty/cty/function"
    12  
    13  	"github.com/terramate-io/tf/addrs"
    14  	"github.com/terramate-io/tf/experiments"
    15  	"github.com/terramate-io/tf/tfdiags"
    16  )
    17  
    18  type ParseRef func(traversal hcl.Traversal) (*addrs.Reference, tfdiags.Diagnostics)
    19  
    20  // Scope is the main type in this package, allowing dynamic evaluation of
    21  // blocks and expressions based on some contextual information that informs
    22  // which variables and functions will be available.
    23  type Scope struct {
    24  	// Data is used to resolve references in expressions.
    25  	Data Data
    26  
    27  	// ParseRef is a function that the scope uses to extract references from
    28  	// a hcl.Traversal. This controls the type of references the scope currently
    29  	// supports. As an example, the testing scope can reference outputs directly
    30  	// while the main Terraform context scope can not. This means that this
    31  	// function for the testing scope will happily return outputs, while the
    32  	// main context scope would fail if a user attempts to reference an output.
    33  	ParseRef ParseRef
    34  
    35  	// SelfAddr is the address that the "self" object should be an alias of,
    36  	// or nil if the "self" object should not be available at all.
    37  	SelfAddr addrs.Referenceable
    38  
    39  	// SourceAddr is the address of the source item for the scope. This will
    40  	// affect any scoped resources that can be accessed from within this scope.
    41  	//
    42  	// If nil, access is assumed to be at the module level. So, in practice this
    43  	// only needs to be set for items that should be able to access something
    44  	// hidden in their own scope.
    45  	SourceAddr addrs.Referenceable
    46  
    47  	// BaseDir is the base directory used by any interpolation functions that
    48  	// accept filesystem paths as arguments.
    49  	BaseDir string
    50  
    51  	// PureOnly can be set to true to request that any non-pure functions
    52  	// produce unknown value results rather than actually executing. This is
    53  	// important during a plan phase to avoid generating results that could
    54  	// then differ during apply.
    55  	PureOnly bool
    56  
    57  	funcs     map[string]function.Function
    58  	funcsLock sync.Mutex
    59  
    60  	// activeExperiments is an optional set of experiments that should be
    61  	// considered as active in the module that this scope will be used for.
    62  	// Callers can populate it by calling the SetActiveExperiments method.
    63  	activeExperiments experiments.Set
    64  
    65  	// ConsoleMode can be set to true to request any console-only functions are
    66  	// included in this scope.
    67  	ConsoleMode bool
    68  
    69  	// PlanTimestamp is a timestamp representing when the plan was made. It will
    70  	// either have been generated during this operation or read from the plan.
    71  	PlanTimestamp time.Time
    72  }
    73  
    74  // SetActiveExperiments allows a caller to declare that a set of experiments
    75  // is active for the module that the receiving Scope belongs to, which might
    76  // then cause the scope to activate some additional experimental behaviors.
    77  func (s *Scope) SetActiveExperiments(active experiments.Set) {
    78  	s.activeExperiments = active
    79  }