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 MarshalJSON(ast *AST, options ...MarshalJSONOption) ([]byte, 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 Entry
- type MapEntry
- type MarshalJSONOption
- type MarshalOption
- type Node
- type Number
- type Position
- type Value
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddParentRefs ¶ added in v0.1.5
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 MarshalJSON ¶ added in v0.1.5
func MarshalJSON(ast *AST, options ...MarshalJSONOption) ([]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 ¶
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 ¶ added in v0.1.5
func UnmarshalBlock(block *Block, v interface{}, options ...MarshalOption) error
UnmarshalBlock into a struct.
Types ¶
type AST ¶
type AST struct { Pos lexer.Position `parser:"" json:"-"` Entries []*Entry `parser:"@@*" json:"entries,omitempty"` TrailingComments []string `parser:"@Comment*" json:"trailingComments,omitempty"` Schema bool `parser:"" json:"schema,omitempty"` }
AST for HCL.
func BlockSchema ¶ added in v0.1.5
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 ¶ added in v0.1.5
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 ¶ added in v0.1.5
func MustSchema(v interface{}, options ...MarshalOption) *AST
MustSchema constructs a schema from a Go type, or panics.
func Schema ¶ added in v0.1.5
func Schema(v interface{}, options ...MarshalOption) (*AST, error)
Schema reflects a schema from a Go value.
A schema is itself HCL.
func (*AST) MarshalJSON ¶ added in v0.1.5
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"` // This will be populated during unmarshalling. Default *Value `parser:"" json:"default,omitempty"` // This will be parsed from the enum tag and will be helping the validation during unmarshalling Enum []*Value `parser:"" json:"enum,omitempty"` // Set for schemas when the attribute is optional. Optional bool `parser:"" json:"optional,omitempty"` }
Attribute is a key+value attribute.
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:"trailingComments,omitempty"` // The block can be repeated. This is surfaced in schemas. Repeated bool `parser:"" json:"repeated,omitempty"` }
Block represents am optionally labelled HCL block.
type Entry ¶
type Entry struct { Pos lexer.Position `parser:"" json:"-"` Parent Node `parser:"" json:"-"` RecursiveSchema bool `parser:"" json:"-"` Block *Block `parser:"( @@" json:"block,omitempty"` Attribute *Attribute `parser:" | @@ )" json:"attribute,omitempty"` }
Entry at the top-level of a HCL file 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.
type MarshalJSONOption ¶ added in v0.1.11
type MarshalJSONOption func(o *marshalJSONOptions)
MarshalJSONOption implementations control how JSON is marshalled.
func IncludeComments ¶ added in v0.1.11
func IncludeComments(ok bool) MarshalJSONOption
IncludeComments includes comments as __comments__ attributes in the generated JSON.
type MarshalOption ¶ added in v0.1.9
type MarshalOption func(options *marshalState)
MarshalOption configures optional marshalling behaviour.
func AllowExtra ¶ added in v0.4.0
func AllowExtra(ok bool) MarshalOption
AllowExtra fields in configuration to be skipped.
func BareBooleanAttributes ¶ added in v0.1.12
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 ¶ added in v0.1.11
func HereDocsForMultiLine(n int) MarshalOption
HereDocsForMultiLine will marshal multi-line strings >= n lines as indented heredocs rather than quoted strings.
func InferHCLTags ¶ added in v0.1.9
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 ¶ added in v0.2.1
func WithSchemaComments(v bool) MarshalOption
WithSchemaComments will export the contents of the help struct tag as comments when marshaling.
type Node ¶
type Node interface {
// contains filtered or unexported methods
}
Node is the the interface implemented by all AST nodes.
type Number ¶ added in v0.1.13
Number of arbitrary precision.
type Value ¶
type Value struct { Pos lexer.Position `parser:"" json:"-"` Parent Node `parser:"" json:"-"` Bool *Bool `parser:"( @('true':Ident | 'false':Ident)" json:"bool,omitempty"` Number *Number `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:"heredocDelimiter,omitempty"` Heredoc *string `parser:" @(Body | EOL)* End)" json:"heredoc,omitempty"` HaveList bool `parser:" | ( @'['" json:"haveList,omitempty"` // Need this to detect empty lists. List []*Value `parser:" ( @@ ( ',' @@ )* )? ','? ']' )" json:"list,omitempty"` HaveMap bool `parser:" | ( @'{'" json:"haveMap,omitempty"` // Need this to detect empty maps. Map []*MapEntry `parser:" ( @@ ( ',' @@ )* ','? )? '}' ) )" json:"map,omitempty"` }
Value is a scalar, list or map.
func (*Value) GetHeredoc ¶ added in v0.1.5
GetHeredoc gets the heredoc as a string.
This will correctly format indented heredocs.