initial

scrbl/class.scrbl~

@@ -0,0 +1,119 @@
+#lang scribble/manual
+
+@title{Keystore Class}
+
+@defmodule[keystore/class]
+
+An object-oriented wrapper around @racketmodname[keystore], providing
+a small fluent interface for working with a persistent key–value store.
+
+@section{Class}
+
+@defclass[keystore% object% ()]{
+
+Creates a keystore instance backed by SQLite.
+
+@defconstructor[([file (or/c path? string? symbol?)])]{
+
+Opens or creates a keystore using @racket[file]. The interpretation
+of @racket[file] is identical to @racket[ks-open].
+}
+
+@section{Methods}
+
+@defmethod[(handle) keystore?]{
+
+Returns the underlying keystore handle as produced by @racket[ks-open].
+}
+
+@defmethod[(set! [key any/c] [value any/c]) (is-a?/c keystore%)]{
+
+Stores @racket[value] under @racket[key]. The method returns the
+instance itself, allowing chaining.
+}
+
+@defmethod[(get [key any/c] [default any/c] ...) any/c]{
+
+Retrieves the value associated with @racket[key]. If no value is found,
+the optional default is returned; otherwise @racket['ks-nil] is returned.
+}
+
+@defmethod[(drop! [key any/c]) (is-a?/c keystore%)]{
+
+Removes @racket[key] and returns the instance.
+}
+
+@defmethod[(exists? [key any/c]) boolean?]{
+
+Checks whether @racket[key] exists.
+}
+
+@defmethod[(keys) (listof any/c)]{
+
+Returns all keys.
+}
+
+@defmethod[(key-values) (listof (cons/c any/c any/c))]{
+
+Returns all key–value pairs.
+}
+
+@section{Glob Queries}
+
+Glob operations match against the lowercase string representation of keys.
+
+@defmethod[(glob [pattern string?]) (listof any/c)]{
+
+Returns keys matching @racket[pattern].
+}
+
+@defmethod[(keys-glob [pattern string?]) (listof any/c)]{
+
+Alias for @racket[glob].
+}
+
+@defmethod[(glob-kv [pattern string?])
+           (listof (cons/c any/c any/c))]{
+
+Returns key–value pairs matching @racket[pattern].
+}
+
+@section{Examples}
+
+@subsection{Basic Usage}
+
+@racketblock[
+(define ks (new keystore% [file 'demo]))
+
+(send ks set! 'a 42)
+(send ks set! "b" '(1 2 3))
+
+(send ks get 'a)         ; => 42
+(send ks get 'missing)   ; => 'ks-nil
+(send ks get 'missing 0) ; => 0
+]
+
+@subsection{Chaining}
+
+@racketblock[
+(define ks (new keystore% [file 'demo]))
+
+(send ks
+      set! 'a 1)
+      set! 'b 2)
+      drop! 'a))
+]
+
+@subsection{Glob Queries}
+
+@racketblock[
+(send ks glob "*b*")
+(send ks glob-kv "*b*")
+]
+
+@section{Notes}
+
+This class is a thin wrapper around @racketmodname[keystore]. All
+semantics, including serialization and glob matching, are inherited
+directly from the underlying functional API.
+}