source: project/F-operator/F-operator-eggdoc.scm @ 2773

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

Added nounwind -values routines.

File size: 12.0 KB
Line 
1;;;; F-operator-eggdoc.scm
2
3(use eggdoc)
4
5(define license #<<EOF
6Copyright (c) 2006, 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.
25
26Does not supercede any restrictions found in the source code.
27EOF
28)
29
30(define examples
31"
32;;
33;; See \"F-operator-test.scm\" in the unpacked egg for more examples.
34;;
35")
36
37(define doc `(
38  (eggdoc:begin
39    (name "F-operator")
40    (description (p "Shift/Reset Control Operators"))
41    (author (url "mailto:klovett@pacbell.net" "Kon Lovett"))
42    (history
43      (version "1.3" "Added %bshift-values/%breset-values & %shift-values/%reset-values")
44      (version "1.2" "Renamed H datatype stuff")
45      (version "1.1" "reflect/reify")
46      (version "1.0" "Conditioned on hygenic vs. non-hygenic macros, stopped disabling interrupts")
47      (version "0.6" "Exports")
48      (version "0.5" "Rename *v *-values")
49      (version "0.4" "Rename H datatype")
50      (version "0.3" "%shift/%reset, %bshift/%breset, bug fix bshiftv")
51      (version "0.2" "shiftv/resetv, bshiftv/bresetv")
52      (version "0.1" "Initial release"))
53    (requires
54      (url "datatype.html" "datatype")
55      "Chicken 2.310+")
56    (download "F-operator.egg")
57
58    (documentation
59
60      (p "The static delimited continuation operators shift and reset.")
61
62      (subsection "Shift/Reset - Dynamically scoped shift/reset"
63
64        (pre "(require-extension shift-reset)")
65
66        (p "A \"stuck on control\" situation, a 'shift' without an "
67        "enclosing 'reset', is an error.")
68
69        (macro "(%reset EXPRESSION ...)"
70          (p "Evaluate the body " (tt "EXPRESSION ...") " with a "
71          "delimited continuation. The body will contain one or more "
72          "instances of " (code "(%shift ...)") ".")
73
74          (p "Any use of " (code "(dynamic-wind ...)") " within the "
75          "dynamic scope of the partial continuation will be " (b
76          "ignored") "!"))
77
78        (macro "(%shift PC-TAG EXPRESSION)"
79          (p "Within the scope of " (tt "EXPRESSION") " " (tt "PC-TAG")
80          " is bound to the reified partial continuation delimited by "
81          "the enclosing " (code "(%reset ...)") ". Provide a value to the "
82          "partial continuation using the form " (code "(PC-TAG "
83          "<something>)") "."))
84
85        (macro "(reset EXPRESSION ...)"
86          (p "Evaluate the body " (tt "EXPRESSION ...") " with a "
87          "delimited continuation. The body will contain one or more "
88          "instances of " (code "(shift ...)") "."))
89
90        (macro "(shift PC-TAG EXPRESSION)"
91          (p "Within the scope of " (tt "EXPRESSION") " " (tt "PC-TAG")
92          " is bound to the reified partial continuation delimited by "
93          "the enclosing " (code "(reset ...)") ". Provide a value to the "
94          "partial continuation using the form " (code "(PC-TAG "
95          "<something>)") "."))
96
97        (macro "(%reset-values EXPRESSION ...)"
98          (p "Multiple value return version of " (code "(%reset ...)") ". "
99          "The body will contain one or more instances of " (code
100          "(%shift-values ...)") ".")
101
102          (p "Any use of " (code "(dynamic-wind ...)") " within the "
103          "dynamic scope of the partial continuation will be " (b
104          "ignored") "!"))
105
106        (macro "(%shift-values PC-TAG EXPRESSION)"
107          (p "Multiple value return version of " (code "(%shift ...)") ". "
108          "Provide a value to the partial continuation using the form "
109          (code "(PC-TAG <something> ...)") "."))
110
111        (macro "(reset-values EXPRESSION ...)"
112          (p "Multiple value return version of " (code "(reset ...)") ". "
113          "The body will contain one or more instances of " (code
114          "(shift-values ...)") "."))
115
116        (macro "(shift-values PC-TAG EXPRESSION)"
117          (p "Multiple value return version of " (code "(shift ...)") ". "
118          "Provide a value to the partial continuation using the form "
119          (code "(PC-TAG <something> ...)") "."))
120      )
121
122      (subsection "BShift/BReset - Statically scoped shift/reset"
123
124        (pre "(require-extension bshift-breset)")
125
126        (p "Invalid delimited continuations, what " (tt "RC-TAG") " "
127        "below represents, and \"stuck on control\" will generate an "
128        "error.")
129
130        (macro "(%breset RC-TAG EXPRESSION ...)"
131          (p "Evaluate the body " (tt "EXPRESSION ...") " with a "
132          "delimited continuation named " (tt "RC-TAG") ". The body will "
133          "contain one or more instances of " (code "(%bshift RC-TAG "
134          "...)") ".")
135
136          (p "Any use of " (code "(dynamic-wind ...)") " within the "
137          "dynamic scope of the partial continuation will be " (b
138          "ignored") "!"))
139
140        (macro "(%bshift RC-TAG PC-TAG EXPRESSION)"
141          (p "Within the scope of " (tt "EXPRESSION") " " (tt "PC-TAG")
142          " is bound to the reified partial continuation delimited by "
143          "the enclosing " (code "(%breset RC-TAG ...)") ". Provide a "
144          "value to the partial continuation using the form " (code
145          "(PC-TAG <something>)") "."))
146
147        (macro "(breset RC-TAG EXPRESSION ...)"
148          (p "Evaluate the body " (tt "EXPRESSION ...") " with a "
149          "delimited continuation named " (tt "RC-TAG") ". The body will "
150          "contain one or more instances of " (code "(bshift RC-TAG "
151          "...)") "."))
152
153        (macro "(bshift RC-TAG PC-TAG EXPRESSION)"
154          (p "Within the scope of " (tt "EXPRESSION") " " (tt "PC-TAG")
155          " is bound to the reified partial continuation delimited by "
156          "the enclosing " (code "(breset RC-TAG ...)") ". Provide a "
157          "value to the partial continuation using the form " (code
158          "(PC-TAG <something>)") "."))
159
160        (macro "(%breset-values RC-TAG EXPRESSION ...)"
161          (p "Multiple value return version of " (code "(%breset ...)")
162          ". The body will contain one or more instances of " (code
163          "(%bshift-values RC-TAG ...)") ".")
164
165          (p "Any use of " (code "(dynamic-wind ...)") " within the "
166          "dynamic scope of the partial continuation will be " (b
167          "ignored") "!"))
168
169        (macro "(%bshift-values RC-TAG PC-TAG EXPRESSION)"
170          (p "Multiple value return version of " (code "(%bshift ...)")
171          ". Provide a value to the partial continuation using the form "
172          (code "(PC-TAG <something> ...)") "."))
173
174        (macro "(breset-values RC-TAG EXPRESSION ...)"
175          (p "Multiple value return version of " (code "(breset ...)")
176          ". The body will contain one or more instances of " (code
177          "(bshift-values RC-TAG ...)") "."))
178
179        (macro "(bshift-values RC-TAG PC-TAG EXPRESSION)"
180          (p "Multiple value return version of " (code "(bshift ...)")
181          ". Provide a value to the partial continuation using the form "
182          (code "(PC-TAG <something> ...)") "."))
183
184        (macro "(range RC-TAG FROM VALUE STEP TO?)"
185          (p "The value of the delimited continuation " (tt "") " ranges "
186          "over the set of values specified by the state generation "
187          "procedure suite. For use with " (code "(breset ...)") ".")
188
189          (symbol-table
190
191            (describe FROM
192              (p "Zero argument procedure, returning the initial "
193              "state."))
194
195            (describe VALUE
196              (p "Single argument procedure, of the state, returning the "
197              "value of the state."))
198
199            (describe STEP
200              (p "Single argument procedure, of the state, returning the "
201              "next state."))
202
203            (describe TO?
204              (p "Single argument procedure, of the state, returning "
205              (code "#t") " when the range is complete."))
206          ))
207
208        (macro "(range RC-TAG FROM [STEP] TO)"
209          (p "The value of the delimited continuation " (tt "") " ranges "
210          "over the number interval [" (tt "FROM") "  " (tt "TO") "], by "
211          (tt "STEP") ". The increment is 1 when missing. For use with "
212          (code "(breset ...)") "."))
213
214        (macro "(%range RC-TAG FROM VALUE STEP TO?)"
215          (p "Version of " (code "(range ...)") " for use with " (code
216          "(%breset ...)") "."))
217
218        (macro "(%range RC-TAG FROM [STEP] TO)"
219          (p "Version of " (code "(range ...)") " for use with " (code
220          "(%breset ...)") "."))
221      )
222
223      (subsection "Reflect/Reify - Monads"
224
225        (pre "(require-extension reflect-reify)")
226
227        (macro "(define-unit KIND BODY ...)"
228          (p "Expands to " (code "(define (KIND-unit obj) BODY ...)") ".") )
229
230        (macro "(define-bind KIND BODY ...)"
231          (p "Expands to " (code "(define (KIND-bind monad func) BODY ...)") ".") )
232
233        (macro "(reflect KIND MONAD)"
234          (p "Extract value from " (tt "MONAD") ". Plays the role of Haskell '<-'.") )
235
236        (macro "(reflect-values KIND MONAD)"
237          (p "Extract value from " (tt "MONAD") ". Plays the role of Haskell '<-'.") )
238
239        (macro "(%reflect KIND MONAD)"
240          (p "Extract value from " (tt "MONAD") ". Plays the role of Haskell '<-'.") )
241
242        (macro "(reify KIND EXPRESSION)"
243          (p "Return result of " (tt "EXPRESSION") " as a monad.") )
244
245        (macro "(reify-values KIND EXPRESSION)"
246          (p "Return result of " (tt "EXPRESSION") " as a monad.") )
247
248        (macro "(%reify KIND EXPRESSION)"
249          (p "Return result of " (tt "EXPRESSION") " as a monad.") )
250      )
251
252      (subsection "GShift/GReset - Generalized shift/reset"
253
254        (pre "(require-extension gshift-greset)")
255
256        (p "The generalized shift and reset operator family from " (url
257        "http://www.cs.indiana.edu/cgi-bin/techreports/TRNNN.cgi?trnum=TR611"
258        "How to remove a dynamic prompt: static and dynamic "
259        "delimited continuation operators are equally expressible") ".")
260
261        (macro "(greset HR E)"
262          (p "Reset parameterized by the H Reset procedure " (tt "HR")
263          "."))
264
265        (macro "(gshift HS F E)"
266          (p "Shift parameterized by the H Shift procedure " (tt "HS")
267          "."))
268
269        (procedure "(hr-stop V)"
270          (p "H Reset Stop."))
271
272        (procedure "(hs-stop V)"
273          (p "H Shift Stop."))
274
275        (procedure "(hr-prop V)"
276          (p "H Reset Propagate."))
277
278        (procedure "(hs-prop V)"
279          (p "H Shift Propagate."))
280
281        (procedure "(h-compose F X)"
282          (p "Returns the composition of " (tt "F") " and " (tt "X") " "
283          "as an h-datatype."))
284
285        (procedure "(h-value V)"
286          (p "Returns the value of " (tt "V") " as an h-datatype."))
287
288        (procedure "(h-datatype? OBJECT)"
289          (p "Is " (tt "OBJECT") " an h-datatype?"))
290
291        (macro "(h-cases E ((F X) ON-h-EXPR) (V ON-V-EXPR))"
292          (p "Deconstructs the h-datatype " (tt "E") ", binding " (tt
293          "F") " & " (tt "X") " for an evaluation of the " (tt
294          "ON-h-EXPR") " and " (tt "V") " for an evaluation of the " (tt
295          "ON-V-EXPR") "."))
296      )
297    )
298
299    (section "Issues"
300
301      (p "Not a direct implementation of partial continuations. "
302      "Simulated using full continuations.")
303    )
304
305    (section "Examples" (pre ,examples))
306
307    (section "License" (pre ,license))
308  )
309))
310
311(eggdoc->html doc)
Note: See TracBrowser for help on using the repository browser.