initial

scrbl/class.scrbl

@@ -0,0 +1,108 @@
+#lang scribble/manual
+
+@(require (for-label racket/base
+                     racket/class
+                     "../keystore.rkt"
+                     "../class.rkt"))
+
+@title{Keystore Class}
+
+@defmodule[keystore/class]
+
+An object-oriented wrapper around @racketmodname[keystore]. It provides
+a small class interface to the persistent key–value store.
+
+@defclass[keystore% object% ()]{
+
+A keystore class backed by SQLite.
+
+@defconstructor[([file (or/c path? string? symbol?)])]{
+
+Opens or creates a keystore using @racket[file]. The meaning of
+@racket[file] is the same as for @racket[ks-open].
+}
+
+@defmethod[(handle) keystore?]{
+
+Returns the underlying keystore handle.
+}
+
+@defmethod[(set! [key any/c] [value any/c]) (is-a?/c keystore%)]{
+
+Stores @racket[value] under @racket[key]. Returns the object itself,
+so method calls may be nested.
+}
+
+@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] from the store and returns the object itself.
+}
+
+@defmethod[(exists? [key any/c]) boolean?]{
+
+Returns @racket[#t] if @racket[key] exists, and @racket[#f] otherwise.
+}
+
+@defmethod[(glob [pattern string?]) (listof any/c)]{
+
+Returns keys matching @racket[pattern].
+}
+
+@defmethod[(glob-kv [pattern string?]) (listof (cons/c any/c any/c))]{
+
+Returns key–value pairs matching @racket[pattern].
+}
+
+@defmethod[(keys-glob [pattern string?]) (listof any/c)]{
+
+Alias for @racket[glob].
+}
+
+@defmethod[(keys) (listof any/c)]{
+
+Returns all keys.
+}
+
+@defmethod[(key-values) (listof (cons/c any/c any/c))]{
+
+Returns all key–value pairs.
+}
+}
+
+@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{Nested Calls}
+
+@racketblock[
+(define ks (new keystore% [file 'demo]))
+
+(send (send (send ks set! 'a 1)
+            set! 'b 2)
+      drop! 'a)
+]
+
+@subsection{Glob Queries}
+
+@racketblock[
+(send ks glob "*b*")
+(send ks glob-kv "*b*")
+]