[cl-store-cvs] CVS update: cl-store/doc/cl-store.texi
Sean Ross
sross at common-lisp.net
Fri Feb 18 08:50:10 UTC 2005
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}
-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}
+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
+ at 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}.
+The latest cl-store release will always be available from @uref{http://common-lisp.net,,cl.net}.
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
+ at anchor {Variable *nuke-existing-packages*}
+ at vindex *nuke-existing-packages*
+ at 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.
+ at end deftp
+
+ at anchor {Variable *store-used-packages*}
+ at vindex *store-used-packages*
+ at 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.
+ at 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*
- at deftp {Variable} *default-backend* @emph{Default *cl-store-backend*}
+ at deftp {Variable} *default-backend*
The backend that will be used by default.
@end deftp
- at anchor {Variable *cl-store-backend*}
- at vindex *cl-store-backend*
- at deftp {Variable} *cl-store-backend*
-The CL-STORE Backend.
- at end deftp
-
-
@section Functions
@anchor {Generic store}
@deffn {Generic} store object place &optional (backend *default-backend*)
@@ -282,22 +291,10 @@
@section Macros
- at anchor {Macro multiple-value-store}
- at 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.
- at lisp
-(multiple-value-store (values 1 2 3) "/tmp/values.out")
-(restore "/tmp/values.out")
-=> 1, 2, 3
- at end lisp
- at 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}
- at deffn {Function} register-code name &optional (errorp t)
+ at 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}
- at deffn {Generic} store-object object place
+ at 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}. at 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
- at subsection Variables
- at anchor {Variable *postfix-setters*}
- at deftp {Variable} *postfix-setters* @emph{Default (gethash)}
-Setfable places which take the object to set after all other arguments.
- at 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}
- at deffn {Generic} backend-restore place backend
+ at 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}
- at deffn {Generic} backend-restore place backend
+ at 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}
- at deffn {Generic} backend-store obj place backend
+ at 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}
- at deffn {Generic} backend-store-object obj place backend
+ at 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}
- at deffn {Generic} get-next-reader place backend
+ at 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
+ at section Backend Designators
+The @emph{backend} argument to store, restore and with-backend
+is a backend designator which can be one of.
+ at itemize @bullet
+ at item A backend returned by @code{(find-backend name)}
+ at item A symbol designating a backend (the first argument to defbackend).
+ at 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.
- at 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.
+ at item Thomas Stenhaug: Comprehensive package storing and miscellaneous improvements.
@end itemize
@node Index
More information about the Cl-store-cvs
mailing list