#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.
}