/[cl-store]/cl-store/README
ViewVC logotype

Contents of /cl-store/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.9 - (hide annotations)
Wed Oct 13 12:35:57 2004 UTC (9 years, 6 months ago) by sross
Branch: MAIN
CVS Tags: v0-3
Changes since 1.8: +16 -7 lines
Changelogs 2004-10-07 to 2004-10-13
1 sross 1.4 README for Package CL-STORE.
2 sross 1.1 Author: Sean Ross
3     Homepage: http://www.common-lisp.net/project/cl-store/
4 sross 1.9 Version: 0.3
5 sross 1.1
6     0. About.
7     CL-STORE is an portable serialization package which
8     should give you the ability to store all common-lisp
9 sross 1.9 data types (well not all yet) into streams.
10 sross 1.1
11    
12     1. Installation.
13 sross 1.4 The first thing you need is a common-lisp, CL-STORE currently
14     supports SBCL, CMUCL, Lispworks, CLISP and OpenMCL.
15 sross 1.1
16 sross 1.4 Hopefully you've asdf-install to install this in which case
17     all should be fine.
18 sross 1.1
19 sross 1.4 Otherwise symlink cl-store.asd to somewhere on asdf:*central-registry*
20     and run (asdf:oos 'asdf:load-op :cl-store).
21 sross 1.1
22 sross 1.4 The xml backend can be loaded with (asdf:oos 'asdf:loaded :cl-store-xml).
23     This requires xmls which can be found on http://www.cliki.net and
24     is asdf-installable.
25    
26 sross 1.8 Run (asdf:oos 'asdf:test-op :cl-store) and (asdf:oos 'asdf:test-op :cl-store-xml)
27     to make sure that everything works. Running these tests will try to
28 sross 1.4 load the RT package, which is asdf-installable.
29     If anything breaks drop me a line, see
30     http://www.common-lisp.net/project/cl-store/ for mailing-lists.
31 sross 1.1
32    
33     2. Usage
34 sross 1.9 The main entry points are
35     - [Function] cl-store:store (obj place &optional (backend *default-backend*)) i
36 sross 1.4 => obj
37 sross 1.7 Where place is a path designator or stream and
38     backend is one of the registered backends.
39 sross 1.4
40 sross 1.9 - [Function] cl-store:restore (place &optional (backend *default-backend*))
41     => restored-objects
42 sross 1.4 Where place and backend is as above.
43 sross 1.1
44 sross 1.9 - [Macro] cl-store:multiple-value-store (values-form place &optional (backend *default-backend*))
45     => objects
46     Stores all the values returned by VALUES-FORM into place as per cl-store:store.
47    
48 sross 1.1 - cl-store:restore is setfable, which I think makes
49     for a great serialized hit counter.
50     eg. (incf (restore place))
51 sross 1.9
52 sross 1.1
53 sross 1.9 NOTE.
54     All errors signalled within store and restore can
55     be handled by catching store-error and restore-error respectively.
56    
57 sross 1.1
58     3. Extending
59 sross 1.4 CL-STORE is more or less extensible. Using defstore-<backend-name>
60     and defrestore-<backend-name> allows you to customize the storing
61     and restoring of your own classes.
62    
63 sross 1.2 contrived eg.
64    
65 sross 1.4 (in-package :cl-user)
66    
67     (use-package :cl-store)
68    
69 sross 1.5 (setf *default-backend* *cl-store-backend*)
70    
71 sross 1.4 (defclass random-obj () ((a :accessor a :initarg :a)))
72    
73 sross 1.8 (defvar *random-obj-code* (register-code 110 'random-obj))
74 sross 1.4
75     (defstore-cl-store (obj random-obj stream)
76     (output-type-code *random-obj-code* stream)
77     (store-object (a obj) stream))
78 sross 1.2
79 sross 1.4 (defrestore-cl-store (random-obj stream)
80     (random (restore-object stream)))
81 sross 1.2
82 sross 1.4 (store (make-instance 'random-obj :a 10) "/tmp/random")
83 sross 1.2
84     (restore "/tmp/random")
85     => ; some number from 0 to 9
86 sross 1.4
87    
88     4. Backends
89     CL-STORE now has a concept of backends, suggested by Robert Sedgewick.
90     Two backends are in releases now, a default backend which is much
91     what cl-store used to be (pre 0.2) and an xml backend which writes out
92     xml to character streams.
93 sross 1.7
94 sross 1.4 Store and Restore now take an optional backend argument which
95 sross 1.8 currently can be one of *default-backend*, *xml-backend* or
96     a self defined backend.
97    
98 sross 1.4 The xml written out is not very human readable.
99     I recommend using a tool like tidy <http://tidy.sourceforge.net/>
100     to view it in a nice format.
101    
102 sross 1.2
103 sross 1.4 5. Issues
104 sross 1.9 There are a number of issues with CL-STORE as it stands.
105 sross 1.1
106     - Functions, closures and anything remotely funcallable is unserializable.
107     - MOP classes are largely unsupported at the moment.
108 sross 1.6 - Structure instances are not supported in MCL, OpenMCL and Clisp.
109 sross 1.1 - Structure definitions aren't supported at all.
110     - No documentation.
111 sross 1.3 - Older cmucl versions, where (eq 'cl:class 'pcl::class)
112     returns nil, cannot store classes obtained using cl:find-class.
113     The solution for this is to use pcl::find-class.
114 sross 1.8
115 sross 1.1
116     Enjoy
117     Sean.

  ViewVC Help
Powered by ViewVC 1.1.5