database

Documentation

Overview

Package database is a very simple way of storing structured and arbitrary entry types. It's as simple as simple can be but is still useful in helping to organise what is essentially a flat file.

Use of a database requires starting a "session". We do this with the StartSession() function, coupled with an EndSession() once we're done. For example (error handling removed for clarity):

db, _ := database.StartSession(dbPath, database.ActivityCreating, initDBSession)
defer db.EndSession(true)

The first agument is the path to the database file on the local disk. The second argument is a description of the type of activity that will be happening during the session. In this instance, we saying that the database will be created if it does not already exist. If the database already exists ActivityCreating is treated the same as ActivityModifying. If we don't want to modify the database at all, then we can use ActivityReading.

The third argument is the database initialisation function. An important part of this database package is its ability to handle arbitrary entry types. The initialisation function takes a pointer to the new database session as its sole argument:

func initSession(db *database.Session) {
	db.RegisterEntryType("foo", deserialseFoo)
	db.RegisterEntryType("bar", deserialseBar
}

The RegisterEntryType() lets the database know what entry types it might expect. The first argument specifies the entry ID that will be stored in the database. On reading, the database will call the deserialisation function specified in the second argument.

The deserialise function takes an array of strings as it's only argument and returns a new database.Entry and any errors. Database entries are deserialised as part of the StartSession() function. Any errors created by the deserialiser function cause the StartSession() to fail and to propagate the error outwards.

func deserialiseFoo(fields []string) (database.Entry, error) {
	ent := &fooEntry{}
	ent.numOfFoos = fields[0]
	return ent, nil
}

In this example, a Foo entry contains just one field. Fields are numbered from zero (the database entry will contain other fields but they are not passed to the deserialise function).

For convenience, we copy the field entry to the fooEntry() type. In this instance, we do not need to convert the field type but if we did (it might be more convenient to treat a field as a boolean, for example) we would do it here.

Deserialisation functions return a value that satisfies the database.Entry interface. See the Entry interface definition for details.

Once a database session has successfully initialised, entries can be added, removed and selected/listed; activity type permitted.

Index

• Constants
• type Activity
• type Deserialiser
• type Entry
• type SerialisedEntry
• type Session
  • func StartSession(path string, activity Activity, init func(*Session) error) (*Session, error)
  • func (db *Session) Add(ent Entry) error
  • func (db *Session) Delete(key int) error
  • func (db *Session) EndSession(commitChanges bool) error
  • func (db Session) ForEach(f func(key int, e Entry) error) error
  • func (db Session) NumEntries() int
  • func (db *Session) RegisterEntryType(id string, des Deserialiser) error
  • func (db Session) SelectAll(onSelect func(Entry) error) (Entry, error)
  • func (db Session) SelectKeys(onSelect func(Entry) error, keys ...int) (Entry, error)
  • func (db Session) SortedKeyList() []int

Constants

const (
	NotAvailable = "database: not available (%s)"
)

Sentinal error returned when requested database is not available.

Types

type Activity

type Activity int

Activity is used to specify the general activity of what will be occurring during the database session.

const (
	ActivityReading Activity = iota

	// Modifying implies Reading.
	ActivityModifying

	// Creating implies Modifying (which in turn implies Reading).
	ActivityCreating
)

Valid activities: the "higher level" activities inherit the activity abilities of the activity levels lower down the scale.

type Deserialiser

type Deserialiser func(fields SerialisedEntry) (Entry, error)

Deserialiser extracts/converts fields from a SerialisedEntry.

type Entry

type Entry interface {
	// ID returns the string that is used to identify the entry type in
	// the database
	ID() string

	// String should return information about the entry in a human readable
	// format. by contrast, machine readable representation is returned by the
	// Serialise function
	String() string

	// return the Entry data as an instance of SerialisedEntry.
	Serialise() (SerialisedEntry, error)

	// a clenaup is perfomed when entry is deleted from the database
	CleanUp() error
}

Entry represents the generic entry in the database.

type SerialisedEntry

type SerialisedEntry []string

SerialisedEntry is the Entry data represented as an array of strings.

type Session

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

Session keeps track of a database session.

func StartSession

func StartSession(path string, activity Activity, init func(*Session) error) (*Session, error)

StartSession starts/initialises a new DB session. The init argument is the function to call when database has been successfully opened. This function should be used to add information about the different entries that are to be used in the database (see AddEntryType() function).

Calls to StartSession must be paired with a call to EndSesion().

func (*Session) Add

func (db *Session) Add(ent Entry) error

Add an entry to the db.

func (*Session) Delete

func (db *Session) Delete(key int) error

Delete deletes an entry with the specified key. returns DatabaseKeyError if not such entry exists.

func (*Session) EndSession

func (db *Session) EndSession(commitChanges bool) error

EndSession closes the database.

func (Session) ForEach

func (db Session) ForEach(f func(key int, e Entry) error) error

ForEach entry in the database run the function against that entry.

func (Session) NumEntries

func (db Session) NumEntries() int

NumEntries returns the number of entries in the database.

func (*Session) RegisterEntryType

func (db *Session) RegisterEntryType(id string, des Deserialiser) error

RegisterEntryType tells the database what entries it may expect in the database and how to deserialise the entry.

func (Session) SelectAll

func (db Session) SelectAll(onSelect func(Entry) error) (Entry, error)

SelectAll entries in the database. onSelect can be nil.

onSelect() should return true if select process is to continue. Continue flag is ignored if error is not nil.

Returns last matched entry in selection or an error with the last entry matched before the error occurred.

func (Session) SelectKeys

func (db Session) SelectKeys(onSelect func(Entry) error, keys ...int) (Entry, error)

SelectKeys matches entries with the specified key(s). keys can be singular. if list of keys is empty then all keys are matched (SelectAll() maybe more appropriate in that case). onSelect can be nil.

onSelect() should return true if select process is to continue. If error is not nil then not continuing the select process is implied.

Returns last matched entry in selection or an error with the last entry matched before the error occurred.

func (Session) SortedKeyList

func (db Session) SortedKeyList() []int

SortedKeyList returns a sorted list of database keys.