source: project/release/3/misc-extn/trunk/misc-extn-eggdoc.scm @ 11839

Last change on this file since 11839 was 11839, checked in by Kon Lovett, 13 years ago

Needed Unit files.

File size: 31.3 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 "Directories"
340
341        (usage "(require-extension misc-extn-directory)")
342
343        (procedure "(push-directory DIRECTORY)"
344          (p "Push the current directory and change to the " (tt "DIRECTORY") ".") )
345
346        (procedure "(pop-directory)"
347          (p "Pop the last directory and change to it.") )
348
349        (procedure "(pop-toplevel-directory)"
350          (p "Pop the earliest directory and change to it.") )
351
352        (procedure "(create-directory/parents DIRECTORY)"
353          (p "Ensures the directory pathname " (tt "DIRECTORY") " exists.")
354
355          (p "Like the *NIX `\"mkdir -p DIRECTORY\" command.") )
356
357        (procedure "(create-pathname-directory PATHNAME)"
358          (p "Ensures the directory component of " (tt "PATHNAME") " exist.")
359
360          (p "Like the *NIX `\"mkdir -p `dirname PATHNAME`\" command.") )
361
362        (procedure "(make-program-filename COMMAND)"
363          (p "Returns the platform specific form of an executable command "
364          "filename.")
365
366          (p "On Windows the " (code "exe") " extension is added unless an "
367          "extension is already present. Does nothing on other platforms.") )
368
369        (procedure "(make-shell-filename COMMAND)"
370          (p "Returns the platform specific form of a shell command "
371          "filename.")
372
373          (p "On Windows the " (code "bat") " extension is added unless an "
374          "extension is already present. On *NIX platforms adds " (code ".sh") ".") )
375
376        (procedure "(file-exists/directory? FILENAME [DIRECTORY | DIRECTORY-LIST])"
377          (p "Returns the pathname when " (tt "FILENAME") " exists in the "
378          (tt "DIRECTORY") ", otherwise " (code "#f") ".")
379
380          (p (tt "DIRECTORY-LIST") " is as for " (code "make-pathname") ".")
381
382          (p "When only the " (tt "FILENAME") " parameter supplied then the "
383          "same as " (code "file-exists?") ".") )
384
385        (procedure "(find-file-pathnames FILENAME [DIRECTORY | DIRECTORY-LIST] ...)"
386          (p "Returns a list of all pathnames found for " (tt "FILENAME") " in "
387          "the supplied directory/directories, or " (code "#f") " when not found.")
388
389          (p "The list of pathnames is in the same relative order as that of "
390          "the directory parameter(s).") )
391
392        (procedure "(find-program-pathnames COMMAND-NAME [DIRECTORY | DIRECTORY-LIST] ...)"
393          (p "Returns a list of all pathnames found for " (tt "COMMAND-NAME") " in "
394          "the supplied directory/directories, or " (code "#f") " when not found.")
395
396          (p "Uses " (code "make-program-filename") " to make a filename.")
397
398          (p "On Windows also uses " (code "make-shell-filename") " to make a filename.")
399
400          (p "Does not ensure that the file is executable!") )
401
402        (procedure "(which-command-pathnames COMMAND-NAME [ENVIRONMENT-VARIABLE])"
403          (p "Returns the pathnames of " (tt "COMMAND-NAME") " in the " (tt
404          "ENVIRONMENT-VARIABLE") " where the file exists, or " (code "#f") " "
405          "when nothing found.")
406
407          (p "The default " (tt "ENVIRONMENT-VARIABLE") " is " (code "\"PATH\"") ".")
408
409          (p "Uses the platform specific \"PATH\" environment variable element "
410          "separator - a ';' for Windows, & a ':' otherwise.") )
411
412        (procedure "(which-command-pathname COMMAND-NAME [ENVIRONMENT-VARIABLE])"
413          (p "Same as " (code "which-command-pathnames") " but returns the "
414          "first pathname only.")
415
416          (p "Like the *NIX \"which COMMAND-NAME\" command.") )
417
418        (procedure "(remove-dotfiles FILES)"
419          (p "Remove dot files from a directory list. Useful with " (code "glob") "."))
420      )
421
422      (subsection "Posix"
423
424        (usage "(require-extension misc-extn-posix)")
425
426                                (subsubsection "File Descriptors"
427
428          (procedure "(replace-fileno NEW-FILENO KNOWN-FILENO)"
429            (p "Replaces the meaning of " (tt "KNOWN-FILENO") " with "
430            (tt "NEW-FILENO") ". I/O Redirection.") )
431        )
432
433                                (subsubsection "Scheduling Priority"
434
435          (p "Parameter Descriptions")
436          (symbol-table
437            (describe priority/process
438              "Process WHICH - WHO is 0 for current process or a process identifier.")
439            (describe priority/process-group
440              "Process Group WHICH - WHO is 0 for current process group or a process group identifier.")
441            (describe priority/user
442              "User WHICH - WHO is 0 for current user or a user identifier.")
443            (describe PRIORITY
444              "An integer [-20 20].") )
445          (br)
446
447          (procedure "(scheduling-priority WHICH WHO)"
448            (p "Returns the priority of " (tt "WHO") " of kind " (tt "WHICH") ".") )
449
450          (procedure "(set-scheduling-priority! WHICH WHO PRIORITY)"
451            (p "Sets the priority of " (tt "WHO") " of kind " (tt "WHICH") " to "
452            (tt "PRIORITY") ".") )
453        )
454
455                                (subsubsection "Pseudo-TTY"
456
457          (p "Currently a thin wrapper around the C interface. Scheme bindings "
458          "for the necessary C constants are not provided.")
459
460          (procedure "(alloc-winsize)"
461            (p "Returns the pointer to a new C struct winsize.") )
462
463          (procedure "(free-winsize (nonnull-pointer WINSIZE))"
464            (p "Releases a C struct winsize.") )
465
466          (p "Accessors for a struct winsize")
467          (symbol-table
468            (describe winsize-col "Returns ws_col")
469            (describe winsize-col-set! "Sets ws_col")
470            (describe winsize-row "Returns ws_row")
471            (describe winsize-row-set! "Sets ws_row")
472            (describe winsize-xpixel "Returns ws_xpixel")
473            (describe winsize-xpixel-set! "Sets ws_xpixel")
474            (describe winsize-ypixel "Returns ws_ypixel")
475            (describe winsize-ypixel-set! "Sets ws_ypixel") )
476          (br)
477
478          (procedure "(alloc-termios)"
479            (p "Returns the pointer to a new C struct termios.") )
480
481          (procedure "(free-termios (nonnull-pointer TERMIOS))"
482            (p "Releases a C struct termios.") )
483
484          (p "Accessors for a struct termios")
485          (symbol-table
486            (describe termios-cc "Returns c_cc[idx]")
487            (describe termios-cc-set! "Sets c_cc[idx]")
488            (describe termios-cflag "Returns c_cflag")
489            (describe termios-cflag-set! "Sets c_cflag")
490            (describe termios-iflag "Returns c_iflag")
491            (describe termios-iflag-set! "Sets c_iflag")
492            (describe termios-lflag "Returns c_lflag")
493            (describe termios-lflag-set! "Sets c_lflag")
494            (describe termios-oflag "Returns c_oflag")
495            (describe termios-oflag-set! "Sets c_oflag")
496            (describe termios-ispeed "Returns c_ispeed")
497            (describe termios-ispeed-set! "Sets c_ispeed")
498            (describe termios-ospeed "Returns c_ospeed")
499            (describe termios-ospeed-set! "Sets c_ospeed") )
500          (br)
501
502          (procedure "(login-tty SLAVE-FILENO)"
503            (p "The C procedure.") )
504
505          (procedure "(open-pty (nonnull-pointer MASTER-FILENO) (nonnull-pointer SLAVE-FILENO) (c-string NAME) (pointer WINSIZE) (pointer TERMIOS))"
506            (p "The C procedure.") )
507        )
508      )
509
510      (subsection "Symbol"
511
512        (usage "(require-extension misc-extn-symbol)")
513
514        (macro "(unbound-value)"
515          (p "Returns the value representing \"unbound\".") )
516
517        (macro "(unbound-value? OBJECT)"
518          (p "Is the " (tt "OBJECT") " the unbound value?") )
519
520        (macro "(unbound? SYMBOL)"
521          (p "Is the " (tt "SYMBOL") " unbound?")
522
523          (p (tt "SYMBOL") " is " (b "not") " treated as a literal, be "
524          "sure to quote if a literal desired.") )
525
526        (macro "(symbol-value SYMBOL [NOT-FOUND #f])"
527          (p "Returns the " (tt "SYMBOL") " binding when bound, "
528          "otherwise the " (tt "NOT-FOUND") ".")
529
530          (p (tt "SYMBOL") " is " (b "not") " treated as a literal, be "
531          "sure to quote if a literal desired.") )
532
533        (macro "(undefined-value)"
534          (p "Returns the value representing \"undefined\".") )
535
536        (macro "(undefined-value? OBJECT)"
537          (p "Is the " (tt "OBJECT") " the undefined value?") )
538
539        (macro "(undefined? OBJECT)"
540          (p "Is the " (tt "OBJECT") " the undefined value?") )
541
542        (procedure "(make-qualified-symbol NAMESPACE SYMBOL)"
543          (p "Returns the Chicken namespace qualified " (tt "SYMBOL") " for the "
544          (tt "NAMESPACE") ".")
545
546          (p "An exception is generated when the " (tt "NAMESPACE") " "
547          "length exceeds the system limit.") )
548
549        (procedure "(make-qualified-uninterned-symbol NAMESPACE SYMBOL)"
550          (p "Returns the Chicken namespace qualified " (tt "SYMBOL") " for the "
551          (tt "NAMESPACE") ".") )
552
553        (procedure "(qualified-symbol? SYMBOL)"
554          (p "Is the " (tt "SYMBOL") " a Chicken namespace qualified symbol."))
555
556        (procedure "(symbol->qualified-string SYMBOL)"
557          (p "Returns the printname of a Chicken namespace qualified " (tt "SYMBOL") "."))
558
559        (procedure "(interned-symbol? SYMBOL)"
560          (p "Is the " (tt "SYMBOL") " interned?"))
561      )
562
563      (subsection "Conditions"
564
565        (usage "(require-extension misc-extn-condition)")
566
567        (p "The build condition API macros are currently " (b "unavailable") " when using "
568        (b "hygienic") " macros.")
569
570        (macro "(build-condition-naming-api FORM ...)"
571          (p "Expands into one or more macros that expand into a condition specification "
572          "form, suitable for use with " (code "build-property-condition-api") " and "
573          (code "build-composite-condition-api") ".")
574
575          (p "Example: "
576          (code "(build-condition-naming (exn location message arguments) foo (bar rope))"))
577
578          (p "Creates the following:")
579
580          (ul
581            (li (code "(define-macro (exn-condition) '(exn location message arguments))") )
582            (li (code "(define-macro (foo-condition) 'foo)") )
583            (li (code "(define-macro (bar-condition) '(bar rope))") ) ) )
584
585        (macro "(build-property-condition-api FORM ...)"
586          (p "Expands into a suite of procedures to construct and test SRFI-12 property "
587          "condition objects.")
588
589          (p "When only one " (tt "FORM") " is supplied a single property condition API is "
590          "built. When more than one " (tt "FORM") " are supplied then all the property "
591          "condition APIs are built.")
592
593          (p "When " (tt "FORM") " is a symbol it is a condition " (tt "KIND-KEY") " and "
594          "identifies a condition without properties. When " (tt "FORM") " is a list the first "
595          "element is the condition " (tt "KIND-KEY") " and the following elements are property "
596          "keys.")
597
598          (p "A condition constructor is named as " (tt "make-KIND-KEY-condition") " "
599          "and has 0 or more formal parameters, which are the property keys.")
600
601          (p "A condition predicate is named as " (tt "KIND-KEY-condition?") " "
602          "and has 1 formal parameter, the object to test.")
603
604          (p "Property condition constructors without properties always return the same "
605          "condition object!")
606
607          (p "Example: "
608          (code "(build-property-condition-api (exn location message arguments) foo (bar rope))"))
609
610          (p "Creates the following:")
611
612          (ul
613            (li (code "(make-exn-condition location message arguments)"))
614            (li (code "(exn-condition? object)") )
615            (li (code "(make-foo-condition)") )
616            (li (code "(foo-condition? object)") )
617            (li (code "(make-bar-condition rope)") )
618            (li (code "(bar-condition? object)") ) ) )
619
620        (macro "(build-composite-condition-api FORM ...)"
621          (p "Expands into a suite of procedures to construct and test SRFI-12 a composite "
622          "condition object.")
623
624          (p (tt "FORM") " is the same as " (tt "FORM") " in the "
625          (code "build-property-condition-api") " definition.")
626
627          (p "When zero or one " (tt "FORM") " are supplied nothing is built. When more than "
628          "one " (tt "FORM") " are supplied then a composite API is built.")
629
630          (p "A composite condition constructor is like a property condition constructor, "
631           "except that the " (tt "KIND-KEY") " is a concatenation of every condition "
632           (tt "KEY") ", interspersed with a hyphen.")
633
634          (p "A composite condition predicate is like a property condition predicate, "
635           "except that the " (tt "KIND-KEY") " is a concatenation of every condition "
636           (tt "KEY") ", interspersed with a hyphen.")
637
638          (p "Example: "
639          (code "(build-composite-condition-api (exn location message arguments) foo (bar rope))"))
640
641          (p "Creates the following:")
642
643          (ul
644            (li (code "(make-exn-foo-bar-condition location message arguments rope)") )
645            (li (code "(exn-foo-bar-condition? object)") ) ) )
646
647        (procedure "(handle-condition THUNK [HANDLER identity])"
648          (p "Simplified " (code "with-exception-handler") " where the "
649          (tt "HANDLER") " result is always returned to the caller.")
650
651          (p (tt "HANDLER") " is (-> condition object).") )
652
653        (procedure "(composite-condition? OBJECT [KIND-KEY ...])"
654          (p "Is the " (tt "OBJECT") " a SRFI-12 composite condition?")
655
656          (p "When one or more " (tt "KIND-KEY") " are supplied then the composite condition "
657          "must compose at least those kind keys.") )
658
659        (procedure "(condition-kind-keys CONDITION)"
660          (p "Returns a list of the kind-keys of the SRFI-12 "
661          (tt "CONDITION") ".") )
662
663        (procedure "(condition-property-keys CONDITION [KIND-KEY])"
664          (p "Returns a list of the property-keys for " (tt "KIND-KEY") " "
665          "of the SRFI-12 " (tt "CONDITION") ", or " (code "#f") " when no "
666          "property keys or the " (tt "CONDITION") " is not of the kind "
667          (tt "KIND-KEY") ".")
668
669          (p "When " (tt "KIND-KEY") " is missing some kind-key of the "
670          (tt "CONDITION") " is used.") )
671
672        (procedure "(condition-properties CONDITION [KIND-KEY])"
673          (p "Returns an association list of the property keys & values "
674          "for " (tt "KIND-KEY") " of the SRFI-12 " (tt "CONDITION")
675          ", or " (code "#f") " when no " "property keys or the "
676          (tt "CONDITION") " is not of the kind " (tt "KIND-KEY") ".")
677
678          (p "When " (tt "KIND-KEY") " is missing some kind-key of the "
679          (tt "CONDITION") " is used.") )
680
681        (procedure "(condition-explode CONDITION)"
682          (p "Returns an association list of every kind-key of the "
683          "SRFI-12 " (tt "CONDITION") ". The value of each entry is the "
684          "result of " (code "(condition-properties CONDITION KIND-KEY") " "
685          "for that " (tt "KIND-KEY") ".") )
686
687        (procedure "(make-property-condition/list KIND-LIST PROPERTY-LIST)"
688          (p "Returns a new condition.")
689
690          (p (tt "KIND-LIST") " is a list of kind-key.")
691
692          (p (tt "PROPERTY-LIST") " is a property list, where the key "
693          "element is a pair, (<kind-key> . <property-key>).") )
694      )
695
696      (subsection "Input/Output"
697
698        (usage "(require-extension misc-extn-io)")
699
700        (procedure "(cout EXPR ...)"
701          (p "Like cout << arguments << args where argument can be any "
702          "Scheme object. If it's a procedure (without args) it's "
703          "executed rather than printed (like newline)."))
704
705        (procedure "(cerr EXPR ...)"
706          (p "Like cerr << arguments << args where argument can be any "
707          "Scheme object. If it's a procedure (without args) it's "
708          "executed rather than printed (like newline)."))
709
710        (constant "nl"
711          (p "String form of the newline character."))
712      )
713     )
714
715    (section "Contributions"
716
717      (p "William Annis - hash-let.")
718
719      (p "Oleg Kiselyov's Standard Scheme \"Prelude\" - ++, ...")
720    )
721
722    (examples ,examples)
723
724    (history
725      (version "3.1.3" "Needed Unit files.")
726      (version "3.1" "Added misc-extn-directory; moved file-exists/directory, find-file-pathnames, find-program-pathnames, whch-command-pathname, remove-dotfiles from misc-extn-posix.")
727      (version "3.003" "Added list macros. Deprecated alist-delete*, filter-rest-argument!. Added misc-extn-dsssl.")
728      (version "3.002" "Reverted to 3.0 behavior for unbound Wasn't a bug.")
729      (version "3.001" "Bugfix for unbound")
730      (version "3.0" "Split into macro/procedure files, file renames. Incompatible!")
731      (version "2.9.3" "Added priority, termios, and winsize for Solaris. Patch for pty header file on BSD. [From Peter Bex]")
732      (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")
733      (version "2.9.1" "Added create-directory/parents, make-program-filename, make-program-pathname. Removed pseudo-tty for Solaris.")
734      (version "2.9" "Added 'typecase' macro, pseudo-tty procedures.")
735      (version "2.8" "Removed 'define-structure'. Added srfi-12 api macros.")
736      (version "2.7" "Split -procs into -list, -sym, -control, -io, with -procs an umbrella. Added -srfi-12.")
737      (version "2.62" "Added which-command-directory.")
738      (version "2.61" "Added set!/op, removed set-op!, fix for shift!/set, errorf.")
739      (version "2.6" "Added priority routines to posix extension.")
740      (version "2.5" "Removed defined-symbol? & make-log-function, added alist-delete*, shift!/set, unzip-alist")
741      (version "2.4" "Bug fix for defined-symbol?")
742      (version "2.3" "Added undefined & unbound stuff")
743      (version "2.2" "Added 'chain-implicit-exit-handler'")
744      (version "2.1" "Added 'whennot', 'inc', 'dec','create-pathname-directory'")
745      (version "2.0" "Added 'define-inline-unchecked-record-type'")
746      (version "1.9" "Rename ++f* -> f*++, remove mu & nu; me stupid")
747      (version "1.8" "Moved procedures to own extension")
748      (version "1.7" "Exports, additions")
749      (version "1.6" "More stuff, rename fp++, etc -> ++fp")
750      (version "1.5" "Added alist-delete-first")
751      (version "1.4" "Added mu, nu, moved looping constructs to miscmacros")
752      (version "1.3" "Removed use of define-syntax")
753      (version "1.2" "Added assure, nl, rename set*! to stiff-set!, fp++, etc.")
754      (version "1.1" "Added plain repeat, assoc macros signal errors")
755      (version "1.0" "Initial release"))
756
757    (section "License" (pre ,license))
758  )
759))
760
761(eggdoc->html doc
762  `(,@(eggdoc:make-stylesheet doc)
763    (constant *macro* . ,eggdoc:make-defsig)))
Note: See TracBrowser for help on using the repository browser.