hclwrite

Documentation

Overview

Package hclwrite deals with the problem of generating HCL configuration and of making specific surgical changes to existing HCL configurations.

It operates at a different level of abstraction than the main HCL parser and AST, since details such as the placement of comments and newlines are preserved when unchanged.

Index

• Variables
• func Format(src []byte) []byte
• type Attribute
  • func (n *Attribute) Tokens() *TokenSeq
• type Block
  • func (n *Block) Tokens() *TokenSeq
• type Body
  • func (n *Body) AppendItem(node Node)
  • func (n *Body) AppendUnstructuredTokens(seq *TokenSeq)
  • func (n *Body) FindAttribute(name string) *Attribute
  • func (n *Body) SetAttributeTraversal(name string, traversal hcl.Traversal) *Attribute
  • func (n *Body) SetAttributeValue(name string, val cty.Value) *Attribute
  • func (n *Body) Tokens() *TokenSeq
• type Expression
  • func (n *Expression) Tokens() *TokenSeq
• type File
  • func ParseConfig(src []byte, filename string, start hcl.Pos) (*File, hcl.Diagnostics)
  • func (f *File) Bytes() []byte
  • func (f *File) Format()
  • func (f *File) WriteTo(wr io.Writer) (int, error)
• type Node
• type Token
  • func (t *Token) EachToken(cb TokenCallback)
• type TokenCallback
• type TokenGen
• type TokenSeq
  • func (ts *TokenSeq) EachToken(cb TokenCallback)
  • func (ts *TokenSeq) IsIdent(name []byte) bool
  • func (ts *TokenSeq) SoloToken() *Token
  • func (ts *TokenSeq) Tokens() Tokens
  • func (ts *TokenSeq) WriteTo(wr io.Writer) (int, error)
• type Tokens
  • func (ts Tokens) Bytes() []byte
  • func (ts Tokens) Columns() int
  • func (ts Tokens) EachToken(cb TokenCallback)
  • func (ts Tokens) WriteTo(wr io.Writer) (int, error)
• type VarRef
  • func (n *VarRef) Tokens() *TokenSeq

Variables

var TokenSeqEmpty = TokenSeq([]TokenGen(nil))

TokenSeqEmpty is a TokenSeq that contains no tokens. It can be used anywhere, but its primary purpose is to be assigned as a replacement for a non-empty TokenSeq when eliminating a section of an input file.

Functions

func Format

func Format(src []byte) []byte

Format takes source code and performs simple whitespace changes to transform it to a canonical layout style.

Format skips constructing an AST and works directly with tokens, so it is less expensive than formatting via the AST for situations where no other changes will be made. It also ignores syntax errors and can thus be applied to partial source code, although the result in that case may not be desirable.

Types

type Attribute

type Attribute struct {
	AllTokens *TokenSeq

	LeadCommentTokens *TokenSeq
	NameTokens        *TokenSeq
	EqualsTokens      *TokenSeq
	Expr              *Expression
	LineCommentTokens *TokenSeq
	EOLTokens         *TokenSeq
}

func (*Attribute) Tokens

func (n *Attribute) Tokens() *TokenSeq

type Block

type Block struct {
	AllTokens *TokenSeq

	LeadCommentTokens *TokenSeq
	TypeTokens        *TokenSeq
	LabelTokens       []*TokenSeq
	LabelTokensFlat   *TokenSeq
	OBraceTokens      *TokenSeq
	Body              *Body
	CBraceTokens      *TokenSeq
	EOLTokens         *TokenSeq
}

func (*Block) Tokens

func (n *Block) Tokens() *TokenSeq

type Body

type Body struct {
	// Items may contain Attribute, Block and Unstructured instances.
	// Items and AllTokens should be updated only by methods of this type,
	// since they must be kept synchronized for correct operation.
	Items     []Node
	AllTokens *TokenSeq

	// IndentLevel is the number of spaces that should appear at the start
	// of lines added within this body.
	IndentLevel int
}

func (*Body) AppendItem

func (n *Body) AppendItem(node Node)

func (*Body) AppendUnstructuredTokens

func (n *Body) AppendUnstructuredTokens(seq *TokenSeq)

func (*Body) FindAttribute

func (n *Body) FindAttribute(name string) *Attribute

FindAttribute returns the first attribute item from the body that has the given name, or returns nil if there is currently no matching attribute.

A valid AST has only one definition of each attribute, but that constraint is not enforced in the hclwrite AST, so a tree that has been mutated by other calls may contain additional matching attributes that cannot be seen by this method.

func (*Body) SetAttributeTraversal

func (n *Body) SetAttributeTraversal(name string, traversal hcl.Traversal) *Attribute

SetAttributeTraversal either replaces the expression of an existing attribute of the given name or adds a new attribute definition to the end of the block.

The new expression is given as a hcl.Traversal, which must be an absolute traversal. To set a literal value, use SetAttributeValue.

The return value is the attribute that was either modified in-place or created.

func (*Body) SetAttributeValue

func (n *Body) SetAttributeValue(name string, val cty.Value) *Attribute

SetAttributeValue either replaces the expression of an existing attribute of the given name or adds a new attribute definition to the end of the block.

The value is given as a cty.Value, and must therefore be a literal. To set a variable reference or other traversal, use SetAttributeTraversal.

The return value is the attribute that was either modified in-place or created.

func (*Body) Tokens

func (n *Body) Tokens() *TokenSeq

type Expression

type Expression struct {
	AllTokens *TokenSeq
	VarRefs   []*VarRef
}

func (*Expression) Tokens

func (n *Expression) Tokens() *TokenSeq

type File

type File struct {
	Name     string
	SrcBytes []byte

	Body      *Body
	AllTokens *TokenSeq
}

func ParseConfig

func ParseConfig(src []byte, filename string, start hcl.Pos) (*File, hcl.Diagnostics)

ParseConfig interprets the given source bytes into a *hclwrite.File. The resulting AST can be used to perform surgical edits on the source code before turning it back into bytes again.

func (*File) Bytes

func (f *File) Bytes() []byte

Bytes returns a buffer containing the source code resulting from the tokens underlying the receiving file. If any updates have been made via the AST API, these will be reflected in the result.

func (*File) Format

func (f *File) Format()

Format makes in-place modifications to the tokens underlying the receiving file in order to change the whitespace to be in canonical form.

func (*File) WriteTo

func (f *File) WriteTo(wr io.Writer) (int, error)

WriteTo writes the tokens underlying the receiving file to the given writer.

type Node

type Node interface {
	Tokens() *TokenSeq
	// contains filtered or unexported methods
}

type Token

type Token struct {
	Type  hclsyntax.TokenType
	Bytes []byte

	// We record the number of spaces before each token so that we can
	// reproduce the exact layout of the original file when we're making
	// surgical changes in-place. When _new_ code is created it will always
	// be in the canonical style, but we preserve layout of existing code.
	SpacesBefore int
}

Token is a single sequence of bytes annotated with a type. It is similar in purpose to hclsyntax.Token, but discards the source position information since that is not useful in code generation.

func (*Token) EachToken

func (t *Token) EachToken(cb TokenCallback)

type TokenCallback

type TokenCallback func(*Token)

TokenCallback is used with TokenGen implementations to specify the action that is to be taken for each token in the flattened token sequence.

type TokenGen

type TokenGen interface {
	EachToken(TokenCallback)
}

TokenGen is an abstract type that can append tokens to a list. It is the low-level foundation underlying the hclwrite AST; the AST provides a convenient abstraction over raw token sequences to facilitate common tasks, but it's also possible to directly manipulate the tree of token generators to make changes that the AST API doesn't directly allow.

type TokenSeq

type TokenSeq []TokenGen

TokenSeq combines zero or more TokenGens together to produce a flat sequence of tokens from a tree of TokenGens.

func (*TokenSeq) EachToken

func (ts *TokenSeq) EachToken(cb TokenCallback)

func (*TokenSeq) IsIdent

func (ts *TokenSeq) IsIdent(name []byte) bool

IsIdent returns true if and only if the token sequence represents a single ident token whose name matches the given string.

func (*TokenSeq) SoloToken

func (ts *TokenSeq) SoloToken() *Token

SoloToken returns the single token represented by the receiving sequence, or nil if the sequence does not represent exactly one token.

func (*TokenSeq) Tokens

func (ts *TokenSeq) Tokens() Tokens

Tokens returns the flat list of tokens represented by the receiving token sequence.

func (*TokenSeq) WriteTo

func (ts *TokenSeq) WriteTo(wr io.Writer) (int, error)

WriteTo takes an io.Writer and writes the bytes for each token to it, along with the spacing that separates each token. In other words, this allows serializing the tokens to a file or other such byte stream.

type Tokens

type Tokens []*Token

Tokens is a flat list of tokens.

func (Tokens) Bytes

func (ts Tokens) Bytes() []byte

func (Tokens) Columns

func (ts Tokens) Columns() int

Columns returns the number of columns (grapheme clusters) the token sequence occupies. The result is not meaningful if there are newline or single-line comment tokens in the sequence.

func (Tokens) EachToken

func (ts Tokens) EachToken(cb TokenCallback)

func (Tokens) WriteTo

func (ts Tokens) WriteTo(wr io.Writer) (int, error)

type VarRef

type VarRef struct {
	// Tokens alternate between TokenIdent and TokenDot, with the first
	// and last elements always being TokenIdent.
	AllTokens *TokenSeq
}

func (*VarRef) Tokens

func (n *VarRef) Tokens() *TokenSeq