source: project/release/3/F-operator/F-operator-eggdoc.scm @ 8904

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

Save.

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