README
¶
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
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, partial comments (via the help:"" tag). |
| AST | Go | Structure, values. |
Schema reflection
HCL has no real concept of schemas (that I can find), but there is precedent for something similar in Terraform variable
definition files. This package supports reflecting a rudimentary schema from Go, where the value for each attribute is
one of the scalar types number, string or boolean. Lists and maps are typed by example.
Here's an example schema.
// A string field.
str = string
num = number
bool = boolean
list = [string]
// A map.
map = {
string: number,
}
// A block.
block "name" {
attr = string
}
// Repeated blocks.
block_slice "label0" "label1" {
attr = string
}
Comments are from help:"" tags. See schema_test.go for
details.
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 must be of type []hcl.Entry. |
Additionally, a separate help:"" tag can be specified to populate comment fields in the AST when serialising Go
structures.
Position
Any block with a field named Pos of the type hcl.Position will have that field populated with positional
information:
Pos Position `hcl:"-"`
Documentation
¶
Overview ¶
Package hcl implements parsing, encoding and decoding of HCL from Go types.
Its purpose is to provide idiomatic Go functions and types for HCL.
Index ¶
- func AddParentRefs(node Node) error
- func Marshal(v interface{}, options ...MarshalOption) ([]byte, error)
- func MarshalAST(ast Node) ([]byte, error)
- func MarshalASTToWriter(ast Node, w io.Writer) error
- func StripComments(node Node) error
- func Unmarshal(data []byte, v interface{}, options ...MarshalOption) error
- func UnmarshalAST(ast *AST, v interface{}, options ...MarshalOption) error
- func UnmarshalBlock(block *Block, v interface{}, options ...MarshalOption) error
- func Visit(node Node, visitor func(node Node, next func() error) error) error
- type AST
- func BlockSchema(name string, v interface{}, options ...MarshalOption) (*AST, error)
- func MarshalToAST(v interface{}, options ...MarshalOption) (*AST, error)
- func MustBlockSchema(name string, v interface{}, options ...MarshalOption) *AST
- func MustSchema(v interface{}, options ...MarshalOption) *AST
- func Parse(r io.Reader) (*AST, error)
- func ParseBytes(data []byte) (*AST, error)
- func ParseString(str string) (*AST, error)
- func Schema(v interface{}, options ...MarshalOption) (*AST, error)
- type Attribute
- type Block
- type Bool
- type Call
- type Entries
- type Entry
- type Heredoc
- type List
- type Map
- type MapEntry
- type MarshalOption
- type Node
- type Number
- type Position
- type RecursiveEntry
- type String
- type Type
- type Value
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddParentRefs ¶
AddParentRefs recursively updates an AST's parent references.
This is called automatically during Parse*(), but can be called on a manually constructed AST.
func Marshal ¶
func Marshal(v interface{}, options ...MarshalOption) ([]byte, error)
Marshal a Go type to HCL.
func MarshalAST ¶
MarshalAST marshals an AST to HCL bytes.
func MarshalASTToWriter ¶
MarshalASTToWriter marshals a hcl.AST to an io.Writer.
func StripComments ¶
StripComments recursively from an AST node.
func Unmarshal ¶
func Unmarshal(data []byte, v interface{}, options ...MarshalOption) error
Unmarshal HCL into a Go struct.
func UnmarshalAST ¶
func UnmarshalAST(ast *AST, v interface{}, options ...MarshalOption) error
UnmarshalAST unmarshalls an already parsed or constructed AST into a Go struct.
func UnmarshalBlock ¶
func UnmarshalBlock(block *Block, v interface{}, options ...MarshalOption) error
UnmarshalBlock into a struct.
Types ¶
type AST ¶
type AST struct {
Pos lexer.Position `parser:""`
Entries Entries `parser:"@@*"`
TrailingComments []string `parser:"@Comment*"`
Schema bool `parser:""`
}
AST for HCL.
func BlockSchema ¶
func BlockSchema(name string, v interface{}, options ...MarshalOption) (*AST, error)
BlockSchema reflects a block schema for a Go struct.
func MarshalToAST ¶
func MarshalToAST(v interface{}, options ...MarshalOption) (*AST, error)
MarshalToAST marshals a Go type to a hcl.AST.
func MustBlockSchema ¶
func MustBlockSchema(name string, v interface{}, options ...MarshalOption) *AST
MustBlockSchema reflects a block schema from a Go struct, panicking if an error occurs.
func MustSchema ¶
func MustSchema(v interface{}, options ...MarshalOption) *AST
MustSchema constructs a schema from a Go type, or panics.
func Schema ¶
func Schema(v interface{}, options ...MarshalOption) (*AST, error)
Schema reflects a schema from a Go value.
A schema is itself HCL.
type Attribute ¶
type Attribute struct {
Pos lexer.Position `parser:""`
Parent Node `parser:""`
Comments []string `parser:"@Comment*"`
Key string `parser:"@Ident"`
Value Value `parser:"( '=':Punct @@ )?"`
Default Value `parser:"( '(' ( ( 'default' '(' @@ ')'"`
Enum []Value `parser:" | 'enum' '(' @@ (',' @@)* ')'"`
Optional bool `parser:" | @'optional' ) )+ ')' )?"`
}
Attribute is a key=value attribute.
type Block ¶
type Block struct {
Pos lexer.Position `parser:""`
Parent Node `parser:""`
Comments []string `parser:"@Comment*"`
Name string `parser:"@Ident"`
Repeated bool `parser:"( '(' @'repeated' ')' )?"`
Labels []string `parser:"@( Ident | String )*"`
Body Entries `parser:"'{' @@*"`
TrailingComments []string `parser:"@Comment* '}'"`
}
Block represents am optionally labelled HCL block.
type Bool ¶
type Bool struct {
Pos lexer.Position `parser:""`
Parent Node `parser:""`
Bool bool `parser:"@'true':Ident | 'false':Ident"`
}
Bool represents a parsed boolean value.
type Call ¶
type Call struct {
Pos lexer.Position `parser:""`
Parent Node `parser:""`
Args []Value `parser:"'(' @@ ( ',' @@ )* ')'"`
}
Call represents a function call.
type Entries ¶
type Entries []Entry
Entries in the root of the AST or a Block.
func (Entries) MarshalJSON ¶
type Heredoc ¶
type Heredoc struct {
Pos lexer.Position `parser:""`
Parent Node `parser:""`
Delimiter string `parser:"(@Heredoc"`
Doc string `parser:" @(Body | EOL)* End)"`
}
Heredoc represents a heredoc string.
func (*Heredoc) GetHeredoc ¶
GetHeredoc gets the heredoc as a string.
This will correctly format indented heredocs.
type List ¶
type List struct {
Pos lexer.Position `parser:""`
Parent Node `parser:""`
List []Value `parser:"( '[' ( @@ ( ',' @@ )* )? ','? ']' )"`
}
A List of values.
type Map ¶
type Map struct {
Pos lexer.Position `parser:""`
Parent Node `parser:""`
Entries []*MapEntry `parser:"( '{' ( @@ ( ',' @@ )* ','? )? '}' )"`
}
A Map of key to value.
type MapEntry ¶
type MapEntry struct {
Pos lexer.Position `parser:""`
Parent Node `parser:""`
Comments []string `parser:"@Comment*"`
Key Value `parser:"@@ ':'"`
Value Value `parser:"@@"`
}
MapEntry represents a key+value in a map.
type MarshalOption ¶
type MarshalOption func(options *marshalState)
MarshalOption configures optional marshalling behaviour.
func AllowExtra ¶
func AllowExtra(ok bool) MarshalOption
AllowExtra fields in configuration to be skipped.
func BareBooleanAttributes ¶
func BareBooleanAttributes(v bool) MarshalOption
BareBooleanAttributes specifies whether attributes without values will be treated as boolean true values.
eg.
attr
NOTE: This is non-standard HCL.
func HereDocsForMultiLine ¶
func HereDocsForMultiLine(n int) MarshalOption
HereDocsForMultiLine will marshal multi-line strings >= n lines as indented heredocs rather than quoted strings.
func InferHCLTags ¶
func InferHCLTags(v bool) MarshalOption
InferHCLTags specifies whether to infer behaviour if hcl:"" tags are not present.
This currently just means that all structs become blocks.
func WithSchemaComments ¶
func WithSchemaComments(v bool) MarshalOption
WithSchemaComments will export the contents of the help struct tag as comments when marshaling.
type Node ¶
type Node interface {
Position() Position
Detach() bool
// contains filtered or unexported methods
}
Node is the the interface implemented by all AST nodes.
type Number ¶
type Number struct {
Pos lexer.Position `parser:""`
Parent Node `parser:""`
Float *big.Float `parser:"@Number"`
}
Number of arbitrary precision.
type RecursiveEntry ¶
type RecursiveEntry struct{}
RecursiveEntry is an Entry representing that a schema is recursive.
func (*RecursiveEntry) Clone ¶
func (*RecursiveEntry) Clone() Entry
func (*RecursiveEntry) Detach ¶
func (*RecursiveEntry) Detach() bool
func (*RecursiveEntry) EntryKey ¶
func (*RecursiveEntry) EntryKey() string
func (*RecursiveEntry) Position ¶
func (*RecursiveEntry) Position() Position
type String ¶
type String struct {
Pos lexer.Position `parser:""`
Parent Node `parser:""`
Str string `parser:"@(String | Ident)"`
}
String literal.
Source Files