documentation

scrbl/wv-settings.scrbl

@@ -0,0 +1,121 @@
+#lang scribble/manual
+
+@(require scribble/racket
+          scribble/example
+          scribble/core
+          (for-label racket/base
+                     racket/string
+                     racket/class
+                     racket/file)
+          )
+
+@defmodule[wv-settings]
+
+@title{Object-Oriented Interface: @racket[wv-settings%]}
+@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]
+
+@defclass[wv-settings% object% ()]{
+
+An OO wrapper around a settings backend implementing the
+@racket[simple-ini/class] interface.
+
+A @racket[wv-settings%] object represents a view on one settings section.
+The supplied @racket[wv-context] value is used as the section identifier for
+context-local settings.
+
+The class delegates all actual storage operations to the supplied
+@racket[ini] object.
+
+@defconstructor[([ini object?]
+                 [wv-context any/c])]{
+Creates a new settings object.
+
+The @racket[ini] argument is the backing settings object.
+
+The @racket[wv-context] argument is used as the section identifier for
+context-local settings.
+
+The class assumes that @racket[ini] supports methods compatible with:
+
+@itemlist[#:style 'compact
+ @item{@racket[(send ini get section key)]}
+ @item{@racket[(send ini get section key default)]}
+ @item{@racket[(send ini set! section key value)]}
+]
+
+In typical use, @racket[ini] is an instance of a class from
+@racket[simple-ini/class].
+}
+
+@defmethod*[([(get [key any/c]) any/c]
+             [(get [key any/c] [default-value any/c]) any/c])]{
+Returns the value associated with @racket[key] in the current section.
+
+Without a default value, this method delegates to:
+
+@racketblock[
+(send ini get wv-context key)
+]
+
+With a default value, it delegates to:
+
+@racketblock[
+(send ini get wv-context key default-value)
+]
+}
+
+@defmethod*[([(set! [key any/c] [value any/c]) this])]{
+Stores @racket[value] under @racket[key] in the current section.
+
+This method delegates to:
+
+@racketblock[
+(send ini set! wv-context key value)
+]
+}
+
+@defmethod*[([(get/global [key any/c]) any/c]
+             [(get/global [key any/c] [default-value any/c]) any/c])]{
+Returns the value associated with @racket[key] in the global section.
+
+Without a default value, this method delegates to:
+
+@racketblock[
+(send ini get 'global key)
+]
+
+With a default value, it delegates to:
+
+@racketblock[
+(send ini get 'global key default-value)
+]
+}
+
+@defmethod*[([(set/global! [key any/c] [value any/c]) this])]{
+Stores @racket[value] under @racket[key] in the global section.
+
+This method delegates to:
+
+@racketblock[
+(send ini set! 'global key value)
+]
+}
+
+@defmethod*[([(clone [context any/c]) (is-a?/c wv-settings%)])]{
+Creates a new @racket[wv-settings%] object using the same
+@racket[ini] backend but another section identifier.
+
+This method is equivalent to:
+
+@racketblock[
+(new wv-settings% [ini ini] [wv-context context])
+]
+
+It is intended to support cheap creation of per-section settings views.
+}
+
+@defmethod*[([(context) any/c])]{
+Returns the section identifier associated with this settings object.
+}
+
+} ; end class