storage

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Aug 15, 2023 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package storage is a utility package that allows zedpm to conveniently slice and dice shared properties between plugins.

Index

Constants

View Source 
const ExportPrefix = "__export__."

ExportPrefix is the prefix required in order for a value to be visible within KVExp.

Variables

This section is empty.

Functions

This section is empty.

Types

type KV 

type KV interface {
	// AllKeys returns a string list representing all the key names stored in
	// the KV. Keys in this list will be in dot-format.
	AllKeys() []string

	// AllSettings returns a hierarchical map of maps containing all the
	// properties that are set on this KV.
	AllSettings() map[string]any

	// AllSettingsStrings returns a flat map of key/value pairs containing all
	// the properties that are set on this KV. Keys in this map are in
	// dot-separated format.
	AllSettingsStrings() map[string]string

	// Get a value from the KV.
	Get(string) any

	// GetBool gets a boolean value from the KV.
	GetBool(string) bool

	// GetDuration gets a time.Duration value from the KV.
	GetDuration(string) time.Duration

	// GetFloat64 gets a float64 value from the KV.
	GetFloat64(string) float64

	// GetInt gets an int value from the KV.
	GetInt(string) int

	// GetInt32 gets an int32 value from the KV.
	GetInt32(string) int32

	// GetInt64 gets an int64 value from the KV.
	GetInt64(string) int64

	// GetIntSlice gets a slice of ints value from the KV.
	GetIntSlice(string) []int

	// GetString gets a string value from the KV.
	GetString(string) string

	// GetStringMap gets a map of string/any pairs from the KV.
	GetStringMap(string) map[string]any

	// GetStringMapString gets a map of string/string pairs from the KV.
	GetStringMapString(string) map[string]string

	// GetStringMapStringSlice gets a map of string/slice of strings pairs from
	// the KV.
	GetStringMapStringSlice(string) map[string][]string

	// GetStringSlice gets a slice of strings from the KV.
	GetStringSlice(string) []string

	// GetTime gets a time.Time value from the KV.
	GetTime(string) time.Time

	// GetUint gets a uint value from the KV.
	GetUint(string) uint

	// GetUint16 gets a uint16 value from the KV.
	GetUint16(string) uint16

	// GetUint32 gets a uint16 value from the KV.
	GetUint32(string) uint32

	// GetUint64 gets a uint16 value from the KV.
	GetUint64(string) uint64

	// Sub returns a KV that access keys under a subtree.
	Sub(string) KV

	// IsSet returns true if the KV contains a value for the given key.
	IsSet(string) bool

	// Clear deletes all values from the KV.
	Clear()

	// Set sets a value with the given key on the KV.
	Set(string, any)

	// Update sets all the values in the given map on the KV. This overwrites
	// existing keys. It does not perform a merge.
	Update(map[string]any)

	// UpdateStrings sets all the values in the given map on the KV. This will
	// perform a merge operation rather than overwrite.
	UpdateStrings(map[string]string)

	// RegisterAlias establishes a relationship between an old key name and a
	// new key name.
	RegisterAlias(string, string)
}

KV describes a key-value store interface that is used to hold configuration properties used by the various tools in zedpm. The internal storage of a KV is a hierarchical map of maps. This way deeply nested structures can be held. The deeply nested values can be retrieved using keys in dot-format.

For example, setting a value with a key named "git.release.tag" will ensure that the top-level map contains a key named "git" that points to map[string]any pointer. That map object will contain a key named "release" that points to another map[string]any pointer. This inner map will then have a key named "tag" which points to the value set.

The KV allows any kind of value to be set, but all values should coerce to string in order to allow them to be communicated over the wire between plugins.

type KVCfg 

type KVCfg struct {
	KVMem
}

KVCfg is a wrapper around a KVMem that panics if writes are attempted.

func (*KVCfg) Clear 

func (c *KVCfg) Clear()

Clear panics.

func (*KVCfg) Set 

func (c *KVCfg) Set(string, any)

Set panics.

func (*KVCfg) Update 

func (c *KVCfg) Update(map[string]any)

Update panics.

func (*KVCfg) UpdateStrings 

func (c *KVCfg) UpdateStrings(map[string]string)

UpdateStrings panics.

type KVChanges 

type KVChanges struct {

	// Inner is the KV wrapped by this and will not be modified by KVChanges
	// when Set or other write methods are called.
	Inner KV
	// contains filtered or unexported fields
}

KVChanges is a key-value store that tracks changes atop the Inner KV. If a value is changed, it will not change the Inner value. However, if that value is retrieved, the changed value will be returned by this object.

func WithChangeTracking 

func WithChangeTracking(inner KV) *KVChanges

WithChangeTracking adds change tracking to inner. The returned KVChanges object will not modify the inner object when write methods are called upon it, but will store the changes that are written.

func (*KVChanges) AllKeys 

func (c *KVChanges) AllKeys() []string

AllKeys will return all keys that have been set either on the Inner KV or added by making writes to this object.

func (*KVChanges) AllSettings 

func (c *KVChanges) AllSettings() map[string]any

AllSettings returns the complete map of values. This starts with the values in the Inner KV and then layers on local changes so that any key lookup in the returned map should have the same value there that it would have in the KVChanges object.

func (*KVChanges) AllSettingsStrings 

func (c *KVChanges) AllSettingsStrings() map[string]string

AllSettingsStrings returns the complete map of values as a flat set a strings with any local changes overriding those of the Inner KV.

func (*KVChanges) Changes 

func (c *KVChanges) Changes() map[string]any

Changes returns all the local changes as a hierarchical map of values.

func (*KVChanges) ChangesStrings 

func (c *KVChanges) ChangesStrings() map[string]string

ChangesStrings returns all the local changes as a flat map of string values.

func (*KVChanges) Clear 

func (c *KVChanges) Clear()

Clear will clear both the changes and the Inner.

func (*KVChanges) ClearChanges 

func (c *KVChanges) ClearChanges()

ClearChanges clears the local changes without modifying the Inner.

func (*KVChanges) Get 

func (c *KVChanges) Get(key string) any

func (*KVChanges) GetBool 

func (c *KVChanges) GetBool(key string) bool

func (*KVChanges) GetDuration 

func (c *KVChanges) GetDuration(key string) time.Duration

func (*KVChanges) GetFloat64 

func (c *KVChanges) GetFloat64(key string) float64

func (*KVChanges) GetInt 

func (c *KVChanges) GetInt(key string) int

func (*KVChanges) GetInt32 

func (c *KVChanges) GetInt32(key string) int32

func (*KVChanges) GetInt64 

func (c *KVChanges) GetInt64(key string) int64

func (*KVChanges) GetIntSlice 

func (c *KVChanges) GetIntSlice(key string) []int

func (*KVChanges) GetString 

func (c *KVChanges) GetString(key string) string

func (*KVChanges) GetStringMap 

func (c *KVChanges) GetStringMap(key string) map[string]any

func (*KVChanges) GetStringMapString 

func (c *KVChanges) GetStringMapString(key string) map[string]string

func (*KVChanges) GetStringMapStringSlice 

func (c *KVChanges) GetStringMapStringSlice(key string) map[string][]string

func (*KVChanges) GetStringSlice 

func (c *KVChanges) GetStringSlice(key string) []string

func (*KVChanges) GetTime 

func (c *KVChanges) GetTime(key string) time.Time

func (*KVChanges) GetUint 

func (c *KVChanges) GetUint(key string) uint

func (*KVChanges) GetUint16 

func (c *KVChanges) GetUint16(key string) uint16

func (*KVChanges) GetUint32 

func (c *KVChanges) GetUint32(key string) uint32

func (*KVChanges) GetUint64 

func (c *KVChanges) GetUint64(key string) uint64

func (*KVChanges) IsSet 

func (c *KVChanges) IsSet(key string) bool

IsSet returns true if the given key has been set in either the changes or the Inner.

func (*KVChanges) RegisterAlias 

func (c *KVChanges) RegisterAlias(alias, key string)

RegisterAlias registers an alias in the local changes and in the Inner.

func (*KVChanges) Set 

func (c *KVChanges) Set(key string, value any)

Set adds a setting to local changes and does not modify the Inner.

func (*KVChanges) Sub 

func (c *KVChanges) Sub(key string) KV

func (*KVChanges) Update 

func (c *KVChanges) Update(values map[string]any)

Update applies an update from the given map to local changes and odes not modify the Inner.

func (*KVChanges) UpdateStrings 

func (c *KVChanges) UpdateStrings(values map[string]string)

UpdateStrings applies an update from the given map to local changes and does not modify the Inner.

type KVCon 

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

KVCon wraps a KV in synchronization tooling that prevents concurrent modifications. This uses a sync.RWMutex so that many reads can happen simultaneously, but writes must be exclusive.

func WithLock added in v0.1.0 

func WithLock(inner KV, lock *sync.RWMutex) *KVCon

WithLock wraps the given KV in a concurrency safe KVCon using the given lock.

func WithSafeConcurrency 

func WithSafeConcurrency(inner KV) *KVCon

WithSafeConcurrency wraps the given KV in a concurrency safe KVCon.

func (*KVCon) AllKeys 

func (c *KVCon) AllKeys() []string

AllKeys retrieves all keys after acquiring a read lock.

func (*KVCon) AllSettings 

func (c *KVCon) AllSettings() map[string]any

AllSettings retrieves all settings after acquiring a read lock.

func (*KVCon) AllSettingsStrings 

func (c *KVCon) AllSettingsStrings() map[string]string

AllSettingsStrings gets all settings after acquiring a read lock.

func (*KVCon) Atomic 

func (c *KVCon) Atomic(call func(KV))

Atomic performs the given functional call after acquiring a write lock. The callback will receive the inner KV as an argument. This should be used for any operation that needs to be performed on the inner KV that would have a race condition if performed without a mutex lock around the whole operation.

func (*KVCon) Clear 

func (c *KVCon) Clear()

Clear deletes all value in the inner KV after acquiring a write lock.

func (*KVCon) Get 

func (c *KVCon) Get(key string) any

func (*KVCon) GetBool 

func (c *KVCon) GetBool(key string) bool

func (*KVCon) GetDuration 

func (c *KVCon) GetDuration(key string) time.Duration

func (*KVCon) GetFloat64 

func (c *KVCon) GetFloat64(key string) float64

func (*KVCon) GetInt 

func (c *KVCon) GetInt(key string) int

func (*KVCon) GetInt32 

func (c *KVCon) GetInt32(key string) int32

func (*KVCon) GetInt64 

func (c *KVCon) GetInt64(key string) int64

func (*KVCon) GetIntSlice 

func (c *KVCon) GetIntSlice(key string) []int

func (*KVCon) GetString 

func (c *KVCon) GetString(key string) string

func (*KVCon) GetStringMap 

func (c *KVCon) GetStringMap(key string) map[string]any

func (*KVCon) GetStringMapString 

func (c *KVCon) GetStringMapString(key string) map[string]string

func (*KVCon) GetStringMapStringSlice 

func (c *KVCon) GetStringMapStringSlice(key string) map[string][]string

func (*KVCon) GetStringSlice 

func (c *KVCon) GetStringSlice(key string) []string

func (*KVCon) GetTime 

func (c *KVCon) GetTime(key string) time.Time

func (*KVCon) GetUint 

func (c *KVCon) GetUint(key string) uint

func (*KVCon) GetUint16 

func (c *KVCon) GetUint16(key string) uint16

func (*KVCon) GetUint32 

func (c *KVCon) GetUint32(key string) uint32

func (*KVCon) GetUint64 

func (c *KVCon) GetUint64(key string) uint64

func (*KVCon) IsSet 

func (c *KVCon) IsSet(key string) bool

IsSet reports whether this value is set after acquiring a read lock.

func (*KVCon) RegisterAlias 

func (c *KVCon) RegisterAlias(alias, key string)

RegisterAlias adds an alias to the inner KV after acquiring a write lock.

func (*KVCon) Set 

func (c *KVCon) Set(key string, value any)

Set sets a value on the inner KV after acquiring a write lock.

func (*KVCon) Sub 

func (c *KVCon) Sub(key string) KV

Sub returns an object that retrieves a subset of the values guarded by the same lock.

func (*KVCon) Update 

func (c *KVCon) Update(values map[string]any)

Update applies an update after acquiring a write lock.

func (*KVCon) UpdateStrings 

func (c *KVCon) UpdateStrings(values map[string]string)

UpdateStrings applies an update after acquiring a write lock.

type KVExp 

type KVExp struct {
	KV
}

KVExp is a KV that only exposes a sub-set of values from the wrapped KV. In order for a property to be visible to any of the accessors called on it, there must exist a key named "__export__.<key>". Otherwise, this object will act as if the value is not set.

func ExportsOnly 

func ExportsOnly(values KV) *KVExp

ExportsOnly wraps the given KV in a KVExp.

func (*KVExp) AllKeys 

func (e *KVExp) AllKeys() []string

AllKeys returns exported keys only.

func (*KVExp) AllSettings 

func (e *KVExp) AllSettings() map[string]any

AllSettings returns exported values only.

func (*KVExp) AllSettingsStrings 

func (e *KVExp) AllSettingsStrings() map[string]string

AllSettingsStrings returns exported values only.

func (*KVExp) Get 

func (e *KVExp) Get(key string) any

func (*KVExp) GetBool 

func (e *KVExp) GetBool(key string) bool

func (*KVExp) GetDuration 

func (e *KVExp) GetDuration(key string) time.Duration

func (*KVExp) GetFloat64 

func (e *KVExp) GetFloat64(key string) float64

func (*KVExp) GetInt 

func (e *KVExp) GetInt(key string) int

func (*KVExp) GetInt32 

func (e *KVExp) GetInt32(key string) int32

func (*KVExp) GetInt64 

func (e *KVExp) GetInt64(key string) int64

func (*KVExp) GetIntSlice 

func (e *KVExp) GetIntSlice(key string) []int

func (*KVExp) GetString 

func (e *KVExp) GetString(key string) string

func (*KVExp) GetStringMap 

func (e *KVExp) GetStringMap(key string) map[string]any

func (*KVExp) GetStringMapString 

func (e *KVExp) GetStringMapString(key string) map[string]string

func (*KVExp) GetStringMapStringSlice 

func (e *KVExp) GetStringMapStringSlice(key string) map[string][]string

func (*KVExp) GetStringSlice 

func (e *KVExp) GetStringSlice(key string) []string

func (*KVExp) GetTime 

func (e *KVExp) GetTime(key string) time.Time

func (*KVExp) GetUint 

func (e *KVExp) GetUint(key string) uint

func (*KVExp) GetUint16 

func (e *KVExp) GetUint16(key string) uint16

func (*KVExp) GetUint32 

func (e *KVExp) GetUint32(key string) uint32

func (*KVExp) GetUint64 

func (e *KVExp) GetUint64(key string) uint64

func (*KVExp) IsSet 

func (e *KVExp) IsSet(key string) bool

func (*KVExp) Sub 

func (e *KVExp) Sub(key string) KV

type KVLayer 

type KVLayer struct {
	// Layers are the layers that make up the KV. Index 0 of Layers is the only
	// KV that can be modified by KVLayer. When performing read operations,
	// index 0 is checked for a value first, then 1, then 2, and so on until the
	// last layer is read.
	//
	// There must be at least one layer here if you like to avoid panics.
	Layers []KV
}

KVLayer is a KV built from other KV implementations. When setting a value, only the first KV in the Layers list is ever modified. When getting a value, the first layer is checked to see if it has that setting. If it does, that's the value returned. If not, the next layer is checked. This continues until the last layer is reached. If no layer has that setting set, the zero value is returned.

func Layers 

func Layers(layers ...KV) *KVLayer

Layers creates a KVLayer from the layers.

func (*KVLayer) AllKeys 

func (l *KVLayer) AllKeys() []string

AllKeys combines all the keys from all the layers.

func (*KVLayer) AllSettings 

func (l *KVLayer) AllSettings() map[string]any

AllSettings merges all the settings from all the layers.

func (*KVLayer) AllSettingsStrings 

func (l *KVLayer) AllSettingsStrings() map[string]string

AllSettingsStrings merges all the settings from all the layers.

func (*KVLayer) Clear 

func (l *KVLayer) Clear()

Clear clears all layers.

func (*KVLayer) Get 

func (l *KVLayer) Get(key string) any

func (*KVLayer) GetBool 

func (l *KVLayer) GetBool(key string) bool

func (*KVLayer) GetDuration 

func (l *KVLayer) GetDuration(key string) time.Duration

func (*KVLayer) GetFloat64 

func (l *KVLayer) GetFloat64(key string) float64

func (*KVLayer) GetInt 

func (l *KVLayer) GetInt(key string) int

func (*KVLayer) GetInt32 

func (l *KVLayer) GetInt32(key string) int32

func (*KVLayer) GetInt64 

func (l *KVLayer) GetInt64(key string) int64

func (*KVLayer) GetIntSlice 

func (l *KVLayer) GetIntSlice(key string) []int

func (*KVLayer) GetString 

func (l *KVLayer) GetString(key string) string

func (*KVLayer) GetStringMap 

func (l *KVLayer) GetStringMap(key string) map[string]any

func (*KVLayer) GetStringMapString 

func (l *KVLayer) GetStringMapString(key string) map[string]string

func (*KVLayer) GetStringMapStringSlice 

func (l *KVLayer) GetStringMapStringSlice(key string) map[string][]string

func (*KVLayer) GetStringSlice 

func (l *KVLayer) GetStringSlice(key string) []string

func (*KVLayer) GetTime 

func (l *KVLayer) GetTime(key string) time.Time

func (*KVLayer) GetUint 

func (l *KVLayer) GetUint(key string) uint

func (*KVLayer) GetUint16 

func (l *KVLayer) GetUint16(key string) uint16

func (*KVLayer) GetUint32 

func (l *KVLayer) GetUint32(key string) uint32

func (*KVLayer) GetUint64 

func (l *KVLayer) GetUint64(key string) uint64

func (*KVLayer) IsSet 

func (l *KVLayer) IsSet(key string) bool

IsSet returns true if the key is set in any layer.

func (*KVLayer) RegisterAlias 

func (l *KVLayer) RegisterAlias(alias, key string)

RegisterAlias registers the alias in all layers.

func (*KVLayer) Set 

func (l *KVLayer) Set(key string, value any)

Set sets the key in the first layer.

func (*KVLayer) Sub 

func (l *KVLayer) Sub(key string) KV

func (*KVLayer) Update 

func (l *KVLayer) Update(values map[string]any)

Update sets values in the first layer.

func (*KVLayer) UpdateStrings 

func (l *KVLayer) UpdateStrings(values map[string]string)

UpdateStrings sets values in the first layer.

type KVMem 

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

KVMem is the base building block of the storage package. It provides a basic in-memory store of a hierarchy of key/value pairs.

func New 

func New() *KVMem

New returns a new, empty KVMem.

func (*KVMem) AllKeys 

func (m *KVMem) AllKeys() []string

AllKeys returns a slice of strings that point to all the end values. It does not include any key that would point to a map of more values somewhere down the tree.

func (*KVMem) AllSettings 

func (m *KVMem) AllSettings() map[string]any

AllSettings returns a deep copy of the internal storage of KVMem.

func (*KVMem) AllSettingsStrings 

func (m *KVMem) AllSettingsStrings() map[string]string

AllSettingsStrings returns a flattened copy of the internal storage of KVMem.

func (*KVMem) Clear 

func (m *KVMem) Clear()

Clear resets the storage to empty.

func (*KVMem) Get 

func (m *KVMem) Get(key string) any

Get returns the value for the given key or nil.

func (*KVMem) GetBool 

func (m *KVMem) GetBool(key string) bool

GetBool returns the value of the given key as a boolean or false.

func (*KVMem) GetDuration 

func (m *KVMem) GetDuration(key string) time.Duration

GetDuration returns ehe value of the given key as a duration or zero.

func (*KVMem) GetFloat64 

func (m *KVMem) GetFloat64(key string) float64

GetFloat64 returns the value of the given key as a floating point value or zero.

func (*KVMem) GetInt 

func (m *KVMem) GetInt(key string) int

GetInt returns the value of the given key as an integer or zero.

func (*KVMem) GetInt32 

func (m *KVMem) GetInt32(key string) int32

GetInt32 returns the value of the given key as a 32-bit integer or zero.

func (*KVMem) GetInt64 

func (m *KVMem) GetInt64(key string) int64

GetInt64 returns the value of the given key as a 64-bit integer or zero.

func (*KVMem) GetIntSlice 

func (m *KVMem) GetIntSlice(key string) []int

GetIntSlice returns the value of the given key as an integer slice or nil.

func (*KVMem) GetString 

func (m *KVMem) GetString(key string) string

GetString returns the value of the given key as a string or an empty string.

func (*KVMem) GetStringMap 

func (m *KVMem) GetStringMap(key string) map[string]any

GetStringMap returns the value of the given key as a map of strings to any or nil.

func (*KVMem) GetStringMapString 

func (m *KVMem) GetStringMapString(key string) map[string]string

GetStringMapString returns the value of the given key as a map of strings to strings or nil.

func (*KVMem) GetStringMapStringSlice 

func (m *KVMem) GetStringMapStringSlice(key string) map[string][]string

GetStringMapStringSlice returns the value of the given key as a map of strings to string slices or nil.

func (*KVMem) GetStringSlice 

func (m *KVMem) GetStringSlice(key string) []string

GetStringSlice returns the value of the given key as a string slice or nil.

func (*KVMem) GetTime 

func (m *KVMem) GetTime(key string) time.Time

GetTime returns the value of the given key as a time.

func (*KVMem) GetUint 

func (m *KVMem) GetUint(key string) uint

GetUint returns the value of the given key as an unsigned integer.

func (*KVMem) GetUint16 

func (m *KVMem) GetUint16(key string) uint16

GetUint16 returns the value of the given key as a 16-bit unsigned integer.

func (*KVMem) GetUint32 

func (m *KVMem) GetUint32(key string) uint32

GetUint32 returns the value of the given key as a 32-bit unsigned integer.

func (*KVMem) GetUint64 

func (m *KVMem) GetUint64(key string) uint64

GetUint64 returns the value of the given key as a 64-bit unsigned integer.

func (*KVMem) IsPassingRequirements 

func (m *KVMem) IsPassingRequirements() bool

IsPassingRequirements returns true if all the required keys have been set.

func (*KVMem) IsRequired 

func (m *KVMem) IsRequired(key string) bool

IsRequired returns true if the given key has been marked as required.

func (*KVMem) IsSet 

func (m *KVMem) IsSet(key string) bool

IsSet returns true if the key has been set.

func (*KVMem) MarkRequired 

func (m *KVMem) MarkRequired(key string)

MarkRequired adds the given key to the list of required keys.

func (*KVMem) MissingRequirements 

func (m *KVMem) MissingRequirements() []string

MissingRequirements returns all the keys that are missing a value from the list of required keys.

func (*KVMem) RO 

func (m *KVMem) RO() *KVCfg

RO returns a KVCfg, which is a read-only version of the KVMem.

func (*KVMem) RegisterAlias 

func (m *KVMem) RegisterAlias(alias, key string)

RegisterAlias creates an alias so that any attempt to get or set alias will get or set key instead.

func (*KVMem) Set 

func (m *KVMem) Set(key string, value any)

Set sets the key to the given value.

func (*KVMem) Sub 

func (m *KVMem) Sub(key string) KV

Sub returns a KVMem pointing to all the same internals as this KVMem, but with a prefix set so that all reads ad writes only happen to keys with the given prefix.

func (*KVMem) Update 

func (m *KVMem) Update(values map[string]any)

Update replaces the top level keys with the given values. This does not merge.

func (*KVMem) UpdateStrings 

func (m *KVMem) UpdateStrings(values map[string]string)

UpdateStrings sets all the keys in the map. This effectively does a merge.

type Requirements 

type Requirements interface {
	// MarkRequired marks the name key as a required value that must be set.
	MarkRequired(string)

	// IsRequired returns true if the given key has been marked as required.
	IsRequired(string) bool

	// IsPassingRequirements returns true if all the required keys are set.
	IsPassingRequirements() bool

	// MissingRequirements returns the names of all the keys that are required,
	// but not currently not set.
	MissingRequirements() []string
}

Requirements is an additional layer that can be added to a KV to apply requirements to KVs.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.