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} 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}
-@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
