README
¶
Stow
Usage
This package provides a persistence manager for objects backed by bbolt (orig. boltdb).
package main
import (
"encoding/gob"
"fmt"
"log"
bolt "go.etcd.io/bbolt"
"gopkg.in/djherbis/stow.v2"
)
func main() {
// Create a boltdb (bbolt fork) database
db, err := bolt.Open("my.db", 0600, nil)
if err != nil {
log.Fatal(err)
}
// Open/Create a Json-encoded Store, Xml and Gob are also built-in
// We'll we store a greeting and person in a boltdb bucket named "people"
peopleStore := stow.NewJSONStore(db, []byte("people"))
peopleStore.Put("hello", Person{Name: "Dustin"})
peopleStore.ForEach(func(greeting string, person Person) {
fmt.Println(greeting, person.Name)
})
// Open/Create a Gob-encoded Store. The Gob encoding keeps type information,
// so you can encode/decode interfaces!
sayerStore := stow.NewStore(db, []byte("greetings"))
var sayer Sayer = Person{Name: "Dustin"}
sayerStore.Put("hello", &sayer)
var retSayer Sayer
sayerStore.Get("hello", &retSayer)
retSayer.Say("hello")
sayerStore.ForEach(func(sayer Sayer) {
sayer.Say("hey")
})
}
type Sayer interface {
Say(something string)
}
type Person struct {
Name string
}
func (p Person) Say(greeting string) {
fmt.Printf("%s says %s.\n", p.Name, greeting)
}
func init() {
gob.Register(&Person{})
}
Installation
go get gopkg.in/djherbis/stow.v3
Documentation
¶
Overview ¶
Package stow is used to persist objects to a bolt.DB database.
Index ¶
- Variables
- func Register(value interface{})
- func RegisterName(name string, value interface{})
- type Codec
- type Decoder
- type Encoder
- type GobCodec
- type JSONCodec
- type Store
- func (s *Store) Delete(key interface{}) error
- func (s *Store) DeleteAll() error
- func (s *Store) ForEach(do interface{}) error
- func (s *Store) Get(key interface{}, b interface{}) error
- func (s *Store) NewCustomNestedStore(bucket []byte, codec Codec) *Store
- func (s *Store) NewNestedStore(bucket []byte) *Store
- func (s *Store) Pull(key interface{}, b interface{}) error
- func (s *Store) Put(key interface{}, b interface{}) error
- type XMLCodec
Constants ¶
This section is empty.
Variables ¶
ErrNotFound indicates object is not in database.
Functions ¶
func Register ¶
func Register(value interface{})
Register registers the type using gob.Register for use with NewStore() and the GobCodec.
Types ¶
type Codec ¶
Codec provides a mechanism for storing/retriving objects as streams of data.
func NewPooledCodec ¶
NewPooledCodec creates a new Codec which re-uses Encoder/Decoders created by the codec. Warning, this is only useful when creating Encoders/Decoders is 'expensive' and when they support being re-used. In order to support re-use encoders/decoders must be equivalent. For example, a new Gob Encoder is not equivalent to a Gob Encoder which has encoded a non-primitive type [it has cached type info]. On the other hand, a json Encoder is safe for re-use and so is a Primed Gob Encoder which has only encoded primed types since all primed types are cached for all encoders/decoders.
func NewPrimedCodec ¶
NewPrimedCodec delegates to the passed codec for creating Encoders/Decoders. Newly created Encoder/Decoders will Encode/Decode the passed sample structs without actually writing/reading from their respective Writer/Readers. This is useful for Codec's like GobCodec{} which encodes/decodes extra type information whenever it sees a new type. Pass sample values for types you plan on Encoding/Decoding to this method in order to avoid the storage overhead of encoding their type informaton for every NewEncoder/NewDecoder. The order that types are listed (even through recursive encoding of a type) of the passed sample types must be consistent across re-loads. This means that modifying the definition of sample types may not be supported. Also, avoid introducing types via map keys/values as map iteration isn't consistent. Introducing new types during encoding will prevent you from adding new types to the Primed type-set, and also will include the type definiftion over-head in thier output. Warning, PrimedCodec should be used consistently (for reading & writing). It won't be able to read data written by unprimed encoders, and data written by it won't be able to be read by unprimed decoders.
type Decoder ¶
type Decoder interface {
Decode(interface{}) error
}
Decoder is used to decode objects
type Encoder ¶
type Encoder interface {
Encode(interface{}) error
}
Encoder is used to encode objects
type GobCodec ¶
type GobCodec struct{}
GobCodec is used to encode/decode using the Gob format.
func (GobCodec) NewDecoder ¶
NewDecoder returns a new gob decoder which reads from r
type JSONCodec ¶
type JSONCodec struct{}
JSONCodec is used to encode/decode JSON
func (JSONCodec) NewDecoder ¶
NewDecoder returns a new json decoder which reads from r
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store manages objects persistence.
func NewCustomStore ¶
NewCustomStore allows you to create a store with a custom underlying Encoding
func NewJSONStore ¶
NewJSONStore creates a new Store, using the underlying bolt.DB "bucket" to persist objects as json.
func NewStore ¶
NewStore creates a new Store, using the underlying bolt.DB "bucket" to persist objects. NewStore uses GobEncoding, your objects must be registered via gob.Register() for this encoding to work.
func NewXMLStore ¶
NewXMLStore creates a new Store, using the underlying bolt.DB "bucket" to persist objects as xml.
func (*Store) Delete ¶
Delete will remove the item with the specified key from the store. It returns nil if the item was not found (like BoltDB).
func (*Store) ForEach ¶
ForEach will run do on each object in the store. do can be a function which takes either: 1 param which will take on each "value" or 2 params where the first param is the "key" and the second is the "value".
func (*Store) Get ¶
Get will retrieve b with key "key". If key is []byte or string it uses the key directly. Otherwise, it marshals the given type into bytes using the stores Encoder.
func (*Store) NewCustomNestedStore ¶
NewCustomNestedStore works the same as NewNestedStore except you can override the Codec used by the returned Store.
func (*Store) NewNestedStore ¶
NewNestedStore returns a new Store which is nested inside the current store's bucket. It inherits the original store's Codec, and will be deleted by the parent store's DeleteAll method. Also note that buckets are in the parents key-space so you cannot have a NestedStore whose "bucket" is the same as a parent's key.
func (*Store) Pull ¶
Pull will retrieve b with key "key", and removes it from the store.
Source Files