3.7 Stores

Grip module that provides the <store> class and its methods, which you may import using:

(use-modules (grip store))

Conceptually, a store - as in storage - is a simple key-value database, based on Goops and Association Lists, meant to be used to handle small number of entries only¹.

Store entry keys are symbols, and equality tests use eq? (it uses assq and assq- prefixed association lists procedures). In a store, there can only be a single entry for a given key (stores do not use the acons procedure)².

Like in scheme, methods that mutate a <store> inventory are postfixed using !. In scheme, set! is a syntax, and therefore it is not possible to create a generic function for its name and add a method with its code … as a consequence, we had to choose another name, and went for set-!

Here is a small (incomplete) example:

(define a-store
        (init! (make <store>)
               '((foo . bar) (baz . 2))))

(save a-store "/tmp/a-store")
-|
$3 = #t

(load! (make <store>)
       "/tmp/a-store" #:no-checks #t)
-|
$4 = #<<store> 560a1d7aaba0>

(inventory a-store)
-|
$5 = ((foo . bar) (baz . 2))

…

Class, Methods and Procedures

<store>

get

ref

set-!

remove!

inventory

init!

load!

save

store-inventory?

Class, methods and Procedures

Class: <store>

Slot definition:

store

#:init-keyword #:store
#:init-thunk list

Note:

• when you create a <store> instance using the #:store #:init-keyword, its value is checked to verify that it is a well-formed store inventory (see store-inventory?). If you wan’t to by-pass these checks, use init! with #:no-checks instead - to be used with caution and at your own risk.
  
  
• although the store slot also defines a !store accessor (not exported and used internally), it is not recommended to use it: instead, use the <store> API methods inventory, init! and load!;

Method: get (self <store>) (key <symbol>)

Returns the self (key . value) pair for the given key, if it exists. Otherwise, it returns #f.

Method: ref (self <store>) (key <symbol>)

Returns the self value for the given key, if it exists. Otherwise, it returns #f.

When the returned value is #f, it can be either because key was not found, or that its value is #f: if you need to differentiate these cases, use get.

Method: set-! (self <store>) (key <symbol>) val

Returns the self store inventory.

Either reassociate key with val if the key existed already, or otherwise, add a new (key . val) to the self store inventory.

Method: remove! (self <store>) (key <symbol>)

Returns the self store inventory.

Removes the self (key . value) pair for the given key, if it exists.

Method: inventory (self <store>)

Returns the self store inventory (the content of the self store slot).

Method: init! (self <store>) vals [#:no-checks #f]

Returns self.

Sets the self store inventory to vals. Unless #:no-checks is #t - to be used with caution and at your own risk - this method calls store-inventory? and raises an exception if vals is not a well-formed store inventory.

Method: load! (self <store>) filename [#:no-checks #f]

Returns self.

Sets the self store inventory to the content of filename. Unless #:no-checks is #t - to be used with caution and at your own risk - this method calls store-inventory? and raises an exception if the content of filename is not a well-formed store inventory.

Method: save (self <store>) filename

The return value is unspecified.

Saves the store inventory for self in filename.

Procedure: store-inventory? vals

Return three values:

#t 'well-formed #t

Everything is fine.

#f 'not-a-pair PAIR

One of the entry is ot a well-formed pair.

#f 'wrong-key-type PAIR

One of the keys was find not to be a symbol.

#f 'duplicate-key PAIR

One of the key has a duplicate entry.

A well-formed store inventory is either an empty list or a list of (KEY . VALUE) PAIRs, where KEY is a symbol for all PAIRs and all KEYs are unique.