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 ¶
- func Block(block string) func(*sharedFields)
- func Comment(comment string) func(*sharedFields)
- func EmptyLines(emptyLines bool) func(*Encoder)
- func Indent(indent int) func(*Encoder)
- func Separator(separator bool) func(*Encoder)
- func Wrap(wrap int) func(*Encoder)
- type Encoder
- type List
- func (list *List) Add(values ...interface{})
- func (shared List) Block() string
- func (shared List) Comment() string
- func (shared *List) Get(...string) Node
- func (shared *List) Set(modifiers ...NodeModifier)
- func (shared *List) SetValue(interface{})
- func (list *List) String() string
- func (list *List) Values() []Node
- type Mapping
- func (mapping *Mapping) Add(name string, value interface{}, modifiers ...NodeModifier)
- func (shared Mapping) Block() string
- func (shared Mapping) Comment() string
- func (mapping *Mapping) Get(names ...string) Node
- func (mapping *Mapping) Merge(merge *Mapping)
- func (mapping *Mapping) Names() []string
- func (shared *Mapping) Set(modifiers ...NodeModifier)
- func (shared *Mapping) SetValue(interface{})
- func (mapping *Mapping) Sort() *Mapping
- func (mapping *Mapping) String() string
- func (shared *Mapping) Values() []Node
- type Node
- type NodeModifier
- type Scalar
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 ¶
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 ¶
Indent sets the indentation amount per nesting level for the YAML encoding. The default value is 2. This is also the minimum allowed.
func Wrap ¶
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 ¶
NewEncoder returns an Encoder holding the output stream and encoding options.
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) Set ¶
func (shared *List) Set(modifiers ...NodeModifier)
Set applies NodeModifier functions to the embedded sharedFields struct.
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 ¶
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) 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.
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) 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.
Source Files