source: project/wiki/tagged-begin @ 8852

Last change on this file since 8852 was 8852, checked in by Alaric Snell-Pym, 12 years ago

First draft of wikified docs for tagged-begin

Examples aren't coming out right, but that may or may not be my fault.

No idea how to represent the author's name - Jens Axel Søgaard - in wiki markup...

File size: 7.5 KB
Line 
1[[tags: egg]]
2
3== Introduction
4
5A form of {{begin}} that resembles the Common Lisp {{tagbody}} construct.
6
7== Examples
8
9<example>
10  <init>(use tagged-begin)</init>
11  <expr>
12; Example 1 (tagged-begin returns (void))
13 (let ([i 0])
14   (tagged-begin
15    loop (set! i (+ i 1))
16         (if (< i 41) (go loop)))
17   i)</expr>
18   <result>41</result>
19</example>
20   
21<example>
22  <init>(use tagged-begin)</init>
23  <expr>
24; Example 2 (tagged-begin returns 42)
25 (let ([i 0])
26   (tagged-begin
27    loop (set! i (+ i 1))
28         (if (< i 42) (go loop))
29         (return i)))</expr>
30  <result>42</result>
31</example>
32
33<example>
34  <init>(use tagged-begin)</init>
35  <expr>
36; Example 3 (tagged-begin returns 43)
37 (let ([i 0])
38   (tagged-begin
39    loop (set! i (+ i 1))
40         (go b)
41    a    (if (< i 43) (go loop))
42         (return i)
43    b    (go a)))</expr>
44  <result>43</result>
45</example>
46
47<example>
48  <init>(use tagged-begin)</init>
49  <expr>
50; Example 4 (http://www.emacswiki.org/cgi-bin/wiki.pl?StateMachine)
51
52(define (display/nl v)
53  (display v)
54  (newline))
55
56(let ((a 0))
57   (tagged-begin
58     start
59      (set! a 0)
60     part-1
61      (set! a (+ a 1))
62      (display/nl a)
63      (cond
64        ((>= a  9)  (go end))
65        ((even? a)  (go part-1))
66        (else       (go part-2)))
67     part-2
68      (set! a (+ a 1))
69      (go part-1)
70     end
71      (display/nl "We're done printing the odd numbers between 0 and 10")))</expr>
72  <output>1
733
745
757
769
77We're done printing the odd numbers between 0 and 10</output>
78</example>
79
80<example>
81  <init>(use tagged-begin)</init>
82  <expr>
83; Example 5 ( Knuth: "The Art of Computer Programming", vol1, p.176)
84
85; Inplace inversion of a permutation represented as a vector.
86
87(define permutation (vector 'dummy 6 2 1 5 4 3))      ; (Knuth counts from 1 not 0 :-) )
88(define n           (- (vector-length permutation) 1))
89(define (X i)       (vector-ref permutation i))
90(define (X! i j)    (vector-set! permutation i j))
91
92(let ([m 0] [i 0] [j 0])
93  (tagged-begin
94   I1   ; Initialize
95        (set! m n)
96        (set! j -1)
97   I2   ; Next element
98        (set! i (X m))
99        (if (< i 0) (go I5))
100   I3   ; Invert one
101        (X! m j)
102        (set! j (- m))
103        (set! m i)
104        (set! i (X m))
105   I4   ; End of cycle?
106        (if (> i 0) (go I3))
107        (set! i j)
108   I5   ; Store final value
109        (X! m (- i))
110   I6   ; Loop on m
111        (set! m (- m 1))
112        (if (> m 0) (go I2))))
113
114permutation</expr>
115  <result>#(dummy 3 2 6 5 4 1)</result>
116</example>
117
118<example>
119  <init>(use tagged-begin)</init>
120  <expr>
121; Example 6 (The CommonLisp Hyper Spec examples of tagbody)     
122 
123(define val 'foo)
124(tagged-begin
125    (set! val 1)
126       (go a)
127 c     (set! val (+ val 4))
128       (go b)
129       (set! val (+ val 32))
130 a     (set! val (+ val 2))
131       (go c)
132       (set! val (+ val 64))
133 b     (set! val (+ val 8)))
134
135(define (f1 flag)
136  (let ((n 1))
137    (tagged-begin
138     (set! n (f2 flag (lambda () (go out))))
139     out
140     (return n))))
141
142(define (f2 flag escape)
143  (if flag (escape) 2))
144
145(list val (f1 #f) (f1 #t))</expr>
146  <result>(15 2 1)</result>
147</example>
148
149<example>
150  <init>(use tagged-begin)</init>
151  <expr>
152; Example 7
153;   Demonstrates lexical scoping of tagged-begins,
154;   and that an inner tagged-begin can use an outer tag.
155
156(tagged-begin
157 a (tagged-begin
158      (go b))
159 b (return 'hello-world))
160</expr>
161  <result>hello-world</result>
162</example>
163
164<example>
165  <init>(use tagged-begin)</init>
166  <expr>
167; Demonstrates that tags are lexically shadowed.
168(tagged-begin
169 a (tagged-begin
170        (go b)
171        (return 'wrong)
172      b (go c))
173 b (return 'wrong)
174 c (return 'correct))
175</expr>
176  <result>correct</result>
177</example>
178
179<example>
180  <init>(use tagged-begin)</init>
181  <expr>
182;;; EXPANSION EXAMPLE           
183           
184(pp (macroexpand
185  '(tagged-begin
186       (set! val 1)
187       (go a)
188 c     (set! val (+ val  4))
189       (go b)
190       (set! val (+ val 32))
191 a     (set! val (+ val  2))
192       (go c)
193       (set! val (+ val 64))
194 b     (set! val (+ val  8)))))</expr>
195 <output>((call/cc
196    (lambda (go)
197      (let ((return (lambda (v) (go (lambda () v)))))
198        (letrec ((g14 (lambda () (set! val 1) (go a) (c)))
199                 (c (lambda ()
200                      (set! val (+ val 4))
201                      (go b)
202                      (set! val (+ val 32))
203                      (a)))
204                 (a (lambda ()
205                      (set! val (+ val 2))
206                      (go c)
207                      (set! val (+ val 64))
208                      (b)))
209                 (b (lambda () (set! val (+ val 8)) (return (void)))))
210          (g14))))))</output>
211</example>
212
213== Authors
214
215Jens Axel S&oslash;gaard, low-level macro implementation by [[felix winkelmann|Felix Winkelmann]].
216
217== License
218
219Copyright (c) 2005, Jens Axel S&oslash;gaard
220All rights reserved.
221
222Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
223conditions are met:
224
225* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
226* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
227* Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
228
229THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
230OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
231AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
232CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
233CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
234SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
235THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
236OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
237POSSIBILITY OF SUCH DAMAGE.
238
239== Documentation
240
241This is a little macro that resembles the Common Lisp [[http://www-2.cs.cmu.edu/Groups/AI/html/hyperspec/HyperSpec/Body/speope_tagbody.html#tagbody|tagbody]] construct.
242See also "Applications of Continuations" of Daniel P. Friedman.
243
244=== Motivation
245
246Many algorithms is specified in an imperative manner
247in the literature (see Example 5 from Knuth). For a no-brain-
248conversion to Scheme tagged-begin is convenient.
249
250=== Syntax
251 
252<macro> (tagged-begin (''tag'' | ''expression'')* )</macro>
253
254where {{tag}} is a symbol and duplicate tags are not allowed.
255
256=== Semantics
257
258The form evaluates the expressions in a lexical environment
259that provides functions {{go}} and {{return}} both of one argument to transfer control.
260
261The expressions in {{tagged-begin}} are evaluated sequentially.
262If no expressions are left {{(void)}} is returned.
263
264If an expression evaluates {{(go ''tag'')}} then control is transfered
265to the expression following tag. The tags have lexical scope.
266The dynamic extent of tag is indefinite.  An {{(go ''tag'')}} is allowed
267to transfer control to an outer tagbody. The call {{(go ''tag'')}} has the
268proper tail recursive property, even in a situation where the call
269syntactically is not in tail position.
270
271If {{(return ''expression'')}} is evaluted, the value of {{expression}} is
272the value of the entire tagged-begin form.
273
274== Version History
275
276* 1.1: {{tagged-begin.scm}} needed srfi-1
277* 1.0
Note: See TracBrowser for help on using the repository browser.