4 "github.com/zclconf/go-cty/cty"
7 // File is the top-level node that results from parsing a HCL file.
12 // Nav is used to integrate with the "hcled" editor integration package,
13 // and with diagnostic information formatters. It is not for direct use
14 // by a calling application.
18 // Block represents a nested block within a Body.
24 DefRange Range // Range that can be considered the "definition" for seeking in an editor
25 TypeRange Range // Range for the block type declaration specifically.
26 LabelRanges []Range // Ranges for the label values specifically.
29 // Blocks is a sequence of Block.
32 // Attributes is a set of attributes keyed by their names.
33 type Attributes map[string]*Attribute
35 // Body is a container for attributes and blocks. It serves as the primary
36 // unit of heirarchical structure within configuration.
38 // The content of a body cannot be meaningfully intepreted without a schema,
39 // so Body represents the raw body content and has methods that allow the
40 // content to be extracted in terms of a given schema.
42 // Content verifies that the entire body content conforms to the given
43 // schema and then returns it, and/or returns diagnostics. The returned
44 // body content is valid if non-nil, regardless of whether Diagnostics
45 // are provided, but diagnostics should still be eventually shown to
47 Content(schema *BodySchema) (*BodyContent, Diagnostics)
49 // PartialContent is like Content except that it permits the configuration
50 // to contain additional blocks or attributes not specified in the
51 // schema. If any are present, the returned Body is non-nil and contains
52 // the remaining items from the body that were not selected by the schema.
53 PartialContent(schema *BodySchema) (*BodyContent, Body, Diagnostics)
55 // JustAttributes attempts to interpret all of the contents of the body
56 // as attributes, allowing for the contents to be accessed without a priori
57 // knowledge of the structure.
59 // The behavior of this method depends on the body's source language.
60 // Some languages, like JSON, can't distinguish between attributes and
61 // blocks without schema hints, but for languages that _can_ error
62 // diagnostics will be generated if any blocks are present in the body.
64 // Diagnostics may be produced for other reasons too, such as duplicate
65 // declarations of the same attribute.
66 JustAttributes() (Attributes, Diagnostics)
68 // MissingItemRange returns a range that represents where a missing item
69 // might hypothetically be inserted. This is used when producing
70 // diagnostics about missing required attributes or blocks. Not all bodies
71 // will have an obvious single insertion point, so the result here may
72 // be rather arbitrary.
73 MissingItemRange() Range
76 // BodyContent is the result of applying a BodySchema to a Body.
77 type BodyContent struct {
81 MissingItemRange Range
84 // Attribute represents an attribute from within a body.
85 type Attribute struct {
93 // Expression is a literal value or an expression provided in the
94 // configuration, which can be evaluated within a scope to produce a value.
95 type Expression interface {
96 // Value returns the value resulting from evaluating the expression
97 // in the given evaluation context.
99 // The context may be nil, in which case the expression may contain
100 // only constants and diagnostics will be produced for any non-constant
101 // sub-expressions. (The exact definition of this depends on the source
104 // The context may instead be set but have either its Variables or
105 // Functions maps set to nil, in which case only use of these features
106 // will return diagnostics.
108 // Different diagnostics are provided depending on whether the given
109 // context maps are nil or empty. In the former case, the message
110 // tells the user that variables/functions are not permitted at all,
111 // while in the latter case usage will produce a "not found" error for
112 // the specific symbol in question.
113 Value(ctx *EvalContext) (cty.Value, Diagnostics)
115 // Variables returns a list of variables referenced in the receiving
116 // expression. These are expressed as absolute Traversals, so may include
117 // additional information about how the variable is used, such as
118 // attribute lookups, which the calling application can potentially use
119 // to only selectively populate the scope.
120 Variables() []Traversal
126 // OfType filters the receiving block sequence by block type name,
127 // returning a new block sequence including only the blocks of the
129 func (els Blocks) OfType(typeName string) Blocks {
130 ret := make(Blocks, 0)
131 for _, el := range els {
132 if el.Type == typeName {
133 ret = append(ret, el)
139 // ByType transforms the receiving block sequence into a map from type
140 // name to block sequences of only that type.
141 func (els Blocks) ByType() map[string]Blocks {
142 ret := make(map[string]Blocks)
143 for _, el := range els {
146 ret[ty] = make(Blocks, 0, 1)
148 ret[ty] = append(ret[ty], el)