ordered

Documentation

Overview

Package ordered implements an ordered map type.

Index

• Variables
• func DecodeYAML(n *yaml.Node) (any, error)
• func Equal[K comparable, V any](a, b *Map[K, V]) bool
• func ToMapRecursive(src any) any
• func Unmarshal(src, dst any) error
• type Map
  • func AssertValues[V any](m *MapSA) (*Map[string, V], error)
  • func MapFromItems[K comparable, V any](ps ...Tuple[K, V]) *Map[K, V]
  • func NewMap[K comparable, V any](cap int) *Map[K, V]
  • func TransformValues[K comparable, V1, V2 any](m *Map[K, V1], f func(V1) V2) *Map[K, V2]
  • func (m *Map[K, V]) Contains(k K) bool
  • func (m *Map[K, V]) Delete(k K)
  • func (m *Map[K, V]) Get(k K) (V, bool)
  • func (m *Map[K, V]) IsZero() bool
  • func (m *Map[K, V]) Len() int
  • func (m *Map[K, V]) MarshalJSON() ([]byte, error)
  • func (m *Map[K, V]) MarshalYAML() (any, error)
  • func (m *Map[K, V]) Range(f func(k K, v V) error) error
  • func (m *Map[K, V]) Replace(old, new K, v V)
  • func (m *Map[K, V]) Set(k K, v V)
  • func (m *Map[K, V]) ToMap() map[K]V
  • func (m *Map[K, V]) UnmarshalJSON(b []byte) error
  • func (m *Map[K, V]) UnmarshalOrdered(src any) error
  • func (m *Map[K, V]) UnmarshalYAML(n *yaml.Node) error
• type MapSA
• type MapSS
• type Slice
  • func (s *Slice) UnmarshalYAML(n *yaml.Node) error
• type Strings
  • func (s *Strings) UnmarshalYAML(n *yaml.Node) error
• type Tuple
• type TupleSA
• type TupleSS
• type Unmarshaler

Variables

var (
	ErrIntoNonPointer       = errors.New("cannot unmarshal into non-pointer")
	ErrIntoNil              = errors.New("cannot unmarshal into nil")
	ErrIncompatibleTypes    = errors.New("incompatible types")
	ErrUnsupportedSrc       = errors.New("cannot unmarshal from src")
	ErrMultipleInlineFields = errors.New(`multiple fields tagged with yaml:",inline"`)
)

Errors that can be returned by Unmarshal (typically wrapped - use errors.Is).

var EqualSA = Equal[string, any]

EqualSA is a convenience alias to reduce keyboard wear.

var EqualSS = Equal[string, string]

EqualSS is a convenience alias to reduce keyboard wear.

Functions

func DecodeYAML

func DecodeYAML(n *yaml.Node) (any, error)

DecodeYAML recursively unmarshals n into a generic type (any, []any, or *Map[string, any]) depending on the kind of n. Where yaml.v3 typically infer map[string]any for unmarshaling mappings into any, DecodeYAML chooses *Map[string, any] instead.

func Equal

func Equal[K comparable, V any](a, b *Map[K, V]) bool

Equal reports if the two maps are equal (they contain the same items in the same order). Keys are compared directly; values are compared using go-cmp (provided with Equal[string, any] and Equal[string, string] as a comparers).

func ToMapRecursive

func ToMapRecursive(src any) any

ToMapRecursive converts a weakly typed nested structure consisting of *Map[string, any], []any, and any (i.e. output from DecodeYAML), into one containing the same data but where each *Map[string, any] is map[string]any.

func Unmarshal

func Unmarshal(src, dst any) error

Unmarshal recursively unmarshals src into dst. src and dst can be a variety of types under the hood, but some combinations don't work. Good luck!

• If dst is nil, then src must be nil.
• If src is yaml.Node or *yaml.Node, then DecodeYAML is called to translate the node into another type.
• If dst is a pointer and src is nil, then the value dst points to is set to zero.
• If dst is a pointer to a pointer, Unmarshal recursively calls Unmarshal on the inner pointer, creating a new value of the type being pointed to as needed.
• If dst implements Unmarshaler, Unmarshal returns dst.UnmarshalOrdered(src).
• If dst is *any, Unmarshal copies src directly into *dst.

Otherwise, it acts a lot like yaml.Unmarshal, except that the type S of src and type D of dst can be one of the following:

• S = *Map[string, any] (recursively containing values with types from this list); D must be one of: a pointer to a struct with yaml tags, or a map or a pointer to a map (either *Map or map) with string keys. yaml tags includes ",inline". Inline fields must themselves be a type that Unmarshal can unmarshal *Map[string, any] into - another struct or Map or map with string keys.
• S = []any (also recursively containing values with types from this list), which is recursively unmarshaled elementwise; D is *[]any or *[]somethingElse.
• S ∊ {string, float64, int, bool}; D must be *S (value copied directly), *[]S or *[]any (value appended), *string (value formatted through fmt.Sprint) or *[]string (formatted value appended).

Types

type Map

type Map[K comparable, V any] struct {
	// contains filtered or unexported fields
}

Map is an order-preserving map with string keys. It is intended for working with YAML in an order-preserving way (off-spec, strictly speaking) and JSON (more of the same).

func AssertValues

func AssertValues[V any](m *MapSA) (*Map[string, V], error)

AssertValues converts a map with "any" values into a map with V values by type-asserting each value. It returns an error if any value is not assertable to V.

func MapFromItems

func MapFromItems[K comparable, V any](ps ...Tuple[K, V]) *Map[K, V]

MapFromItems creates an Map with some items.

func NewMap

func NewMap[K comparable, V any](cap int) *Map[K, V]

NewMap returns a new empty map with a given initial capacity.

func TransformValues

func TransformValues[K comparable, V1, V2 any](m *Map[K, V1], f func(V1) V2) *Map[K, V2]

TransformValues converts a map with V1 values into a map with V2 values by running each value through a function.

func (*Map[K, V]) Contains

func (m *Map[K, V]) Contains(k K) bool

Contains reports if the map contains the key.

func (*Map[K, V]) Delete

func (m *Map[K, V]) Delete(k K)

Delete deletes a key from the map. It does nothing if the key is not in the map.

func (*Map[K, V]) Get

func (m *Map[K, V]) Get(k K) (V, bool)

Get retrieves the value associated with a key, and reports if it was found.

func (*Map[K, V]) IsZero

func (m *Map[K, V]) IsZero() bool

IsZero reports if m is nil or empty. It is used by yaml.v3 to check emptiness.

func (*Map[K, V]) Len

func (m *Map[K, V]) Len() int

Len returns the number of items in the map.

func (*Map[K, V]) MarshalJSON

func (m *Map[K, V]) MarshalJSON() ([]byte, error)

MarshalJSON marshals the ordered map to JSON. It preserves the map order in the output.

func (*Map[K, V]) MarshalYAML

func (m *Map[K, V]) MarshalYAML() (any, error)

MarshalYAML returns a *yaml.Node encoding this map (in order), or an error if any of the items could not be encoded into a *yaml.Node.

func (*Map[K, V]) Range

func (m *Map[K, V]) Range(f func(k K, v V) error) error

Range ranges over the map (in order). If f returns an error, it stops ranging and returns that error.

func (*Map[K, V]) Replace

func (m *Map[K, V]) Replace(old, new K, v V)

Replace replaces an old key in the same spot with a new key and value. If the old key doesn't exist in the map, the item is inserted at the end. If the new key already exists in the map (and isn't equal to the old key), then it is deleted. This provides a way to change a single key in-place (easier than deleting the old key and all later keys, adding the new key, then restoring the rest).

func (*Map[K, V]) Set

func (m *Map[K, V]) Set(k K, v V)

Set sets the value for the given key. If the key exists, it remains in its existing spot, otherwise it is added to the end of the map.

func (*Map[K, V]) ToMap

func (m *Map[K, V]) ToMap() map[K]V

ToMap creates a regular (un-ordered) map containing the same data. If m is nil, ToMap returns nil.

func (*Map[K, V]) UnmarshalJSON

func (m *Map[K, V]) UnmarshalJSON(b []byte) error

UnmarshalJSON unmarshals to JSON. It only supports K = string. This is yaml.Unmarshal in a trenchcoat (YAML is a superset of JSON).

func (*Map[K, V]) UnmarshalOrdered

func (m *Map[K, V]) UnmarshalOrdered(src any) error

UnmarshalOrdered unmarshals a value into this map. K must be string, src must be *Map[string, any], and each value in src must be unmarshallable into *V.

func (*Map[K, V]) UnmarshalYAML

func (m *Map[K, V]) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML unmarshals a YAML mapping node into this map. It only supports K = string. Where yaml.v3 typically infers map[string]any for unmarshaling mappings into any, this method chooses *Map[string, any] instead. If V = *yaml.Node, then the value nodes are not decoded. This is useful for a shallow unmarshaling step.

type MapSA

type MapSA = Map[string, any]

MapSA is a convenience alias to reduce keyboard wear.

type MapSS

type MapSS = Map[string, string]

MapSS is a convenience alias to reduce keyboard wear.

type Slice

type Slice []any

Slice is []any, but unmarshaling into it prefers *Map[string,any] over map[string]any.

func (*Slice) UnmarshalYAML

func (s *Slice) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML unmarshals sequence nodes. Any mapping nodes are unmarshaled as *Map[string,any].

type Strings

type Strings []string

Strings is []string, but unmarshaling handles both sequences and single scalars.

func (*Strings) UnmarshalYAML

func (s *Strings) UnmarshalYAML(n *yaml.Node) error

UnmarshalYAML unmarshals n depending on its Kind as either - a sequence of strings (into a slice), or - a single string (into a one-element slice). For example, unmarshaling either `["foo"]` or `"foo"` should result in a one-element slice (`Strings{"foo"}`).

type Tuple

type Tuple[K comparable, V any] struct {
	Key   K
	Value V
	// contains filtered or unexported fields
}

Tuple is used for storing values in Map.

type TupleSA

type TupleSA = Tuple[string, any]

TupleSA is a convenience alias to reduce keyboard wear.

type TupleSS

type TupleSS = Tuple[string, string]

TupleSS is a convenience alias to reduce keyboard wear.

type Unmarshaler

type Unmarshaler interface {
	// UnmarshalOrdered should unmarshal src into the implementing value. src
	// will generally be one of *Map[string, any], []any, or a "scalar" built-in
	// type.
	UnmarshalOrdered(src any) error
}

Unmarshaler is an interface that types can use to override the default unmarshaling behaviour.