github.com/terramate-io/tf@v0.0.0-20230830114523-fce866b4dfcd/configs/configschema/schema.go (about)

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