Documentation
¶
Overview ¶
Package ordered implements an ordered map type, suitable for use when decoding yaml documents where mappings must be preserved, such as in certain parts of the buildkite pipeline yaml.
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 (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 Tuple
- type TupleSA
- type TupleSS
- type Unmarshaler
Constants ¶
This section is empty.
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 ¶
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 ¶
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 ¶
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. Struct targets can also have `aliases` tags of the form `aliases:"apple,banana,citron"` If the field name or yaml tag key doesn't match, Unmarshal looks through the aliases list to see if any are present, and uses the value for the first.
- 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 ¶
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]) 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]) IsZero ¶
IsZero reports if m is nil or empty. It is used by yaml.v3 to check emptiness.
func (*Map[K, V]) MarshalJSON ¶
MarshalJSON marshals the ordered map to JSON. It preserves the map order in the output.
func (*Map[K, V]) MarshalYAML ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 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 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.
// If UnmarshalOrdered returns a non-nil error that is not a warning, the
// whole unmarshaling process may halt at that point and report that error
// (wrapped).
// Unlike other errors, returning a warning lets unmarshalling continue
// so that all warnings can be printed together at the end.
UnmarshalOrdered(src any) error
}
Unmarshaler is an interface that types can use to override the default unmarshaling behaviour.
Source Files