source: project/release/3/mysql/trunk/eggdoc-mysql.scm @ 7925

Last change on this file since 7925 was 7925, checked in by Kon Lovett, 12 years ago

Split test into common section. Added MY_CHARSET_INFO, srfi-12 (instead of error), Options, SSL, Rmvd dep mysql procs., mysql-fetch-lengths, chgd field struct api (more mysql-ish).

  • Property svn:executable set to *
File size: 18.3 KB
Line 
1#!/usr/local/bin/csi -script
2; vim: ts=2:sw=2:et:
3; eggdoc-mysql.scm,v 1.8 2005/08/05 00:27:02 tbutzon Exp
4
5(use eggdoc)
6
7(define license-text #<<END
8Copyright (c) 2005 Toby Butzon.
9
10Permission is hereby granted, free of charge, to any person obtaining a
11copy of this software and associated documentation files (the "Software"),
12to deal in the Software without restriction, including without limitation
13the rights to use, copy, modify, merge, publish, distribute, sublicense,
14and/or sell copies of the Software, and to permit persons to whom the
15Software is furnished to do so, subject to the following conditions:
16
17The above copyright notice and this permission notice shall be included
18in all copies or substantial portions of the Software.
19
20THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
23THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
24OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
25ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
26OTHER DEALINGS IN THE SOFTWARE.
27END
28)
29
30(define ex1-text #<<END
31(use mysql)
32
33(let [(db (mysql-connect host: "mysql.example.com" user: "example"
34                         passwd: "secret"))]
35  (mysql-query db "SHOW DATABASES")
36  (do [(row (mysql-fetch-row db) (mysql-fetch-row db))]
37      [(not row)]
38    (display (conc "Row " idx ": " (row "Database") "\n")))
39  (mysql-close db))
40END
41)
42
43(define ex2-text #<<END
44(use mysql)
45
46(let [(db (mysql-connect host: "mysql.example.com" user: "example"
47                         passwd: "secret"))]
48  (mysql-query-foreach db "SHOW DATABASES"
49                       (lambda (row idx)
50                         (display (conc "Row " idx ": " (row "Database") "\n"))))
51  (mysql-close db))
52END
53)
54
55(define doc `(
56  (eggdoc:begin
57    (name "mysql")
58    (description (p "MySQL bindings for Chicken."))
59    (author (url "mailto:toby@butzon.com" "Toby Butzon"))
60    (history
61      (version "1.3" "Additional functions [Kon Lovett].")
62      (version "1.2" "Fix for ticket #297 [Mario Domenech Goulart].")
63      (version "1.1" "Cross-platform compilation fixes, et al.")
64      (version "1.0" "Initial release") )
65    (requires (span "MySQL client library (" (tt "-lmysqlclient") ")"))
66    (usage)
67    (download "mysql.egg")
68
69    (documentation
70
71      (p
72        "The MySQL egg provides (most of) the functions offered by the MySQL C "
73        "API (the " (tt "foreign-mysql-*") " functions). It also maps those to a "
74        "set of slightly more convenient Scheme functions (the " (tt "mysql-*") " "
75        "functions). Finally, a few extra functions are provided for easy of use.")
76
77      (p
78        "Only the most often used MySQL functions are described in this "
79        "document. If you really want to see the full listing, consult the "
80        (url "mysql-mole.html" "mole documentation") ".")
81
82      (p
83        "Please send bug reports and suggestions to "
84        (url "mailto:toby@butzon.com" "toby@butzon.com") ".")
85
86      (subsection "Exceptions"
87     
88        (p
89          "Conditions of the kind " (code "(exn mysql)") " are signaled "
90          "for error conditions.")
91        (symbol-table "Properties"
92          (describe location "Where the error occured - usually a procedure name.")
93          (describe arguments "Values that contributed to the error.")
94          (describe message "Error message"))
95      )
96
97      (subsection "Connections"
98
99        (procedure "(mysql-connect [KEYWORDS])"
100          (p
101            "Connect to a MySQL server.")
102          (p
103            "Returns a MySQL connection object suitable for passing to "
104            "the other MySQL functions. This object is referred to as "
105            (tt "DB") " when passed by all the other MySQL functions. "
106            "Signals an exception when the connection fails.")
107          (p
108            "Any number of the following " (tt "KEYWORDS") " may be included:"
109            (ul
110              (li "host")
111              (li "user")
112              (li "passwd")
113              (li "db")
114              (li "port")
115              (li "unix-socket")
116              (li "client-flag")
117              #;(li "ssl")
118              #;(li "options")))
119          (p
120            "Note that default values are available for all of these "
121            "arguments. (Consult the "
122            (url "http://dev.mysql.com/doc/mysql/en/c.html" "MySQL C API") " "
123            "for details on how these defaults are determined.)") )
124
125        (procedure "(mysql-close DB)"
126          (p
127            "Closes the connection to " (tt "DB") ". This frees any remaining "
128            "MySQL resources from memory, but invalidates the MySQL connection "
129            "object (" (tt "DB") ") so that it may no longer be used.") )
130      )
131
132      (subsection "Basic Operations"
133
134        (procedure "(mysql-query DB SQL-STRING)"
135          (p
136            "Executes " (tt "SQL-STRING") " on the MySQL server "
137            "and stores the result in memory. Signals an exception "
138            "if the query fails.") )
139
140        (procedure "(mysql-fetch-row DB)"
141          (p
142            "Fetches a row from the result set returned by the "
143            "most recent call to " (tt "mysql-query") ". If the "
144            "last query failed, or if there are no more rows left "
145            "in the result set, returns " (tt "#f") "; otherwise "
146            "returns a row object.")
147          (a (@ (" name='rowobj'")))
148          (p
149            "A row object is defined as a function that "
150            "takes a single argument. If the argument is a number, "
151            "the function returns the value of the field for which "
152            "that number is the index, or " (tt "#f") " if the "
153            "index is out of range. Otherwise, the argument must "
154            "be a symbol or string, in which case the function returns "
155            "the value of the field for which that string (or symbol "
156            "converted into a string) is the field/column name. If "
157            "no such field exists, returns " (tt "#f") ".") )
158
159        (procedure "(mysql-rewind DB)"
160          (p
161            "Rewinds the result set; that is, resets the pointer used by "
162            (tt "mysql-fetch-row") " so that the next call to it will "
163            "return the first row of the result set. If there is no current "
164            "result set, does nothing.") )
165
166        (procedure "(mysql-num-rows DB)"
167          (p
168            "Returns the number of rows in the current result set. "
169            "If no result set exists, returns " (tt "#f") ".") )
170      )
171
172      (subsection "Row Mapping"
173
174        (procedure "(mysql-row-fold DB PROC INIT)"
175          (p
176            "Iterates over the entire result set (regardless of any rows that may "
177            "have already been returned by " (tt "mysql-fetch-row") "), calling "
178            (tt "PROC") " on each row.")
179          (p
180            "Returns the final accumulated value.")
181          (p
182            (tt "PROC") " must take three arguments: the row (as "
183            (url "#rowobj" "described") ") for " (tt "mysql-fetch-row") ", "
184            "the index of that row in the result set, starting with " (tt "1") " "
185            "and ending with " (tt "(mysql-num-rows DB)") ", and the "
186            "current accumulated value (initially " (tt "INIT") ").")
187          (p
188            (tt "PROC") " must return a value.") )
189
190        (procedure "(mysql-row-for-each DB PROC)"
191          (p
192            "Iterates over the entire result set (regardless of any rows that "
193            "may have already been returned by " (tt "mysql-fetch-row") "), calling "
194            (tt "PROC") " on each row.")
195          (p
196            (tt "PROC") " must take three arguments: the row (as "
197            (url "#rowobj" "described") ") for " (tt "mysql-fetch-row")
198            ", and the index of that row in the result set, starting with "
199            (tt "1") " and ending with " (tt "(mysql-num-rows DB)") ".") )
200
201        (procedure "(mysql-row-map DB PROC)"
202          (p
203            "Iterates over the entire result set (regardless of any rows that "
204            "may have already been returned by " (tt "mysql-fetch-row") "), "
205            "calling " (tt "PROC") " on each row.")
206          (p
207            "Returns the list of results of the " (tt "PROC") " invocations.")
208          (p
209            (tt "PROC") " must take three arguments: the row (as "
210            (url "#rowobj" "described") ") for " (tt "mysql-fetch-row")
211            ", and the index of that row in the result set, starting "
212            "with " (tt "1") " and ending with " (tt "(mysql-num-rows DB)") ".")
213          (p
214            (tt "PROC") " must return a value.") )
215
216        (procedure "(mysql-query-fold DB QUERY PROC INIT)"
217          (p
218            "Combines " (tt "mysql-query") " and " (tt "mysql-row-fold") ".") )
219
220        (procedure "(mysql-query-for-each DB QUERY PROC)"
221          (p
222            "Combines " (tt "mysql-query") " and " (tt "mysql-row-for-each") ".") )
223
224        (procedure "(mysql-query-map DB QUERY PROC)"
225          (p
226            "Combines " (tt "mysql-query") " and " (tt "mysql-row-map") ".") )
227
228        (procedure "(mysql-foreach-row DB BODY)"
229          (p
230            "Synonym for " (code "mysql-row-for-each") ".") )
231
232        (procedure "(mysql-query-foreach DB QUERY BODY)"
233          (p
234            "Synonym for " (code "mysql-query-for-each") ".") )
235      )
236
237      (subsection "Field Access"
238
239        (subsubsection "Field Set Access"
240
241          (procedure "(mysql-field-slots MYSQL-FIELD-POINTER MYSQL-FIELD-GETTER ...)"
242            (p
243              "Returns a list of MYSQL_FIELD entry values, "
244              "from each " (tt "MYSQL-FIELD-GETTER") ".")
245            (p
246              (tt "MYSQL-FIELD-POINTER") " is a pointer to a MYSQL_FIELD, or "
247              (code "#f") ". "
248              (tt "MYSQL-FIELD-GETTER") " is a " (code "mysql-field-*") " "
249              "reference function.") )
250
251          (procedure "(mysql-fetch-field-slots-direct DB FIELD-NUMBER MYSQL-FIELD-GETTER ...)"
252            (p
253              "Combination of " (code "mysql-fetch-field-direct") " and "
254              (code "mysql-field-slots") ".") )
255
256          (procedure "(mysql-fetch-field-slots DB MYSQL-FIELD-GETTER ...)"
257            (p
258              "Combination of " (code "mysql-fetch-field") " and "
259              (code "mysql-field-slots") ".") )
260
261        )
262
263        (subsubsection "Field Entry Access"
264
265          (procedure "(mysql-field-org-name MYSQL-FIELD-POINTER)"
266            (p
267              "Returns " (code "string") ".") )
268
269          (procedure "(mysql-field-name MYSQL-FIELD-POINTER)"
270            (p
271              "Returns " (code "string") ".") )
272
273          (procedure "(mysql-field-org-table MYSQL-FIELD-POINTER)"
274            (p
275              "Returns " (code "string") ".") )
276
277          (procedure "(mysql-field-org-table MYSQL-FIELD-POINTER)"
278            (p
279              "Returns " (code "string") ".") )
280
281          (procedure "(mysql-field-db MYSQL-FIELD-POINTER)"
282            (p
283              "Returns " (code "string") ".") )
284
285          (procedure "(mysql-field-catalog MYSQL-FIELD-POINTER)"
286            (p
287              "Returns " (code "string") ".") )
288
289          (procedure "(mysql-field-def MYSQL-FIELD-POINTER)"
290            (p
291              "Returns " (code "string") ".") )
292
293          (procedure "(mysql-field-table MYSQL-FIELD-POINTER)"
294            (p
295              "Returns " (code "string") ".") )
296
297          (procedure "(mysql-field-type MYSQL-FIELD-POINTER)"
298            (p
299              "Returns " (code "enum enum_field_types value") ".") )
300
301          (procedure "(mysql-field-charsetnr MYSQL-FIELD-POINTER)"
302            (p
303              "Returns " (code "unsigned-integer") ".") )
304
305          (procedure "(mysql-field-flags MYSQL-FIELD-POINTER)"
306            (p
307              "Returns " (code "unsigned-integer") ".") )
308
309          (procedure "(mysql-field-decimals MYSQL-FIELD-POINTER)"
310            (p
311              "Returns " (code "unsigned-integer") ".") )
312
313          (procedure "(mysql-field-def-length MYSQL-FIELD-POINTER)"
314            (p
315              "Returns " (code "unsigned-integer") ".") )
316
317          (procedure "(mysql-field-catalog-length MYSQL-FIELD-POINTER)"
318            (p
319              "Returns " (code "unsigned-integer") ".") )
320
321          (procedure "(mysql-field-db-length MYSQL-FIELD-POINTER)"
322            (p
323              "Returns " (code "unsigned-integer") ".") )
324
325          (procedure "(mysql-field-org-table-length MYSQL-FIELD-POINTER)"
326            (p
327              "Returns " (code "unsigned-integer") ".") )
328
329          (procedure "(mysql-field-table-length MYSQL-FIELD-POINTER)"
330            (p
331              "Returns " (code "unsigned-integer") ".") )
332
333          (procedure "(mysql-field-org-name-length MYSQL-FIELD-POINTER)"
334            (p
335              "Returns " (code "unsigned-integer") ".") )
336
337          (procedure "(mysql-field-name-length MYSQL-FIELD-POINTER)"
338            (p
339              "Returns " (code "unsigned-integer") ".") )
340
341          (procedure "(mysql-field-max-length MYSQL-FIELD-POINTER)"
342            (p
343              "Returns " (code "unsigned-integer") ".") )
344
345          (procedure "(mysql-field-length MYSQL-FIELD-POINTER)"
346            (p
347              "Returns " (code "unsigned-integer") ".") )
348        )
349      )
350
351      (subsection "Enumeration Values"
352
353        (symbol-table "enum enum_mysql_set_option"
354          (describe mysql-option-multi-statements-on "MYSQL_OPTION_MULTI_STATEMENTS_ON")
355          (describe mysql-option-multi-statements-off "MYSQL_OPTION_MULTI_STATEMENTS_OFF") )
356
357        (symbol-table "enum mysql_option"
358          (describe mysql-opt-connect-timeout "MYSQL_OPT_CONNECT_TIMEOUT")
359          (describe mysql-opt-compress "MYSQL_OPT_COMPRESS")
360          (describe mysql-opt-named-pipe "MYSQL_OPT_NAMED_PIPE")
361          (describe mysql-init-command "MYSQL_INIT_COMMAND")
362          (describe mysql-read-default-file "MYSQL_READ_DEFAULT_FILE")
363          (describe mysql-read-default-group "MYSQL_READ_DEFAULT_GROUP")
364          (describe mysql-set-charset-dir "MYSQL_SET_CHARSET_DIR")
365          (describe mysql-set-charset-name "MYSQL_SET_CHARSET_NAME")
366          (describe mysql-opt-local-infile "MYSQL_OPT_LOCAL_INFILE")
367          (describe mysql-opt-protocol "MYSQL_OPT_PROTOCOL")
368          (describe mysql-shared-memory-base-name "MYSQL_SHARED_MEMORY_BASE_NAME")
369          (describe mysql-opt-read-timeout "MYSQL_OPT_READ_TIMEOUT")
370          (describe mysql-opt-write-timeout "MYSQL_OPT_WRITE_TIMEOUT")
371          (describe mysql-opt-use-result "MYSQL_OPT_USE_RESULT")
372          (describe mysql-opt-use-remote-connection "MYSQL_OPT_USE_REMOTE_CONNECTION")
373          (describe mysql-opt-use-embedded-connection "MYSQL_OPT_USE_EMBEDDED_CONNECTION")
374          (describe mysql-opt-guess-connection "MYSQL_OPT_GUESS_CONNECTION")
375          (describe mysql-set-client-ip "MYSQL_SET_CLIENT_IP")
376          (describe mysql-secure-auth "MYSQL_SECURE_AUTH")
377          (describe mysql-report-data-truncation "MYSQL_REPORT_DATA_TRUNCATION") )
378
379        (symbol-table "enum enum_field_types"
380          (describe mysql-type-decimal "MYSQL_TYPE_DECIMAL")
381          (describe mysql-type-tiny "MYSQL_TYPE_TINY")
382          (describe mysql-type-short "MYSQL_TYPE_SHORT")
383          (describe mysql-type-long "MYSQL_TYPE_LONG")
384          (describe mysql-type-float "MYSQL_TYPE_FLOAT")
385          (describe mysql-type-double "MYSQL_TYPE_DOUBLE")
386          (describe mysql-type-null "MYSQL_TYPE_NULL")
387          (describe mysql-type-timestamp "MYSQL_TYPE_TIMESTAMP")
388          (describe mysql-type-longlong "MYSQL_TYPE_LONGLONG")
389          (describe mysql-type-int24 "MYSQL_TYPE_INT24")
390          (describe mysql-type-date "MYSQL_TYPE_DATE")
391          (describe mysql-type-time "MYSQL_TYPE_TIME")
392          (describe mysql-type-datetime "MYSQL_TYPE_DATETIME")
393          (describe mysql-type-year "MYSQL_TYPE_YEAR")
394          (describe mysql-type-newdate "MYSQL_TYPE_NEWDATE")
395          (describe mysql-type-varchar "MYSQL_TYPE_VARCHAR")
396          (describe mysql-type-bit "MYSQL_TYPE_BIT")
397          (describe mysql-type-newdecimal "MYSQL_TYPE_NEWDECIMAL")
398          (describe mysql-type-enum "MYSQL_TYPE_ENUM")
399          (describe mysql-type-set "MYSQL_TYPE_SET")
400          (describe mysql-type-tiny-blob "MYSQL_TYPE_TINY_BLOB")
401          (describe mysql-type-medium-blob "MYSQL_TYPE_MEDIUM_BLOB")
402          (describe mysql-type-long-blob "MYSQL_TYPE_LONG_BLOB")
403          (describe mysql-type-blob "MYSQL_TYPE_BLOB")
404          (describe mysql-type-var-string "MYSQL_TYPE_VAR_STRING")
405          (describe mysql-type-string "MYSQL_TYPE_STRING")
406          (describe mysql-type-geometry "MYSQL_TYPE_GEOMETRY") )
407
408        (symbol-table "MYSQL_FIELD flags"
409          (describe not-null-flag "NOT-NULL-FLAG")
410          (describe pri-key-flag "PRI-KEY-FLAG")
411          (describe unique-key-flag "UNIQUE-KEY-FLAG")
412          (describe multiple-key-flag "MULTIPLE-KEY-FLAG")
413          (describe unsigned-flag "UNSIGNED-FLAG")
414          (describe zerofill-flag "ZEROFILL-FLAG")
415          (describe binary-flag "BINARY-FLAG")
416          (describe auto-increment-flag "AUTO-INCREMENT-FLAG")
417          (describe no-default-value-flag "NO-DEFAULT-VALUE-FLAG") )
418      )
419    ) ; documentation
420
421    (examples
422      (p
423        "A bulky usage might look like:"
424        (pre ,ex1-text) )
425      (p
426        "A slightly more compact version that does the same thing:"
427        (pre ,ex2-text) )
428    ) ; examples
429
430    (section "Data Type Conversion"
431      (p
432        "All MySQL result data (except NULL) are returned as Scheme strings. "
433        "The NULL value is represented by " (tt "#f") ". Booleans are expressed "
434        "as Scheme strings " (tt "\"1\"") " and " (tt "\"0\"") ". All remaining "
435        "types, including numeric types and strings are returned as Scheme "
436        "strings.")
437    ) ; section "Data Type Conversion"
438
439    (section "Bugs"
440      (p
441        "This is alpha quality software. Only very basic functionality "
442        "has been tested so far. I look forward to providing a more complete "
443        "test suite (and probably a slew of bugfixes) with the next release.")
444      (p
445        (tt "mysql-escape-string") " is broken when it's used for binary data.")
446      (p
447        "I need to nail down the supported libmysqlclient versions. Right "
448        "now there are some functions I've put off because they may or may "
449        "not be supported in my target range. We'll see, soon...")
450    ) ; section "Bugs"
451
452    (license ,license-text)
453  ) ; eggdoc:begin
454) ) ; doc
455
456(eggdoc->html doc)
Note: See TracBrowser for help on using the repository browser.