Update of /project/cl-store/cvsroot/cl-store/doc In directory common-lisp.net:/tmp/cvs-serv1333/doc

Modified Files: cl-store.texi Log Message: Changelog 2005-03-17 Date: Thu Mar 17 13:07:59 2005 Author: sross

Index: cl-store/doc/cl-store.texi diff -u cl-store/doc/cl-store.texi:1.8 cl-store/doc/cl-store.texi:1.9 --- cl-store/doc/cl-store.texi:1.8 Fri Feb 18 12:11:03 2005 +++ cl-store/doc/cl-store.texi Thu Mar 17 13:07:59 2005 @@ -131,7 +131,7 @@ CL-STORE uses @uref{http://cliki.net/asdf,,asdf%7D as it's system definition tool and is required whenever you load the package. You will need to download it, or if you have @uref{http://sbcl.org,,sbcl%7D -@lisp (require 'asdf) @end lisp +@code{(require 'asdf)}

@section Downloading @@ -139,7 +139,7 @@ @item ASDF-INSTALL CL-STORE is available through asdf-install. If you are new to Common Lisp this is the suggested download method. With asdf-install loaded run -@lisp (asdf-install:install :cl-store) @end lisp +@code{(asdf-install:install :cl-store)} This will download and install the package for you. Asdf-install will try to verify that the package signature is correct and that you trust the author. If the key is not found or the trust level is not sufficient a continuable error will be signalled. @@ -163,16 +163,14 @@

@section Installing Once downloaded and symlinked you can load CL-STORE at anytime using -@lisp (asdf:oos 'asdf:load-op :cl-store) @end lisp +@code{(asdf:oos 'asdf:load-op :cl-store)} This will compile CL-STORE the first time it is loaded.

@section Testing Once installed you can run the regression tests for it. The tests depend on the @uref{http://cliki.net/rt,,Regression Tests} asdf package which is asdf-installable. The tests can be run be executing -@lisp -(asdf:oos 'asdf:test-op :cl-store) -@end lisp +@code{(asdf:oos 'asdf:test-op :cl-store)}

If any tests fail please send a message to one of the Mailing Lists.

@@ -181,21 +179,21 @@ @chapter API

@section Variables -@anchor {Variable *nuke-existing-classes*} +@anchor{Variable *nuke-existing-classes*} @vindex *nuke-existing-classes* @deftp {Variable} *nuke-existing-classes* @emph{Default NIL} Determines wether or not to override existing classes when restoring a CLOS Class. If @code{*nuke-existing-classes*} is not NIL the current definition will be overridden. @end deftp

-@anchor {Variable *store-class-superclasses*} +@anchor{Variable *store-class-superclasses*} @vindex *store-class-superclasses* @deftp {Variable} *store-class-superclasses* @emph{Default NIL} If @code{*store-class-superclasses*} is not NIL when storing a CLOS Class all superclasses will be stored. @end deftp

-@anchor {Variable *store-class-slots*} +@anchor{Variable *store-class-slots*} @vindex *store-class-slots* @deftp {Variable} *store-class-slots* @emph{Default T} If @code{*store-class-slots*} is NIL slots which are class allocated will @@ -203,14 +201,14 @@ @end deftp

-@anchor {Variable *nuke-existing-packages*} +@anchor{Variable *nuke-existing-packages*} @vindex *nuke-existing-packages* @deftp {Variable} *nuke-existing-packages* @emph{Default NIL} If @code{*nuke-existing-packages*} is non-nil then packages which already exist will be deleted when restoring packages. @end deftp

-@anchor {Variable *store-used-packages*} +@anchor{Variable *store-used-packages*} @vindex *store-used-packages* @deftp {Variable} *store-used-packages* @emph{Default NIL} The variable determines the how packages on a package use @@ -218,7 +216,7 @@ be fully serialized, otherwise only the name will be stored. @end deftp

-@anchor {Variable *store-hash-size*} +@anchor{Variable *store-hash-size*} @vindex *store-hash-size* @deftp {Variable} *store-hash-size* @emph{Default 1000} The default size of the hash-table created to keep track of @@ -227,7 +225,7 @@ involved by rehashing hash-tables. @end deftp

-@anchor {Variable *restore-hash-size*} +@anchor{Variable *restore-hash-size*} @vindex *restore-hash-size* @deftp {Variable} *restore-hash-size* @emph{Default 1000} The default size of the hash-table created to keep track of @@ -237,7 +235,7 @@ @end deftp

-@anchor {Variable *check-for-circs*} +@anchor{Variable *check-for-circs*} @vindex *check-for-circs* @deftp {Variable} *check-for-circs* @emph{Default t} Binding this variable to nil when storing or restoring @@ -249,7 +247,7 @@ your data (eg spam-filter hash-tables). @end deftp

-@anchor {Variable *default-backend*} +@anchor{Variable *default-backend*} @vindex *default-backend* @deftp {Variable} *default-backend* The backend that will be used by default. @@ -257,7 +255,7 @@

@section Functions -@anchor {Generic store} +@anchor{Generic store} @deffn {Generic} store object place &optional (backend *default-backend*) Stores @emph{object} into @emph{place} using @emph{backend}. @emph{Place} must be either a @code{stream} or a @code{pathname-designator}. All @@ -265,7 +263,7 @@ If the @code{store-error} is not handled the causing error will be signalled. @end deffn

-@anchor {Generic restore} +@anchor{Generic restore} @deffn {Generic} restore place &optional (backend *default-backend*) Restores an object serialized using @code{store} from @emph{place} using @emph{backend}. @emph{Place} must be either a @code{stream} or a @code{pathname-designator}. @@ -279,19 +277,19 @@ @end deffn

-@anchor {Function find-backend} +@anchor{Function find-backend} @deffn {Function} find-backend name Returns the backend named by @emph{name} or nil if it does not exist. @end deffn

-@anchor {Function caused-by} +@anchor{Function caused-by} @deffn {Function} caused-by cl-store-error Returns the @code{condition} which caused @code{cl-store-error} to be signalled. @end deffn

@section Macros -@anchor {Macro with-backend} +@anchor{Macro with-backend} @deffn {Macro} with-backend backend &body body Execute @emph{body} with @code{*default-backend*} bound to the backend designated by @emph{backend}. @@ -299,7 +297,7 @@

@section Conditions -@anchor {Condition cl-store-error} +@anchor{Condition cl-store-error} @deftp {Condition} cl-store-error Class Precedence: @code{condition}

@@ -307,22 +305,22 @@ can be handled by catching @code{cl-store-error} @end deftp

-@anchor {Condition store-error} +@anchor{Condition store-error} @deftp {Condition} store-error Class Precedence: @code{cl-store-error}

A @code{store-error} will be signalled when an error occurs within @code{store} or @code{multiple-value-store}. The causing error can be -obtained using @lisp (caused-by condition) @end lisp +obtained using @code{(caused-by condition)} @end deftp

-@anchor {Condition restore-error} +@anchor{Condition restore-error} @deftp {Condition} restore-error Class Precedence: @code{cl-store-error}

A @code{restore-error} will be signalled when an error occurs within @code{restore}. The causing error can be obtained using -@lisp (caused-by condition) @end lisp +@code{(caused-by condition)} @end deftp

@@ -377,7 +375,7 @@ will be similar in structure.

@subsection Functions -@anchor {Function register-code} +@anchor{Function register-code} @deffn {Function} register-code code name &optional (errorp t) Registers @emph{name} under the code @emph{code} into the cl-store-backend. The backend will use this mapping when restoring values. @@ -385,50 +383,50 @@ Currently codes 1 through 33 are in use. @end deffn

-@anchor {Function output-type-code} +@anchor{Function output-type-code} @deffn {Function} output-type-code type-code stream Writes @emph{type-code} into @emph{stream}. This must be done when writing out objects so that the type of the object can be identified on deserialization. @end deffn

-@anchor {Function store-32-bit} +@anchor{Function store-32-bit} @deffn {Function} store-32-bit integer stream Outputs the the low 32 bits from @emph{integer} into @emph{stream}. @end deffn

-@anchor {Function read-32-bit} +@anchor{Function read-32-bit} @deffn {Function} read-32-bit stream Reads a 32-bit integer from @emph{stream}. @end deffn

-@anchor {Generic store-object} +@anchor{Generic store-object} @deffn {Generic} store-object object place Stores @emph{object} into @emph{place}. This should be used inside @code{defstore-cl-store} to output parts of objects. @code{store} should not be used. @end deffn

-@anchor {Generic restore-object} +@anchor{Generic restore-object} @deffn {Generic} restore-object place Restore an object, written out using @code{store-object} from @emph{place}. @end deffn

-@anchor {Generic get-slot-details} +@anchor{Generic get-slot-details} @deffn {Generic} get-slot-details slot-definition Generic function which returns a list of slots details which can be used as an argument to @code{ensure-class}. Currently it is only specialized on slot-definition @end deffn

-@anchor {Generic serializable-slots} +@anchor{Generic serializable-slots} @deffn {Generic} serializable-slots object Method which returns a list of slot-definition objects which will be serialized for @emph{object}. The default is to call @code{serializable-slots-using-class}. @end deffn

-@anchor {Generic serializable-slots-using-class} +@anchor{Generic serializable-slots-using-class} @deffn {Generic} serializable-slots-using-class object class Returns a list of slot-definition objects which will be serialized for object and class. @@ -449,7 +447,7 @@ @vskip 0pt plus 1filll

@subsection Macros -@anchor {Macro defstore-cl-store} +@anchor{Macro defstore-cl-store} @deffn {Macro} defstore-cl-store (var type stream &key qualifier) &body body Create a custom storing mechanism for @emph{type} which must be a legal Class Name. @emph{Body} will be called when an object of class @emph{type} @@ -466,7 +464,7 @@ @end lisp @end deffn

-@anchor {Macro defrestore-cl-store} +@anchor{Macro defrestore-cl-store} @deffn {Macro} defrestore-cl-store (type stream) &body body Create a custom restoring mechanism for the @emph{type} registered using @code{register-code}.@emph{Body} will be executed with @@ -480,7 +478,7 @@ @end lisp @end deffn

-@anchor {Macro resolving-object} +@anchor{Macro resolving-object} @deffn {Macro} resolving-object (var create) &body body Executes @emph{body} resolving circularities detected in @emph{object}. Resolving-object works by creating a closure, containing code to set a @@ -498,7 +496,7 @@

@vskip 0pt plus 1filll

-@anchor {Macro setting} +@anchor{Macro setting} @deffn {Macro} setting place get This macro can only be used inside @code{resolving-object}. It sets the value designated by @emph{place} to @emph{get} for the object that is being resolved. @@ -518,7 +516,7 @@ @end lisp @end deffn

-@anchor {Macro setting-hash} +@anchor{Macro setting-hash} @deffn {Macro} setting-hash getting-key getting-value @code{setting-hash} works identically to setting although it is used exclusively on hash-tables due to the fact that both the key and the value @@ -692,33 +690,33 @@ @section API

@subsection Functions -@anchor {Generic backend-restore} +@anchor{Generic backend-restore} @deffn {Generic} backend-restore backend place Restore the object found in stream @emph{place} using backend @emph{backend}. Checks the magic-number and invokes @code{backend-restore-object}. Called by @code{restore}, override for custom restoring. @end deffn

-@anchor {Generic backend-restore-object} +@anchor{Generic backend-restore-object} @deffn {Generic} backend-restore backend place Find the next function to call to restore the next object with @emph{backend} and invoke it with @emph{place}. Called by @code{restore-object}, override this method to do custom restoring (see @file{circularities.lisp} for an example). @end deffn

-@anchor {Generic backend-store} +@anchor{Generic backend-store} @deffn {Generic} backend-store backend place obj Stores the backend code and calls @code{store-object}. This is called by @code{store}. Override for custom storing. @end deffn

-@anchor {Generic backend-store-object} +@anchor{Generic backend-store-object} @deffn {Generic} backend-store-object backend obj place Called by @code{store-object}, override this to do custom storing (see @file{circularities.lisp} for an example). @end deffn

-@anchor {Generic get-next-reader} +@anchor{Generic get-next-reader} @deffn {Generic} get-next-reader backend place Method which must be specialized for @emph{backend} to return the next symbol designating a @code{defrestore} instance to restore an object from @emph{place}. @@ -727,9 +725,9 @@

@subsection Macros -@anchor {Macro defbackend} +@anchor{Macro defbackend} @deffn {Macro} defbackend name &key (stream-type (required-arg "stream-type")) magic-number fields (extends 'backend) old-magic-numbers -eg. @lisp (defbackend pickle :stream-type 'character) @end lisp +eg. @code{(defbackend pickle :stream-type 'character)} This creates a new backend called @emph{name}, @emph{stream-type} describes the type of stream that the backend will serialize to which must be suitable as an argument to open. @emph{Magic-number}, when present, must be of type (unsigned-byte 32) which will be written as a verifier for the backend. @emph{Fields} are extra fields to be