139 lines
3.0 KiB
Racket
139 lines
3.0 KiB
Racket
#lang scribble/manual
|
||
|
||
@title{Keystore}
|
||
|
||
@defmodule[keystore]
|
||
|
||
A small persistent key–value store backed by SQLite. Keys and values
|
||
may be arbitrary Racket values and are stored using transparent
|
||
serialization.
|
||
|
||
@section{Overview}
|
||
|
||
The keystore provides persistent storage with automatic
|
||
serialization and deserialization. Keys are additionally stored in a
|
||
stringified lowercase form, which allows glob-style queries.
|
||
|
||
@section{Structure}
|
||
|
||
@defstruct*[keystore
|
||
([file any/c]
|
||
[path path?]
|
||
[dbh any/c])]{
|
||
|
||
Represents an open keystore. The @racket[file] field contains the
|
||
original argument, @racket[path] is the resolved database path, and
|
||
@racket[dbh] is the SQLite connection.
|
||
}
|
||
|
||
@section{Opening}
|
||
|
||
@defproc[(ks-open [file (or/c path? string? symbol?)]) keystore?]{
|
||
|
||
Opens or creates a keystore. When @racket[file] is a symbol, a cache
|
||
location is used; otherwise it is interpreted as a filesystem path.
|
||
The database schema is created automatically if it does not yet exist.
|
||
}
|
||
|
||
@section{Basic Operations}
|
||
|
||
@defproc[(ks-set! [ks keystore?] [key any/c] [value any/c]) boolean?]{
|
||
|
||
Stores @racket[value] under @racket[key], replacing any existing value.
|
||
The function always returns @racket[#t].
|
||
}
|
||
|
||
@defproc[(ks-get [ks keystore?] [key any/c] [default any/c] ...) any/c]{
|
||
|
||
Retrieves the value associated with @racket[key]. If the key is not
|
||
present, the provided default value is returned when given; otherwise
|
||
the symbol @racket['ks-nil] is returned.
|
||
}
|
||
|
||
@defproc[(ks-exists? [ks keystore?] [key any/c]) boolean?]{
|
||
|
||
Returns @racket[#t] if the key exists, and @racket[#f] otherwise.
|
||
}
|
||
|
||
@defproc[(ks-drop! [ks keystore?] [key any/c]) boolean?]{
|
||
|
||
Removes the key from the store. The function always returns @racket[#t].
|
||
}
|
||
|
||
@section{Enumeration}
|
||
|
||
@defproc[(ks-keys [ks keystore?]) (listof any/c)]{
|
||
|
||
Returns all keys in the store.
|
||
}
|
||
|
||
@defproc[(ks-key-values [ks keystore?]) (listof (cons/c any/c any/c))]{
|
||
|
||
Returns all key–value pairs as cons cells.
|
||
}
|
||
|
||
@section{Glob Queries}
|
||
|
||
Glob queries operate on a lowercase string representation of keys.
|
||
|
||
@defproc[(ks-keys-glob [ks keystore?] [pattern string?]) (listof any/c)]{
|
||
|
||
Returns all keys whose string form matches @racket[pattern].
|
||
}
|
||
|
||
@defproc[(ks-key-values-glob [ks keystore?] [pattern string?])
|
||
(listof (cons/c any/c any/c))]{
|
||
|
||
Returns key–value pairs whose keys match @racket[pattern].
|
||
}
|
||
|
||
@section{Raw Access}
|
||
|
||
@defproc[(ks-keys-raw [ks keystore?]) list?]{
|
||
|
||
Returns raw key rows in the form:
|
||
|
||
@racketblock[
|
||
(list key-string str-key)
|
||
]
|
||
}
|
||
|
||
@defproc[(ks-key-values-raw [ks keystore?]) list?]{
|
||
|
||
Returns raw key–value rows in the form:
|
||
|
||
@racketblock[
|
||
(list key-string str-key value-string)
|
||
]
|
||
}
|
||
|
||
@section{Examples}
|
||
|
||
@subsection{Basic Usage}
|
||
|
||
@racketblock[
|
||
(define ks (ks-open 'demo))
|
||
|
||
(ks-set! ks 'a 42)
|
||
(ks-set! ks "b" '(1 2 3))
|
||
|
||
(ks-get ks 'a) ; => 42
|
||
(ks-get ks 'missing) ; => 'ks-nil
|
||
(ks-get ks 'missing 0) ; => 0
|
||
]
|
||
|
||
@subsection{Enumeration Example}
|
||
|
||
@racketblock[
|
||
(ks-keys ks)
|
||
;; => '(a "b")
|
||
|
||
(ks-key-values ks)
|
||
;; => '((a . 42) ("b" . (1 2 3)))
|
||
]
|
||
|
||
@subsection{Glob Query Example}
|
||
|
||
@racketblock[
|
||
(ks-keys-glob ks "*b*")
|
||
] |