stow

package module
Version: v4.0.0 Latest Latest
Warning

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

Go to latest
Published: Apr 25, 2021 License: MIT Imports: 11 Imported by: 0

README

Stow

GoDoc Release Software License Build Status Coverage Status Go Report Card

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.v3"
)

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 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

Constants

This section is empty.

Variables

View Source
var ErrNotFound = errors.New("not found")

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.

func RegisterName

func RegisterName(name string, value interface{})

RegisterName registers the type using gob.RegisterName for use with NewStore() and the GobCodec.

Types

type Codec

type Codec interface {
	NewEncoder(io.Writer) Encoder
	NewDecoder(io.Reader) Decoder
}

Codec provides a mechanism for storing/retriving objects as streams of data.

func NewPooledCodec

func NewPooledCodec(codec Codec) Codec

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

func NewPrimedCodec(codec Codec, types ...interface{}) (Codec, error)

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

func (c GobCodec) NewDecoder(r io.Reader) Decoder

NewDecoder returns a new gob decoder which reads from r

func (GobCodec) NewEncoder

func (c GobCodec) NewEncoder(w io.Writer) Encoder

NewEncoder returns a new gob encoder which writes to w

type JSONCodec

type JSONCodec struct{}

JSONCodec is used to encode/decode JSON

func (JSONCodec) NewDecoder

func (c JSONCodec) NewDecoder(r io.Reader) Decoder

NewDecoder returns a new json decoder which reads from r

func (JSONCodec) NewEncoder

func (c JSONCodec) NewEncoder(w io.Writer) Encoder

NewEncoder returns a new json encoder which writes to w

type Store

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

Store manages objects persistence.

func NewCustomStore

func NewCustomStore(db *bolt.DB, bucket []byte, codec Codec) *Store

NewCustomStore allows you to create a store with a custom underlying Encoding

func NewJSONStore

func NewJSONStore(db *bolt.DB, bucket []byte) *Store

NewJSONStore creates a new Store, using the underlying bolt.DB "bucket" to persist objects as json.

func NewStore

func NewStore(db *bolt.DB, bucket []byte) *Store

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

func NewXMLStore(db *bolt.DB, bucket []byte) *Store

NewXMLStore creates a new Store, using the underlying bolt.DB "bucket" to persist objects as xml.

func (*Store) Delete

func (s *Store) Delete(key interface{}) error

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) DeleteAll

func (s *Store) DeleteAll() error

DeleteAll empties the store

func (*Store) ForEach

func (s *Store) ForEach(do interface{}) error

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

func (s *Store) Get(key interface{}, b interface{}) error

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

func (s *Store) NewCustomNestedStore(bucket []byte, codec Codec) *Store

NewCustomNestedStore works the same as NewNestedStore except you can override the Codec used by the returned Store.

func (*Store) NewNestedStore

func (s *Store) NewNestedStore(bucket []byte) *Store

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

func (s *Store) Pull(key interface{}, b interface{}) error

Pull will retrieve b with key "key", and removes it from the store.

func (*Store) Put

func (s *Store) Put(key interface{}, b interface{}) error

Put will store 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.

type XMLCodec

type XMLCodec struct{}

XMLCodec is used to encode/decode XML

func (XMLCodec) NewDecoder

func (c XMLCodec) NewDecoder(r io.Reader) Decoder

NewDecoder returns a new xml decoder which reads from r

func (XMLCodec) NewEncoder

func (c XMLCodec) NewEncoder(w io.Writer) Encoder

NewEncoder returns a new xml encoder which writes to w

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL