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