hcl

package module
v2.6.0 Latest Latest
Warning

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

 Go to latest Published: Feb 7, 2026 License: MIT Imports: 15 Imported by: 1

README

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

CircleCI Go Report Card Slack chat

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.
embed Flattens the fields of a struct into the parent, as opposed to block which wraps them in a named block. The field must be a struct or pointer to struct.
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

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddParentRefs 

func AddParentRefs(node Node) error

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 

func MarshalAST(ast Node) ([]byte, error)

MarshalAST marshals an AST to HCL bytes.

func MarshalASTToWriter 

func MarshalASTToWriter(ast Node, w io.Writer) error

MarshalASTToWriter marshals a hcl.AST to an io.Writer.

func StripComments 

func StripComments(node Node) error

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.

func Visit 

func Visit(node Node, visitor func(node Node, next func() error) error) error

Visit nodes in the AST.

"next" may be called to continue traversal of child nodes.

Types

type AST 

type AST struct {
	Pos lexer.Position `parser:""`

	Entries          Entries `parser:"@@*"`
	TrailingComments CommentList
	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 Parse 

func Parse(r io.Reader, options ...ParseOption) (*AST, error)

Parse HCL from an io.Reader.

func ParseBytes 

func ParseBytes(data []byte, options ...ParseOption) (*AST, error)

ParseBytes parses HCL from bytes.

func ParseString 

func ParseString(str string, options ...ParseOption) (*AST, error)

ParseString parses HCL from a string.

func Schema 

func Schema(v interface{}, options ...MarshalOption) (*AST, error)

Schema reflects a schema from a Go value.

A schema is itself HCL.

func (*AST) Children added in v2.6.0 

func (a *AST) Children() Entries

func (*AST) Clone 

func (a *AST) Clone() *AST

Clone the AST.

func (*AST) Detach 

func (a *AST) Detach() bool

func (*AST) Position 

func (a *AST) Position() Position

type Attribute 

type Attribute struct {
	Pos    lexer.Position `parser:""`
	Parent Node           `parser:""`

	Comments CommentList

	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.

func (*Attribute) Clone 

func (a *Attribute) Clone() Entry

Clone the AST.

func (*Attribute) Detach 

func (a *Attribute) Detach() bool

func (*Attribute) EntryKey 

func (a *Attribute) EntryKey() string

func (*Attribute) Position 

func (a *Attribute) Position() Position

func (*Attribute) String 

func (a *Attribute) String() string

type Block 

type Block struct {
	Pos    lexer.Position `parser:""`
	Parent Node           `parser:""`

	Comments CommentList

	Name     string   `parser:"@Ident"`
	Repeated bool     `parser:"( '(' @'repeated' ')' )?"`
	Labels   []string `parser:"@( Ident | String )*"`
	Body     Entries  `parser:"'{' @@* '}'"`

	TrailingComments CommentList
}

Block represents am optionally labelled HCL block.

func (*Block) Children added in v2.6.0 

func (b *Block) Children() Entries

func (*Block) Clone 

func (b *Block) Clone() Entry

Clone the AST.

func (*Block) Detach 

func (b *Block) Detach() bool

Detach Block from parent.

func (*Block) EntryKey 

func (b *Block) EntryKey() string

EntryKey implements Entry

func (*Block) Position 

func (b *Block) Position() Position

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.

func (*Bool) Capture 

func (b *Bool) Capture(values []string) error

func (*Bool) Clone 

func (b *Bool) Clone() Value

func (*Bool) Detach 

func (b *Bool) Detach() bool

func (*Bool) Position 

func (b *Bool) Position() lexer.Position

func (*Bool) String 

func (b *Bool) String() string

type Call 

type Call struct {
	Pos    lexer.Position `parser:""`
	Parent Node           `parser:""`

	Args []Value `parser:"'(' @@ ( ',' @@ )* ')'"`
}

Call represents a function call.

func (*Call) Clone 

func (f *Call) Clone() *Call

func (*Call) Detach 

func (f *Call) Detach() bool

func (*Call) Position 

func (f *Call) Position() lexer.Position

func (*Call) String 

func (f *Call) String() string

type Comment added in v2.3.0 

type Comment struct {
	Pos    lexer.Position `parser:""`
	EndPos lexer.Position `parser:""`
	Parent Node           `parser:""`

	Comments CommentList `parser:"@Comment"`
}

func (*Comment) Clone added in v2.3.0 

func (a *Comment) Clone() Entry

Clone the AST.

func (*Comment) Detach added in v2.3.0 

func (a *Comment) Detach() bool

func (*Comment) EndPosition added in v2.3.0 

func (a *Comment) EndPosition() Position

func (*Comment) EntryKey added in v2.3.0 

func (a *Comment) EntryKey() string

func (*Comment) Position added in v2.3.0 

func (a *Comment) Position() Position

func (*Comment) String added in v2.3.0 

func (a *Comment) String() string

type CommentList added in v2.3.0 

type CommentList []string

CommentList represents a list of comments that can handle multiline comment splitting

func (*CommentList) Capture added in v2.3.0 

func (c *CommentList) Capture(values []string) error

Capture implements the participle Capture interface to split multiline comments

type Entries 

type Entries []Entry

Entries in the root of the AST or a Block.

func (Entries) MarshalJSON 

func (e Entries) MarshalJSON() ([]byte, error)

type Entry 

type Entry interface {
	Detach() bool
	Clone() Entry
	EntryKey() string
	Node
}

Entry at the top-level of a HCL file or block.

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) Clone 

func (h *Heredoc) Clone() Value

func (*Heredoc) Detach 

func (h *Heredoc) Detach() bool

func (*Heredoc) GetHeredoc 

func (h *Heredoc) GetHeredoc() string

GetHeredoc gets the heredoc as a string.

This will correctly format indented heredocs.

func (*Heredoc) Position 

func (h *Heredoc) Position() lexer.Position

func (*Heredoc) String 

func (h *Heredoc) String() string

type List 

type List struct {
	Pos    lexer.Position `parser:""`
	Parent Node           `parser:""`

	List []Value `parser:"( '[' ( @@ ( ',' @@ )* )? ','? ']' )"`
}

A List of values.

func (*List) Clone 

func (l *List) Clone() Value

func (*List) Detach 

func (l *List) Detach() bool

func (*List) Position 

func (l *List) Position() lexer.Position

func (*List) String 

func (l *List) String() string

type Map 

type Map struct {
	Pos    lexer.Position `parser:""`
	Parent Node           `parser:""`

	Entries []*MapEntry `parser:"( '{' ( @@ ( ',' @@ )* ','? )? '}' )"`
}

A Map of key to value.

func (*Map) Clone 

func (m *Map) Clone() Value

func (*Map) Detach 

func (m *Map) Detach() bool

func (*Map) Position 

func (m *Map) Position() lexer.Position

func (*Map) String 

func (m *Map) String() string

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.

func (*MapEntry) Clone 

func (e *MapEntry) Clone() *MapEntry

Clone the AST.

func (*MapEntry) Detach 

func (e *MapEntry) Detach() bool

func (*MapEntry) Position 

func (e *MapEntry) Position() Position

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 HydratedImplicitBlocks added in v2.6.0 

func HydratedImplicitBlocks(v bool) MarshalOption

HydratedImplicitBlocks will treat single (non-repeated) blocks as always present during unmarshalling, even if absent from the config. This causes defaults within those blocks to be applied and required fields to be enforced.

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 WithDefaultTransformer added in v2.4.0 

func WithDefaultTransformer(transformer func(string) string) MarshalOption

WithDefaultTransformer allows custom processing of default values in struct tags.

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.

func Find 

func Find(node Node, names ...string) (nodes []Node)

Find and return blocks, attributes or map entries with the given key.

type Number 

type Number struct {
	Pos    lexer.Position `parser:""`
	Parent Node           `parser:""`

	Float *big.Float `parser:"@Number"`
}

Number of arbitrary precision.

func (*Number) Clone 

func (n *Number) Clone() Value

func (*Number) Detach 

func (n *Number) Detach() bool

func (*Number) GoString 

func (n *Number) GoString() string

func (*Number) Parse 

func (n *Number) Parse(lex *lexer.PeekingLexer) error

Parse override because big.Float doesn't directly support 0-prefix octal parsing... why?

func (*Number) Position 

func (n *Number) Position() lexer.Position

func (*Number) String 

func (n *Number) String() string

type ParseOption added in v2.3.0 

type ParseOption func(*parseConfig)

ParseOption represents a functional option for Parse, ParseString, and ParseBytes.

func WithDetachedComments added in v2.3.0 

func WithDetachedComments(preserve bool) ParseOption

WithDetachedComments controls whether comments that are not directly associated with a block or attribute are preserved in the AST. If set to false (default), detached comments will be stripped from the AST during post-processing. If set to true, detached comments will be preserved as separate entries in the AST.

type Position 

type Position = lexer.Position

Position in source file.

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.

func (*String) Clone 

func (s *String) Clone() Value

func (*String) Detach 

func (s *String) Detach() bool

func (*String) Position 

func (s *String) Position() lexer.Position

func (*String) String 

func (s *String) String() string

type Type 

type Type struct {
	Pos    lexer.Position `parser:""`
	Parent Node           `parser:""`

	Type string `parser:"@('string':Ident | 'number':Ident | 'boolean':Ident)"`
}

Type of a Value.

func (*Type) Clone 

func (t *Type) Clone() Value

func (*Type) Detach 

func (t *Type) Detach() bool

func (*Type) Position 

func (t *Type) Position() lexer.Position

func (*Type) String 

func (t *Type) String() string

type Value 

type Value interface {
	Clone() Value
	String() string
	Node
	// contains filtered or unexported methods
}

Value represents a terminal value, either scalar or a map or list.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.