]>
Commit | Line | Data |
---|---|---|
15c0b25d AP |
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 | ||
107c1cdb ND |
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 | ||
15c0b25d AP |
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 | ||
107c1cdb ND |
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 | ||
15c0b25d AP |
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 | ) |