Data.HMemDb

Tables of values and keys for that tables.

Each value in the table may be accompanied with references to other tables.

Documentation

type MS = MaybeT STM

STM that can fail. Note that it doesn't revert the transaction on failure.

class Binary u => Multitude u

Closed class. It's instances allow us to choose whether we want to get a single value or multiple ones.

Instances

Multitude Multiple

Multitude Single

data Single

This type specifies that we want a single value.

Instances

Eq Single

Ord Single

Binary Single

Multitude Single

data Multiple

This type specifies that we want multiple values.

Instances

Eq Multiple

Binary Multiple

Multitude Multiple

Main structures

data Table t r a

Abstract type, which represents a collection of values of type a, possibly accompanied with some references to other Tables. The type t is an abstract type, used to ensure that we don't confuse different tables with values of the same type. r is a type of references accompanying each value.

data Key t a i u

Abstract type, which allows us to select one or many values from the Table. Type t is an abstract type, same as in the Table. Type a is a type of values, also same as in the Table. Type i is a type of index values, used by this key. Type u is either Multiple or Single, depending on whether this key allows different values to have the same index, or not.

Value references

data TableVarU t a u

Base type for TableVar and TableVars Type t is an abstract type, same as in the Table. Type a is a type of value, which can be obtained with unVar, also same as in the Table.

Instances

Eq u => Eq (TableVarU t a u)

Ord u => Ord (TableVarU t a u)

type TableVar t a = TableVarU t a Single

Reference to a single value in some table.

type TableVars t a = TableVarU t a Multiple

Reference to multiple values in a single table.

fromList :: [TableVar t a] -> TableVars t a

Function that converts a list of single-value references to a single multiple-value reference. Normally it should only be used in cInsert statments.

toList :: TableVars t a -> [TableVar t a]

Function that converts a multiple-value reference to a list of single-value references. Should be used with multiple-value references accompanying values in the Table.

readVar :: Table t r a -> TableVar t a -> MS a

Function that dereferences a value from table. Note that we have to provide the Table along with TableVar.

readRefs :: Table t r a -> TableVar t a -> MS (r TableVarU)

Function that reads all references accompanying the value.

Specifications

data Spec r k a

Type of table specifications.

Constructors

Spec

Fields

sRefs :: r TableRef

Other tables that should be referenced by values of this one.

sKeys :: k (KeySpec r a)

Keys for the table-to-be

Foreign table references

data TableRef t a u

Type that is a template for references to another table. Used only in Specs. Type t is an abstract type, same as in the Table. Type a is a type of values in that Table. Type u is either Single or Multiple, depending on whether the reference, accompanying the value, should be single-value or multiple-value

only :: Table t r a -> TableRef t a Single

Each value in the table-to-be should be accompanied with a single-value reference.

some :: Table t r a -> TableRef t a Multiple

Each value in the table-to-be should be accompanied with a multiple-value reference.

class RefsC r

Class of table reference specifications, used in the sRefs field of the Spec.

Instances

RefsC Refs

(RefsC rs, RefsComponent r) => RefsC (:&: rs r)

data Refs f

Empty reference specification. It doesn't specify any reference whatsoever.

Constructors

Refs

Instances

RefsC Refs

class RefsComponent r

Class of the part of reference specification, corresponding to one reference.

Instances

Multitude u => RefsComponent (Ref t a u)

data Ref t a u

One table reference specification. Note that it can't be used in the sRefs field by itself, but rather should be combined with Refs with the :&: operator.

Instances

Multitude u => RefsComponent (Ref t a u)

data (rs :&: r) f where

Combining operator for reference specifications.

Constructors

:&: :: rs f -> f t a u -> (rs :&: Ref t a u) f

Instances

(RefsC rs, RefsComponent r) => RefsC (:&: rs r)

splitRef :: (rs :&: Ref t a u) f -> (rs f, f t a u)

Splitting references.

Keys

data KeySpec r a i u

Type that is a template for the key. Used only in Specs. Type t is an abstract type, same as in the Table. Type a is a type of values in that Table. Type i is a type of index values, used by this key. Type u is either Multiple or Single, depending on whether this key allows different values to have the same index, or not.

single :: (a -> i) -> KeySpec r a i Single

This key will provide access to a single value within a Table. It's index will be calculated, based on this value alone.

multiple :: (a -> i) -> KeySpec r a i Multiple

This key will provide access to multiple values in the same Table. Their indices will be calculated based on the value alone.

single_ :: (a -> r TableVarU -> i) -> KeySpec r a i Single

This is a more generic version of single. The difference is that value index will be calculated based on both the value and it's accompanying references.

multiple_ :: (a -> r TableVarU -> i) -> KeySpec r a i Multiple

This is a more generic version of multiple. The difference is that value index will be calculated based on both the value and it's accompanying references.

class KeysC k

Class of key specifications, used in the sKeys field of the Spec.

Instances

KeysC Keys

(KeysC ks, KeysComponent k) => KeysC (:+: ks k)

data Keys f

Empty key specification. It doesn't specify any key whatsoever.

Constructors

Keys

Instances

KeysC Keys

class KeysComponent k

Class of the part of key specification, corresponding to one key.

Instances

(Multitude u, Ord i) => KeysComponent (KeyRef i u)

data KeyRef i u

One key specification. Note that it can't be used in the sKeys field by itself, but rather should be combined with Keys with the :+: operator.

Instances

(Multitude u, Ord i) => KeysComponent (KeyRef i u)

data (ks :+: k) f where

Combining operator for key specifications.

Constructors

:+: :: ks f -> f i u -> (ks :+: KeyRef i u) f

Instances

(KeysC ks, KeysComponent k) => KeysC (:+: ks k)

splitKey :: (ks :+: KeyRef i u) f -> (ks f, f i u)

Splitting keys.

Table manipulation

data Created r k a where

Output of the createTable function. Contains the created table and the keys to it.

Constructors

Created :: Table t r a -> k (Key t a) -> Created r k a

createTable :: (KeysC k, RefsC r) => Spec r k a -> STM (Created r k a)

Function that creates the table (along with keys and everything) based on a Spec.

select :: Ord i => Key t a i Single -> i -> MS (TableVar t a)

Function that selects one value from a Key. Note that the value is not returned directly. Instead, a reference to it is returned, which allows to get other references, accompanying that value in the Table.

select_ :: (Multitude u, Ord i) => Key t a i u -> i -> (forall o. Ord o => o -> o -> Bool) -> STM [TableVar t a]

A more generic version of select. Instead of one value, it returns multiple ones. It can also select values with indices that are smaller or greater to the provided one, depending on the third argument, which could be anything like (>), (<=), (/=), or even return True.

 select_ k i (==) ~~ [select k i]

selectBetween

Arguments

:: (Multitude u, Ord i)

=> Key t a i u

-> i

lower bound

-> Bool

including lower bound?

-> i

upper bound

-> Bool

including upper bound?

-> STM [TableVar t a]

A variant of select_, which allows to choose two bounds for the index. Additional boolean arguments show whether to include bounds themselves or not.

insert :: Table t r a -> a -> r TableVarU -> MS (TableVar t a)

Function that lets one to insert a new value to the Table. Of course, we have to provide accompanying references as well. This function can fail if some key clashes with an already existing one.

update :: Table t r a -> TableVar t a -> a -> MS ()

Function that writes another value to the referenced place in the Table. It doesn't change the accompanying references. In case that it fails due to some single-value key prohibiting the new value, nothing is changed, and the Table remains the same.

update_ :: Table t r a -> TableVar t a -> a -> r TableVarU -> MS ()

More generic version of update. It allows changing accompanying references as well as the value.

delete :: Table t r a -> TableVar t a -> MS ()

Function that removes the value (along with accompanying references) from the Table. It only fails if the value was already removed.

Persistence

getTable :: Binary a => Table t r a -> Get (STM ())

Function that makes it possible to read the table from the file or other source. Table should be created beforehand, as specifications are not serializable.

getTable_ :: Get a -> Table t r a -> Get (STM ())

More generic version of getTable that allows to change the way values are serialized.

getTable__ :: (Monad m, MonadSTM m) => Get (m a) -> Table t r a -> Get (m ())

The most generic version of getTable. Not only it allows to change the way values are serialized, it also permits side-effects during the deserialization. The table is still filled in one STM transaction, thus avoiding any difficulties with multithreading.

putTable :: Binary a => Table t r a -> STM Put

Function that makes it possible to write the table to the file or other storage.

putTable_ :: (a -> Put) -> Table t r a -> STM Put

More generic version of putTable that allows to change the way values are serialized.

putTable__ :: (Monad m, MonadSTM m) => (a -> m Put) -> Table t r a -> m Put

The most generic version of putTable. Not only it allows to change the way values are serialized, it also permits side-effects during the serialization. The table is still read in one STM transaction, thus avoiding any difficulties with multithreading.