value

package
v0.0.0-...-52b58a3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 31, 2022 License: Apache-2.0, Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package value defines types for an in-memory representation of yaml or json objects, organized for convenient comparison with a schema (as defined by the sibling schema package). Functions for reading and writing the objects are also provided.

Index

Constants

View Source
const (
	// Unordered indicates that the map traversal has no ordering requirement.
	Unordered = iota
	// LexicalKeyOrder indicates that the map traversal is ordered by key, lexically.
	LexicalKeyOrder
)

Variables

View Source
var EmptyRange = &emptyRange{}
View Source
var HeapAllocator = &heapAllocator{}

HeapAllocator simply allocates objects to the heap. It is the default allocator used receiver functions on the value interfaces that do not accept an allocator and should be used whenever allocating objects that will not be given back to an allocator by calling Allocator.Free(Value).

Functions

func BoolCompare

func BoolCompare(lhs, rhs bool) int

Compare compares booleans. The result will be 0 if b==rhs, -1 if b < rhs, and +1 if b > rhs.

func Compare

func Compare(lhs, rhs Value) int

Compare provides a total ordering for Value (so that they can be sorted, even if they are of different types). The result will be 0 if v==rhs, -1 if v < rhs, and +1 if v > rhs.

func CompareUsing

func CompareUsing(a Allocator, lhs, rhs Value) int

CompareUsing uses the provided allocator and provides a total ordering for Value (so that they can be sorted, even if they are of different types). The result will be 0 if v==rhs, -1 if v < rhs, and +1 if v > rhs.

func Equals

func Equals(lhs, rhs Value) bool

Equals returns true iff the two values are equal.

func EqualsUsing

func EqualsUsing(a Allocator, lhs, rhs Value) bool

EqualsUsing uses the provided allocator and returns true iff the two values are equal.

func FloatCompare

func FloatCompare(lhs, rhs float64) int

Compare compares floats. The result will be 0 if lhs==rhs, -1 if f < rhs, and +1 if f > rhs.

func IntCompare

func IntCompare(lhs, rhs int64) int

IntCompare compares integers. The result will be 0 if i==rhs, -1 if i < rhs, and +1 if i > rhs.

func Less

func Less(lhs, rhs Value) bool

Less provides a total ordering for Value (so that they can be sorted, even if they are of different types).

func ListCompare

func ListCompare(lhs, rhs List) int

ListCompare compares two lists lexically. The result will be 0 if l==rhs, -1 if l < rhs, and +1 if l > rhs.

func ListCompareUsing

func ListCompareUsing(a Allocator, lhs, rhs List) int

ListCompareUsing uses the provided allocator and compares two lists lexically. The result will be 0 if l==rhs, -1 if l < rhs, and +1 if l > rhs.

func ListEquals

func ListEquals(lhs, rhs List) bool

ListEquals compares two lists lexically. WARN: This is a naive implementation, calling lhs.Equals(rhs) is typically the most efficient.

func ListEqualsUsing

func ListEqualsUsing(a Allocator, lhs, rhs List) bool

ListEqualsUsing uses the provided allocator and compares two lists lexically. WARN: This is a naive implementation, calling lhs.EqualsUsing(allocator, rhs) is typically the most efficient.

func ListLess

func ListLess(lhs, rhs List) bool

ListLess compares two lists lexically.

func MapCompare

func MapCompare(lhs, rhs Map) int

MapCompare compares two maps lexically.

func MapCompareUsing

func MapCompareUsing(a Allocator, lhs, rhs Map) int

MapCompareUsing uses the provided allocator and compares two maps lexically.

func MapEquals

func MapEquals(lhs, rhs Map) bool

MapEquals returns true if lhs == rhs, false otherwise. This function acts on generic types and should not be used by callers, but can help implement Map.Equals. WARN: This is a naive implementation, calling lhs.Equals(rhs) is typically the most efficient.

func MapEqualsUsing

func MapEqualsUsing(a Allocator, lhs, rhs Map) bool

MapEqualsUsing uses the provided allocator and returns true if lhs == rhs, false otherwise. This function acts on generic types and should not be used by callers, but can help implement Map.Equals. WARN: This is a naive implementation, calling lhs.EqualsUsing(allocator, rhs) is typically the most efficient.

func MapLess

func MapLess(lhs, rhs Map) bool

MapLess compares two maps lexically.

func MapZip

func MapZip(lhs, rhs Map, order MapTraverseOrder, fn func(key string, lhs, rhs Value) bool) bool

MapZip iterates over the entries of two maps together. If both maps contain a value for a given key, fn is called with the values from both maps, otherwise it is called with the value of the map that contains the key and nil for the other map. Returning false in the closure prematurely stops the iteration.

func MapZipUsing

func MapZipUsing(a Allocator, lhs, rhs Map, order MapTraverseOrder, fn func(key string, lhs, rhs Value) bool) bool

MapZipUsing uses the provided allocator and iterates over the entries of two maps together. If both maps contain a value for a given key, fn is called with the values from both maps, otherwise it is called with the value of the map that contains the key and nil for the other map. Returning false in the closure prematurely stops the iteration.

func ToJSON

func ToJSON(v Value) ([]byte, error)

ToJSON is a helper function for producing a JSon document.

func ToString

func ToString(v Value) string

ToString returns a human-readable representation of the value.

func ToYAML

func ToYAML(v Value) ([]byte, error)

ToYAML marshals a value as YAML.

func WriteJSONStream

func WriteJSONStream(v Value, stream *jsoniter.Stream)

WriteJSONStream writes a value into a JSON stream.

Types

type Allocator

type Allocator interface {
	// Free gives the allocator back any value objects returned by the "Using"
	// receiver functions on the value interfaces.
	// interface{} may be any of: Value, Map, List or Range.
	Free(interface{})
	// contains filtered or unexported methods
}

Allocator provides a value object allocation strategy. Value objects can be allocated by passing an allocator to the "Using" receiver functions on the value interfaces, e.g. Map.ZipUsing(allocator, ...). Value objects returned from "Using" functions should be given back to the allocator once longer needed by calling Allocator.Free(Value).

func NewFreelistAllocator

func NewFreelistAllocator() Allocator

NewFreelistAllocator creates freelist based allocator. This allocator provides fast allocation and freeing of short lived value objects.

The freelists are bounded in size by freelistMaxSize. If more than this amount of value objects is allocated at once, the excess will be returned to the heap for garbage collection when freed.

This allocator is unsafe and must not be accessed concurrently by goroutines.

This allocator works well for traversal of value data trees. Typical usage is to acquire a freelist at the beginning of the traversal and use it through out for all temporary value access.

type Field

type Field struct {
	Name  string
	Value Value
}

Field is an individual key-value pair.

type FieldCacheEntry

type FieldCacheEntry struct {
	// JsonName returns the name of the field according to the json tags on the struct field.
	JsonName string

	TypeEntry *TypeReflectCacheEntry
	// contains filtered or unexported fields
}

FieldCacheEntry keeps data gathered using reflection about how the field of a struct is converted to/from unstructured.

func (*FieldCacheEntry) CanOmit

func (f *FieldCacheEntry) CanOmit(fieldVal reflect.Value) bool

func (*FieldCacheEntry) GetFrom

func (f *FieldCacheEntry) GetFrom(structVal reflect.Value) reflect.Value

GetFrom returns the field identified by this FieldCacheEntry from the provided struct.

type FieldList

type FieldList []Field

FieldList is a list of key-value pairs. Each field is expected to have a different name.

func (FieldList) Compare

func (f FieldList) Compare(rhs FieldList) int

Compare compares two lists lexically. The result will be 0 if f==rhs, -1 if f < rhs, and +1 if f > rhs.

func (FieldList) Equals

func (f FieldList) Equals(rhs FieldList) bool

Equals returns true if the two fieldslist are equals, false otherwise.

func (FieldList) Less

func (f FieldList) Less(rhs FieldList) bool

Less compares two lists lexically.

func (FieldList) Sort

func (f FieldList) Sort()

Sort sorts the field list by Name.

type List

type List interface {
	// Length returns how many items can be found in the map.
	Length() int
	// At returns the item at the given position in the map. It will
	// panic if the index is out of range.
	At(int) Value
	// AtUsing uses the provided allocator and returns the item at the given
	// position in the map. It will panic if the index is out of range.
	// The returned Value should be given back to the Allocator when no longer needed
	// by calling Allocator.Free(Value).
	AtUsing(Allocator, int) Value
	// Range returns a ListRange for iterating over the items in the list.
	Range() ListRange
	// RangeUsing uses the provided allocator and returns a ListRange for
	// iterating over the items in the list.
	// The returned Range should be given back to the Allocator when no longer needed
	// by calling Allocator.Free(Value).
	RangeUsing(Allocator) ListRange
	// Equals compares the two lists, and return true if they are the same, false otherwise.
	// Implementations can use ListEquals as a general implementation for this methods.
	Equals(List) bool
	// EqualsUsing uses the provided allocator and compares the two lists, and return true if
	// they are the same, false otherwise. Implementations can use ListEqualsUsing as a general
	// implementation for this methods.
	EqualsUsing(Allocator, List) bool
}

List represents a list object.

type ListRange

type ListRange interface {
	// Next increments to the next item in the range, if there is one, and returns true, or returns false if there are no more items.
	Next() bool
	// Item returns the index and value of the current item in the range. or panics if there is no current item.
	// For efficiency, Item may reuse the values returned by previous Item calls. Callers should be careful avoid holding
	// pointers to the value returned by Item() that escape the iteration loop since they become invalid once either
	// Item() or Allocator.Free() is called.
	Item() (index int, value Value)
}

ListRange represents a single iteration across the items of a list.

type Map

type Map interface {
	// Set changes or set the value of the given key.
	Set(key string, val Value)
	// Get returns the value for the given key, if present, or (nil, false) otherwise.
	Get(key string) (Value, bool)
	// GetUsing uses the provided allocator and returns the value for the given key,
	// if present, or (nil, false) otherwise.
	// The returned Value should be given back to the Allocator when no longer needed
	// by calling Allocator.Free(Value).
	GetUsing(a Allocator, key string) (Value, bool)
	// Has returns true if the key is present, or false otherwise.
	Has(key string) bool
	// Delete removes the key from the map.
	Delete(key string)
	// Equals compares the two maps, and return true if they are the same, false otherwise.
	// Implementations can use MapEquals as a general implementation for this methods.
	Equals(other Map) bool
	// EqualsUsing uses the provided allocator and compares the two maps, and return true if
	// they are the same, false otherwise. Implementations can use MapEqualsUsing as a general
	// implementation for this methods.
	EqualsUsing(a Allocator, other Map) bool
	// Iterate runs the given function for each key/value in the
	// map. Returning false in the closure prematurely stops the
	// iteration.
	Iterate(func(key string, value Value) bool) bool
	// IterateUsing uses the provided allocator and runs the given function for each key/value
	// in the map. Returning false in the closure prematurely stops the iteration.
	IterateUsing(Allocator, func(key string, value Value) bool) bool
	// Length returns the number of items in the map.
	Length() int
	// Empty returns true if the map is empty.
	Empty() bool
	// Zip iterates over the entries of two maps together. If both maps contain a value for a given key, fn is called
	// with the values from both maps, otherwise it is called with the value of the map that contains the key and nil
	// for the map that does not contain the key. Returning false in the closure prematurely stops the iteration.
	Zip(other Map, order MapTraverseOrder, fn func(key string, lhs, rhs Value) bool) bool
	// ZipUsing uses the provided allocator and iterates over the entries of two maps together. If both maps
	// contain a value for a given key, fn is called with the values from both maps, otherwise it is called with
	// the value of the map that contains the key and nil for the map that does not contain the key. Returning
	// false in the closure prematurely stops the iteration.
	ZipUsing(a Allocator, other Map, order MapTraverseOrder, fn func(key string, lhs, rhs Value) bool) bool
}

Map represents a Map or go structure.

type MapTraverseOrder

type MapTraverseOrder int

MapTraverseOrder defines the map traversal ordering available.

type TypeReflectCacheEntry

type TypeReflectCacheEntry struct {
	// contains filtered or unexported fields
}

TypeReflectCacheEntry keeps data gathered using reflection about how a type is converted to/from unstructured.

func TypeReflectEntryOf

func TypeReflectEntryOf(t reflect.Type) *TypeReflectCacheEntry

TypeReflectEntryOf returns the TypeReflectCacheEntry of the provided reflect.Type.

func (TypeReflectCacheEntry) CanConvertFromUnstructured

func (e TypeReflectCacheEntry) CanConvertFromUnstructured() bool

CanConvertFromUnstructured returns true if this TypeReflectCacheEntry can convert objects of the type from unstructured.

func (TypeReflectCacheEntry) CanConvertToUnstructured

func (e TypeReflectCacheEntry) CanConvertToUnstructured() bool

CanConvertToUnstructured returns true if this TypeReflectCacheEntry can convert values of its type to unstructured.

func (TypeReflectCacheEntry) Fields

Fields returns a map of JSON field name to FieldCacheEntry for structs, or nil for non-structs.

func (TypeReflectCacheEntry) FromUnstructured

func (e TypeReflectCacheEntry) FromUnstructured(sv, dv reflect.Value) error

FromUnstructured converts the provided source value from unstructured into the provided destination value.

func (TypeReflectCacheEntry) OrderedFields

func (e TypeReflectCacheEntry) OrderedFields() []*FieldCacheEntry

Fields returns a map of JSON field name to FieldCacheEntry for structs, or nil for non-structs.

func (TypeReflectCacheEntry) ToUnstructured

func (e TypeReflectCacheEntry) ToUnstructured(sv reflect.Value) (interface{}, error)

ToUnstructured converts the provided value to unstructured and returns it.

type UnstructuredConverter

type UnstructuredConverter interface {
	json.Marshaler // require that json.Marshaler is implemented

	// ToUnstructured returns the unstructured representation.
	ToUnstructured() interface{}
}

UnstructuredConverter defines how a type can be converted directly to unstructured. Types that implement json.Marshaler may also optionally implement this interface to provide a more direct and more efficient conversion. All types that choose to implement this interface must still implement this same conversion via json.Marshaler.

type Value

type Value interface {
	// IsMap returns true if the Value is a Map, false otherwise.
	IsMap() bool
	// IsList returns true if the Value is a List, false otherwise.
	IsList() bool
	// IsBool returns true if the Value is a bool, false otherwise.
	IsBool() bool
	// IsInt returns true if the Value is a int64, false otherwise.
	IsInt() bool
	// IsFloat returns true if the Value is a float64, false
	// otherwise.
	IsFloat() bool
	// IsString returns true if the Value is a string, false
	// otherwise.
	IsString() bool
	// IsMap returns true if the Value is null, false otherwise.
	IsNull() bool

	// AsMap converts the Value into a Map (or panic if the type
	// doesn't allow it).
	AsMap() Map
	// AsMapUsing uses the provided allocator and converts the Value
	// into a Map (or panic if the type doesn't allow it).
	AsMapUsing(Allocator) Map
	// AsList converts the Value into a List (or panic if the type
	// doesn't allow it).
	AsList() List
	// AsListUsing uses the provided allocator and converts the Value
	// into a List (or panic if the type doesn't allow it).
	AsListUsing(Allocator) List
	// AsBool converts the Value into a bool (or panic if the type
	// doesn't allow it).
	AsBool() bool
	// AsInt converts the Value into an int64 (or panic if the type
	// doesn't allow it).
	AsInt() int64
	// AsFloat converts the Value into a float64 (or panic if the type
	// doesn't allow it).
	AsFloat() float64
	// AsString converts the Value into a string (or panic if the type
	// doesn't allow it).
	AsString() string

	// Unstructured converts the Value into an Unstructured interface{}.
	Unstructured() interface{}
}

A Value corresponds to an 'atom' in the schema. It should return true for at least one of the IsXXX methods below, or the value is considered "invalid"

func FromJSON

func FromJSON(input []byte) (Value, error)

FromJSON is a helper function for reading a JSON document.

func FromJSONFast

func FromJSONFast(input []byte) (Value, error)

FromJSONFast is a helper function for reading a JSON document.

func NewValueInterface

func NewValueInterface(v interface{}) Value

NewValueInterface creates a Value backed by an "interface{}" type, typically an unstructured object in Kubernetes world. interface{} must be one of: map[string]interface{}, map[interface{}]interface{}, []interface{}, int types, float types, string or boolean. Nested interface{} must also be one of these types.

func NewValueReflect

func NewValueReflect(value interface{}) (Value, error)

NewValueReflect creates a Value backed by an "interface{}" type, typically an structured object in Kubernetes world that is uses reflection to expose. The provided "interface{}" value must be a pointer so that the value can be modified via reflection. The provided "interface{}" may contain structs and types that are converted to Values by the jsonMarshaler interface.

func ReadJSONIter

func ReadJSONIter(iter *jsoniter.Iterator) (Value, error)

ReadJSONIter reads a Value from a JSON iterator.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL