1b9738a196
These are wrappers around the lower-level hclwrite package that are able to reverse a subset of the behavior of the Decode functions to populate an hclwrite DOM. They are not fully symmetrical with DecodeBody because that function can leave certain parts of the configuration in its opaque form for later decoding, and these encode functions don't have enough information to repack that abstract/opaque form into new source code. In practice we expect that callers using complex techniques like partial decoding will also use more complex techniques with the hclwrite API directly, since they will need to coordinate partial _encoding_ of data that has been portioned off into separate structures, which gohcl is not equipped to do itself.
54 lines
2.8 KiB
Go
54 lines
2.8 KiB
Go
// Package gohcl allows decoding HCL configurations into Go data structures.
|
|
//
|
|
// It provides a convenient and concise way of describing the schema for
|
|
// configuration and then accessing the resulting data via native Go
|
|
// types.
|
|
//
|
|
// A struct field tag scheme is used, similar to other decoding and
|
|
// unmarshalling libraries. The tags are formatted as in the following example:
|
|
//
|
|
// ThingType string `hcl:"thing_type,attr"`
|
|
//
|
|
// Within each tag there are two comma-separated tokens. The first is the
|
|
// name of the corresponding construct in configuration, while the second
|
|
// is a keyword giving the kind of construct expected. The following
|
|
// kind keywords are supported:
|
|
//
|
|
// attr (the default) indicates that the value is to be populated from an attribute
|
|
// block indicates that the value is to populated from a block
|
|
// label indicates that the value is to populated from a block label
|
|
// remain indicates that the value is to be populated from the remaining body after populating other fields
|
|
//
|
|
// "attr" fields may either be of type *hcl.Expression, in which case the raw
|
|
// expression is assigned, or of any type accepted by gocty, in which case
|
|
// gocty will be used to assign the value to a native Go type.
|
|
//
|
|
// "block" fields may be of type *hcl.Block or hcl.Body, in which case the
|
|
// corresponding raw value is assigned, or may be a struct that recursively
|
|
// uses the same tags. Block fields may also be slices of any of these types,
|
|
// in which case multiple blocks of the corresponding type are decoded into
|
|
// the slice.
|
|
//
|
|
// "label" fields are considered only in a struct used as the type of a field
|
|
// marked as "block", and are used sequentially to capture the labels of
|
|
// the blocks being decoded. In this case, the name token is used only as
|
|
// an identifier for the label in diagnostic messages.
|
|
//
|
|
// "remain" can be placed on a single field that may be either of type
|
|
// hcl.Body or hcl.Attributes, in which case any remaining body content is
|
|
// placed into this field for delayed processing. If no "remain" field is
|
|
// present then any attributes or blocks not matched by another valid tag
|
|
// will cause an error diagnostic.
|
|
//
|
|
// Only a subset of this tagging/typing vocabulary is supported for the
|
|
// "Encode" family of functions. See the EncodeIntoBody docs for full details
|
|
// on the constraints there.
|
|
//
|
|
// Broadly-speaking this package deals with two types of error. The first is
|
|
// errors in the configuration itself, which are returned as diagnostics
|
|
// written with the configuration author as the target audience. The second
|
|
// is bugs in the calling program, such as invalid struct tags, which are
|
|
// surfaced via panics since there can be no useful runtime handling of such
|
|
// errors and they should certainly not be returned to the user as diagnostics.
|
|
package gohcl
|