Documentation
¶
Overview ¶
Package yamlx provides extended YAML parsing functionalities. It supports both references and merges.
Index ¶
- Variables
- func Apply(node *yaml.Node, replacement yaml.Node)
- func Child(node *yaml.Node, name string) (*yaml.Node, error)
- func Find(node *yaml.Node, path ...string) (*yaml.Node, error)
- func Iterate(node *yaml.Node) traversal.Iterator[Path]
- func Marshal(value any) (*yaml.Node, error)
- func Replace(node *yaml.Node, replacement yaml.Node, path ...string) error
- func ReplaceWith(node *yaml.Node, replacement any, path ...string) error
- func Transplant(node, donor *yaml.Node, SkipMissing bool) error
- type ChildError
- type ChildNotFound
- type MappingExpectedScalar
- type Path
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrNodeIsNil error = findError("node is nil") ErrUnexpectedScalar error = findError("unexpected scalar node") ErrUnexpectedSequence error = findError("unexpected sequence node") ErrExpectedMapping error = findError("expected mapping node") )
Common errors for finding a node
Functions ¶
func Apply ¶
func Apply(node *yaml.Node, replacement yaml.Node)
Apply applies a replacement to a node.
If the node is nil, it is not replaced. Otherwise, the following fields are copied: - Kind - Style - Tag - Value - Alias - Content Note that the original comments are maintained.
func Child ¶
Child finds the child node with the given name. If it does not exist, it returns an error.
func Find ¶
Find attempts to find the yaml node with the given path inside a yaml tree. A path is a set of strings, and assumed to be keys inside yaml mapping nodes. The empty path returns (a possibly de-referenced version of) node.
The returned node is guaranteed to never be a document or alias node, these are resolved automatically. As such find should not be used on untrusted input.
If the node does not exist, it returns a nil yaml.Node and an error. A nil node being passed in is considered an error.
func Iterate ¶
Iterate iterates over all paths in node.
Calling Find(node, path.Path) == path.Node is guaranteed for all paths. See also Find.
func Marshal ¶
Marshal marshals a value into a new yaml node
Example ¶
//spellchecker:words yamlx
package main
//spellchecker:words testing github pkglib yamlx gopkg yaml
import (
"fmt"
"testing"
"github.com/tkw1536/pkglib/yamlx"
"gopkg.in/yaml.v3"
)
func main() {
// take a random value to encode
value := map[string]any{
"count": 2,
"numbers": map[string]any{
"42": "the answer",
"69": "nice",
},
}
// marshal it as a node
node, err := yamlx.Marshal(value)
if err != nil {
panic(err)
}
// and print it out
fmt.Println(mustMarshal(nil, node))
}
func mustMarshal(t testing.TB, node *yaml.Node) string {
result, err := yaml.Marshal(node)
if err != nil {
msg := fmt.Sprintf("unable to marshal: %v", err)
if t != nil {
t.Error(msg)
t.Fail()
}
panic(msg)
}
return string(result)
}
func mustUnmarshal(t testing.TB, source string) *yaml.Node {
var node yaml.Node
err := yaml.Unmarshal([]byte(source), &node)
if err != nil {
msg := fmt.Sprintf("unable to unmarshal: %v", err)
if t != nil {
t.Error(msg)
t.Fail()
}
panic(msg)
}
return &node
}
Output: count: 2 numbers: "42": the answer "69": nice
func Replace ¶
Replace replaces the node found by Find(node, path...) with replacement. If the original node is an anchor, it will not be replaced. If the original node is not an anchor, it will be replaced
Example ¶
// some people see the dress and white and gold
dress := mustUnmarshal(nil, "dress:\n color: \"white and gold\"")
// others as blue and black
blue_and_black, err := yamlx.Marshal("blue and black")
if err != nil {
panic(err)
}
// replace the color of the dress with blue and black
if err := yamlx.Replace(dress, *blue_and_black, "dress", "color"); err != nil {
panic(err)
}
fmt.Println(mustMarshal(nil, dress))
Output: dress: color: blue and black
func ReplaceWith ¶
ReplaceWith is like Replace, except that the replacement is first marshalled to yaml.
func Transplant ¶
Transplant transplants all nodes found inside donor onto node.
Unless SkipMissing is true, donor and node should be of the same shape. Being of the same shape means every path where
Find(donor, path...)
does not return an error should also not return an error in node.
Example ¶
template := mustUnmarshal(nil, "person:\n # the name of the person\n name: \"name goes here\"\n # how they see the dress\n dress_color: \"e.g. black and blue\"\n")
// the actual values
values := mustUnmarshal(nil, "person:\n name: \"Testy Tester\"\n dress_color: \"black and blue\"\n")
// "transplant", i.e. copy over all the values
if err := yamlx.Transplant(template, values, false); err != nil {
panic(err)
}
fmt.Println(mustMarshal(nil, template))
Output: person: # the name of the person name: "Testy Tester" # how they see the dress dress_color: "black and blue"
Types ¶
type ChildError ¶
ChildError indicates an error that has occurred inside a specific child node
func (ChildError) Error ¶
func (pe ChildError) Error() string
func (ChildError) Unwrap ¶
func (pe ChildError) Unwrap() error
type ChildNotFound ¶
type ChildNotFound string
ChildNotFound indicates that the given child was not found
func (ChildNotFound) Error ¶
func (cnf ChildNotFound) Error() string
type MappingExpectedScalar ¶
type MappingExpectedScalar int
func (MappingExpectedScalar) Error ¶
func (mes MappingExpectedScalar) Error() string
Source Files