KVDB - Key Value DB

kvdb is a simple hybrid key value store that is worked with in memory but can be stored to and read from disk. It is a pretty basic wrapper around slope's assoc procedure, with some added bells and whistles.

If called without an argument a new in-memory db will be created. If called with an argument that argument should be a filepath for an existing file or the file you want to create.

Creating or Loading a database

The kvdb procedure will create a new database if called with no arguments. If an argument is given it should be a path to an existing kvdb database:

(define new-db      (kvdb::kvdb))                ; Create a new empty database
(define existing-db (kvdb::kvdb "~/mydb.kvdb"))  ; Load an existing one

Using the database

In this section a database called my-db will be used. It will have been created via one of the above methods.

The kvdb::kvdb procedure returns a lambda representing the in memory db. It takes the following form:

(my-db [action: string|symbol] [argument...])

The available actions are: GET, SET, DEL, FIND, SAVE, REVERT. They can be passed as strings or symbols in upper, lower, or mixed case.

'GET

GET is used to retrieve a value based on a key. It takes a key (any valid slope expression) and returns the expression associated with that key:

(my-db 'GET [key: expression]) => expression|symbol

For example:

(my-db 'GET "Key1")

If the key cannot be found a symbol, 'NOKEY, will be returned. This is so that there will not be confusion between #f returning from no key and #f returning as the value associated with a given key. It also prevents exceptions being raised constantly. If you want to check if the returned value is a no-key error you can check equality like so: (equal? 'NOKEY my-val) or with the following procedure: (kvdb::error? my-val) where my-val is a variable that was created by a call to the GET command.

'SET

SET is used to set the value of a given key. If the key does not yet exist in the database it and its value will both be added. If the key does exist, its value will be updated. A boolean will be returned to detail the success of the opperation.

(my-db 'SET [key: expression] [value: expression]) => bool

For example:

(my-db 'SET "Key1" '(1 2 3))

'DEL

DEL deletes records from the database based on a key. If only one argument is given it should be a key held in the database. If a second value is given it should be #t to indicate that the key is a regular expression. You could, alternatively, pass #f as the second value to retain the default behavior of passing a specific key. If a regular expression is used all records with a key matching the given regular expression will be deleted. As such, be careful and use caution. The procedure will return the number of records that were successfully deleted.

(my-db 'DEL [key: expression|regex-string] [[use-regex?: bool]]) => #t

For example:

(my-db 'DEL "Key1")          ; => 1
(my-db 'DEL "Key[0-9]+")  ; => 3

'FIND

FIND returns an association list containing the rows that were found when searching by regular expression against keys or values.

(my-db 'FIND [term: regex-string] [[search-values?: bool]]) => list

For example:

(my-db 'FIND "dogs" #t)    ; Search the db for a value containing the word "dogs"
(my-db 'FIND "Key[0-9]+")  ; Searches the db for a key starting with the letters `Key` followed by any positive integer

; Example return:
; (("Animals" ("cats" "dogs" "lemurs")))
; (("Key1" 55) ("Key4" 7612) ("Key 54" -1.23))

'SAVE

SAVE will store the current state of the database. If no arguments are given it will attempt to save to the path used when opening the database. If no path was given to open the database (ie. a new database was created) #f will be returned. If an argument is given it should be a string represending a filepath (use path-abs if need be when passing the argument). That filepath will be used to save the database. If the filepath is different than the path that was used to open the database that path will be updated to the new one and all future calls to save, without arguments, will be to the new path. An exception will be raised if the file cannot be opened/created. If the save was successfull #t will be returned.

(my-db 'SAVE [[filepath: string]])

For example:

(my-db 'SAVE)
(my-db 'SAVE (path-abs "~/my-db.kvdb"))

'REVERT

REVERT will revert the current database to the state of the last time it was saved, destroying any edits that were made in the interim. It takes no arguments and always returns #t or an exception (if a file cannot be read). If there has not been a save to file and the database is not associated with a file the database will be cleared of all values.

(my-db 'REVERT)