source: project/sqlite3-tinyclos/tags/1.2.3/doc.scm @ 4991

Last change on this file since 4991 was 4991, checked in by Thomas Chust, 13 years ago

[sqlite3-tinyclos] Conversion of repository directory layout, step 1

File size: 15.6 KB
Line 
1(use eggdoc htmlprag sxml-tools)
2
3(define (pull-demo-code-in)
4  (write-shtml-as-html
5    (car
6      ((sxpath '(// pre))
7        (call-with-input-file "sqlite3-tinyclos-demo.html" html->sxml)))))
8
9(define doc
10  `((eggdoc:begin
11      (name "sqlite3-tinyclos")
12      (description (p "A bridge between persistent storage in SQLite3 tables and TinyCLOS objects."))
13      (author (url "http://www.chust.org/" "Thomas Chust"))
14      (history
15        (version "1.2.3" "Fixed compiler flags to pull in tinyclos")
16        (version "1.2.2" "Alternative superclass for generated classes added")
17        (version "1.2.0" "Superclasses of generated classes can be specified arbitrarily")
18        (version "1.1.0" "Facility to prevent creation of certain getter and/or setter methods")
19        (version "1.0.0" "Initial release"))
20
21      (usage)
22      (download "sqlite3-tinyclos.egg")
23      (requires "sqlite3")
24     
25      (documentation
26        (p "This egg is intended to quickly establish an object oriented interface to data in an SQLite3 database. The interface you are provided with is rather basic, but easily extensible.")
27        (p "In the simplest case you just create the database with its schema of tables and then call " (tt "sqlite3:define-stored-object-class") " once for each table you want to access through this interface. See the example below for a first impression.")
28
29        (subsection "The class generator procedure"
30          (group
31            (procedure "(sqlite3:define-stored-object-class (db <sqlite3:database>) (table <string>) #!key prefix name symbol add-super supers slots) => <void>"
32              (p "This procedure creates a TinyCLOS class of metaclass " (tt "<sqlite3:stored-object-class>") " and superclasses " (tt "supers") ", defaulting to a list containing only " (tt "<sqlite3:stored-object>") ". The new class can be instantiated to access data stored in the " (tt "table") " of the given SQLite3 " (tt "db") ".")
33              (p "Additional value slots for the instances can be obtained by specifying a list as keyword parameter " (tt "slots") ".")
34              (p "The list specified for " (tt "supers") " can be chosen arbitrarily but it should probably contain either " (tt "<sqlite3:stored-object>") " itself or a subclass of it. To just add superclasses in addition to the default one you may want to use " (tt "add-super") " keyword parameters, which are prepended in sequence to the list specified by " (tt "supers") " or the default list.")
35              (p "The prefix referred to in the following paragraphs is either taken from the corresponding keyword argument or, if no such argument is given, is assumed to be the empty string.")
36              (p "The generated class has the name given as a keyword argument or, if no such argument is present, a name composed of the prefix and the table name stripped of any trailing 's' characters.")
37              (p "The generated class is assigned to the global variable specified by " (tt "symbol") " or, if no such argument is given, the symbol composed of an opening angle bracket, the name of the class and a closing angle bracket.")
38              (p "For all columns in the table that are not part of the primary key, two accessor methods for retrieving and setting them are defined, with names computed by " (tt "sqlite3:field-name->getter-symbol") " and " (tt "sqlite3:field-name->setter-symbol") " respectively. If a list is passed in the keyword argument " (tt "no-getter-or-setter") " and it contains the name of a database field, no getter or setter is created for this field. Likewise no getter is generated for columns mentioned in " (tt "no-getter") " and no setter is generated for those mentioned in " (tt "no-setter") "."))))
39
40        (subsection "Generated getter and setter methods"
41          (group
42            (definition
43              (signatures
44                (signature "method" "(<prefix><name> (self <subclass of sqlite3:stored-object>)) => <top>")
45                (signature "method" "(<prefix><name>? (self <subclass of sqlite3:stored-object>)) => <boolean>"))
46              (p "These methods defined by " (tt "sqlite3:define-stored-object-class") " retrieve the value of a regular or boolean field in the database respectively. For boolean fields, whose names start with " (tt "is_") " in the database, an automatic conversion from " (tt "NULL") " or " (tt "0") " to " (tt "#f") " and anything else to " (tt "#t") " is performed."))
47            (definition
48              (signatures
49                (signature "method" "(<prefix>set-<name>! (self <subclass of sqlite3:stored-object>) (value <top>)) => <void>"))
50              (p "These methods defined by " (tt "sqlite3:define-stored-object-class") " set the value of a field in the database. For boolean fields, whose names start with " (tt "is_") " in the database, an automatic conversion from " (tt "#f") " to " (tt "0") " and anything else to " (tt "1") " is performed."))))
51       
52        (subsection "Metaclasses and classes"
53          (group
54            (definition
55              (signatures
56                (signature "class" "<sqlite3:stored-object-class>"))
57              (p "The metaclass for classes generated by " (tt "sqlite3:define-stored-object-class") ". It provides its class instances with facilities to store the database handle and analyze the schema.")
58              (p "In particular, instances of this class contain " (tt "db") ", " (tt "table") ", " (tt "pk") " and " (tt "fields") " slots. Of these " (tt "db") " and " (tt "table") " must be set when instantiating (which is automatically done by " (tt "sqlite3:define-stored-object-class") "), while " (tt "pk") " and " (tt "fields") " are computed by the " (tt "initialize") " method. All these fields should be read with the accessors described below."))
59            (definition
60              (signatures
61                (signature "class" "<sqlite3:stored-object>"))
62              (p "The common base class of classes generated by " (tt "sqlite3:define-stored-object-class") ". It provides general facilities for row level data access.")
63              (p "In particular, instances of this class contain a " (tt "pk") " slot storing the current values of the primary key columns for this object. The contents of this slot should be retrieved and set using the accessors described below. When creating an object of class " (tt "<sqlite3:stored-object>") ", the " (tt "pk") " slot can either be set with the usual TinyCLOS initialization argument syntax or by specifying exactly all the primary key values as initialization arguments.")
64              (p "The " (tt "initialize") " method for this class also checks whether a row with the specified primary key already exists in the database using " (tt "sqlite3:in-store?") " and inserts such a row using " (tt "sqlite3:create-in-store!") " if this is not the case."))
65            (definition
66              (signatures
67                (signature "class" "<sqlite3:stored-object/automatic-integer-pk>"))
68              (p "This subclass of " (tt "<sqlite3:stored-object>") " has a modified " (tt "sqlite3:in-store?") " method that automatically allocates a new primary key one larger than the largest one in use if the object was created with an empty primary key. This means that objects created by a simple " (tt "(make <class>)") " call, where " (tt "<class>") " is a subclass of " (tt "<sqlite3:stored-object/automatic-integer-pk>") ", will immediately be entered into the database with a new unique id.")
69              (p (em "Note that this class can only be used sensibly with tables that have a single integer primary key. Also note that instances of this class should only be created with proper exclusive locks on the database in place.")))))
70
71        (subsection "Methods"
72          (group
73            (p "The following methods are common to the standard metaclass and class:")
74            (definition
75              (signatures
76                (signature "method" "(sqlite3:db (self <sqlite3:stored-object-class>)) => <sqlite3:database>")
77                (signature "method" "(sqlite3:db (self <sqlite3:stored-object>)) => <sqlite3:database>"))
78              (p "Given a stored object class or a stored object instance this method returns the database connection that object belongs to."))
79            (definition
80              (signatures
81                (signature "method" "(sqlite3:table (self <sqlite3:stored-object-class>)) => <string>")
82                (signature "method" "(sqlite3:table (self <sqlite3:stored-object>)) => <string>"))
83              (p "Given a stored object class or a stored object instance this method returns the name of the database table that holds the instances of the class or the object respectively."))
84            (definition
85              (signatures
86                (signature "method" "(sqlite3:pk (self <sqlite3:stored-object-class>)) => <list of string>")
87                (signature "method" "(sqlite3:pk (self <sqlite3:stored-object>)) => <list of string>"))
88              (p "Given a stored object class this method returns a list of column names that hold the primary key for objects of this class.")
89              (p "Given a stored object instance this method returns the list of primary key values for this object corresponding in sequence to the list of primary key columns."))
90            (definition
91              (signatures
92                (signature "method" "(sqlite3:pk/select (self <sqlite3:stored-object-class>)) => <string>")
93                (signature "method" "(sqlite3:pk/select (self <sqlite3:stored-object>)) => <string>"))
94              (p "Given a stored object class or a stored object instance this method returns a comma separated list of primary key column names."))
95            (definition
96              (signatures
97                (signature "method" "(sqlite3:pk/update (self <sqlite3:stored-object-class>)) => <string>")
98                (signature "method" "(sqlite3:pk/update (self <sqlite3:stored-object>)) => <string>"))
99              (p "Given a stored object class or a stored object instance this method returns a comma separated list of tokens in the form " (tt "primary_key_column_name = ?") "."))
100            (definition
101              (signatures
102                (signature "method" "(sqlite3:pk/where (self <sqlite3:stored-object-class>)) => <string>")
103                (signature "method" "(sqlite3:pk/where (self <sqlite3:stored-object>)) => <string>"))
104              (p "Given a stored object class or a stored object instance this method returns a list of tokens in the form " (tt "primary_key_column_name = ?") ", separated by the word " (tt "AND") "."))
105            (definition
106              (signatures
107                (signature "method" "(sqlite3:fields (self <sqlite3:stored-object-class>)) => <list of string>")
108                (signature "method" "(sqlite3:fields (self <sqlite3:stored-object>)) => <list of string>"))
109              (p "Given a stored object class or a stored object instance this method returns a list of column names which are not part of the primary key.")))
110          (group
111            (p "The following methods are available for objects of class " (tt "<sqlite3:stored-object>") ":")
112            (definition
113              (signatures
114                (signature "method" "(sqlite3:set-pk! (self <sqlite3:stored-object>) . new-pk) => <void>"))
115              (p "Changes the value of the primary key columns for the given object to the new given values."))
116            (definition
117              (signatures
118                (signature "method" "(sqlite3:in-store? (self <sqlite3:stored-object>)) => <boolean>"))
119              (p "Checks whether a row with the currently set primary key column values (still) exists in the database."))
120            (definition
121              (signatures
122                (signature "method" "(sqlite3:create-in-store! (self <sqlite3:stored-object>)) => <boolean>"))
123              (p "Creates a row with the currently set primary key column values and default values for all other columns if no such row already exists. Returns " (tt "#t") " or " (tt "#f") " if a row was inserted or not.")
124              (p "This method may return " (tt "#f") " if a row with the given primary key already exists, but it may also return " (tt "#f") " if the database imposes some constraints on the values of further rows that is not fulfilled by the default values. You should generally either not create tables with such constraints for use with this egg or you should override " (tt "sqlite3:create-in-store!") " for your stored object classes because it is called from " (tt "initialize") " if an object of class " (tt "<sqlite3:stored-object>") " is created with a not yet existing primary key."))
125            (definition
126              (signatures
127                (signature "method" "(sqlite3:remove-from-store! (self <sqlite3:stored-object>)) => <boolean>"))
128              (p "Removes the row with the currently stored primary key column values from the database and returns " (tt "#t") " or returns " (tt "#f") " and does nothing if no such row exists.")))
129          (group
130            (p "The following two methods should seldomly be needed, as specific field accessors are generated automatically by " (tt "sqlite3:define-stored-object-class") ":")
131            (definition
132              (signatures
133                (signature "method" "(sqlite3:get-stored-property (self <sqlite3:stored-object>) (name <string>)) => <top>"))
134              (p "Retrieves the value stored in column " (tt "name") " from the table apropriate for this object where the primary key columns have the values currently stored in this object."))
135            (definition
136              (signatures
137                (signature "method" "(sqlite3:set-stored-property! (self <sqlite3:stored-object>) (name <string>) (value <top>)) => <void>"))
138              (p "Sets the column " (tt "name") " to the given " (tt "value") " in the table apropriate for this object where the primary key columns have the values stored in this object."))))
139
140        (subsection "Helper procedures"
141          (group
142            (procedure "(sqlite3:field-name->getter-symbol (name <string>) #!optional ((prefix <string|symbol>) \"\")) => <symbol>"
143              (p "Given the name of a database column this procedure returns a mangled version of the name with underscores replaced by dashes and the prefix " (tt "is-") " replaced by a trailing question mark. Thus the return value is a scheme symbol in the form " (tt "<prefix><name>[?]") ".")
144              (p "This procedure is internally used by " (tt "sqlite3:define-stored-object-class") " to compute the names of getter methods."))
145            (procedure "(sqlite3:field-name->setter-symbol (name <string>) #!optional ((prefix <string|symbol>) \"\")) => <symbol>"
146              (p "Given the name of a database column this procedure returns a mangled version of the name with underscores replaced by dashes and the prefix " (tt "is-") " stripped. In addition to the given prefix, " (tt "set-") " is prepended to the result and an exclamation mark is appended. Thus the return value is a scheme symbol in the form " (tt "<prefix>set-<name>!") ".")
147              (p "This procedure is internally used by " (tt "sqlite3:define-stored-object-class") " to compute the names of setter methods."))))
148     
149        (examples ,pull-demo-code-in)
150
151        (license
152          "Copyright (c) 2006, Thomas Chust <chust@web.de>.  All rights reserved.
153
154Redistribution and use in source and binary forms, with or without
155modification, are permitted provided that the following conditions are met:
156
157  Redistributions of source code must retain the above copyright notice,
158  this list of conditions and the following disclaimer. Redistributions in
159  binary form must reproduce the above copyright notice, this list of
160  conditions and the following disclaimer in the documentation and/or
161  other materials provided with the distribution. Neither the name of the
162  author nor the names of its contributors may be used to endorse or
163  promote products derived from this software without specific prior
164  written permission.
165
166THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS
167IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
168THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
169PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
170CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
171EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
172PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
173PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
174LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
175NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
176SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.")))))
177
178(eggdoc->html doc (eggdoc:make-stylesheet doc))
179
180;;;; vim:set shiftwidth=2 softtabstop=2: ;;;;
Note: See TracBrowser for help on using the repository browser.