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

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

Rel 1.0.0 (no real changes)

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 "syntax-case.html" "syntax-case")
39                        (url "misc-extn.html" "misc-extn") )
40
41                (usage)
42                (download "procedure-surface.egg")
43
44                (documentation
45
46                        (p "Warning - procedure surface is experimental!")
47
48                        (p "The procedure-surface egg provides a facility for generic "
49                        "programming in Scheme, similar in purpose to the \"structures\" "
50                        "egg. Unlike the normal pattern of use for \"structures\" this "
51                        "facility will delay loading of any library or extension until an "
52                        "actual binding is required. The use of a 'define' form as a "
53                        "procedure reference with 'make-procedure-means' is not "
54                        "supported, unlike the analogous 'structure' from \"structures\".")
55
56                        (p "Odd names are used for parsimony. Read 'interface' for "
57                        "'surface', and 'implementation' for 'means'.")
58
59                        (subsection "Syntax Interface"
60
61                                (macro "(define-procedure-surface NAME PROC-SYM CONTRACT ... [KEY-ARG ...])"
62                                        (p "Sets the symbol " (tt "NAME") " to the described procedure "
63                                        "surface. Uses " (tt "NAME") " as the keyword argument #:name "
64                                        "for the surface. See 'make-procedure-surface' for argument "
65                                        "descriptions."))
66
67                                (macro "(declare-procedure-means NAME SURFACE PROC-SYM PROC-REF ... [KEY-ARG ...])"
68                                        (p "Sets the symbol " (tt "NAME") " to the described procedure "
69                                        "surface means. See 'make-procedure-means' for "
70                                        "argument descriptions."))
71
72                                (macro "(call-thru-procedure-means MEANS PROC-SYM [ARG ...])"
73                                        (p "Invoke the procedure identified by " (tt "PROC-SYM") " in "
74                                        "the " (tt "MEANS") " with the " (tt "ARG ...") " list."))
75
76                                (macro "(apply-thru-procedure-means MEANS PROC-SYM ARG ...)"
77                                        (p "Apply the procedure identified by " (tt "PROC-SYM") " in "
78                                        "the " (tt "MEANS") " to the " (tt "ARG ...") " list."))
79
80                                (macro "(let-procedure-means ([(PROC-SYM ...) MEANS] ...) BODY ...)"
81                                        (p "Bind the local symbol(s) " (tt "PROC-SYM ...") " to the "
82                                        "corresponding procedure(s) in the " (tt "MEANS") " and "
83                                        "evaluate the " (tt "BODY") "."))
84
85                                (macro "(call/means MEANS PROC-SYM [ARG ...])"
86                                        (p "Abbreviation of 'call-thru-procedure-means'."))
87
88                                (macro "(apply/means MEANS PROC-SYM ARG ...)"
89                                        (p "Abbreviation of 'apply-thru-procedure-means'."))
90
91                                (macro "(let/means ([(PROC-SYM ...) MEANS] ...) BODY ...)"
92                                        (p "Abbreviation of 'let-procedure-means'."))
93                        )
94
95                        (subsection "Direct Call Interface"
96
97                                (procedure "(make-procedure-signature IDENTIFIER CONTRACT)"
98                                        (p "Returns a procedure signature for " (tt "IDENTIFIER") " "
99                                        "with " (tt "CONTRACT") ".")
100
101                                        (p "The contract grammar is described below. Can be null, '(), "
102                                        "for no contract."))
103
104                                (procedure "(procedure-signature? OBJECT)"
105                                        (p "Is " (tt "OBJECT") " a procedure signature?"))
106
107                                (procedure "(procedure-signature-identifier SIGNATURE)"
108                                        (p "Returns the procedure signature identifier of the " (tt "SIGNATURE") "."))
109
110                                (procedure "(procedure-signature-contract SIGNATURE)"
111                                        (p "Returns the procedure signature contract of the " (tt "SIGNATURE") "."))
112
113                                (procedure "(make-procedure-surface PROC-SYM CONTRACT ... [#:immutable #f] [#:name #f])"
114                                        (p "Creates and returns a procedure surface. A collection of "
115                                        "procedure identifiers and contracts.")
116                                        (symbol-table
117                                                (describe #:immutable
118                                                        "A boolean. Immutable (#t) or mutable (#f).")
119                                                (describe #:name
120                                                        "A symbol or string. The name of the surface. When missing a name of the form \"ps#\" will be created.")
121                                                (describe PROC-SYM
122                                                        "A symbol. The procedure identifier.")
123                                                (describe CONTRACT
124                                                        "A list. The source form of a procedure signature. The contract grammar is described below. null, '(), for no contract.")) )
125
126                                (procedure "(procedure-surface? OBJECT)"
127                                        (p "Is the " (tt "OBJECT") " a procedure surface?"))
128
129                                (procedure "(procedure-surface-name SURFACE)"
130                                        (p "Returns the name, or names as list if composite, of the " (tt "SURFACE") "."))
131
132                                (procedure "(procedure-surface-immutable? SURFACE)"
133                                        (p "Is the " (tt "SURFACE") " immutable?"))
134
135                                (procedure "(procedure-surface-mutable? SURFACE)"
136                                        (p "Is the " (tt "SURFACE") " mutable?"))
137
138                                (procedure "(procedure-surface-ref SURFACE PROC-SYM)"
139                                        (p "Returns the procedure signature of the " (tt "SURFACE") "."))
140
141                                (procedure "(procedure-surface-set! SURFACE PROC-SYM CONTRACT ...)"
142                                        (p "Adds or updates procedure signatures in " (tt "SURFACE") "."))
143
144                                (procedure "(procedure-surface-delete! SURFACE PROC-SYM)"
145                                        (p "Removes the procedure signature for " (tt "PROC-SYM") " "
146                                        "from " (tt "SURFACE") "."))
147
148                                (procedure "(procedure-surface->alist SURFACE)"
149                                        (p "Returns a alist, (<procedure-symbol> . "
150                                        "<procedure-signature>), from " (tt "SURFACE") "."))
151
152                                (procedure "(make-composite-procedure-surface SURFACE ...)"
153                                        (p "Returns a procedure surface, the combination of "
154                                        (tt "SURFACE ...") " set. Should any surface be immutable then the "
155                                        "composite is immutable."))
156
157                                (procedure "(composite-procedure-surface? SURFACE)"
158                                        (p "Is the " (tt "SURFACE") " a composite?"))
159
160                                (procedure "(make-procedure-means SURFACE PROC-SYM PROC-REF ... [#:immutable #f] [#:extension #f] [#:library #f] [#:pathname #f])"
161                                        (p "Supply procedures for the " (tt "SURFACE") ".")
162                                        (symbol-table
163                                                (describe #:immutable
164                                                        "A boolean. Immutable (#t) or mutable (#f).")
165                                                (describe #:extension
166                                                        "A symbol or string. The name of the extension.")
167                                                (describe #:library
168                                                        "A symbol or string. The name of the library.")
169                                                (describe #:pathname
170                                                        "A string. The absolute pathname of the extension or library. Required when the extension or library is not in the Chicken repository.")
171                                                (describe PROC-SYM
172                                                        "A symbol. The procedure identifier. Must match a procedure identifier from SURFACE.")
173                                                (describe PROC-REF
174                                                        "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.")) )
175
176                                (procedure "(procedure-means? OBJECT)"
177                                        (p "Is the " (tt "OBJECT") " a procedure surface?"))
178
179                                (procedure "(procedure-means-immutable? MEANS)"
180                                        (p "Are the " (tt "MEANS") " immutable?"))
181
182                                (procedure "(procedure-means-mutable? MEANS)"
183                                        (p "Are the " (tt "MEANS") " mutable?"))
184
185                                (procedure "(procedure-means-alias MEANS PROC-SYM)"
186                                        (p "Returns the alias of " (tt "PROC-SYM") " in " (tt "MEANS") "."))
187
188                                (procedure "(procedure-means-ref MEANS PROC-SYM)"
189                                        (p "Returns the current binding of " (tt "PROC-SYM") " in the "
190                                        (tt "MEANS") ", which maybe the unbound value."))
191
192                                (procedure "(procedure-means-closure MEANS PROC-SYM)"
193                                        (p "Forces a load, if necessary. Returns the current binding "
194                                        "of " (tt "PROC-SYM") " in the " (tt "MEANS") ", which maybe "
195                                        "the unbound value."))
196
197                                (procedure "(procedure-means-implements MEANS)"
198                                        (p "Returns the procedure surface, or a list of procedure "
199                                        "surface when composite, that the " (tt "MEANS") " "
200                                        "implements."))
201
202                                (procedure "(procedure-means-complete? MEANS)"
203                                        (p "Are all procedures in the procedure surface(s) of the "
204                                        (tt "MEANS") " declared?"))
205
206                                (procedure "(procedure-means-bound? MEANS)"
207                                        (p "Are all the procedures in the " (tt "MEANS") " bound?"))
208
209                                (procedure "(procedure-means-incompletes MEANS)"
210                                        (p "Returns an alist, (<procedure identifier> . <procedure "
211                                        "surface>), of all procedures in the procedure surface(s) of "
212                                        "the " (tt "MEANS ...") " that are undeclared."))
213
214                                (procedure "(procedure-means-unbounds MEANS)"
215                                        (p "Returns an alist, (<procedure-symbol> . "
216                                        "<procedure-surface>), of all the unbound procedures in " (tt "MEANS") "."))
217
218                                (procedure "(procedure-means-incomplete-closure? MEANS PROC-SYM)"
219                                        (p "Is the procedure identified by " (tt "PROC-SYM") " without "
220                                        "a declaration in the " (tt "MEANS") "?"))
221
222                                (procedure "(procedure-means->alist MEANS)"
223                                        (p "Returns an alist, (<procedure-symbol> . "
224                                        "<procedure-alias/closure), from the " (tt "MEANS") "."))
225
226                                (procedure "(procedure-means-set! MEANS PROC-SYM PROC-REF ...)"
227                                        (p "Adds or updates procedures for an existing " (tt "MEANS") "."))
228
229                                (procedure "(procedure-means-delete! MEANS PROC-SYM)"
230                                        (p "Removes the procedure " (tt "PROC-SYM") " from the " (tt "MEANS") "."))
231
232                                (procedure "(procedure-means-load! MEANS)"
233                                        (p "Load of any libraries and extensions required by the " (tt "MEANS") "."))
234
235                                (procedure "(make-composite-procedure-means MEANS ...)"
236                                        (p "Returns a procedure means, the combination of "
237                                        (tt "MEANS ...") " set. Should any means be immutable then the "
238                                        "composite is immutable."))
239
240                                (procedure "(composite-procedure-means? MEANS)"
241                                        (p "Are the " (tt "MEANS") " a composite?"))
242
243                                (procedure "(procedure-unbound? PROCEDURE)"
244                                        (p "Is this surface means procedure loaded?"))
245
246                                (procedure "(procedure-identifier->closure SYMBOL)"
247                                        (p "Returns the top level binding, if any, for the procedure "
248                                        "named " (tt "SYMBOL") "."))
249                        )
250
251                        (subsection "Signature Types"
252
253                                (p "The signature type system supports multiple-inheritance, via "
254                                "the 'extends' property.")
255
256                                (procedure "(build-signature-type-builtins)"
257                                        (p "Creates all the builtin types."))
258
259                                (procedure "(make-signature-type NAME #!optional (EXTENDS #f) (PREDICATE #f) (SPECIALIZER #f))"
260                                        (p "Creates a new signature type object.")
261                                        (symbol-table
262                                                (describe NAME
263                                                        "A symbol. The name of the new type.")
264                                                (describe EXTENDS
265                                                        "A symbol or list. The type(s) that the new type is extending.")
266                                                (describe PREDICATE
267                                                        "A procedure. Determines whether an arbitrary object is a value of the new type.")
268                                                (describe SPECIALIZER
269                                                        "A procedure. Determines whether a specialization for the new type is valid.")))
270
271                                (procedure "(signature-type? OBJECT)"
272                                        (p "Is " (tt "OBJECT") " a signature type?"))
273
274                                (procedure "(signature-extended-type? TYPE/NAME)"
275                                        (p "Does a type extend " (tt "TYPE/NAME") "."))
276
277                                (procedure "(signature-leaf-type? TYPE/NAME)"
278                                        (p "Does " (tt "TYPE/NAME") " not extend a type?"))
279
280                                (procedure "(signature-type-a-kind-of? TYPE/NAME-SUB TYPE/NAME-SUPER)"
281                                        (p "Does " (tt "TYPE/NAME-SUB") " extend " (tt "TYPE/NAME-SUPER") "?")
282
283                                        (p "The most distant ancestor of all Scheme types is 'object'. "
284                                        "However, roots are not considered when determining the kind of "
285                                        "relationship from an intermediate type. So to check if a type "
286                                        "is a kind of 'object' do so directly."))
287
288                                (procedure "(signature-type-ref NAME)"
289                                        (p "Returns the signature type for " (tt "NAME") "."))
290
291                                (procedure "(signature-type-name TYPE)"
292                                        (p "Returns the name of " (tt "TYPE") "."))
293
294                                (procedure "(signature-type-predicate TYPE/NAME)"
295                                        (p "Returns the predicate for " (tt "TYPE/NAME") "."))
296
297                                (procedure "(signature-type-specializer TYPE/NAME)"
298                                        (p "Returns the specializer for " (tt "TYPE/NAME") "."))
299
300                                (procedure "(signature-type-extends TYPE/NAME)"
301                                        (p "Return a list of the types that " (tt "TYPE/NAME") " extends."))
302
303                                (procedure "(signature-type-extension TYPE/NAME)"
304                                        (p "Return a list of the types that extend " (tt "TYPE/NAME") "."))
305
306                                (procedure "(signature-type-delete! TYPE/NAME)"
307                                        (p "Remove the " (tt "TYPE/NAME") "."))
308
309                                (procedure "(signature-type-replace! TYPE/NAME #!optional (NEW-NAME #f) (EXTENDS #f) (PREDICATE #f) (SPECIALIZER #f))"
310                                        (p "Replace the existing " (tt "TYPE/NAME") " with a new "
311                                        "definition."))
312
313                                (procedure "(make-signature-contract CONTRACT)"
314                                        (p "Validates the source form of a contract and returns the internal form."))
315                        )
316
317                        (subsection "Procedure Signature Grammar"
318
319                                (symbol-table
320                                        (describe contract
321                                                "<map> | (or <map> ...)")
322                                        (describe type
323                                                "<symbol> | <specialization>")
324                                        (describe specialization
325                                                "<map> | (<type> [<parameter> ...]) | (or <type> ...)")
326                                        (describe parameter
327                                                "<object>")
328                                        (describe domain
329                                                "[<type> ...] [#!optional <type> ...] [#!rest list | (list <type> ...)] [#!key (<keyword> <type>) ...]")
330                                        (describe range
331                                                "<type> | (values <type> ...)")
332                                        (describe map
333                                                "(-> <domain> <range> [<throw> ...])")
334                                        (describe throw
335                                                "(signals <exception> ...) | (aborts <exception> ...)")
336                                        (describe exception
337                                                "<symbol> | (<symbol> ...)") )
338
339                                (p "A <map> is a specialization of '->', the type of a procedure.")
340
341                                (p "'()' is a synonym of 'null' for this grammar.")
342
343                                (p "Example: (-> (array (rank 2)) object (values integer complex "
344                                "vector object)) - a procedure (<map>) taking a matrix & any "
345                                "object, returning 4 multiple values.")
346
347                                (subsubsection "Builtin Types"
348
349                                        (ul
350                                                (li "object")
351                                                (li "void")
352                                                (li "structure")
353                                                (li "boolean")
354                                                (li "symbol")
355                                                (li "keyword")
356                                                (li "char")
357                                                (li "string")
358                                                (li "vector")
359                                                (li "list")
360                                                (li "pair")
361                                                (li "null")
362                                                (li "port")
363                                                (li "input-port")
364                                                (li "output-port")
365                                                (li "eof")
366                                                (li "procedure")
367                                                (li "macro")
368                                                (li "continuation")
369                                                (li "promise")
370                                                (li "environment")
371                                                (li "read-table")
372                                                (li "hash-table")
373                                                (li "queue")
374                                                (li "condition")
375                                                (li "number")
376                                                (li "exact")
377                                                (li "inexact")
378                                                (li "real")
379                                                (li "integer")
380                                                (li "fixnum")
381                                                (li "flonum")
382                                                (li "rational")
383                                                (li "complex")
384                                                (li "u8vector")
385                                                (li "s8vector")
386                                                (li "u16vector")
387                                                (li "s16vector")
388                                                (li "u32vector")
389                                                (li "s32vector")
390                                                (li "f32vector")
391                                                (li "f64vector")
392                                                (li "char-set")
393                                                (li "mmap")
394                                                (li "terminal-port")
395                                                (li "tcp-listener")
396                                                (li "thread")
397                                                (li "lock")
398                                                (li "mutex")
399                                                (li "condition-variable")
400                                                (li "time")
401                                                (li "regexp")
402                                                (li "pointer")
403                                                (li "tagged-pointer")
404                                                (li "swig-pointer")
405                                                (li "locative")
406                                                (li "byte-vector")
407                                                (li "extended-procedure")
408                                                (li "object-evicted")
409                                                (li "record")
410                                                (li "clos-object")
411                                                (li "class")
412                                                (li "method")
413                                                (li "generic")
414                                                (li "c++-object")
415                                                (li "date")
416                                                (li "array")
417                                                (li "future")
418                                        )
419                                )
420                        )
421                )
422
423                #;(examples
424                        (p "%%EXAMPLES%%") )
425
426                (history
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.