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