Documentation

Overview

Package helm implements a generic config file writer, emitting templatized YAML documents. The documents are built up in memory from Scalar, List, and Mapping nodes, which all implement the Node interface.

Each node can have an associated comment, and be wrapped by a template block (any template action that encloses text and terminates with an {{end}}). For example:

map.Add("Answer", NewNode("42", Comment("A comment"), Block("if .Values.enabled")))

will generate:

# A comment
{{- if .Values.enabled }}
Answer: 42
{{- end }}

Scalar values are emitted as-is, that means the value needs to include quotes if it needs to be quoted to be valid YAML. Literal values are also not line-wrapped because that might break template expressions.

The only exception are literal values including newlines. These values will be emitted with newlines intact, and subsequent lines indented to match the document structure. This means lines containing literal newlines characters should not be quoted (and conversely, newlines in quoted strings need to be escaped, e.g. "\"Multiple\nLines\"".

An Encoder object holds an io.Writer target as well as additional encoding options, like the max line length for comments, or the YAML indentation level:

NewEncoder(os.Stdout, Indent(4), Wrap(80)).Encode(documentRoot)

Tricks:

* Throw an error if the the configuration cannot possibly work

list.Add(NewNode(`{{ fail "Cannot proceed" }}`, Block("if le (int .count) 0")))

* Use a block action to generate multiple list elements

  tcp := NewMapping()
  tcp.Set(Block("range $key, $value := .Values.tcp"))
  tcp.Add("name", NewNode("\"{{ $key }}-tcp\""))
  tcp.Add("containerPort", NewNode("$key"))
  tcp.Add("protocol", NewNode("TCP"))

  ports := NewList(Comment("List of TCP ports"))
  ports.Add(tcp)
  root.Add("ports", ports)

Generates this document:

  # List of TCP ports
  ports:
  {{- range $key, $value := .Values.tcp }}
  - name: "{{ $key }}-tcp"
    containerPort: $key
    protocol: TCP
  {{- end }}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Block

func Block(block string) func(*sharedFields)

Block returns a modifier function to set the block action of a node.

func Comment

func Comment(comment string) func(*sharedFields)

Comment returns a modifier function to set the comment of a node.

func EmptyLines

func EmptyLines(emptyLines bool) func(*Encoder)

EmptyLines turns generation of additional empty lines on or off. In general each node that has a comment or a block action will be separated by additional empty lines from the rest of the document. The leading empty line will be omitted for the first element of a list or mapping, and the trailing empty line will be omitted for the last element. The default value is false.

func Indent

func Indent(indent int) func(*Encoder)

Indent sets the indentation amount per nesting level for the YAML encoding. The default value is 2. This is also the minimum allowed.

func Separator

func Separator(separator bool) func(*Encoder)

Separator selects if a document separator should be emitted

func Wrap

func Wrap(wrap int) func(*Encoder)

Wrap sets the maximum line length for comments. This number includes the columns needed for indentation, so comments on more deeply nested nodes have more tightly wrapped comments than outer level nodes. Wrapping applies only to comments and not to block actions or scalar values. The default value is 80.

Types

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder writes the config data to an output stream.

func NewEncoder

func NewEncoder(writer io.Writer, modifiers ...func(*Encoder)) *Encoder

NewEncoder returns an Encoder holding the output stream and encoding options.

func (*Encoder) Encode

func (enc *Encoder) Encode(node Node) error

Encode writes the config mapping held by the node to the stream.

func (*Encoder) Set

func (enc *Encoder) Set(modifiers ...func(*Encoder))

Set applies Encoder modifier functions to set option values.

func (*Encoder) Write

func (enc *Encoder) Write(buffer []byte) (int, error)

Write implements the io.Writer interface. It just forwards to the embedded writer until an error occurs. This allows for error checking just once at the end of Encode().

type List

type List struct {
	// contains filtered or unexported fields
}

List represents an ordered list of unnamed nodes.

func NewList

func NewList(values ...interface{}) *List

NewList creates a list node initialized with a slice of values. The list and element nodes will not have comments nor block actions.

func (*List) Add

func (list *List) Add(values ...interface{})

Add one or more nodes at the end of the list.

func (List) Block

func (shared List) Block() string

Block is a shared getter function for all node types.

func (List) Comment

func (shared List) Comment() string

Comment is a shared getter function for all node types.

func (*List) Get

func (shared *List) Get(...string) Node

Get returns a named node from a mapping node.

func (*List) Set

func (shared *List) Set(modifiers ...NodeModifier)

Set applies NodeModifier functions to the embedded sharedFields struct.

func (*List) SetValue

func (shared *List) SetValue(interface{})

SetValue updates the value of a scalar node.

func (*List) String

func (list *List) String() string

func (*List) Values

func (list *List) Values() []Node

Values returns a slice of all the elements of the list.

type Mapping

type Mapping struct {
	// contains filtered or unexported fields
}

Mapping represents an ordered list of named nodes.

func NewMapping

func NewMapping(values ...interface{}) *Mapping

NewMapping creates a new mapping node initialized with a slice of keys and values, interleaved. The keys are stored in the even-numbered indices and must be strings. Values are odd-numbered. The mapping and element nodes will not have comments nor block actions.

func (*Mapping) Add

func (mapping *Mapping) Add(name string, value interface{}, modifiers ...NodeModifier)

Add a single named node at the end of the list, replacing any existing entries of the same name.

func (Mapping) Block

func (shared Mapping) Block() string

Block is a shared getter function for all node types.

func (Mapping) Comment

func (shared Mapping) Comment() string

Comment is a shared getter function for all node types.

func (*Mapping) Get

func (mapping *Mapping) Get(names ...string) Node

Get returns the named node, or nil if the name cannot be found. Multiple names may be used, which will be treated as a string of Get() calls, but with the advantage of not crashing if any intermediate node does not exist.

func (*Mapping) Merge

func (mapping *Mapping) Merge(merge *Mapping)

Merge appends all named nodes from another mapping.

func (*Mapping) Names

func (mapping *Mapping) Names() []string

Names returns the ordered list of node names in the mapping.

func (*Mapping) Set

func (shared *Mapping) Set(modifiers ...NodeModifier)

Set applies NodeModifier functions to the embedded sharedFields struct.

func (*Mapping) SetValue

func (shared *Mapping) SetValue(interface{})

SetValue updates the value of a scalar node.

func (*Mapping) Sort

func (mapping *Mapping) Sort() *Mapping

Sort all nodes of the mapping by name.

func (*Mapping) String

func (mapping *Mapping) String() string

func (*Mapping) Values

func (shared *Mapping) Values() []Node

Values returns all the elements of a list node.

type Node

type Node interface {
	// Every node will embed a sharedFields struct and inherit these methods:
	Block() string
	Comment() string
	Set(...NodeModifier)

	// Scalar node methods:
	SetValue(interface{})
	String() string

	// List node methods:
	Values() []Node

	// Mapping node methods:
	Get(...string) Node
	// contains filtered or unexported methods
}

Node is the interface implemented by all config node types.

func NewNode

func NewNode(value interface{}, modifiers ...NodeModifier) Node

NewNode creates a new node (scalar of various types, list, map) depending on the (runtime type of the) specified value.

type NodeModifier

type NodeModifier func(*sharedFields)

NodeModifier functions can be used to set values of shared fields in a node.

type Scalar

type Scalar struct {
	// contains filtered or unexported fields
}

Scalar represents a scalar value inside a list or mapping.

func (Scalar) Block

func (shared Scalar) Block() string

Block is a shared getter function for all node types.

func (Scalar) Comment

func (shared Scalar) Comment() string

Comment is a shared getter function for all node types.

func (*Scalar) Get

func (shared *Scalar) Get(...string) Node

Get returns a named node from a mapping node.

func (*Scalar) Set

func (shared *Scalar) Set(modifiers ...NodeModifier)

Set applies NodeModifier functions to the embedded sharedFields struct.

func (*Scalar) SetValue

func (scalar *Scalar) SetValue(value interface{})

SetValue updates the value of a scalar node.

func (*Scalar) String

func (scalar *Scalar) String() string

String returns the string value of a scalar node. This value will *not* include the surrounding quotes used for literal YAML strings.

func (*Scalar) Values

func (shared *Scalar) Values() []Node

Values returns all the elements of a list node.

Source Files