Documentation ¶
Overview ¶
camellia is a lightweight, persistent, hierarchical key-value store.
Its minimal footprint (just a single SQLite .db file) makes it suitable for usage in embedded systems, or simply as a minimalist application settings container.
For more info about usage and examples, see the README at https://github.com/debevv/camellia
Index ¶
- Variables
- func Close() error
- func Delete(path string) error
- func EntryToJSON(path string) (string, error)
- func Exists(path string) (bool, error)
- func Force[T Stringable](path string, value T) error
- func ForceOrPanic[T Stringable](path string, value T)
- func Get[T Stringable](path string) (T, error)
- func GetDBPath() string
- func GetOrPanic[T Stringable](path string) T
- func GetOrPanicEmpty[T Stringable](path string) T
- func GetSupportedDBSchemaVersion() uint64
- func IsOpen() bool
- func Migrate(dbPath string) (bool, error)
- func Open(path string) (bool, error)
- func Recurse(path string, depth int, cb func(entry *Entry, parent *Entry, depth uint) error) error
- func Set[T Stringable](path string, value T) error
- func SetEntriesFromJSON(reader io.Reader, onlyMerge bool) error
- func SetHooksEnabled(enabled bool)
- func SetOrPanic[T Stringable](path string, value T)
- func SetPostSetHook(path string, callback func(path string, value string) error, async bool) error
- func SetPreSetHook(path string, callback func(path string, value string) error) error
- func SetValuesFromJSON(reader io.Reader, onlyMerge bool) error
- func ValuesToJSON(path string) (string, error)
- func Wipe() error
- type BaseType
- type Entry
- type Stringable
Constants ¶
This section is empty.
Variables ¶
var ( ErrPathInvalid = errors.New("invalid path") ErrPathNotFound = errors.New("path not found") ErrPathIsNotAValue = errors.New("path is not a value") ErrValueEmpty = errors.New("value is empty") ErrNoDB = errors.New("no DB currently opened") ErrDBVersionMismatch = errors.New("DB version mismatch") )
Functions ¶
func EntryToJSON ¶
ValuesToJSON represents the hierarchy of Entries at the specified path in the extended JSON format.
func Force ¶
func Force[T Stringable](path string, value T) error
Force sets a value of type T to the specified path.
If a non-value Entry already exists at the specified path, it is deleted first.
func ForceOrPanic ¶
func ForceOrPanic[T Stringable](path string, value T)
ForceOrPanic calls Force with the specified parameters, and panics in case of error.
func Get ¶
func Get[T Stringable](path string) (T, error)
Get reads the value a the specified path and returns it as type T.
func GetOrPanic ¶
func GetOrPanic[T Stringable](path string) T
GetOrPanic calls Get with the specified parameters, and panics in case of error.
func GetOrPanicEmpty ¶
func GetOrPanicEmpty[T Stringable](path string) T
GetOrPanic calls Get with the specified parameters, and panics if the read value is empty or in case of error.
func GetSupportedDBSchemaVersion ¶
func GetSupportedDBSchemaVersion() uint64
GetSupportedDBSchemaVersion returns the current supported DB schema version.
func Migrate ¶
Migrate migrates a DB at dbPath to the current supported DB schema version.
Returns true if the DB was actually migrated, false if it was already at the current supported DB schema version.
func Open ¶
Open initializes a camellia DB for usage.
Most of the API methods will return ErrNoDB if Open is not called first.
func Recurse ¶
Recurse recurses, breadth-first, the hierarchy of Entries at the specified path, starting with the Entry at the path.
For each entry, calls the specified callback with the Entry itself, its parent Entry, and the current relative depth in the hierarchy, with 0 being the depth of the Entry at the specified path.
func Set ¶
func Set[T Stringable](path string, value T) error
Set sets a value of type T to the specified path.
func SetEntriesFromJSON ¶
SetValuesFromJSON set (forces) the values found in the extended JSON representation read from reader.
If onlyMerge == true, does not overwrite an Entry with the one found in the JSON, if it already exists in the DB.
func SetHooksEnabled ¶
func SetHooksEnabled(enabled bool)
func SetOrPanic ¶
func SetOrPanic[T Stringable](path string, value T)
SetOrPanic calls Set with the specified parameters, and panics in case of error.
func SetPostSetHook ¶
SetPreSetHook registers a callback to be called after the value at the specified path is changed.
If async == false, if one of the registered callbacks on a path returns an error, the setting of the value at that path fails.
If async == true, the registered callback will be called inside a new goroutine, and its returned error is ignored.
Callback are always called in the same order as they were registered.
func SetPreSetHook ¶
SetPreSetHook registers a callback to be called before the value at the specified path is changed.
If one of the registered callbacks on a path returns an error, the setting of the value at that path fails.
Callbacks are called on the same thread executing the set operation, in the same order as they were registered.
func SetValuesFromJSON ¶
SetValuesFromJSON set (forces) the values found in the JSON representation read from reader.
If onlyMerge == true, does not overwrite an Entry with the value found in the JSON, if it already exists in the DB.
func ValuesToJSON ¶
ValuesToJSON represents the hierarchy of values at the specified path in the default JSON format.
Types ¶
type BaseType ¶
type BaseType interface { ~int | ~uint | ~int8 | ~uint8 | ~int32 | ~uint32 | ~int64 | ~uint64 | ~float32 | ~float64 | ~bool | ~string }
BaseType is the type set of built-in types accepted by Get/Set functions
type Entry ¶
type Entry struct { Path string LastUpdate time.Time IsValue bool Value string Children map[string]*Entry }
Entry represents a single node in the hierarchical store.
When IsValue == true, the Entry carries a value, and it's a leaf node in the hierarchy.
When IsValue == false, the Entry does not carry a value, but its Children map can contain Entires.
func GetEntry ¶
GetEntry returns the Entry at the specified path, including the eventual full hierarchy of children Entries.
func GetEntryDepth ¶
GetEntry returns the Entry at the specified path, including the eventual hierarchy of children Entries, but stopping at a specified depth.
With depth > 0, stops at the specified depth.
With depth == 0, returns the Entry with an empty Children map.
With depth < 0, returns the full hierarchy of children Entries.
func (Entry) MarshalJSON ¶
func (*Entry) UnmarshalJSON ¶
type Stringable ¶
type Stringable interface { BaseType }
Stringable is the type set of types accepted by Get/Set functions