vendor/github.com/hashicorp/terraform/configs/configschema/schema.go

   1 package configschema
   2
   3 import (
   4         "github.com/zclconf/go-cty/cty"
   5 )
   6
   7 // Block represents a configuration block.
   8 //
   9 // "Block" here is a logical grouping construct, though it happens to map
  10 // directly onto the physical block syntax of Terraform's native configuration
  11 // syntax. It may be a more a matter of convention in other syntaxes, such as
  12 // JSON.
  13 //
  14 // When converted to a value, a Block always becomes an instance of an object
  15 // type derived from its defined attributes and nested blocks
  16 type Block struct {
  17         // Attributes describes any attributes that may appear directly inside
  18         // the block.
  19         Attributes map[string]*Attribute
  20
  21         // BlockTypes describes any nested block types that may appear directly
  22         // inside the block.
  23         BlockTypes map[string]*NestedBlock
  24 }
  25
  26 // Attribute represents a configuration attribute, within a block.
  27 type Attribute struct {
  28         // Type is a type specification that the attribute's value must conform to.
  29         Type cty.Type
  30
  31         // Description is an English-language description of the purpose and
  32         // usage of the attribute. A description should be concise and use only
  33         // one or two sentences, leaving full definition to longer-form
  34         // documentation defined elsewhere.
  35         Description string
  36
  37         // Required, if set to true, specifies that an omitted or null value is
  38         // not permitted.
  39         Required bool
  40
  41         // Optional, if set to true, specifies that an omitted or null value is
  42         // permitted. This field conflicts with Required.
  43         Optional bool
  44
  45         // Computed, if set to true, specifies that the value comes from the
  46         // provider rather than from configuration. If combined with Optional,
  47         // then the config may optionally provide an overridden value.
  48         Computed bool
  49
  50         // Sensitive, if set to true, indicates that an attribute may contain
  51         // sensitive information.
  52         //
  53         // At present nothing is done with this information, but callers are
  54         // encouraged to set it where appropriate so that it may be used in the
  55         // future to help Terraform mask sensitive information. (Terraform
  56         // currently achieves this in a limited sense via other mechanisms.)
  57         Sensitive bool
  58 }
  59
  60 // NestedBlock represents the embedding of one block within another.
  61 type NestedBlock struct {
  62         // Block is the description of the block that's nested.
  63         Block
  64
  65         // Nesting provides the nesting mode for the child block, which determines
  66         // how many instances of the block are allowed, how many labels it expects,
  67         // and how the resulting data will be converted into a data structure.
  68         Nesting NestingMode
  69
  70         // MinItems and MaxItems set, for the NestingList and NestingSet nesting
  71         // modes, lower and upper limits on the number of child blocks allowed
  72         // of the given type. If both are left at zero, no limit is applied.
  73         //
  74         // As a special case, both values can be set to 1 for NestingSingle in
  75         // order to indicate that a particular single block is required.
  76         //
  77         // These fields are ignored for other nesting modes and must both be left
  78         // at zero.
  79         MinItems, MaxItems int
  80 }
  81
  82 // NestingMode is an enumeration of modes for nesting blocks inside other
  83 // blocks.
  84 type NestingMode int
  85
  86 //go:generate stringer -type=NestingMode
  87
  88 const (
  89         nestingModeInvalid NestingMode = iota
  90
  91         // NestingSingle indicates that only a single instance of a given
  92         // block type is permitted, with no labels, and its content should be
  93         // provided directly as an object value.
  94         NestingSingle
  95
  96         // NestingGroup is similar to NestingSingle in that it calls for only a
  97         // single instance of a given block type with no labels, but it additonally
  98         // guarantees that its result will never be null, even if the block is
  99         // absent, and instead the nested attributes and blocks will be treated
 100         // as absent in that case. (Any required attributes or blocks within the
 101         // nested block are not enforced unless the block is explicitly present
 102         // in the configuration, so they are all effectively optional when the
 103         // block is not present.)
 104         //
 105         // This is useful for the situation where a remote API has a feature that
 106         // is always enabled but has a group of settings related to that feature
 107         // that themselves have default values. By using NestingGroup instead of
 108         // NestingSingle in that case, generated plans will show the block as
 109         // present even when not present in configuration, thus allowing any
 110         // default values within to be displayed to the user.
 111         NestingGroup
 112
 113         // NestingList indicates that multiple blocks of the given type are
 114         // permitted, with no labels, and that their corresponding objects should
 115         // be provided in a list.
 116         NestingList
 117
 118         // NestingSet indicates that multiple blocks of the given type are
 119         // permitted, with no labels, and that their corresponding objects should
 120         // be provided in a set.
 121         NestingSet
 122
 123         // NestingMap indicates that multiple blocks of the given type are
 124         // permitted, each with a single label, and that their corresponding
 125         // objects should be provided in a map whose keys are the labels.
 126         //
 127         // It's an error, therefore, to use the same label value on multiple
 128         // blocks.
 129         NestingMap
 130 )