dig

README

Dig

A simple zero-dependency go package that provides a Ruby-like Hash.dig mechanism for map[string]any, which in YAML is refered to as "Mapping".

Usage

The provided dig.Mapping is handy when unmarshaling arbitrary YAML/JSON documents.

Example

package main

import (
  "fmt"

  "github.com/k0sproject/dig"
  "gopkg.in/yaml.v2"
)

var yamlDoc = []byte(`---
i18n:
  hello:
    se: Hejsan
    fi: Moi
  world:
    se: Värld
    fi: Maailma
`)

func main() {
  m := dig.Mapping{}
  if err := yaml.Unmarshal(yamlDoc, &m); err != nil {
    panic(err)
  }

  // You can use DigMapping to access a deeply nested map and set values.
  // Any missing Mapping level in between will be created.
  m.DigMapping("i18n", "hello")["es"] = "Hola"
  m.DigMapping("i18n", "world")["es"] = "Mundo"

  langs := []string{"fi", "se", "es"}
  for _, l := range langs {

    // You can use Dig to access a deeply nested value
    greeting := m.Dig("i18n", "hello", l).(string)

    // ..or DigString to avoid having to cast it to string.
    target := m.DigString("i18n", "world", l)

    fmt.Printf("%s, %s!\n", greeting, target)
  }
}

Output:

Moi, Maailma!
Hejsan, Värld!
Hola, Mundo!

Documentation

Overview

Package dig provides a map[string]any Mapping type that has ruby-like "dig" functionality.

It can be used for example to access and manipulate arbitrary nested YAML/JSON structures.

Index

• type Mapping
  • func (m *Mapping) Dig(keys ...string) any
  • func (m *Mapping) DigMapping(keys ...string) Mapping
  • func (m *Mapping) DigString(keys ...string) string
  • func (m *Mapping) Dup() Mapping
  • func (m *Mapping) HasKey(key string) bool
  • func (m *Mapping) HasMapping(key string) bool
  • func (m Mapping) Merge(source Mapping, opts ...MergeOption)
  • func (m *Mapping) UnmarshalJSON(text []byte) error
  • func (m *Mapping) UnmarshalYAML(unmarshal func(any) error) error
• type MergeOption
  • func WithAppend() MergeOption
  • func WithNillify() MergeOption
  • func WithOverwrite() MergeOption
• type MergeOptions

Examples

• Mapping.Dig
• Mapping.DigMapping
• Mapping.DigString

Types

type Mapping

type Mapping map[string]any

Mapping is a nested key-value map where the keys are strings and values are any. In Ruby it is called a Hash (with string keys), in YAML it's called a "mapping".

func (*Mapping) Dig

func (m *Mapping) Dig(keys ...string) any

Dig is a simplistic implementation of a Ruby-like Hash.dig functionality.

It returns a value from a (deeply) nested tree structure.

Example

package main

import (
	"fmt"

	"github.com/k0sproject/dig"
)

func main() {
	h := dig.Mapping{
		"greeting": dig.Mapping{
			"target": "world",
		},
	}
	fmt.Println("Hello,", h.Dig("greeting", "target"))
}

Output:

Hello, world

func (*Mapping) DigMapping

func (m *Mapping) DigMapping(keys ...string) Mapping

DigMapping always returns a mapping, creating missing or overwriting non-mapping branches in between

Example

package main

import (
	"fmt"

	"github.com/k0sproject/dig"
)

func main() {
	h := dig.Mapping{}
	h.DigMapping("greeting")["target"] = "world"
	fmt.Println("Hello,", h.Dig("greeting", "target"))
}

Output:

Hello, world

func (*Mapping) DigString

func (m *Mapping) DigString(keys ...string) string

DigString is like Dig but returns the value as string

Example

package main

import (
	"fmt"

	"github.com/k0sproject/dig"
)

func main() {
	h := dig.Mapping{}
	h.DigMapping("greeting")["target"] = "world"
	fmt.Println("Hello,", h.DigString("greeting", "target"), "!")
	fmt.Println("Hello,", h.Dig("greeting", "non-existing"), "!")
	fmt.Println("Hello,", h.DigString("greeting", "non-existing"), "!")
}

Output:

Hello, world !
Hello, <nil> !
Hello,  !

func (*Mapping) Dup

func (m *Mapping) Dup() Mapping

Dup creates a dereferenced copy of the Mapping

func (*Mapping) HasKey

func (m *Mapping) HasKey(key string) bool

HasKey checks if the key exists in the Mapping.

func (*Mapping) HasMapping

func (m *Mapping) HasMapping(key string) bool

HasMapping checks if the key exists in the Mapping and is a Mapping.

func (Mapping) Merge

func (m Mapping) Merge(source Mapping, opts ...MergeOption)

Merge deep merges the source map into the target map. Regardless of options, Mappings will be merged recursively.

func (*Mapping) UnmarshalJSON

func (m *Mapping) UnmarshalJSON(text []byte) error

UnmarshalText for supporting json.Unmarshal

func (*Mapping) UnmarshalYAML

func (m *Mapping) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML for supporting yaml.Unmarshal

type MergeOption

type MergeOption func(*MergeOptions)

func WithAppend

func WithAppend() MergeOption

WithAppend sets the Append option to true.

func WithNillify

func WithNillify() MergeOption

WithNillify sets the Nillify option to true.

func WithOverwrite

func WithOverwrite() MergeOption

WithOverwrite sets the Overwrite option to true.

type MergeOptions

type MergeOptions struct {
	// Overwrite existing values in the target map
	Overwrite bool
	// Nillify removes keys from the target map if the value is nil in the source map
	Nillify bool
	// Append slices instead of overwriting them
	Append bool
}

MergeOptions are used to configure the Merge function.