source: project/release/4/s11n/trunk/doc.scm @ 15283

Last change on this file since 15283 was 15283, checked in by felix winkelmann, 10 years ago

updated doc.scm

File size: 5.2 KB
Line 
1(use eggdoc)
2
3(define license
4"Copyright (c) 2005, Felix Winkelmann.  All rights reserved.
5
6Permission is hereby granted, free of charge, to any person obtaining a
7copy of this software and associated documentation files (the Software),
8to deal in the Software without restriction, including without limitation
9the rights to use, copy, modify, merge, publish, distribute, sublicense,
10and/or sell copies of the Software, and to permit persons to whom the
11Software is furnished to do so, subject to the following conditions:
12
13The above copyright notice and this permission notice shall be included
14in all copies or substantial portions of the Software.
15
16THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
20OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
22OTHER DEALINGS IN THE SOFTWARE.")
23
24(define email "mailto:felix@call-with-current-continuation.org")
25
26(define doc
27  `((eggdoc:begin
28     (name "s11n")
29     (description (p "Serialization and deserialization of arbitrary objects"))
30     
31     (author (url ,email "felix"))
32
33     (history
34      (version "0.9.2" "ported to CHICKEN 4")
35      (version "0.9" "doesn't use easyffi anymore")
36      (version "0.8" "Made fallback-handler more useful and fixed a bug [Thanks to Daishi Kato]")
37      (version "0.7" "Added fallback-handler to `deserialize'")
38      (version "0.6" "Nasty little bug in backreferences fixed")
39      (version "0.5" "Hash-table-deserialization bug reported by Kabir Soorya")
40      (version "0.4" "Fixed small bug in port-serialization; added note about continuations")
41      (version "0.3" "Serialization of hash-tables is more storage efficient; added `chicken-dump' program")
42      (version "0.2" "Failure handling for some cases was invalid")
43      (version "0.1" "Initial release"))
44
45     (usage)
46     (download "s11n.egg")
47
48     (documentation
49      (p "This extension allows serializing and deserializing arbitrary data (including procedures"
50         " and continuations) into/from ports. Circular data is support as well as uninterned symbols."
51         " Foreign-pointer objects and ports other than the default input-, output- and error-ports"
52         " can not be serialized. Threads may be serialized provided they are not running or ready"
53         " (this means suspended or created but not yet started threads).")
54      (p "The serialized data is endianness- and word-size dependent.")
55      (p "To enable serialization of procedures and continuations, CHICKEN has to be built with the "
56         (tt "--enable-procedure-tables") " configuration option. In particular, any compiled module that"
57         " is referenced in serialized data has to be compiled with a CHICKEN version that has procedure"
58         " tables enabled.")
59      (p "Compiled procedures and continuations can be deserialized, provided that the same executable"
60         " or libraries are loaded/linked - the compiled code must be available so that the deserialization"
61         " process can find the associated code.")
62      (p "Continuations can be serialized but care has to be taken about what exactly is stored in such an"
63         " object. Every invocation of " (tt "call-with-current-continuation") " includes the complete list"
64         " of pending " (tt "dynamic-wind") " thunks (and their dynamic environment) which is likely to include"
65         " non-serializable state.")
66      (p "Since the deserialization process breaks any assumptions about a unique identity of objects,"
67         " TinyCLOS instances and classes can currently not be deserialized.")
68      (p "CHICKEN version 2.207 or higher is required to use this extension.")
69
70      (group
71       (procedure "(serialize X [PORT [SERIALIZER]])"
72                  (p "Writes a binary representation of " (tt "X") " into " (tt "PORT") " which defaults to the"
73                     " value of " (tt "(current-output-port)") ". If the serialization is unable to handle some"
74                     " object, the procedure " (tt "SERIALIZER") " is invoked with that object as it's sole argument."
75                     " The procedure should either signal an error or return a placeholder object that is to be"
76                     " serialized instead. If no serializer is specified, an error will be signalled.") )
77
78       (procedure "(deserialize [PORT [DESERIALIZER]])"
79                  (p "Reads a binary representation of a Scheme data object from " (tt "PORT") " which defaults"
80                     " to the value of " (tt "(current-input-port)") ". The deserialized object is returned.")
81                  (p "If " (tt "DESERIALIZER") " is given, then it will be called for procedure objects that"
82                     " can not be deserialized (normally because a serialized file was generated by a different"
83                     " version of CHICKEN) with the procedure-id (internal name) and the deserialized closure object as argument.") ) )
84
85      (group
86       (p "A separate tool is also available, named " (tt "chicken-dump") " that writes "
87          "a description about the contents of a serialized file. Just invoke "
88          (pre "chicken-dump FILENAME")
89          (p "on the command prompt.") ) ) )
90     
91     (section "License" (pre ,license)))))
92
93(eggdoc->html doc)
94
Note: See TracBrowser for help on using the repository browser.