unikv

README

unikv

(sub project of apiles)

Simple KV memory middleware library (for Golang).

Installation

go get github.com/apiles/unikv

Usage

First import packages:

import (
    "github.com/apiles/unikv"
    _ "github.com/apiles/unikv/drivers"
)

Note that github.com/apiles/unikv/drivers contains all the available drivers.

You can specify that with importing github.com/apiles/unikv/memory or something.

Available drivers:

name	address
memory	github.com/apiles/unikv/memory
redis	github.com/apiles/unikv/redis

Then you need to specify an unikv.yml. An example is included in docs/unikv.yml.

Note that unikv will look it up in the current work directory. You can also specify it by setting the environment varaible UNIKV_CONFIGURE.

Then you can see this example:

func main() {
    ns := unikv.NewNamespace("hello")
    bucket, err := ns.NewBucket("new")
    defer bucket.Close()
    if err != nil {
        panic(err)
    }
    bucket.PutString("hello", "world")
    bucket.PutInt("new", 1234)
    bucket.Put("c", true)
    var c bool
    bucket.Get("c", &c)
    value, _ := bucket.GetString("hello")
    in, _ := bucket.GetInt("new")
    fmt.Println(value, in, c)
}

API Docs

Go to https://pkg.go.dev/github.com/apiles/unikv.

UniKVd

See <docs/unikvd-protocol.md>.

Documentation

Overview

Package unikv provides a memory kv storage middleware

Index

• Constants
• Variables
• func ConcatPrefix(prefix string, str string) string
• func DriverLoadContext(ctx DriverContextRaw, dest interface{}) error
• func IsErrNotFound(err error) bool
• func RegisterDriver(driver *DriverDescriptor)
• func ReloadConfigure()
• func TrimPrefix(prefix string, str string) string
• type Bucket
  • func (b *Bucket) Close() error
  • func (b *Bucket) Get(key interface{}, dest interface{}) error
  • func (b *Bucket) GetInt(key interface{}) (int, error)
  • func (b *Bucket) GetString(key interface{}) (string, error)
  • func (b *Bucket) List() ([]Key, error)
  • func (b *Bucket) Put(key interface{}, value interface{}) error
  • func (b *Bucket) PutInt(key interface{}, value int) error
  • func (b *Bucket) PutString(key interface{}, str string) error
  • func (b *Bucket) Unset(key interface{}) error
• type Configure
  • func GetConfigure() *Configure
  • func (c *Configure) GetNamespace(name string) (*ConfigureNamespaces, bool)
  • func (c *Configure) GetNamespaceList() []string
• type ConfigureBuckets
• type ConfigureDefault
• type ConfigureNamespaces
  • func (c *ConfigureNamespaces) GetBucket(name string) (*ConfigureBuckets, bool)
  • func (c *ConfigureNamespaces) GetBucketList() []string
• type Driver
• type DriverContextRaw
• type DriverDescriptor
  • func (ds *DriverDescriptor) Construct(prefix string, ctx DriverContextRaw) (Driver, error)
• type Key
  • func NewKey(key interface{}) Key
• type KeyString
  • func (ks KeyString) String() string
• type Namespace
  • func NewNamespace(name string) *Namespace
  • func (ns *Namespace) Close()
  • func (ns *Namespace) NewBucket(name string) (*Bucket, error)

Constants

const ConfigureEnvName = "UNIKV_CONFIGURE"

ConfigureEnvName is the name of the environment variable of unikv's configure file

const DefaultConfigureFile = "unikv.yml"

DefaultConfigureFile is the default filename of unikv's configure

const DefaultDriver = "memory"

DefaultDriver determines the default driver to use when not specified

The driver must be without context

const PrefixSeparator = ":"

PrefixSeparator separates different parts of a key's prefix

const Version = 1

Version declares the api version of unikv

Variables

var ErrNotFound = fmt.Errorf("ErrNotFound")

ErrNotFound is thrown when trying to access an unset key

var KeyNil = KeyString("(unikv_nil)")

KeyNil is blanck key

Functions

func ConcatPrefix

func ConcatPrefix(prefix string, str string) string

ConcatPrefix concats two prefixes together

func DriverLoadContext

func DriverLoadContext(ctx DriverContextRaw, dest interface{}) error

DriverLoadContext loads raw context into a structure

func IsErrNotFound

func IsErrNotFound(err error) bool

IsErrNotFound checks if an error is unikv.ErrNotFound

func RegisterDriver

func RegisterDriver(driver *DriverDescriptor)

RegisterDriver registers a new driver

func ReloadConfigure

func ReloadConfigure()

ReloadConfigure reloads the configure

func TrimPrefix

func TrimPrefix(prefix string, str string) string

TrimPrefix trims the prefix of the given string

Types

type Bucket

type Bucket struct {
	Name          string
	Prefix        string
	NamespaceName string
	Driver        Driver
	// contains filtered or unexported fields
}

Bucket is a unikv store bucket

func (*Bucket) Close

func (b *Bucket) Close() error

Close closes a bucket

func (*Bucket) Get

func (b *Bucket) Get(key interface{}, dest interface{}) error

Get gets value into dest

func (*Bucket) GetInt

func (b *Bucket) GetInt(key interface{}) (int, error)

GetInt gets int value

func (*Bucket) GetString

func (b *Bucket) GetString(key interface{}) (string, error)

GetString gets string value

func (*Bucket) List

func (b *Bucket) List() ([]Key, error)

List lists keys

func (*Bucket) Put

func (b *Bucket) Put(key interface{}, value interface{}) error

Put puts value

func (*Bucket) PutInt

func (b *Bucket) PutInt(key interface{}, value int) error

PutInt puts int value

func (*Bucket) PutString

func (b *Bucket) PutString(key interface{}, str string) error

PutString puts string value

func (*Bucket) Unset

func (b *Bucket) Unset(key interface{}) error

Unset unsets a value

type Configure

type Configure struct {
	Separator  string                          `yaml:"separator" json:"separator"`
	Default    *ConfigureDefault               `yaml:"default" json:"default"`
	Namespaces map[string]*ConfigureNamespaces `yaml:"namespaces" json:"namespaces"`
}

Configure is unikv's configure structure

func GetConfigure

func GetConfigure() *Configure

GetConfigure returns the configure structure

func (*Configure) GetNamespace

func (c *Configure) GetNamespace(name string) (*ConfigureNamespaces, bool)

GetNamespace returns a specificated namespace from the list

func (*Configure) GetNamespaceList

func (c *Configure) GetNamespaceList() []string

GetNamespaceList returns the list of namespaces

type ConfigureBuckets

type ConfigureBuckets struct {
	Prefix  string           `yaml:"prefix" json:"prefix"`
	Driver  string           `yaml:"driver" json:"driver"`
	Context DriverContextRaw `yaml:"context" json:"context"`
}

ConfigureBuckets is the bucket segment in unikv's configure

type ConfigureDefault

type ConfigureDefault struct {
	Driver  string           `yaml:"driver" json:"driver"`
	Context DriverContextRaw `yaml:"context" json:"context"`
}

ConfigureDefault is the default segment in unikv's configure

type ConfigureNamespaces

type ConfigureNamespaces struct {
	Prefix  string                       `yaml:"prefix" json:"prefix"`
	Buckets map[string]*ConfigureBuckets `yaml:"buckets" json:"buckets"`
}

ConfigureNamespaces is the namespace segment in unikv's configure

func (*ConfigureNamespaces) GetBucket

func (c *ConfigureNamespaces) GetBucket(name string) (*ConfigureBuckets, bool)

GetBucket returns the bucket

func (*ConfigureNamespaces) GetBucketList

func (c *ConfigureNamespaces) GetBucketList() []string

GetBucketList returns bucket list

type Driver

type Driver interface {
	Get(key string) (string, error)
	Put(key string, data string) error
	Unset(key string) error
	List() (interface{}, error) // interface{} should be []unikv.Key or []string
	Close() error
}

Driver declares a unikv storage driver

type DriverContextRaw

type DriverContextRaw map[string]interface{}

DriverContextRaw contains the raw map of driver configuration passed in within unikv configure

type DriverDescriptor

type DriverDescriptor struct {
	Name        string
	Constructor func(prefix string, ctx DriverContextRaw) (Driver, error)
}

DriverDescriptor is used for storing meta information of the driver

func (*DriverDescriptor) Construct

func (ds *DriverDescriptor) Construct(prefix string, ctx DriverContextRaw) (Driver, error)

Construct a new driver instance

type Key

type Key interface {
	// Convert to string
	String() string
}

Key is the type of unikv key

func NewKey

func NewKey(key interface{}) Key

NewKey creates a new key

type KeyString

type KeyString string

KeyString is string key

func (KeyString) String

func (ks KeyString) String() string

String converts KeyString to string

type Namespace

type Namespace struct {
	Name   string
	Prefix string
	// contains filtered or unexported fields
}

Namespace is the namespace type

func NewNamespace

func NewNamespace(name string) *Namespace

NewNamespace creates a new namespace

func (*Namespace) Close

func (ns *Namespace) Close()

Close closes all the buckets in a namespace

func (*Namespace) NewBucket

func (ns *Namespace) NewBucket(name string) (*Bucket, error)

NewBucket creates a new bucket on a namespace