gohcl

package module
v0.0.0-...-5331269 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 9, 2022 License: MPL-2.0 Imports: 14 Imported by: 6

README

gohcl

NOTE: gohcl is a work in progress and may have many bugs, user beware.

gohcl is a fork of github.com/hashicorp/hcl/v2/gohcl and github.com/zclconf/go-cty/cty/gocty which includes improvements over the existing package at the expense of making backwards-incompatible changes to the API.

It makes the following changes:

  • Capsule types can be used through a registration system.
  • nil slices will return an empty go-cty list or go-cty set instead of null.
  • It is valid for capsule values to be nil.
  • hcl struct tags are used globally instead of a combination of hcl and cty tags.
  • Encoding a value into a HCL body will no longer clear the existing contents of the body.
  • Capsule types can be encoded as HCL attributes through the use of capsule extension operations; allowing a capsule type to return raw HCL tokens which represent the capsule value.
  • Special handling for time.Duration and binary.TextMarshaler/binary.TextUnmarshaler
  • Support for an interface which exposes a DecodeHCL method

Documentation

Overview

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
optional is the same as attr, but the field is optional
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 that can be converted into 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.

"body" can be placed on a single field of type hcl.Body to capture the full hcl.Body that was decoded for a block. This does not allow leftover values like "remain", so a decoding error will still be returned if leftover fields are given. If you want to capture the decoding body PLUS leftover fields, you must specify a "remain" field as well to prevent errors. The body field and the remain field will both contain the leftover fields.

"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.

"optional" fields behave like "attr" fields, but they are optional and will not give parsing errors if they are missing.

"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.

Values in Go structs must be convertible to and from cty values. Values which are unsupported by default can be registered as a cty capsule type by calling RegisterCapsuleType.

Index