summaryrefslogtreecommitdiff
path: root/doc/ref
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2011-04-28 13:08:22 +0200
committerAndy Wingo <wingo@pobox.com>2011-04-28 15:48:35 +0200
commit91956a94fe6363cf69d574b56397962ec6ef4468 (patch)
treeea37362eaac20eff6924f03e4471d1554517cc48 /doc/ref
parent18e444b40e88cf1969414a1e621adaed27d1dc43 (diff)
downloadguile-91956a94fe6363cf69d574b56397962ec6ef4468.tar.gz
allow while as an expression
* module/ice-9/boot-9.scm (while): Specify the return value as #f under normal conditions, #t under (break), and arg... under (break arg...). * test-suite/tests/syntax.test ("while"): Test. * doc/ref/api-control.texi (while do): Document.
Diffstat (limited to 'doc/ref')
-rw-r--r--doc/ref/api-control.texi18
1 files changed, 15 insertions, 3 deletions
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index 1f33c43b5..1dde8ea9d 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -266,13 +266,12 @@ Concept of Closure}).
@deffn syntax while cond body @dots{}
Run a loop executing the @var{body} forms while @var{cond} is true.
@var{cond} is tested at the start of each iteration, so if it's
-@code{#f} the first time then @var{body} is not executed at all. The
-return value is unspecified.
+@code{#f} the first time then @var{body} is not executed at all.
Within @code{while}, two extra bindings are provided, they can be used
from both @var{cond} and @var{body}.
-@deffn {Scheme Procedure} break
+@deffn {Scheme Procedure} break break-arg...
Break out of the @code{while} form.
@end deffn
@@ -281,6 +280,19 @@ Abandon the current iteration, go back to the start and test
@var{cond} again, etc.
@end deffn
+If the loop terminates normally, by the @var{cond} evaluating to
+@code{#f}, then the @code{while} expression as a whole evaluates to
+@code{#f}. If it terminates by a call to @code{break} with some number
+of arguments, those arguments are returned from the @code{while}
+expression, as multiple values. Otherwise if it terminates by a call to
+@code{break} with no arguments, then return value is @code{#t}.
+
+@example
+(while #f (error "not reached")) @result{} #f
+(while #t (break)) @result{} #t
+(while #f (break 1 2 3)) @result{} 1 2 3
+@end example
+
Each @code{while} form gets its own @code{break} and @code{continue}
procedures, operating on that @code{while}. This means when loops are
nested the outer @code{break} can be used to escape all the way out.