hcl

package module
v0.1.8 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2020 License: MIT Imports: 17 Imported by: 14

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

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 added in v0.1.5 

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{}) ([]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 MarshalJSON added in v0.1.5 

func MarshalJSON(ast *AST, options MarshalJSONOptions) ([]byte, error)

MarshalJSON gives fine-grained control over JSON marshaling of an AST.

Currently this just means that emission of comments can be controlled.

func StripComments 

func StripComments(node Node) error

StripComments recursively from an AST node.

func Unmarshal 

func Unmarshal(data []byte, v interface{}) error

Unmarshal HCL into a Go struct.

func UnmarshalAST 

func UnmarshalAST(ast *AST, v interface{}) error

UnmarshalAST unmarshals an already parsed or constructed AST into a Go struct.

func UnmarshalBlock added in v0.1.5 

func UnmarshalBlock(block *Block, v interface{}) error

UnmarshalBlock into a struct.

func Visit 

func Visit(node Node, visit 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:"" json:"-"`

	Entries          []*Entry `parser:"@@*" json:"entries,omitempty"`
	TrailingComments []string `parser:"@Comment*" json:"trailing_comments,omitempty"`
	Schema           bool     `parser:"" json:"schema,omitempty"`
}

AST for HCL.

func BlockSchema added in v0.1.5 

func BlockSchema(name string, v interface{}) (*AST, error)

BlockSchema reflects a block schema for a Go struct.

func MarshalToAST 

func MarshalToAST(v interface{}) (*AST, error)

MarshalToAST marshals a Go type to a hcl.AST.

func MustBlockSchema added in v0.1.5 

func MustBlockSchema(name string, v interface{}) *AST

MustBlockSchema reflects a block schema from a Go struct, panicking if an error occurs.

func MustSchema added in v0.1.5 

func MustSchema(v interface{}) *AST

MustSchema constructs a schema from a Go type, or panics.

func Parse 

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

Parse HCL from an io.Reader.

func ParseBytes 

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

ParseBytes parses HCL from bytes.

func ParseString 

func ParseString(str string) (*AST, error)

ParseString parses HCL from a string.

func Schema added in v0.1.5 

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

Schema reflects a schema from a Go value.

A schema is itself HCL.

func (*AST) Clone added in v0.1.5 

func (a *AST) Clone() *AST

Clone the AST.

func (*AST) MarshalJSON added in v0.1.5 

func (a *AST) MarshalJSON() ([]byte, error)

type Attribute 

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

	Comments []string `parser:"@Comment*" json:"comments,omitempty"`

	Key   string `parser:"@Ident '='" json:"key"`
	Value *Value `parser:"@@" json:"value"`

	// Set for schemas when the attribute is optional.
	Optional bool `parser:"" json:"optional,omitempty"`
}

Attribute is a key+value attribute.

func (*Attribute) Clone added in v0.1.5 

func (a *Attribute) Clone() *Attribute

Clone the AST.

func (*Attribute) String 

func (a *Attribute) String() string

type Block 

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

	Comments []string `parser:"@Comment*" json:"comments,omitempty"`

	Name   string   `parser:"@Ident" json:"name"`
	Labels []string `parser:"@( Ident | String )*" json:"labels,omitempty"`
	Body   []*Entry `parser:"'{' @@*" json:"body"`

	TrailingComments []string `parser:"@Comment* '}'" json:"trailing_comments,omitempty"`

	// The block can be repeated. This is surfaced in schemas.
	Repeated bool `parser:"" json:"repeated,omitempty"`
}

Block represents am optionally labelled HCL block.

func (*Block) Clone added in v0.1.5 

func (b *Block) Clone() *Block

Clone the AST.

type Bool 

type Bool bool

Bool represents a parsed boolean value.

func (*Bool) Capture 

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

type Entry 

type Entry struct {
	Pos    lexer.Position `parser:"" json:"-"`
	Parent Node           `parser:"" json:"-"`

	Attribute *Attribute `parser:"(   @@" json:"attribute,omitempty"`
	Block     *Block     `parser:"  | @@ )" json:"block,omitempty"`
}

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

func (*Entry) Clone added in v0.1.5 

func (e *Entry) Clone() *Entry

Clone the AST.

func (*Entry) Key 

func (e *Entry) Key() string

Key of the attribute or block.

type MapEntry 

type MapEntry struct {
	Pos    lexer.Position `parser:"" json:"-"`
	Parent Node           `parser:"" json:"-"`

	Comments []string `parser:"@Comment*" json:"comments,omitempty"`

	Key   *Value `parser:"@@ ':'" json:"key"`
	Value *Value `parser:"@@" json:"value"`
}

MapEntry represents a key+value in a map.

func (*MapEntry) Clone added in v0.1.5 

func (e *MapEntry) Clone() *MapEntry

Clone the AST.

type MarshalJSONOptions added in v0.1.5 

type MarshalJSONOptions struct {
	// Include comments as JSON attributes.
	Comments bool
}

MarshalJSONOptions controls how custom JSON marshaling is applied.

type Node 

type Node interface {
	// contains filtered or unexported methods
}

Node is the the interface implemented by all AST nodes.

type Value 

type Value struct {
	Pos    lexer.Position `parser:"" json:"-"`
	Parent Node           `parser:"" json:"-"`

	Bool             *Bool       `parser:"(  @('true' | 'false')" json:"bool,omitempty"`
	Number           *big.Float  `parser:" | @Number" json:"number,omitempty"`
	Type             *string     `parser:" | @('number':Ident | 'string':Ident | 'boolean':Ident)" json:"type,omitempty"`
	Str              *string     `parser:" | @(String | Ident)" json:"str,omitempty"`
	HeredocDelimiter string      `parser:" | (@Heredoc" json:"heredoc_delimiter,omitempty"`
	Heredoc          *string     `parser:"     @(Body | EOL)* End)" json:"heredoc,omitempty"`
	HaveList         bool        `parser:" | ( @'['" json:"have_list,omitempty"` // Need this to detect empty lists.
	List             []*Value    `parser:"     ( @@ ( ',' @@ )* )? ','? ']' )" json:"list,omitempty"`
	HaveMap          bool        `parser:" | ( @'{'" json:"have_map,omitempty"` // Need this to detect empty maps.
	Map              []*MapEntry `parser:"     ( @@ ( ',' @@ )* ','? )? '}' ) )" json:"map,omitempty"`
}

Value is a scalar, list or map.

func (*Value) Clone added in v0.1.5 

func (v *Value) Clone() *Value

Clone the AST.

func (*Value) GetHeredoc added in v0.1.5 

func (v *Value) GetHeredoc() string

GetHeredoc gets the heredoc as a string.

This will correctly format indented heredocs.

func (*Value) String 

func (v *Value) String() string

Source Files

View all Source files

Directories

Path Synopsis
hil module

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.