source: project/misc-extn/trunk/misc-extn-eggdoc.scm @ 6202

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

Rmvd extra dsssl-fixup, put test of dsssl-fixup back in testbase test, works w/ hygienic macros.

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