source: project/sqlite3-tinyclos/doc.scm @ 384

Last change on this file since 384 was 384, checked in by Thomas Chust, 15 years ago

Useless keyword argument add-slot removed from
sqlite3:define-stored-object-class

File size: 15.5 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.2" "Alternative superclass for generated classes added")
16        (version "1.2.0" "Superclasses of generated classes can be specified arbitrarily")
17        (version "1.1.0" "Facility to prevent creation of certain getter and/or setter methods")
18        (version "1.0.0" "Initial release"))
19
20      (usage)
21      (download "sqlite3-tinyclos.egg")
22      (requires "sqlite3")
23     
24      (documentation
25        (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.")
26        (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.")
27
28        (subsection "The class generator procedure"
29          (group
30            (procedure "(sqlite3:define-stored-object-class (db <sqlite3:database>) (table <string>) #!key prefix name symbol add-super supers slots) => <void>"
31              (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") ".")
32              (p "Additional value slots for the instances can be obtained by specifying a list as keyword parameter " (tt "slots") ".")
33              (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.")
34              (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.")
35              (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.")
36              (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.")
37              (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") "."))))
38
39        (subsection "Generated getter and setter methods"
40          (group
41            (definition
42              (signatures
43                (signature "method" "(<prefix><name> (self <subclass of sqlite3:stored-object>)) => <top>")
44                (signature "method" "(<prefix><name>? (self <subclass of sqlite3:stored-object>)) => <boolean>"))
45              (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."))
46            (definition
47              (signatures
48                (signature "method" "(<prefix>set-<name>! (self <subclass of sqlite3:stored-object>) (value <top>)) => <void>"))
49              (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."))))
50       
51        (subsection "Metaclasses and classes"
52          (group
53            (definition
54              (signatures
55                (signature "class" "<sqlite3:stored-object-class>"))
56              (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.")
57              (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."))
58            (definition
59              (signatures
60                (signature "class" "<sqlite3:stored-object>"))
61              (p "The common base class of classes generated by " (tt "sqlite3:define-stored-object-class") ". It provides general facilities for row level data access.")
62              (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.")
63              (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."))
64            (definition
65              (signatures
66                (signature "class" "<sqlite3:stored-object/automatic-integer-pk>"))
67              (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.")
68              (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.")))))
69
70        (subsection "Methods"
71          (group
72            (p "The following methods are common to the standard metaclass and class:")
73            (definition
74              (signatures
75                (signature "method" "(sqlite3:db (self <sqlite3:stored-object-class>)) => <sqlite3:database>")
76                (signature "method" "(sqlite3:db (self <sqlite3:stored-object>)) => <sqlite3:database>"))
77              (p "Given a stored object class or a stored object instance this method returns the database connection that object belongs to."))
78            (definition
79              (signatures
80                (signature "method" "(sqlite3:table (self <sqlite3:stored-object-class>)) => <string>")
81                (signature "method" "(sqlite3:table (self <sqlite3:stored-object>)) => <string>"))
82              (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."))
83            (definition
84              (signatures
85                (signature "method" "(sqlite3:pk (self <sqlite3:stored-object-class>)) => <list of string>")
86                (signature "method" "(sqlite3:pk (self <sqlite3:stored-object>)) => <list of string>"))
87              (p "Given a stored object class this method returns a list of column names that hold the primary key for objects of this class.")
88              (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."))
89            (definition
90              (signatures
91                (signature "method" "(sqlite3:pk/select (self <sqlite3:stored-object-class>)) => <string>")
92                (signature "method" "(sqlite3:pk/select (self <sqlite3:stored-object>)) => <string>"))
93              (p "Given a stored object class or a stored object instance this method returns a comma separated list of primary key column names."))
94            (definition
95              (signatures
96                (signature "method" "(sqlite3:pk/update (self <sqlite3:stored-object-class>)) => <string>")
97                (signature "method" "(sqlite3:pk/update (self <sqlite3:stored-object>)) => <string>"))
98              (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 = ?") "."))
99            (definition
100              (signatures
101                (signature "method" "(sqlite3:pk/where (self <sqlite3:stored-object-class>)) => <string>")
102                (signature "method" "(sqlite3:pk/where (self <sqlite3:stored-object>)) => <string>"))
103              (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") "."))
104            (definition
105              (signatures
106                (signature "method" "(sqlite3:fields (self <sqlite3:stored-object-class>)) => <list of string>")
107                (signature "method" "(sqlite3:fields (self <sqlite3:stored-object>)) => <list of string>"))
108              (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.")))
109          (group
110            (p "The following methods are available for objects of class " (tt "<sqlite3:stored-object>") ":")
111            (definition
112              (signatures
113                (signature "method" "(sqlite3:set-pk! (self <sqlite3:stored-object>) . new-pk) => <void>"))
114              (p "Changes the value of the primary key columns for the given object to the new given values."))
115            (definition
116              (signatures
117                (signature "method" "(sqlite3:in-store? (self <sqlite3:stored-object>)) => <boolean>"))
118              (p "Checks whether a row with the currently set primary key column values (still) exists in the database."))
119            (definition
120              (signatures
121                (signature "method" "(sqlite3:create-in-store! (self <sqlite3:stored-object>)) => <boolean>"))
122              (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.")
123              (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."))
124            (definition
125              (signatures
126                (signature "method" "(sqlite3:remove-from-store! (self <sqlite3:stored-object>)) => <boolean>"))
127              (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.")))
128          (group
129            (p "The following two methods should seldomly be needed, as specific field accessors are generated automatically by " (tt "sqlite3:define-stored-object-class") ":")
130            (definition
131              (signatures
132                (signature "method" "(sqlite3:get-stored-property (self <sqlite3:stored-object>) (name <string>)) => <top>"))
133              (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."))
134            (definition
135              (signatures
136                (signature "method" "(sqlite3:set-stored-property! (self <sqlite3:stored-object>) (name <string>) (value <top>)) => <void>"))
137              (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."))))
138
139        (subsection "Helper procedures"
140          (group
141            (procedure "(sqlite3:field-name->getter-symbol (name <string>) #!optional ((prefix <string|symbol>) \"\")) => <symbol>"
142              (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>[?]") ".")
143              (p "This procedure is internally used by " (tt "sqlite3:define-stored-object-class") " to compute the names of getter methods."))
144            (procedure "(sqlite3:field-name->setter-symbol (name <string>) #!optional ((prefix <string|symbol>) \"\")) => <symbol>"
145              (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>!") ".")
146              (p "This procedure is internally used by " (tt "sqlite3:define-stored-object-class") " to compute the names of setter methods."))))
147     
148        (examples ,pull-demo-code-in)
149
150        (license
151          "Copyright (c) 2006, Thomas Chust <chust@web.de>.  All rights reserved.
152
153Redistribution and use in source and binary forms, with or without
154modification, are permitted provided that the following conditions are met:
155
156  Redistributions of source code must retain the above copyright notice,
157  this list of conditions and the following disclaimer. Redistributions in
158  binary form must reproduce the above copyright notice, this list of
159  conditions and the following disclaimer in the documentation and/or
160  other materials provided with the distribution. Neither the name of the
161  author nor the names of its contributors may be used to endorse or
162  promote products derived from this software without specific prior
163  written permission.
164
165THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS
166IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
167THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
168PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
169CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
170EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
171PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
172PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
173LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
174NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
175SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.")))))
176
177(eggdoc->html doc (eggdoc:make-stylesheet doc))
178
179;;;; vim:set shiftwidth=2 softtabstop=2: ;;;;
Note: See TracBrowser for help on using the repository browser.