source: project/misc-extn/tags/3.002/misc-extn-eggdoc.scm @ 5702

Last change on this file since 5702 was 5702, checked in by Kon Lovett, 14 years ago

unbound reverted to 3.0 behavior.

File size: 27.5 KB
Line 
1;;;; misc-extn-eggdoc.scm
2
3(use eggdoc)
4
5(define license #<<EOF
6"Copyright (c) 2006-2007, Kon Lovett.  All rights reserved.
7
8Permission is hereby granted, free of charge, to any person obtaining a
9copy of this software and associated documentation files (the Software),
10to deal in the Software without restriction, including without limitation
11the rights to use, copy, modify, merge, publish, distribute, sublicense,
12and/or sell copies of the Software, and to permit persons to whom the
13Software is furnished to do so, subject to the following conditions:
14
15The above copyright notice and this permission notice shall be included
16in all copies or substantial portions of the Software.
17
18THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
21THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
22OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
23ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
24OTHER DEALINGS IN THE SOFTWARE.
25EOF
26)
27
28(define examples '((pre #<<EOF
29(use misc-extn-control)
30
31(hash-let ([name (foo "wow")] some-hashtable)
32  (print name " " foo #\newline))
33
34(stiff-set! x 1 y 2)  ; x = 1 y = 2
35(fluid-set! x y y x)  ; x = 2 y = 1
36(swap-set! x y)       ; x = 1 y = 2
37
38; Silly example
39(typecase* (foo bar)
40  [(procedure macro) #f]
41  [symbol #t]
42  [(vector list) #f]
43  [else
44    (error "not what I want" it)])
45EOF
46)))
47
48(define doc `(
49  (eggdoc:begin
50    (name "misc-extn")
51    (description (p "Provides miscellaneous useful stuff."))
52    (author (url "mailto:klovett@pacbell.net" "Kon Lovett"))
53    (history
54      (version "3.002" "Reverted to 3.0 behavior for unbound Wasn't a bug.")
55      (version "3.001" "Bugfix for unbound")
56      (version "3.0" "Split into macro/procedure files, file renames. Incompatible!")
57      (version "2.9.3" "Added priority, termios, and winsize for Solaris. Patch for pty header file on BSD. [From Peter Bex]")
58      (version "2.9.2" "Deprecated chain-implicit-exit-handler - use library unit 'on-exit'. Replace which-command-directory with which-command-pathname. Removed make-program-pathname. Added ensure-list, file-exists/directory?, find-file-pathnames, find-program-pathnames")
59      (version "2.9.1" "Added create-directory/parents, make-program-filename, make-program-pathname. Removed pseudo-tty for Solaris.")
60      (version "2.9" "Added 'typecase' macro, pseudo-tty procedures.")
61      (version "2.8" "Removed 'define-structure'. Added srfi-12 api macros.")
62      (version "2.7" "Split -procs into -list, -sym, -control, -io, with -procs an umbrella. Added -srfi-12.")
63      (version "2.62" "Added which-command-directory.")
64      (version "2.61" "Added set!/op, removed set-op!, fix for shift!/set, errorf.")
65      (version "2.6" "Added priority routines to posix extension.")
66      (version "2.5" "Removed defined-symbol? & make-log-function, added alist-delete*, shift!/set, unzip-alist")
67      (version "2.4" "Bug fix for defined-symbol?")
68      (version "2.3" "Added undefined & unbound stuff")
69      (version "2.2" "Added 'chain-implicit-exit-handler'")
70      (version "2.1" "Added 'whennot', 'inc', 'dec','create-pathname-directory'")
71      (version "2.0" "Added 'define-inline-unchecked-record-type'")
72      (version "1.9" "Rename ++f* -> f*++, remove mu & nu; me stupid")
73      (version "1.8" "Moved procedures to own extension")
74      (version "1.7" "Exports, additions")
75      (version "1.6" "More stuff, rename fp++, etc -> ++fp")
76      (version "1.5" "Added alist-delete-first")
77      (version "1.4" "Added mu, nu, moved looping constructs to miscmacros")
78      (version "1.3" "Removed use of define-syntax")
79      (version "1.2" "Added assure, nl, rename set*! to stiff-set!, fp++, etc.")
80      (version "1.1" "Added plain repeat, assoc macros signal errors")
81      (version "1.0" "Initial release"))
82
83    (download "misc-extn.egg")
84
85    (documentation
86
87      (subsection "Record Types"
88
89        (usage "(require-extension misc-extn-record)")
90
91        (macro "(define-unchecked-record-type T CTOR PRED [SLOT ...])"
92          (p "SRFI-9 '(define-record-type T CTOR PRED [SLOT ...])', "
93          "except no checks are made for correct record type before slot "
94          "access, and the record type symbol is not defined.")
95
96          (p "For use when slot access is attempted " (i "only") " after "
97          "determining the correct record type explicitly. Do " (i "not") " "
98          "make constructed slot access procedures part of a public "
99          "API."))
100
101        (macro "(define-inline-unchecked-record-type T CTOR PRED [SLOT ...])"
102          (p "SRFI-9 '(define-record-type T CTOR PRED [SLOT ...])', "
103          "except no checks are made for correct record type before slot "
104          "access, the record type symbol is not defined, and  "
105          "procedures are inline.")
106
107          (p "For use when slot access is attempted " (i "only") " after "
108          "determining the correct record type explicitly."))
109      )
110
111      (subsection "Control Forms"
112
113        (usage "(require-extension misc-extn-control)")
114
115        (macro "(typecase EXPRESSION [(TYPE-TEST BODY ...) ...])"
116          (p "Expands into a " (code "cond") " form where every case test is a "
117          "type test.")
118
119          (p "A " (tt "TYPE-TEST") " is either a symbol, which must "
120          "be the base symbol of a type predicate, a non-null list, which must "
121          "be a list of the base symbols of type predicates, or the symbol "
122          (code "else") ". An example of a base symbol of a type predicate is "
123          (code "symbol") " and the procedure " (code "(symbol? OBJECT)") " "
124          "is used for the test.")
125
126          (p "The " (tt "BODY") " is not processed. It must be legal as the "
127          "body of a " (code "cond") " case.") )
128
129        (macro "(typecase* EXPRESSION [(TYPE-TEST BODY ...) ...])"
130          (p "Like " (code "typecase") " but binds local variable " (code "it") " "
131          "to the value of " (tt "EXPRESSION") ".") )
132
133        (macro "(whennot CONDITION [BODY ...])"
134          (p "Same as " (code "(unless CONDITION [BODY ...])") "."))
135
136        (macro "(swap-set! VAR1 VAR2)"
137          (p "Swap settings of " (tt "VAR1") " & " (tt "VAR2") "."))
138
139        (macro "(fluid-set! VAR VAL ...)"
140          (p "Set each variable " (tt "VAR") " to the value "
141          (tt "VAL") " in parallel."))
142
143        (macro "(stiff-set! VAR VAL ...)"
144          (p "Set each variable " (tt "VAR") " to the value "
145          (tt "VAL") " in series."))
146
147        (macro "(hash-let (([VAR | (VAR KEY)] ...) HASH-TABLE) BODY ...)"
148          (p "Decompose " (tt "HASH-TABLE") " entries into variable "
149          "bindings. Should the " (tt "KEY") " not be symbol, or the "
150          "desired variable name " (tt "VAR") " should not be the key, "
151          "the '(VAR KEY)' form can be used. The " (tt "BODY ...") " is "
152          "evaluated with the specified bindings."))
153
154        (macro "(set!/op VAR OP ARG ...)"
155          (p "Sets " (tt "VAR") " to the value of " (code "(OP ARG ...)") ", where "
156          "the first occurrence of " (code "<>") " in " (tt "ARG ...") " is "
157          "replaced with " (tt "VAR") ". When there is no occurrence of " (code "<>") " in " (tt "ARG ...")
158          "the template " (tt "(OP <> ARG ...)") " is used.") )
159
160        (procedure "(assure EXPRESSION [ERROR-ARGUMENT ...])"
161          (p "When " (tt "EXPRESSION") " yields " (code "#f") " invoke "
162          (code "(error ERROR-ARGUMENT ...)") ", otherwise return value."))
163
164        (procedure "(identify-error [CALLER] MSG ARGS ...)"
165          (p "Prints a message like " (tt "(error ...)") " to "
166          (tt "(current-error-port)") " but does not throw an exception."))
167
168        (procedure "(errorf [ID] [FORMAT-STRING ARGS ...])"
169          (p "Same as '(error [ID] (sprintf FORMAT-STRING ARGS ...))'.")
170
171          (p "The actual argument for the returned procedure is to be a "
172          "procedure which will be applied with the evaluated expressions "
173          "as the actual argument list."))
174      )
175
176      (subsection "Lists"
177
178        (usage "(require-extension misc-extn-list)")
179
180        (p "The length test macros terminate early when the test is satisfied; i.e they do not "
181        "use " (code "length") ".")
182
183        (macro "(length=0? LIST)"
184          (p "List of length zero?"))
185
186        (macro "(length=1? LIST)"
187          (p "List of length one?"))
188
189        (macro "(length=2? LIST)"
190          (p "List of length two?"))
191
192        (macro "(length>1? LIST)"
193          (p "List of length greater than one?"))
194
195        (macro "(shift!/set SYM [DEFAULT])"
196          (p "Like " (code "shift!") " in the utils unit but assigns the "
197          "variable " (tt "SYM") " the " (code "'()") " after shifting from a "
198          "list of length 1."))
199
200        (p "Error signaling versions of the standard association lookup functions. "
201        "When the " (tt "KEY") " is not found and a " (tt "DEFAULT") " is not supplied an "
202        (code "error") " is invoked.")
203
204        (macro "(assoc-def KEY ALIST [TEST] [DEFAULT])"
205          (p "The assoc procedure with an optional test and default "
206          "value."))
207
208        (macro "(assv-def KEY ALIST [DEFAULT])"
209          (p "The assv procedure with a default value."))
210
211        (macro "(assq-def KEY ALIST [DEFAULT])"
212          (p "The assq procedure with a default value."))
213
214        (procedure "(ensure-list OBJECT)"
215          (p "Returns a list, either the list " (tt "OBJECT") " or "
216          (code "(list OBJECT)") ".") )
217
218        (procedure "(not-null? LIST)"
219          (p "Returns " (code "#f") " if the given " (tt "LIST") " is empty, and "
220          (tt "LIST") " otherwise."))
221
222        (procedure "(filter-rest-argument! REST-LIST [PREDICATE | LIST-OF-KEYWORD])"
223          (p "Destructively remove any keywords & keyword+value items from a "
224          (code "#!rest") " argument list.")
225
226          (p "When the optional predicate is supplied it must return "
227          (code "#t") " or " (code "#f") " indicating whether the item "
228          "is to kept or removed. The predicate takes the current item.")
229
230          (p "When the optional keyword list is supplied only keywords & "
231          "keyword+value items from the list are removed."))
232
233        (procedure "(alist-inverse-ref VALUE ALIST [EQUALITY? eqv?] [DEFAULT #f])"
234          (p "Returns the first key associated with " (tt "VALUE") " in "
235          "the " (tt "ALIST") " using the " (tt "EQUALITY?") " predicate, "
236          "else " (tt "DEFAULT") "."))
237
238        (procedure "(alist-delete* KEY ALIST [COUNT [EQUALITY?]])"
239          (p "Deletes the first (tt "COUNT") associations from alist "
240          (tt "ALIST") "with the given key " (tt "KEY") ", using key-comparison "
241          "procedure " (tt "EQUALITY?") ". The dynamic order in which the "
242          "various applications of equality are made is from the alist "
243          "head to the tail.")
244
245          (p "Returns a new alist. The alist is not disordered - elements that appear "
246          "in the result alist occur in the same order as they occur in "
247          "the argument alist.")
248
249          (p "The equality procedure is used to compare the element "
250          "keys, 'key[i: 0 <= i < (length ALIST)]', of the alist's "
251          "entries to the key parameter in this way: '(EQUALITY? KEY "
252          "key[i])'.")
253
254          (p (tt "COUNT") " defaults to essentially, infinity, and " (tt "EQUALITY?")
255          " defaults to " (code "equal?") ".") )
256
257        (procedure "(alist-delete-first KEY ALIST [EQUALITY?])"
258          (p "Returns " (code "(alist-delete* KEY ALIST 1 [EQUALITY?])") ".") )
259
260        (procedure "(unzip-alist ALIST)"
261          (p "Returns 2 values, a list of the keys & a list of the values from
262          the " (tt "ALIST") ".") )
263      )
264
265      (subsection "Arithmetic"
266
267        (usage "(require-extension misc-extn-numeric)")
268
269        (macro "(inc VAL)"
270          (p "Read-only increment."))
271
272        (macro "(dec VAL)"
273          (p "Read-only decrement."))
274
275        (macro "(++ VAL)"
276          (p "Read-only increment."))
277
278        (macro "(-- VAL)"
279          (p "Read-only decrement."))
280
281        (macro "(fx++ VAL)"
282          (p "Read-only fixnum increment."))
283
284        (macro "(fx-- VAL)"
285          (p "Read-only fixnum decrement."))
286
287        (macro "(fp++ VAL)"
288          (p "Read-only flonum increment."))
289
290        (macro "(fp-- VAL)"
291          (p "Read-only flonum decrement."))
292
293        (macro "(++! VAR)"
294          (p "Mutable increment."))
295
296        (macro "(--! VAR)"
297          (p "Mutable decrement."))
298
299        (macro "(fx++! VAR)"
300          (p "Mutable fixnum increment."))
301
302        (macro "(fx--! VAR)"
303          (p "Mutable fixnum decrement."))
304
305        (macro "(fp++! VAR)"
306          (p "Mutable flonum increment."))
307
308        (macro "(fp--! VAR)"
309          (p "Mutable flonum decrement."))
310      )
311
312      (subsection "Posix"
313
314        (usage "(require-extension misc-extn-posix)")
315
316        (procedure "(replace-fileno NEW-FILENO KNOWN-FILENO)"
317          (p "Replaces the meaning of " (tt "KNOWN-FILENO") " with "
318          (tt "NEW-FILENO") ". I/O Redirection.") )
319
320        (procedure "(create-directory/parents DIRECTORY)"
321          (p "Ensures the directory pathname " (tt "DIRECTORY") " exists.")
322
323          (p "Like the UNIX `\"mkdir -p DIRECTORY\" command.") )
324
325        (procedure "(create-pathname-directory PATHNAME)"
326          (p "Ensures the directory component of " (tt "PATHNAME") " exist.")
327
328          (p "Like the UNIX `\"mkdir -p `dirname PATHNAME`\" command.") )
329
330        (procedure "(make-program-filename COMMAND)"
331          (p "Returns the platform specific form of an executable command "
332          "filename.")
333
334          (p "On Windows the " (code "exe") " extension is added unless an "
335          "extension is already present. Does nothing on other platforms.") )
336
337        (procedure "(file-exists/directory? FILENAME [DIRECTORY | DIRECTORY-LIST])"
338          (p "Returns the pathname when " (tt "FILENAME") " exists in the "
339          (tt "DIRECTORY") ", otherwise " (code "#f") ".")
340
341          (p (tt "DIRECTORY-LIST") " is as for " (code "make-pathname") ".")
342
343          (p "When only the " (tt "FILENAME") " parameter supplied then the "
344          "same as " (code "file-exists?") ".") )
345
346        (procedure "(find-file-pathnames FILENAME [DIRECTORY | DIRECTORY-LIST] ...)"
347          (p "Returns a list of all pathnames found for " (tt "FILENAME") " in "
348          "the supplied directory/directories, or " (code "#f") " when not found.")
349
350          (p "The list of pathnames is in the same relative order as that of "
351          "the directory parameter(s).") )
352
353        (procedure "(find-program-pathnames COMMAND-NAME [DIRECTORY | DIRECTORY-LIST] ...)"
354          (p "Returns a list of all pathnames found for " (tt "COMMAND-NAME") " in "
355          "the supplied directory/directories, or " (code "#f") " when not found.")
356
357          (p "Uses " (code "make-program-filename") " to make a filename.")
358
359          (p "Does not ensure that the file is executable!") )
360
361        (procedure "(which-command-pathname COMMAND-NAME [ENVIRONMENT-VARIABLE "PATH"])"
362          (p "Returns the first directory in the " (tt "ENVIRONMENT-VARIABLE") " "
363          "where a file named " (tt "COMMAND-NAME") " exists, "
364          "or " (code "#f") " when nothing found.")
365
366          (p "Uses the platform specific PATH environment variable element "
367          "separator - a semi-colon for Windows, & a colon otherwise.")
368
369          (p "Like the UNIX \"which COMMAND-NAME\" command.") )
370
371        (procedure "(remove-dotfiles FILES)"
372          (p "Remove dot files from a directory list. Useful with " (code "glob") "."))
373
374                                (subsubsection "Scheduling Priority"
375
376          (p "Parameter Descriptions")
377          (symbol-table
378            (describe priority/process
379              "Process WHICH - WHO is 0 for current process or a process identifier.")
380            (describe priority/process-group
381              "Process Group WHICH - WHO is 0 for current process group or a process group identifier.")
382            (describe priority/user
383              "User WHICH - WHO is 0 for current user or a user identifier.")
384            (describe PRIORITY
385              "An integer [-20 20].") )
386          (br)
387
388          (procedure "(scheduling-priority WHICH WHO)"
389            (p "Returns the priority of " (tt "WHO") " of kind " (tt "WHICH") ".") )
390
391          (procedure "(set-scheduling-priority! WHICH WHO PRIORITY)"
392            (p "Sets the priority of " (tt "WHO") " of kind " (tt "WHICH") " to "
393            (tt "PRIORITY") ".") )
394        )
395
396                                (subsubsection "Pseudo-TTY"
397
398          (p "Currently a thin wrapper around the C interface. Scheme bindings "
399          "for the necessary C constants are not provided.")
400
401          (procedure "(alloc-winsize)"
402            (p "Returns the pointer to a new C struct winsize.") )
403
404          (procedure "(free-winsize (nonnull-pointer WINSIZE))"
405            (p "Releases a C struct winsize.") )
406
407          (p "Accessors for a struct winsize")
408          (symbol-table
409            (describe winsize-col "Returns ws_col")
410            (describe winsize-col-set! "Sets ws_col")
411            (describe winsize-row "Returns ws_row")
412            (describe winsize-row-set! "Sets ws_row")
413            (describe winsize-xpixel "Returns ws_xpixel")
414            (describe winsize-xpixel-set! "Sets ws_xpixel")
415            (describe winsize-ypixel "Returns ws_ypixel")
416            (describe winsize-ypixel-set! "Sets ws_ypixel") )
417          (br)
418
419          (procedure "(alloc-termios)"
420            (p "Returns the pointer to a new C struct termios.") )
421
422          (procedure "(free-termios (nonnull-pointer TERMIOS))"
423            (p "Releases a C struct termios.") )
424
425          (p "Accessors for a struct termios")
426          (symbol-table
427            (describe termios-cc "Returns c_cc[idx]")
428            (describe termios-cc-set! "Sets c_cc[idx]")
429            (describe termios-cflag "Returns c_cflag")
430            (describe termios-cflag-set! "Sets c_cflag")
431            (describe termios-iflag "Returns c_iflag")
432            (describe termios-iflag-set! "Sets c_iflag")
433            (describe termios-lflag "Returns c_lflag")
434            (describe termios-lflag-set! "Sets c_lflag")
435            (describe termios-oflag "Returns c_oflag")
436            (describe termios-oflag-set! "Sets c_oflag")
437            (describe termios-ispeed "Returns c_ispeed")
438            (describe termios-ispeed-set! "Sets c_ispeed")
439            (describe termios-ospeed "Returns c_ospeed")
440            (describe termios-ospeed-set! "Sets c_ospeed") )
441          (br)
442
443          (procedure "(login-tty SLAVE-FILENO)"
444            (p "The C procedure.") )
445
446          (procedure "(open-pty (nonnull-pointer MASTER-FILENO) (nonnull-pointer SLAVE-FILENO) (c-string NAME) (pointer WINSIZE) (pointer TERMIOS))"
447            (p "The C procedure.") )
448        )
449      )
450
451      (subsection "Symbol"
452
453        (usage "(require-extension misc-extn-symbol)")
454
455        (macro "(unbound-value)"
456          (p "Returns the value representing \"unbound\".") )
457
458        (macro "(unbound-value? OBJECT)"
459          (p "Is the " (tt "OBJECT") " the unbound value?") )
460
461        (macro "(unbound? SYMBOL)"
462          (p "Is the " (tt "SYMBOL") " unbound?")
463
464          (p (tt "SYMBOL") " is " (b "not") " treated as a literal, be "
465          "sure to quote if a literal desired.") )
466
467        (macro "(symbol-value SYMBOL [DEFAULT #f])"
468          (p "Returns the " (tt "SYMBOL") " binding when bound, "
469          "otherwise the " (tt "DEFAULT") ".") 
470
471          (p (tt "SYMBOL") " is " (b "not") " treated as a literal, be "
472          "sure to quote if a literal desired.") )
473
474        (macro "(undefined-value)"
475          (p "Returns the value representing \"undefined\".") )
476
477        (macro "(undefined-value? OBJECT)"
478          (p "Is the " (tt "OBJECT") " the undefined value?") )
479
480        (macro "(undefined? OBJECT)"
481          (p "Is the " (tt "OBJECT") " the undefined value?") )
482
483        (procedure "(make-qualified-symbol NAMESPACE SYMBOL)"
484          (p "Returns the Chicken namespace qualified " (tt "SYMBOL") " for the "
485          (tt "NAMESPACE") ".")
486
487          (p "An exception is generated when the " (tt "NAMESPACE") " "
488          "length exceeds the system limit.") )
489
490        (procedure "(make-qualified-uninterned-symbol NAMESPACE SYMBOL)"
491          (p "Returns the Chicken namespace qualified " (tt "SYMBOL") " for the "
492          (tt "NAMESPACE") ".") )
493
494        (procedure "(qualified-symbol? SYMBOL)"
495          (p "Is the " (tt "SYMBOL") " a Chicken namespace qualified symbol."))
496
497        (procedure "(symbol->qualified-string SYMBOL)"
498          (p "Returns the printname of a Chicken namespace qualified " (tt "SYMBOL") "."))
499
500        (procedure "(interned-symbol? SYMBOL)"
501          (p "Is the " (tt "SYMBOL") " interned?"))
502      )
503
504      (subsection "Conditions"
505
506        (usage "(require-extension misc-extn-condition)")
507
508        (p "The build condition API macros are currently " (b "unavailable") " when using "
509        (b "hygienic") " macros.")
510
511        (macro "(build-condition-naming-API FORM ...)"
512          (p "Expands into one or more macros that expand into a condition specification "
513          "form, suitable for use with " (code "build-property-condition-API") " and "
514          (code "build-composite-condition-API") ".")
515
516          (p "Example: "
517          (code "(build-condition-naming (exn location message arguments) foo (bar rope))"))
518
519          (p "Creates the following:")
520
521          (ul
522            (li (code "(define-macro (exn-condition) '(exn location message arguments))") )
523            (li (code "(define-macro (foo-condition) 'foo)") )
524            (li (code "(define-macro (bar-condition) '(bar rope))") ) ) )
525
526        (macro "(build-property-condition-API FORM ...)"
527          (p "Expands into a suite of procedures to construct and test SRFI-12 property "
528          "condition objects.")
529
530          (p "When only one " (tt "FORM") " is supplied a single property condition API is "
531          "built. When more than one " (tt "FORM") " are supplied then all the property "
532          "condition APIs are built.")
533
534          (p "When " (tt "FORM") " is a symbol it is a condition " (tt "KIND-KEY") " and "
535          "identifies a condition without properties. When " (tt "FORM") " is a list the first "
536          "element is the condition " (tt "KIND-KEY") " and the following elements are property "
537          "keys.")
538
539          (p "A condition constructor is named as " (tt "make-KIND-KEY-condition") " "
540          "and has 0 or more formal parameters, which are the property keys.")
541
542          (p "A condition predicate is named as " (tt "KIND-KEY-condition?") " "
543          "and has 1 formal parameter, the object to test.")
544
545          (p "Property condition constructors without properties always return the same "
546          "condition object!")
547
548          (p "Example: "
549          (code "(build-property-condition-API (exn location message arguments) foo (bar rope))"))
550
551          (p "Creates the following:")
552
553          (ul
554            (li (code "(make-exn-condition location message arguments)"))
555            (li (code "(exn-condition? object)") )
556            (li (code "(make-foo-condition)") )
557            (li (code "(foo-condition? object)") )
558            (li (code "(make-bar-condition rope)") )
559            (li (code "(bar-condition? object)") ) ) )
560
561        (macro "(build-composite-condition-API FORM ...)"
562          (p "Expands into a suite of procedures to construct and test SRFI-12 a composite "
563          "condition object.")
564
565          (p (tt "FORM") " is the same as " (tt "FORM") " in the "
566          (code "build-property-condition-API") " definition.")
567
568          (p "When zero or one " (tt "FORM") " are supplied nothing is built. When more than "
569          "one " (tt "FORM") " are supplied then a composite API is built.")
570
571          (p "A composite condition constructor is like a property condition constructor, "
572           "except that the " (tt "KIND-KEY") " is a concatenation of every condition "
573           (tt "KEY") ", interspersed with a hyphen.")
574
575          (p "A composite condition predicate is like a property condition predicate, "
576           "except that the " (tt "KIND-KEY") " is a concatenation of every condition "
577           (tt "KEY") ", interspersed with a hyphen.")
578
579          (p "Example: "
580          (code "(build-composite-condition-API (exn location message arguments) foo (bar rope))"))
581
582          (p "Creates the following:")
583
584          (ul
585            (li (code "(make-exn-foo-bar-condition location message arguments rope)") )
586            (li (code "(exn-foo-bar-condition? object)") ) ) )
587
588        (procedure "(handle-condition THUNK [HANDLER identity])"
589          (p "Simplified " (code "with-exception-handler") " where the "
590          (tt "HANDLER") " result is always returned to the caller.")
591
592          (p (tt "HANDLER") " is (-> condition object).") )
593
594        (procedure "(composite-condition? OBJECT [KIND-KEY ...])"
595          (p "Is the " (tt "OBJECT") " a SRFI-12 composite condition?")
596
597          (p "When one or more " (tt "KIND-KEY") " are supplied then the composite condition "
598          "must compose at least those kind keys.") )
599
600        (procedure "(condition-kind-keys CONDITION)"
601          (p "Returns a list of the kind-keys of the SRFI-12 "
602          (tt "CONDITION") ".") )
603
604        (procedure "(condition-property-keys CONDITION [KIND-KEY])"
605          (p "Returns a list of the property-keys for " (tt "KIND-KEY") " "
606          "of the SRFI-12 " (tt "CONDITION") ", or " (code "#f") " when no "
607          "property keys or the " (tt "CONDITION") " is not of the kind "
608          (tt "KIND-KEY") ".")
609
610          (p "When " (tt "KIND-KEY") " is missing some kind-key of the "
611          (tt "CONDITION") " is used.") )
612
613        (procedure "(condition-properties CONDITION [KIND-KEY])"
614          (p "Returns an association list of the property keys & values "
615          "for " (tt "KIND-KEY") " of the SRFI-12 " (tt "CONDITION")
616          ", or " (code "#f") " when no " "property keys or the "
617          (tt "CONDITION") " is not of the kind " (tt "KIND-KEY") ".")
618
619          (p "When " (tt "KIND-KEY") " is missing some kind-key of the "
620          (tt "CONDITION") " is used.") )
621
622        (procedure "(condition-explode CONDITION)"
623          (p "Returns an association list of every kind-key of the "
624          "SRFI-12 " (tt "CONDITION") ". The value of each entry is the "
625          "result of " (code "(condition-properties CONDITION KIND-KEY") " "
626          "for that " (tt "KIND-KEY") ".") )
627
628        (procedure "(make-property-condition/list KIND-LIST PROPERTY-LIST)"
629          (p "Returns a new condition.")
630
631          (p (tt "KIND-LIST") " is a list of kind-key.")
632
633          (p (tt "PROPERTY-LIST") " is a property list, where the key "
634          "element is a pair, (<kind-key> . <property-key>).") )
635      )
636
637      (subsection "Input/Output"
638
639        (usage "(require-extension misc-extn-io)")
640
641        (procedure "(cout EXPR ...)"
642          (p "Like cout << arguments << args where argument can be any "
643          "Scheme object. If it's a procedure (without args) it's "
644          "executed rather than printed (like newline)."))
645
646        (procedure "(cerr EXPR ...)"
647          (p "Like cerr << arguments << args where argument can be any "
648          "Scheme object. If it's a procedure (without args) it's "
649          "executed rather than printed (like newline)."))
650
651        (constant "nl"
652          (p "String form of the newline character."))
653      )
654     )
655
656    (section "Contributions"
657
658      (p "William Annis - hash-let.")
659
660      (p "Oleg Kiselyov's Standard Scheme \"Prelude\" - ++, ...")
661    )
662
663    (examples ,examples)
664
665    (section "License" (pre ,license))
666  )
667))
668
669(eggdoc->html doc
670  `(,@(eggdoc:make-stylesheet doc)
671    (constant *macro* . ,eggdoc:make-defsig)))
Note: See TracBrowser for help on using the repository browser.