summaryrefslogtreecommitdiff
path: root/doc/scheme-control.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/scheme-control.texi')
-rw-r--r--doc/scheme-control.texi96
1 files changed, 41 insertions, 55 deletions
diff --git a/doc/scheme-control.texi b/doc/scheme-control.texi
index 5098fe4cd..c7517175e 100644
--- a/doc/scheme-control.texi
+++ b/doc/scheme-control.texi
@@ -88,28 +88,22 @@ Instead of using @code{call-with-current-continuation}, the exception
primitives documented here are implemented as built-ins that take
advantage of the @emph{upward only} nature of exceptions.
-@c ARGFIXME tag/key
@c docstring begin (texi-doc-string "guile" "catch")
-@deffn primitive catch tag thunk handler
+@deffn primitive catch key thunk handler
Invoke @var{thunk} in the dynamic context of @var{handler} for
-exceptions matching @var{key}. If thunk throws to the symbol @var{key},
-then @var{handler} is invoked this way:
-
-@example
+exceptions matching @var{key}. If thunk throws to the symbol
+@var{key}, then @var{handler} is invoked this way:
+@lisp
(handler key args ...)
-@end example
-
-@var{key} is a symbol or #t.
-
-@var{thunk} takes no arguments. If @var{thunk} returns normally, that
-is the return value of @code{catch}.
-
-Handler is invoked outside the scope of its own @code{catch}. If
-@var{handler} again throws to the same key, a new handler from further
-up the call chain is invoked.
-
-If the key is @code{#t}, then a throw to @emph{any} symbol will match
-this call to @code{catch}.
+@end lisp
+@var{key} is a symbol or @code{#t}.
+@var{thunk} takes no arguments. If @var{thunk} returns
+normally, that is the return value of @code{catch}.
+Handler is invoked outside the scope of its own @code{catch}.
+If @var{handler} again throws to the same key, a new handler
+from further up the call chain is invoked.
+If the key is @code{#t}, then a throw to @emph{any} symbol will
+match this call to @code{catch}.
@end deffn
@c docstring begin (texi-doc-string "guile" "throw")
@@ -124,7 +118,7 @@ If there is no handler at all, an error is signaled.
@end deffn
@c docstring begin (texi-doc-string "guile" "lazy-catch")
-@deffn primitive lazy-catch tag thunk handler
+@deffn primitive lazy-catch key thunk handler
This behaves exactly like @code{catch}, except that it does
not unwind the stack (this is the major difference), and if
handler returns, its value is returned from the throw.
@@ -145,25 +139,27 @@ displaying @var{msg} and writing @var{args}.
@end deffn
@c end
-@c ARGFIXME rest/data
@c docstring begin (texi-doc-string "guile" "scm-error")
-@deffn primitive scm-error key subr message args rest
-Raise an error with key @var{key}. @var{subr} can be a string naming
-the procedure associated with the error, or @code{#f}. @var{message}
-is the error message string, possibly containing @code{~S} and @code{~A}
-escapes. When an error is reported, these are replaced by formating the
-corresponding members of @var{args}: @code{~A} (was @code{%s}) formats using @code{display}
-and @code{~S} (was @code{%S}) formats using @code{write}. @var{data} is a
-list or @code{#f} depending on @var{key}: if @var{key} is
-@code{system-error} then it should be a list
-containing the Unix @code{errno} value; If @var{key} is @code{signal} then
-it should be a list containing the Unix signal number; otherwise it
-will usually be @code{#f}.
+@deffn primitive scm-error key subr message args data
+Raise an error with key @var{key}. @var{subr} can be a string
+naming the procedure associated with the error, or @code{#f}.
+@var{message} is the error message string, possibly containing
+@code{~S} and @code{~A} escapes. When an error is reported,
+these are replaced by formatting the corresponding members of
+@var{args}: @code{~A} (was @code{%s} in older versions of
+Guile) formats using @code{display} and @code{~S} (was
+@code{%S}) formats using @code{write}. @var{data} is a list or
+@code{#f} depending on @var{key}: if @var{key} is
+@code{system-error} then it should be a list containing the
+Unix @code{errno} value; If @var{key} is @code{signal} then it
+should be a list containing the Unix signal number; otherwise
+it will usually be @code{#f}.
@end deffn
@c docstring begin (texi-doc-string "guile" "strerror")
@deffn primitive strerror err
-Returns the Unix error message corresponding to @var{err}, an integer.
+Return the Unix error message corresponding to @var{err}, which
+must be an integer value.
@end deffn
@c begin (scm-doc-string "boot-9.scm" "false-if-exception")
@@ -181,23 +177,20 @@ if an exception occurs then @code{#f} is returned instead.
be reviewed]
@r5index dynamic-wind
-@c ARGFIXME in-guard/thunk1 thunk/thunk2 out-guard/thunk3
@c docstring begin (texi-doc-string "guile" "dynamic-wind")
-@deffn primitive dynamic-wind thunk1 thunk2 thunk3
+@deffn primitive dynamic-wind in_guard thunk out_guard
All three arguments must be 0-argument procedures.
-
-@var{in-guard} is called, then @var{thunk}, then @var{out-guard}.
-
-If, any time during the execution of @var{thunk}, the continuation
-of the @code{dynamic-wind} expression is escaped non-locally, @var{out-guard}
-is called. If the continuation of the dynamic-wind is re-entered,
-@var{in-guard} is called. Thus @var{in-guard} and @var{out-guard} may
-be called any number of times.
-
-@example
+@var{in_guard} is called, then @var{thunk}, then
+@var{out_guard}.
+If, any time during the execution of @var{thunk}, the
+continuation of the @code{dynamic_wind} expression is escaped
+non-locally, @var{out_guard} is called. If the continuation of
+the dynamic-wind is re-entered, @var{in_guard} is called. Thus
+@var{in_guard} and @var{out_guard} may be called any number of
+times.
+@lisp
(define x 'normal-binding)
@result{} x
-
(define a-cont (call-with-current-continuation
(lambda (escape)
(let ((old-x x))
@@ -205,38 +198,31 @@ be called any number of times.
;; in-guard:
;;
(lambda () (set! x 'special-binding))
-
;; thunk
;;
(lambda () (display x) (newline)
(call-with-current-continuation escape)
(display x) (newline)
x)
-
;; out-guard:
;;
(lambda () (set! x old-x)))))))
-
;; Prints:
special-binding
;; Evaluates to:
@result{} a-cont
-
x
@result{} normal-binding
-
(a-cont #f)
;; Prints:
special-binding
;; Evaluates to:
@result{} a-cont ;; the value of the (define a-cont...)
-
x
@result{} normal-binding
-
a-cont
@result{} special-binding
-@end example
+@end lisp
@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"