hatchback

package module
v0.0.0-...-0574493 Latest Latest
Warning

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

 Go to latest Published: Dec 10, 2021 License: BSD-3-Clause Imports: 10 Imported by: 0

README

Hatchback

builds.sr.ht status go.dev reference

NOTE: Hatchback is in an early state of development. Use it in production at your own risk.

Hatchback is a library for storing data in a standalone SQLite database file for Fyne applications. It can act as a key-value-pair store for string keys and values of many different types, and also supports Fyne data binding and the Fyne Preferences interface. Hatchback aims to offer a mix of simplicity, performance, and robustness suitable for desktop applications that need to store medium amounts of data.

Name

Much like the type of car, Hatchback is designed to provide a mix of ease-of-use, performance, and robustness that will be suitable for a majority of use cases.

Roadmap

Support storing the following data types:

  • DONE Bool
  • DONE BoolList
  • DataMap
  • DONE Float
  • FloatList
  • DONE Int
  • IntList
  • DONE String
  • DONE StringList
  • Struct
  • DONE Untyped
  • UntypedList
  • UntypedMap

Support binding the following data types:

  • DONE Bool
  • DONE BoolList
  • DataMap
  • DONE Float
  • FloatList
  • DONE Int
  • IntList
  • DONE String
  • DONE StringList
  • Struct
  • DONE Untyped
  • UntypedList
  • UntypedMap

Support storing file-like data for use with storage repositories

  • CopyableRepository
  • HierarchicalRepository
  • ListableRepository
  • MovableRepository
  • Repository

Support for JSON marshaling/unmarshaling for backups.

  • Marshal
  • Unmarshal

Discuss & Contribute

Feel free to discuss or send patches via my public inbox.

License

Copyright 2021 Charles Daniels, released under BSD 3-clause. See ./LICENSE.

Documentation

Overview

Package hatchback implements an easy-to-use API, interoperable with Fyne's data binding API for storing data in SQLite databases. Hatchback is intended for implementing application-specific file formats for Fyne applications.

Index

Constants

View Source 
const DatastoreMagic = "9e1f63f7-a6b1-4d50-88e8-269ccca04d89"

DatastoreMagic is stored in the special "metadata" table and is used to verify that this database really came from hatchback.Datastore.

View Source 
const DatastoreVersion = 1

DatastoreVersion identifies the file format version of Datastore. The version history is as follows:

1 - initial version

Variables

This section is empty.

Functions

func IsErrDatastoreNoSuchKey 

func IsErrDatastoreNoSuchKey(e error) bool

IsErrDatastoreNoSuchKey return True if the given error is a ErrDatastoreNoSuchKey.

Types

type Datastore 

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

Datastore allows for storing data in an SQLite 3 database, mimicking the Fyne preferences API (in fact, Datastore is a valid implementation of the Preferences API, though that is not its intended use case), including it's data-binding capabilities. This can be useful for creating application-specific data storage for data that is not suitable for use with the Fyne preferences API - for example data that is relatively large. SQLite offers a number of advantages - correct handling of cross-platform file locking, good performance, ACID compliance, and so on.

Although the preferences API is implemented, meaning that preferences bindings may be used for primitive types, this is discouraged for performance reasons - because the preferences listener API is not very granular, each time a listener must be triggered, the entire set of bound values must be scanned. Though this is fine for a small number of values, it means that performance will degrade linearly on the number of bindings. Datastore should offer roughly O(L) performance assuming an average of L bindings per key.

This API assumes that it is the only API that is used to access the given table - it may create, destroy, or modify any table in the database file as it wishes.

A separate table is created for each binding type, using one column for the key, and one for the value. Keys must be unique across all binding type, and may not be empty.

If a key is written with a particular type, and then with a second, different type, the original value is deleted and the key is now of the second type.

NOTE: this API assumes that overwriting a key with the same value should still trigger event listeners. e.g. X.SetString("foo", "bar"); X.SetString("foo", "bar") would cause a data binding for key "foo" to update twice.

NOTE: concurrent access to the same database by multiple processes is not supported and will result in undefined behavior. However, concurrent access from multiple goroutines in the same process is supported.

func NewDatastore 

func NewDatastore(path string) (*Datastore, error)

NewDatastore instances a new Datastore object.

The path may be either a file on-disk, or ":memory:" for an in-memory database.

func (*Datastore) AddChangeListener 

func (ds *Datastore) AddChangeListener(listener func())

AddChangeListener implements fyne.Preferences

func (*Datastore) BindBool 

func (ds *Datastore) BindBool(key string) binding.Bool

BindBool creates a new bool binding for a key in the datastore.

func (*Datastore) BindBoolList 

func (ds *Datastore) BindBoolList(key string) binding.BoolList

BindBoolList creates a new string binding for a key in the datastore.

func (*Datastore) BindFloat 

func (ds *Datastore) BindFloat(key string) binding.Float

BindFloat creates a new float binding for a key in the datastore.

func (*Datastore) BindInt 

func (ds *Datastore) BindInt(key string) binding.Int

BindInt creates a new int binding for a key in the datastore.

func (*Datastore) BindString 

func (ds *Datastore) BindString(key string) binding.String

BindString creates a new string binding for a key in the datastore.

func (*Datastore) BindStringList 

func (ds *Datastore) BindStringList(key string) binding.StringList

BindStringList creates a new string binding for a key in the datastore.

func (*Datastore) BindUntyped 

func (ds *Datastore) BindUntyped(key string, serialize func(interface{}) ([]byte, error), deserialize func([]byte) (interface{}, error)) binding.Untyped

BindUntyped creates a new untyped binding for a key in the datastore.

The caller must provide the methods that will be used to serialize and serialize the data in the database. The serialization methods cannot be changed after the binding is created.

func (*Datastore) Bool 

func (ds *Datastore) Bool(key string) bool

Bool returns the bool associated with the given key, or false if it does not exist or is not of type bool.

Bool implements the fyne.Preferences interface.

func (*Datastore) BoolList 

func (ds *Datastore) BoolList(key string) []bool

BoolList returns the bool list associated with the given key, or nil if it does not exist or is not of type bool list.

func (*Datastore) BoolListWithFallback 

func (ds *Datastore) BoolListWithFallback(key string, fallback []bool) []bool

BoolListWithFallback returns either the bool list associated with the given key, or else a fallback list.

func (*Datastore) BoolWithFallback 

func (ds *Datastore) BoolWithFallback(key string, fallback bool) bool

BoolWithFallback implements the fyne.Preferences interface.

func (*Datastore) CheckedBool 

func (ds *Datastore) CheckedBool(key string) (bool, error)

CheckedBool works similarly to Bool(), but also returns an error if one was encountered.

func (*Datastore) CheckedBoolList 

func (ds *Datastore) CheckedBoolList(key string) ([]bool, error)

CheckedBoolList works similarly to BoolList(), but also returns an error if one was encountered.

func (*Datastore) CheckedFloat 

func (ds *Datastore) CheckedFloat(key string) (float64, error)

CheckedFloat works similarly to Float(), but also returns an error if one was encountered.

func (*Datastore) CheckedInt 

func (ds *Datastore) CheckedInt(key string) (int, error)

CheckedInt works similarly to Int(), but also returns an error if one was encountered.

func (*Datastore) CheckedRemoveValue 

func (ds *Datastore) CheckedRemoveValue(key string) error

CheckedRemoveValue works identically to RemoveValue(), but returns an error if one was encountered.

func (*Datastore) CheckedSetBool 

func (ds *Datastore) CheckedSetBool(key string, value bool) error

CheckedSetBool works identically to SetBool(), but also returns an error if one occurred.

func (*Datastore) CheckedSetBoolList 

func (ds *Datastore) CheckedSetBoolList(key string, value []bool) error

CheckedSetBoolList works identically to SetBoolList(), but also returns an error if one occurred.

func (*Datastore) CheckedSetFloat 

func (ds *Datastore) CheckedSetFloat(key string, value float64) error

CheckedSetFloat works identically to SetFloat(), but also returns an error if one occurred.

func (*Datastore) CheckedSetInt 

func (ds *Datastore) CheckedSetInt(key string, value int) error

CheckedSetInt works identically to SetInt(), but also returns an error if one occurred.

func (*Datastore) CheckedSetString 

func (ds *Datastore) CheckedSetString(key, value string) error

CheckedSetString works identically to SetString(), but also returns an error if one occurred.

func (*Datastore) CheckedSetStringList 

func (ds *Datastore) CheckedSetStringList(key string, value []string) error

CheckedSetStringList works identically to SetStringList(), but also returns an error if one occurred.

func (*Datastore) CheckedSetUntyped 

func (ds *Datastore) CheckedSetUntyped(key string, value []byte) error

CheckedSetUntyped sets the serialized version of the untyped value referenced by the given key, returning any error that occurred.

func (*Datastore) CheckedString 

func (ds *Datastore) CheckedString(key string) (string, error)

CheckedString works similarly to String(), but also returns an error if one was encountered.

func (*Datastore) CheckedStringList 

func (ds *Datastore) CheckedStringList(key string) ([]string, error)

CheckedStringList works similarly to StringList(), but also returns an error if one was encountered.

func (*Datastore) CheckedUntyped 

func (ds *Datastore) CheckedUntyped(key string) ([]byte, error)

CheckedUntyped returns the serialized version of the untyped data referenced by the given key, or a nil byte array and an error if one occurred.

func (*Datastore) Close 

func (ds *Datastore) Close() error

Close closes the underlying database connection, and removes all listeners from the datastore.

func (*Datastore) Float 

func (ds *Datastore) Float(key string) float64

Float returns the float associated with the given key, or 0.0 if it does not exist or is not of type float.

Float implements the fyne.Preferences interface.

func (*Datastore) FloatWithFallback 

func (ds *Datastore) FloatWithFallback(key string, fallback float64) float64

FloatWithFallback implements the fyne.Preferences interface.

func (*Datastore) GetAppName 

func (ds *Datastore) GetAppName() (string, error)

GetAppName returns the application name if one has been set, and otherwise an empty string an error.

func (*Datastore) GetAppVersion 

func (ds *Datastore) GetAppVersion() (int, error)

GetAppVersion returns the application name if one has been set, and otherwise an empty string an error.

func (*Datastore) GetVersion 

func (ds *Datastore) GetVersion() (int, error)

GetVersion gets the format version of the Datastore file. This may be useful for detecting when upgrades need to be performed, if the format version is ever updated.

func (*Datastore) Int 

func (ds *Datastore) Int(key string) int

Int returns the int associated with the given key, or 0 if it does not exist or is not of type int.

Int implements the fyne.Preferences interface.

func (*Datastore) IntWithFallback 

func (ds *Datastore) IntWithFallback(key string, fallback int) int

IntWithFallback implements the fyne.Preferences interface.

func (*Datastore) Keys 

func (ds *Datastore) Keys() ([]string, error)

Keys returns a list of all keys in the datastore irrespective of type.

func (*Datastore) KeysAndTypes 

func (ds *Datastore) KeysAndTypes() ([]string, []string, error)

KeysAndTypes returns a list of keys, as well as their corresponding data types.

keys, types, err := X.KeysAndTypes()

func (*Datastore) RemoveValue 

func (ds *Datastore) RemoveValue(key string)

RemoveValue implements fyne.Preferences

func (*Datastore) SetAppName 

func (ds *Datastore) SetAppName(name string) error

SetAppName sets the application name overwriting any which already exists.

This functionality can be useful to allow applications to determine if a particular Datastore file originated from an instance of that application.

func (*Datastore) SetAppVersion 

func (ds *Datastore) SetAppVersion(version int) error

SetAppVersion sets the application name overwriting any which already exists.

This functionality can be useful to allow applications to track changes to its own file format version, for example to determine if data from an older version needs to be migrated to a newer one.

func (*Datastore) SetBool 

func (ds *Datastore) SetBool(key string, value bool)

SetBool implements the fyne.Preferences interface.

func (*Datastore) SetBoolList 

func (ds *Datastore) SetBoolList(key string, value []bool)

SetBoolList implements the fyne.Preferences interface.

func (*Datastore) SetFloat 

func (ds *Datastore) SetFloat(key string, value float64)

SetFloat implements the fyne.Preferences interface.

func (*Datastore) SetInt 

func (ds *Datastore) SetInt(key string, value int)

SetInt implements the fyne.Preferences interface.

func (*Datastore) SetString 

func (ds *Datastore) SetString(key, value string)

SetString implements the fyne.Preferences interface.

func (*Datastore) SetStringList 

func (ds *Datastore) SetStringList(key string, value []string)

SetStringList implements the fyne.Preferences interface.

func (*Datastore) SetUntyped 

func (ds *Datastore) SetUntyped(key string, value []byte)

SetUntyped sets the serialized version of the untyped value referenced by the given key.

func (*Datastore) String 

func (ds *Datastore) String(key string) string

String returns the string associated with the given key, or the empty string if it does not exist or is not of type string.

String implements the fyne.Preferences interface.

func (*Datastore) StringList 

func (ds *Datastore) StringList(key string) []string

StringList returns the string list associated with the given key, or nil if it does not exist or is not of type string.

func (*Datastore) StringListWithFallback 

func (ds *Datastore) StringListWithFallback(key string, fallback []string) []string

StringListWithFallback returns either the string list associated with the given key, or else a fallback list.

func (*Datastore) StringWithFallback 

func (ds *Datastore) StringWithFallback(key, fallback string) string

StringWithFallback implements the fyne.Preferences interface.

func (*Datastore) Untyped 

func (ds *Datastore) Untyped(key string) []byte

Untyped returns the serialized version of the untyped data referenced by the given key, or a nil byte array if it does not exist or is the wrong type.

func (*Datastore) UntypedWithFallback 

func (ds *Datastore) UntypedWithFallback(key string, fallback []byte) []byte

UntypedWithFallback returns the serialized version of the untyped data referenced by the given key, or the specified byte array if the key does not exist or is the wrong type.

type ErrDatastoreNoSuchKey 

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

ErrDatastoreNoSuchKey indicates that the requested key either is not present within the datastore, or that it corresponds to a value of a type other than the one requested.

func (*ErrDatastoreNoSuchKey) Error 

func (e *ErrDatastoreNoSuchKey) Error() string

Source Files

View all Source files

Directories

Path Synopsis
cmd
hatchback-explorer

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.