Update of /project/cl-store/cvsroot/cl-store/doc In directory common-lisp.net:/tmp/cvs-serv5237
Modified Files: cl-store.texi Log Message: Updated Manual Date: Fri Feb 18 09:50:09 2005 Author: sross
Index: cl-store/doc/cl-store.texi diff -u cl-store/doc/cl-store.texi:1.6 cl-store/doc/cl-store.texi:1.7 --- cl-store/doc/cl-store.texi:1.6 Tue Feb 1 09:27:40 2005 +++ cl-store/doc/cl-store.texi Fri Feb 18 09:50:09 2005 @@ -79,9 +79,10 @@ the same purpose as Java's ObjectOutput and ObjectInputStream, although it's somewhat more extensible.
-The CL-STORE Home Page is at @uref{http://www.common-lisp.net/project/cl-store%7D -where one can find details about mailing lists, cvs repositories (I hope i spelled that -right) and various releases. +The CL-STORE Home Page is at @uref{http://common-lisp.net/project/cl-store%7D +where one can find details about mailing lists, cvs repositories and various releases. + +This documentation is for CL-STORE version 0.5 .
Enjoy Sean. @@ -120,6 +121,7 @@ @item Lispworks @item Allegro CL @item OpenMCL +@item ECL @end itemize
@@ -146,7 +148,7 @@
@item DOWNLOAD
-The latest cl-store release will always be available from @uref{http://www.common-lisp.net,,cl.net%7D. +The latest cl-store release will always be available from @uref{http://common-lisp.net,,cl.net%7D. Download and untar in an appropriate directory then symlink @file{cl-store.asd} to a directory on @code{asdf:*central-registry*} (see the documentation for asdf for details about setting up asdf). @@ -154,8 +156,8 @@ @item CVS
If you feel the need to be on the bleeding edge you can use -anonymous CVS access, see the @uref{http://www.common-lisp.net/project/cl-store,,Home Page} - for more details for accessing the archive. Once downloaded follow the symlink instructions above. +anonymous CVS access, see the @uref{http://common-lisp.net/project/cl-store,,Home Page} +for more details for accessing the archive. Once downloaded follow the symlink instructions above.
@end itemize
@@ -201,6 +203,21 @@ @end deftp
+@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*} +@vindex *store-used-packages* +@deftp {Variable} *store-used-packages* @emph{Default NIL} +The variable determines the how packages on a package use +list will be serialized. If non-nil the the package will +be fully serialized, otherwise only the name will be stored. +@end deftp + @anchor {Variable *store-hash-size*} @vindex *store-hash-size* @deftp {Variable} *store-hash-size* @emph{Default 1000} @@ -232,21 +249,13 @@ your data (eg spam-filter hash-tables). @end deftp
- @anchor {Variable *default-backend*} @vindex *default-backend* -@deftp {Variable} *default-backend* @emph{Default *cl-store-backend*} +@deftp {Variable} *default-backend* The backend that will be used by default. @end deftp
-@anchor {Variable *cl-store-backend*} -@vindex *cl-store-backend* -@deftp {Variable} *cl-store-backend* -The CL-STORE Backend. -@end deftp - - @section Functions @anchor {Generic store} @deffn {Generic} store object place &optional (backend *default-backend*) @@ -282,22 +291,10 @@
@section Macros -@anchor {Macro multiple-value-store} -@deffn {Macro} multiple-value-store form place &optional (backend *default-backend*) -Stores all values returned by @emph{form} into @emph{place} using @emph{backend}. -As usual @emph{place} must be @code{stream} or a @code{pathname-designator}. -Restoring values stored using @code{multiple-value-store} will return all values. -eg. -@lisp -(multiple-value-store (values 1 2 3) "/tmp/values.out") -(restore "/tmp/values.out") -=> 1, 2, 3 -@end lisp -@end deffn - @anchor {Macro with-backend} @deffn {Macro} with-backend backend &body body -Execute @emph{body} with @code{*default-backend*} bound to @emph{backend}. +Execute @emph{body} with @code{*default-backend*} bound to the +backend designated by @emph{backend}. @end deffn
@@ -345,7 +342,7 @@
(use-package :cl-store)
-(setf *default-backend* *cl-store-backend*) +(setf *default-backend* (find-backend 'cl-store))
;; Create the custom class (defclass random-obj () ((a :accessor a :initarg :a))) @@ -381,11 +378,11 @@
@subsection Functions @anchor {Function register-code} -@deffn {Function} register-code name &optional (errorp t) +@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. Will signal an error if code is already registered and @emph{errorp} is not NIL. -Currently codes 1 through 25 are in use. +Currently codes 1 through 33 are in use. @end deffn
@anchor {Function output-type-code} @@ -406,7 +403,7 @@ @end deffn
@anchor {Generic store-object} -@deffn {Generic} store-object object place +@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. @@ -427,19 +424,13 @@ is stored using @code{store-object} with @emph{var} bound to the object to be stored and @emph{stream} bound to the stream to output to. If @emph{qualifier} is given it must be a legal qualifier to @code{defmethod}. -Example Expansion. +Example. @lisp (defstore-cl-store (obj ratio stream) (output-type-code +ratio-code+ stream) (store-object (numerator obj) stream) (store-object (denominator obj) stream))
-== - -(defmethod internal-store-object ((obj ratio) stream (backend cl-store-backend)) - (output-type-code +ratio-code+ stream) - (store-object (numerator obj) stream) - (store-object (denominator obj) stream)) @end lisp @end deffn
@@ -449,21 +440,11 @@ registered using @code{register-code}.@emph{Body} will be executed with @emph{stream} being the input stream to restore an object from.
-Example Expansion. +Example. @lisp (defrestore-cl-store (ratio stream) (/ (restore-object stream) (restore-object stream))) - -== - -(flet ((#:cl-store-ratio4109 (stream) - (/ (restore-object stream) (restore-object stream)))) - (let* ((backend (find-backend 'cl-store)) - (restorers (restorer-funs backend))) - (when (gethash 'ratio restorers) - (warn "redefining restorer ~a for backend ~(~a~)" 'ratio (name backend))) - (setf (gethash 'ratio restorers) #'#:cl-store-ratio4109))) @end lisp @end deffn
@@ -530,11 +511,6 @@ @end lisp @end deffn
-@subsection Variables -@anchor {Variable *postfix-setters*} -@deftp {Variable} *postfix-setters* @emph{Default (gethash)} -Setfable places which take the object to set after all other arguments. -@end deftp
@node New Backends @chapter New Backends @@ -557,7 +533,7 @@ eg. (from the cl-store-backend) @lisp (defbackend cl-store :magic-number 1347643724 - :stream-type 'binary + :stream-type '(unsigned-byte 8) :old-magic-numbers (1912923 1886611788 1347635532) :extends resolving-backend :fields ((restorers :accessor restorers :initform (make-hash-table)))) @@ -575,6 +551,7 @@
eg. (from the cl-store-backend) @lisp +(defvar *cl-store-backend* (find-backend 'cl-store)) ;; This is a util method to register the code with a symbol (defun register-code (code name &optional (errorp t)) (aif (and (gethash code (restorers *cl-store-backend*)) errorp) @@ -586,7 +563,7 @@ (defconstant +ratio-code+ (register-code 7 'ratio))
;; Extending the get-next-reader method -(defmethod get-next-reader ((stream stream) (backend cl-store-backend)) +(defmethod get-next-reader ((backend cl-store) (stream stream)) (let ((type-code (read-type-code stream))) (or (gethash type-code (restorers backend)) (values nil (format nil "Type ~A" type-code))))) @@ -609,10 +586,10 @@ done you can use @code{resolving-object} and @code{setting} to resolve circularities in objects.
-eg (from the cl-store-backend) +eg (from the cl-store backend) @lisp (defconstant +referrer-code+ (register-code 1 'referrer nil)) -(defmethod store-referrer (ref stream (backend cl-store-backend)) +(defmethod store-referrer (ref stream (backend cl-store)) (output-type-code +referrer-code+ stream) (store-32-bit ref stream))
@@ -629,7 +606,7 @@ (in-package :cl-user) (use-package :cl-store)
-(defbackend pickle :stream-type 'char) +(defbackend pickle :stream-type 'character) @end lisp @vskip 0pt plus 2filll
@@ -641,7 +618,7 @@ (defvar *pickle-mapping* '((#\S . string)))
-(defmethod get-next-reader ((stream stream) (backend pickle-backend)) +(defmethod get-next-reader ((backend pickle) (stream stream)) (let ((type-code (read-char stream))) (or (cdr (assoc type-code *pickle-mapping*)) (values nil (format nil "Type ~A" type-code))))) @@ -666,12 +643,12 @@
pickle.dump('Foobar', open('/tmp/foo.p', 'w'))
Lisp -* (cl-store:restore "/tmp/foo.p" (find-backend 'pickle)) +* (cl-store:restore "/tmp/foo.p" 'pickle) => "Foobar" And
Lisp -* (cl-store:store "BarFoo" "/tmp/foo.p" (find-backend 'pickle)) +* (cl-store:store "BarFoo" "/tmp/foo.p" 'pickle)
Python
pickle.load(open('/tmp/foo.p'))
@@ -684,33 +661,33 @@
@subsection Functions @anchor {Generic backend-restore} -@deffn {Generic} backend-restore place backend +@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} -@deffn {Generic} backend-restore place backend +@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} -@deffn {Generic} backend-store obj place backend +@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} -@deffn {Generic} backend-store-object obj place backend +@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} -@deffn {Generic} get-next-reader place backend +@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}. If no reader is found return a second value which will be included in the error. @@ -720,9 +697,9 @@ @subsection Macros @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 'char) @end lisp +eg. @lisp (defbackend pickle :stream-type 'character) @end lisp This creates a new backend called @emph{name}, @emph{stream-type} describes the type of stream that the -backend will serialize to, currently one of 'binary or 'char. @emph{Magic-number}, when present, must be of type +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 added to the new class which will be created. By default the @emph{extends} keyword is @emph{backend},the root backend, but this can be any legal backend. @emph{Old-magic-numbers} holds previous magic-numbers that have been used by the backend @@ -732,11 +709,18 @@ @node Notes @chapter Notes
+@section Backend Designators +The @emph{backend} argument to store, restore and with-backend +is a backend designator which can be one of. +@itemize @bullet +@item A backend returned by @code{(find-backend name)} +@item A symbol designating a backend (the first argument to defbackend). +@end itemize + @section Known Issues @itemize @bullet @item CLISP, OpenMCL, Allegro CL cannot store structure instances. @item Structure definitions are only supported in SBCL and CMUCL. -@item MOP classes aren't supported. @item Due to the fact that function's aren't fully supported CLOS Classes initfunction slot cannot be serialized. @end itemize
@@ -747,6 +731,7 @@ @item Common-Lisp.net: For project hosting. @item Alain Picard : Structure Storing and support for Infinite Floats for Lispworks. @item Robert Sedgewick: Package Imports for OpenMCL and suggesting Multiple Backends. +@item Thomas Stenhaug: Comprehensive package storing and miscellaneous improvements. @end itemize
@node Index