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

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

Rel 3.1, adds -directory stuff.

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