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 Entries
- type Entry
- type Heredoc
- type List
- type Map
- type MapEntry
- type MarshalJSONOption
- 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 MarshalJSON ¶
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 ¶
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 Entries `parser:"@@*" json:"entries,omitempty"` TrailingComments []string `parser:"@Comment*" json:"trailingComments,omitempty"` Schema bool `parser:"" json:"schema,omitempty"` }
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.
func (*AST) MarshalJSON ¶
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 Entries `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 Bool ¶
type Bool struct { Pos lexer.Position `parser:"" json:"-"` Parent Node `parser:"" json:"-"` Bool bool `parser:"@'true' | 'false'" json:"bool,omitempty"` }
Bool represents a parsed boolean value.
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:"" json:"-"` Parent Node `parser:"" json:"-"` Delimiter string `parser:"(@Heredoc" json:"heredocDelimiter,omitempty"` Doc string `parser:" @(Body | EOL)* End)" json:"heredoc,omitempty"` }
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:"" json:"-"` Parent Node `parser:"" json:"-"` List []Value `parser:"( '[' ( @@ ( ',' @@ )* )? ','? ']' )" json:"list,omitempty"` }
A List of values.
type Map ¶
type Map struct { Pos lexer.Position `parser:"" json:"-"` Parent Node `parser:"" json:"-"` Entries []*MapEntry `parser:"( '{' ( @@ ( ',' @@ )* ','? )? '}' )" json:"map,omitempty"` }
A Map of key to value.
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 ¶
type MarshalJSONOption func(o *marshalJSONOptions)
MarshalJSONOption implementations control how JSON is marshalled.
func IncludeComments ¶
func IncludeComments(ok bool) MarshalJSONOption
IncludeComments includes comments as __comments__ attributes in the generated JSON.
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:"" json:"-"` Parent Node `parser:"" json:"-"` Float *big.Float `parser:"@Number" json:"number,omitempty"` }
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:"" json:"-"` Parent Node `parser:"" json:"-"` Str string `parser:"@(String | Ident)" json:"str,omitempty"` }
String literal.