#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*")
]