source: project/release/3/procedure-surface/trunk/procedure-surface-eggdoc.scm @ 9816

Last change on this file since 9816 was 9816, checked in by Kon Lovett, 11 years ago

Removed syntax-case dependency. Full low-level macro support.

File size: 15.7 KB
Line 
1;;;; -*- Scheme -*-
2;;;; procedure-surface-eggdoc.scm
3
4(use eggdoc)
5
6(define license #<<EOF
7Copyright (c) 2006, Kon Lovett.  All rights reserved.
8
9Permission is hereby granted, free of charge, to any person obtaining a
10copy of this software and associated documentation files (the Software),
11to deal in the Software without restriction, including without limitation
12the rights to use, copy, modify, merge, publish, distribute, sublicense,
13and/or sell copies of the Software, and to permit persons to whom the
14Software is furnished to do so, subject to the following conditions:
15
16The above copyright notice and this permission notice shall be included
17in all copies or substantial portions of the Software.
18
19THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
23OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
24ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
25OTHER DEALINGS IN THE SOFTWARE.
26EOF
27)
28
29(define doc `(
30        (eggdoc:begin
31                (name "procedure-surface")
32                (description (p "Generic Programming Support"))
33
34                (author "Kon Lovett")
35
36                (requires
37                        (url "lookup-table.html" "lookup-table")
38                        (url "misc-extn.html" "misc-extn") )
39
40                (usage)
41                (download "procedure-surface.egg")
42
43                (documentation
44
45                        (p "Warning - procedure surface is experimental!")
46
47                        (p "The procedure-surface egg provides a facility for generic "
48                        "programming in Scheme, similar in purpose to the \"structures\" "
49                        "egg. Unlike the normal pattern of use for \"structures\" this "
50                        "facility will delay loading of any library or extension until an "
51                        "actual binding is required. The use of a 'define' form as a "
52                        "procedure reference with 'make-procedure-means' is not "
53                        "supported, unlike the analogous 'structure' from \"structures\".")
54
55                        (p "Odd names are used for parsimony. Read 'interface' for "
56                        "'surface', and 'implementation' for 'means'.")
57
58                        (subsection "Syntax Interface"
59
60                                (macro "(define-procedure-surface NAME PROC-SYM CONTRACT ... [KEY-ARG ...])"
61                                        (p "Sets the symbol " (tt "NAME") " to the described procedure "
62                                        "surface. Uses " (tt "NAME") " as the keyword argument #:name "
63                                        "for the surface. See 'make-procedure-surface' for argument "
64                                        "descriptions."))
65
66                                (macro "(declare-procedure-means NAME SURFACE PROC-SYM PROC-REF ... [KEY-ARG ...])"
67                                        (p "Sets the symbol " (tt "NAME") " to the described procedure "
68                                        "surface means. See 'make-procedure-means' for "
69                                        "argument descriptions."))
70
71                                (macro "(call-thru-procedure-means MEANS PROC-SYM [ARG ...])"
72                                        (p "Invoke the procedure identified by " (tt "PROC-SYM") " in "
73                                        "the " (tt "MEANS") " with the " (tt "ARG ...") " list."))
74
75                                (macro "(apply-thru-procedure-means MEANS PROC-SYM ARG ...)"
76                                        (p "Apply the procedure identified by " (tt "PROC-SYM") " in "
77                                        "the " (tt "MEANS") " to the " (tt "ARG ...") " list."))
78
79                                (macro "(let-procedure-means ([(PROC-SYM ...) MEANS] ...) BODY ...)"
80                                        (p "Bind the local symbol(s) " (tt "PROC-SYM ...") " to the "
81                                        "corresponding procedure(s) in the " (tt "MEANS") " and "
82                                        "evaluate the " (tt "BODY") "."))
83
84                                (macro "(call/means MEANS PROC-SYM [ARG ...])"
85                                        (p "Abbreviation of 'call-thru-procedure-means'."))
86
87                                (macro "(apply/means MEANS PROC-SYM ARG ...)"
88                                        (p "Abbreviation of 'apply-thru-procedure-means'."))
89
90                                (macro "(let/means ([(PROC-SYM ...) MEANS] ...) BODY ...)"
91                                        (p "Abbreviation of 'let-procedure-means'."))
92                        )
93
94                        (subsection "Direct Call Interface"
95
96                                (procedure "(make-procedure-signature IDENTIFIER CONTRACT)"
97                                        (p "Returns a procedure signature for " (tt "IDENTIFIER") " "
98                                        "with " (tt "CONTRACT") ".")
99
100                                        (p "The contract grammar is described below. Can be null, '(), "
101                                        "for no contract."))
102
103                                (procedure "(procedure-signature? OBJECT)"
104                                        (p "Is " (tt "OBJECT") " a procedure signature?"))
105
106                                (procedure "(procedure-signature-identifier SIGNATURE)"
107                                        (p "Returns the procedure signature identifier of the " (tt "SIGNATURE") "."))
108
109                                (procedure "(procedure-signature-contract SIGNATURE)"
110                                        (p "Returns the procedure signature contract of the " (tt "SIGNATURE") "."))
111
112                                (procedure "(make-procedure-surface PROC-SYM CONTRACT ... [#:immutable #f] [#:name #f])"
113                                        (p "Creates and returns a procedure surface. A collection of "
114                                        "procedure identifiers and contracts.")
115                                        (symbol-table
116                                                (describe #:immutable
117                                                        "A boolean. Immutable (#t) or mutable (#f).")
118                                                (describe #:name
119                                                        "A symbol or string. The name of the surface. When missing a name of the form \"ps#\" will be created.")
120                                                (describe PROC-SYM
121                                                        "A symbol. The procedure identifier.")
122                                                (describe CONTRACT
123                                                        "A list. The source form of a procedure signature. The contract grammar is described below. null, '(), for no contract.")) )
124
125                                (procedure "(procedure-surface? OBJECT)"
126                                        (p "Is the " (tt "OBJECT") " a procedure surface?"))
127
128                                (procedure "(procedure-surface-name SURFACE)"
129                                        (p "Returns the name, or names as list if composite, of the " (tt "SURFACE") "."))
130
131                                (procedure "(procedure-surface-immutable? SURFACE)"
132                                        (p "Is the " (tt "SURFACE") " immutable?"))
133
134                                (procedure "(procedure-surface-mutable? SURFACE)"
135                                        (p "Is the " (tt "SURFACE") " mutable?"))
136
137                                (procedure "(procedure-surface-ref SURFACE PROC-SYM)"
138                                        (p "Returns the procedure signature of the " (tt "SURFACE") "."))
139
140                                (procedure "(procedure-surface-set! SURFACE PROC-SYM CONTRACT ...)"
141                                        (p "Adds or updates procedure signatures in " (tt "SURFACE") "."))
142
143                                (procedure "(procedure-surface-delete! SURFACE PROC-SYM)"
144                                        (p "Removes the procedure signature for " (tt "PROC-SYM") " "
145                                        "from " (tt "SURFACE") "."))
146
147                                (procedure "(procedure-surface->alist SURFACE)"
148                                        (p "Returns a alist, (<procedure-symbol> . "
149                                        "<procedure-signature>), from " (tt "SURFACE") "."))
150
151                                (procedure "(make-composite-procedure-surface SURFACE ...)"
152                                        (p "Returns a procedure surface, the combination of "
153                                        (tt "SURFACE ...") " set. Should any surface be immutable then the "
154                                        "composite is immutable."))
155
156                                (procedure "(composite-procedure-surface? SURFACE)"
157                                        (p "Is the " (tt "SURFACE") " a composite?"))
158
159                                (procedure "(make-procedure-means SURFACE PROC-SYM PROC-REF ... [#:immutable #f] [#:extension #f] [#:library #f] [#:pathname #f])"
160                                        (p "Supply procedures for the " (tt "SURFACE") ".")
161                                        (symbol-table
162                                                (describe #:immutable
163                                                        "A boolean. Immutable (#t) or mutable (#f).")
164                                                (describe #:extension
165                                                        "A symbol or string. The name of the extension.")
166                                                (describe #:library
167                                                        "A symbol or string. The name of the library.")
168                                                (describe #:pathname
169                                                        "A string. The absolute pathname of the extension or library. Required when the extension or library is not in the Chicken repository.")
170                                                (describe PROC-SYM
171                                                        "A symbol. The procedure identifier. Must match a procedure identifier from SURFACE.")
172                                                (describe PROC-REF
173                                                        "A boolean, symbol, or procedure. The procedure alias when a symbol. When boolean use the procedure identifier as the alias. Otherwise this should be a procedure.")) )
174
175                                (procedure "(procedure-means? OBJECT)"
176                                        (p "Is the " (tt "OBJECT") " a procedure surface?"))
177
178                                (procedure "(procedure-means-immutable? MEANS)"
179                                        (p "Are the " (tt "MEANS") " immutable?"))
180
181                                (procedure "(procedure-means-mutable? MEANS)"
182                                        (p "Are the " (tt "MEANS") " mutable?"))
183
184                                (procedure "(procedure-means-alias MEANS PROC-SYM)"
185                                        (p "Returns the alias of " (tt "PROC-SYM") " in " (tt "MEANS") "."))
186
187                                (procedure "(procedure-means-ref MEANS PROC-SYM)"
188                                        (p "Returns the current binding of " (tt "PROC-SYM") " in the "
189                                        (tt "MEANS") ", which maybe the unbound value."))
190
191                                (procedure "(procedure-means-closure MEANS PROC-SYM)"
192                                        (p "Forces a load, if necessary. Returns the current binding "
193                                        "of " (tt "PROC-SYM") " in the " (tt "MEANS") ", which maybe "
194                                        "the unbound value."))
195
196                                (procedure "(procedure-means-implements MEANS)"
197                                        (p "Returns the procedure surface, or a list of procedure "
198                                        "surface when composite, that the " (tt "MEANS") " "
199                                        "implements."))
200
201                                (procedure "(procedure-means-complete? MEANS)"
202                                        (p "Are all procedures in the procedure surface(s) of the "
203                                        (tt "MEANS") " declared?"))
204
205                                (procedure "(procedure-means-bound? MEANS)"
206                                        (p "Are all the procedures in the " (tt "MEANS") " bound?"))
207
208                                (procedure "(procedure-means-incompletes MEANS)"
209                                        (p "Returns an alist, (<procedure identifier> . <procedure "
210                                        "surface>), of all procedures in the procedure surface(s) of "
211                                        "the " (tt "MEANS ...") " that are undeclared."))
212
213                                (procedure "(procedure-means-unbounds MEANS)"
214                                        (p "Returns an alist, (<procedure-symbol> . "
215                                        "<procedure-surface>), of all the unbound procedures in " (tt "MEANS") "."))
216
217                                (procedure "(procedure-means-incomplete-closure? MEANS PROC-SYM)"
218                                        (p "Is the procedure identified by " (tt "PROC-SYM") " without "
219                                        "a declaration in the " (tt "MEANS") "?"))
220
221                                (procedure "(procedure-means->alist MEANS)"
222                                        (p "Returns an alist, (<procedure-symbol> . "
223                                        "<procedure-alias/closure), from the " (tt "MEANS") "."))
224
225                                (procedure "(procedure-means-set! MEANS PROC-SYM PROC-REF ...)"
226                                        (p "Adds or updates procedures for an existing " (tt "MEANS") "."))
227
228                                (procedure "(procedure-means-delete! MEANS PROC-SYM)"
229                                        (p "Removes the procedure " (tt "PROC-SYM") " from the " (tt "MEANS") "."))
230
231                                (procedure "(procedure-means-load! MEANS)"
232                                        (p "Load of any libraries and extensions required by the " (tt "MEANS") "."))
233
234                                (procedure "(make-composite-procedure-means MEANS ...)"
235                                        (p "Returns a procedure means, the combination of "
236                                        (tt "MEANS ...") " set. Should any means be immutable then the "
237                                        "composite is immutable."))
238
239                                (procedure "(composite-procedure-means? MEANS)"
240                                        (p "Are the " (tt "MEANS") " a composite?"))
241
242                                (procedure "(procedure-unbound? PROCEDURE)"
243                                        (p "Is this surface means procedure loaded?"))
244
245                                (procedure "(procedure-identifier->closure SYMBOL)"
246                                        (p "Returns the top level binding, if any, for the procedure "
247                                        "named " (tt "SYMBOL") "."))
248                        )
249
250                        (subsection "Signature Types"
251
252                                (p "The signature type system supports multiple-inheritance, via "
253                                "the 'extends' property.")
254
255                                (procedure "(build-signature-type-builtins)"
256                                        (p "Creates all the builtin types."))
257
258                                (procedure "(make-signature-type NAME #!optional (EXTENDS #f) (PREDICATE #f) (SPECIALIZER #f))"
259                                        (p "Creates a new signature type object.")
260                                        (symbol-table
261                                                (describe NAME
262                                                        "A symbol. The name of the new type.")
263                                                (describe EXTENDS
264                                                        "A symbol or list. The type(s) that the new type is extending.")
265                                                (describe PREDICATE
266                                                        "A procedure. Determines whether an arbitrary object is a value of the new type.")
267                                                (describe SPECIALIZER
268                                                        "A procedure. Determines whether a specialization for the new type is valid.")))
269
270                                (procedure "(signature-type? OBJECT)"
271                                        (p "Is " (tt "OBJECT") " a signature type?"))
272
273                                (procedure "(signature-extended-type? TYPE/NAME)"
274                                        (p "Does a type extend " (tt "TYPE/NAME") "."))
275
276                                (procedure "(signature-leaf-type? TYPE/NAME)"
277                                        (p "Does " (tt "TYPE/NAME") " not extend a type?"))
278
279                                (procedure "(signature-type-a-kind-of? TYPE/NAME-SUB TYPE/NAME-SUPER)"
280                                        (p "Does " (tt "TYPE/NAME-SUB") " extend " (tt "TYPE/NAME-SUPER") "?")
281
282                                        (p "The most distant ancestor of all Scheme types is 'object'. "
283                                        "However, roots are not considered when determining the kind of "
284                                        "relationship from an intermediate type. So to check if a type "
285                                        "is a kind of 'object' do so directly."))
286
287                                (procedure "(signature-type-ref NAME)"
288                                        (p "Returns the signature type for " (tt "NAME") "."))
289
290                                (procedure "(signature-type-name TYPE)"
291                                        (p "Returns the name of " (tt "TYPE") "."))
292
293                                (procedure "(signature-type-predicate TYPE/NAME)"
294                                        (p "Returns the predicate for " (tt "TYPE/NAME") "."))
295
296                                (procedure "(signature-type-specializer TYPE/NAME)"
297                                        (p "Returns the specializer for " (tt "TYPE/NAME") "."))
298
299                                (procedure "(signature-type-extends TYPE/NAME)"
300                                        (p "Return a list of the types that " (tt "TYPE/NAME") " extends."))
301
302                                (procedure "(signature-type-extension TYPE/NAME)"
303                                        (p "Return a list of the types that extend " (tt "TYPE/NAME") "."))
304
305                                (procedure "(signature-type-delete! TYPE/NAME)"
306                                        (p "Remove the " (tt "TYPE/NAME") "."))
307
308                                (procedure "(signature-type-replace! TYPE/NAME #!optional (NEW-NAME #f) (EXTENDS #f) (PREDICATE #f) (SPECIALIZER #f))"
309                                        (p "Replace the existing " (tt "TYPE/NAME") " with a new "
310                                        "definition."))
311
312                                (procedure "(make-signature-contract CONTRACT)"
313                                        (p "Validates the source form of a contract and returns the internal form."))
314                        )
315
316                        (subsection "Procedure Signature Grammar"
317
318                                (symbol-table
319                                        (describe contract
320                                                "<map> | (or <map> ...)")
321                                        (describe type
322                                                "<symbol> | <specialization>")
323                                        (describe specialization
324                                                "<map> | (<type> [<parameter> ...]) | (or <type> ...)")
325                                        (describe parameter
326                                                "<object>")
327                                        (describe domain
328                                                "[<type> ...] [#!optional <type> ...] [#!rest list | (list <type> ...)] [#!key (<keyword> <type>) ...]")
329                                        (describe range
330                                                "<type> | (values <type> ...)")
331                                        (describe map
332                                                "(-> <domain> <range> [<throw> ...])")
333                                        (describe throw
334                                                "(signals <exception> ...) | (aborts <exception> ...)")
335                                        (describe exception
336                                                "<symbol> | (<symbol> ...)") )
337
338                                (p "A <map> is a specialization of '->', the type of a procedure.")
339
340                                (p "'()' is a synonym of 'null' for this grammar.")
341
342                                (p "Example: (-> (array (rank 2)) object (values integer complex "
343                                "vector object)) - a procedure (<map>) taking a matrix & any "
344                                "object, returning 4 multiple values.")
345
346                                (subsubsection "Builtin Types"
347
348                                        (ul
349                                                (li "object")
350                                                (li "void")
351                                                (li "structure")
352                                                (li "boolean")
353                                                (li "symbol")
354                                                (li "keyword")
355                                                (li "char")
356                                                (li "string")
357                                                (li "vector")
358                                                (li "list")
359                                                (li "pair")
360                                                (li "null")
361                                                (li "port")
362                                                (li "input-port")
363                                                (li "output-port")
364                                                (li "eof")
365                                                (li "procedure")
366                                                (li "macro")
367                                                (li "continuation")
368                                                (li "promise")
369                                                (li "environment")
370                                                (li "read-table")
371                                                (li "hash-table")
372                                                (li "queue")
373                                                (li "condition")
374                                                (li "number")
375                                                (li "exact")
376                                                (li "inexact")
377                                                (li "real")
378                                                (li "integer")
379                                                (li "fixnum")
380                                                (li "flonum")
381                                                (li "rational")
382                                                (li "complex")
383                                                (li "u8vector")
384                                                (li "s8vector")
385                                                (li "u16vector")
386                                                (li "s16vector")
387                                                (li "u32vector")
388                                                (li "s32vector")
389                                                (li "f32vector")
390                                                (li "f64vector")
391                                                (li "char-set")
392                                                (li "mmap")
393                                                (li "terminal-port")
394                                                (li "tcp-listener")
395                                                (li "thread")
396                                                (li "lock")
397                                                (li "mutex")
398                                                (li "condition-variable")
399                                                (li "time")
400                                                (li "regexp")
401                                                (li "pointer")
402                                                (li "tagged-pointer")
403                                                (li "swig-pointer")
404                                                (li "locative")
405                                                (li "byte-vector")
406                                                (li "extended-procedure")
407                                                (li "object-evicted")
408                                                (li "record")
409                                                (li "clos-object")
410                                                (li "class")
411                                                (li "method")
412                                                (li "generic")
413                                                (li "c++-object")
414                                                (li "date")
415                                                (li "array")
416                                                (li "future")
417                                        )
418                                )
419                        )
420                )
421
422                #;(examples
423                        (p "%%EXAMPLES%%") )
424
425                (history
426      (version "1.1.0" "Full low-level macro support.")
427      (version "1.0.0" "Use of \"fixup-extended-lambda-list-rest\".")
428      (version "0.301" "Needs lookup-table")
429      (version "0.3" "Added support for explicit library pathname")
430      (version "0.2" "Needs misc-extn > 2.0")
431      (version "0.1" "Initial release"))
432
433                (section "License" (pre ,license))
434        )
435))
436
437(eggdoc->html doc)
Note: See TracBrowser for help on using the repository browser.