]>
Commit | Line | Data |
---|---|---|
15c0b25d AP |
1 | // Package gohcl allows decoding HCL configurations into Go data structures. |
2 | // | |
3 | // It provides a convenient and concise way of describing the schema for | |
4 | // configuration and then accessing the resulting data via native Go | |
5 | // types. | |
6 | // | |
7 | // A struct field tag scheme is used, similar to other decoding and | |
8 | // unmarshalling libraries. The tags are formatted as in the following example: | |
9 | // | |
10 | // ThingType string `hcl:"thing_type,attr"` | |
11 | // | |
12 | // Within each tag there are two comma-separated tokens. The first is the | |
13 | // name of the corresponding construct in configuration, while the second | |
14 | // is a keyword giving the kind of construct expected. The following | |
15 | // kind keywords are supported: | |
16 | // | |
17 | // attr (the default) indicates that the value is to be populated from an attribute | |
18 | // block indicates that the value is to populated from a block | |
19 | // label indicates that the value is to populated from a block label | |
20 | // remain indicates that the value is to be populated from the remaining body after populating other fields | |
21 | // | |
22 | // "attr" fields may either be of type *hcl.Expression, in which case the raw | |
23 | // expression is assigned, or of any type accepted by gocty, in which case | |
24 | // gocty will be used to assign the value to a native Go type. | |
25 | // | |
26 | // "block" fields may be of type *hcl.Block or hcl.Body, in which case the | |
27 | // corresponding raw value is assigned, or may be a struct that recursively | |
28 | // uses the same tags. Block fields may also be slices of any of these types, | |
29 | // in which case multiple blocks of the corresponding type are decoded into | |
30 | // the slice. | |
31 | // | |
32 | // "label" fields are considered only in a struct used as the type of a field | |
33 | // marked as "block", and are used sequentially to capture the labels of | |
34 | // the blocks being decoded. In this case, the name token is used only as | |
35 | // an identifier for the label in diagnostic messages. | |
36 | // | |
37 | // "remain" can be placed on a single field that may be either of type | |
38 | // hcl.Body or hcl.Attributes, in which case any remaining body content is | |
39 | // placed into this field for delayed processing. If no "remain" field is | |
40 | // present then any attributes or blocks not matched by another valid tag | |
41 | // will cause an error diagnostic. | |
42 | // | |
107c1cdb ND |
43 | // Only a subset of this tagging/typing vocabulary is supported for the |
44 | // "Encode" family of functions. See the EncodeIntoBody docs for full details | |
45 | // on the constraints there. | |
46 | // | |
15c0b25d AP |
47 | // Broadly-speaking this package deals with two types of error. The first is |
48 | // errors in the configuration itself, which are returned as diagnostics | |
49 | // written with the configuration author as the target audience. The second | |
50 | // is bugs in the calling program, such as invalid struct tags, which are | |
51 | // surfaced via panics since there can be no useful runtime handling of such | |
52 | // errors and they should certainly not be returned to the user as diagnostics. | |
53 | package gohcl |