README.md

Parsing, encoding and decoding of HCL to and from Go types

This package provides idiomatic Go functions for marshalling and unmarshalling HCL, as well as an AST parser.

It supports the same tags as the Hashicorp hcl2 gohcl package, but is much less complex.

Unlike gohcl it also natively supports time.Duration, time.Time, encoding.TextUnmarshaler and json.Unmarshaler.

It is HCL1 compatible and does not support any HCL2 specific features.

Design

HCL -> AST -> Go -> AST -> HCL

Mapping can start from any point in this cycle.

Marshalling, unmarshalling, parsing and serialisation are all structurally isomorphic operations. That is, HCL can be deserialised into an AST or Go, or vice versa, and the structure on both ends will be identical.

HCL is always parsed into an AST before unmarshaling and, similarly, Go structures are always mapped to an AST before being serialised to HCL.

Between	And	Preserves
HCL	AST	Structure, values, order, comments.
HCL	Go	Structure, values.
AST	Go	Structure, values.

Struct field tags

The tag format is as with other similar serialisation packages:

hcl:"[<name>][,<option>]"

The supported options are:

Tag	Description
attr (default)	Specifies that the value is to be populated from an attribute.
block	Specifies that the value is to populated from a block.
label	Specifies that the value is to populated from a block label.
optional	As with attr, but the field is optional.
remain	Specifies that the value is to be populated from the remaining body after populating other fields. The field type must be hcl.Node.