elisp @@ macro

[bpt/guile.git] / doc / ref / api-control.texi

diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index 320812d..4253a20 100644 (file)
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010,
-@c   2011, 2012, 2013 Free Software Foundation, Inc.
+@c   2011, 2012, 2013, 2014 Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
 @node Control Mechanisms
@@ -494,14 +494,17 @@ those passed to @code{abort-to-prompt}.
 @end deffn
 
 @deffn {Scheme Procedure} make-prompt-tag [stem]
-Make a new prompt tag.  Currently prompt tags are generated symbols.
-This may change in some future Guile version.
+Make a new prompt tag.  A prompt tag is simply a unique object.
+Currently, a prompt tag is a fresh pair.  This may change in some future
+Guile version.
 @end deffn
 
 @deffn {Scheme Procedure} default-prompt-tag
 Return the default prompt tag.  Having a distinguished default prompt
 tag allows some useful prompt and abort idioms, discussed in the next
-section.
+section.  Note that @code{default-prompt-tag} is actually a parameter,
+and so may be dynamically rebound using @code{parameterize}.
+@xref{Parameters}.
 @end deffn
 
 @deffn {Scheme Procedure} abort-to-prompt tag val1 val2 @dots{}
@@ -574,9 +577,58 @@ both.
 
 Before moving on, we should mention that if the handler of a prompt is a
 @code{lambda} expression, and the first argument isn't referenced, an abort to
-that prompt will not cause a continuation to be reified. This can be an
+that prompt will not cause a continuation to be reified.  This can be an
 important efficiency consideration to keep in mind.
 
+@cindex continuation, escape
+One example where this optimization matters is @dfn{escape
+continuations}.  Escape continuations are delimited continuations whose
+only use is to make a non-local exit---i.e., to escape from the current
+continuation.  Such continuations are invoked only once, and for this
+reason they are sometimes called @dfn{one-shot continuations}.  A common
+use of escape continuations is when throwing an exception
+(@pxref{Exceptions}).
+
+The constructs below are syntactic sugar atop prompts to simplify the
+use of escape continuations.
+
+@deffn {Scheme Procedure} call-with-escape-continuation proc
+@deffnx {Scheme Procedure} call/ec proc
+Call @var{proc} with an escape continuation.
+
+In the example below, the @var{return} continuation is used to escape
+the continuation of the call to @code{fold}.
+
+@lisp
+(use-modules (ice-9 control)
+             (srfi srfi-1))
+
+(define (prefix x lst)
+  ;; Return all the elements before the first occurrence
+  ;; of X in LST.
+  (call/ec
+    (lambda (return)
+      (fold (lambda (element prefix)
+              (if (equal? element x)
+                  (return (reverse prefix))  ; escape `fold'
+                  (cons element prefix)))
+            '()
+            lst))))
+
+(prefix 'a '(0 1 2 a 3 4 5))
+@result{} (0 1 2)
+@end lisp
+@end deffn
+
+@deffn {Scheme Syntax} let-escape-continuation k body @dots{}
+@deffnx {Scheme Syntax} let/ec k body @dots{}
+Bind @var{k} within @var{body} to an escape continuation.
+
+This is equivalent to
+@code{(call/ec (lambda (@var{k}) @var{body} @dots{}))}.
+@end deffn
+
+
 @node Shift and Reset
 @subsubsection Shift, Reset, and All That
 
@@ -984,6 +1036,11 @@ to avoid the risk of confusion with POSIX signals.
 This manual prefers to speak of throwing and catching exceptions, since
 this terminology matches the corresponding Guile primitives.
 
+The exception mechanism described in this section has connections with
+@dfn{delimited continuations} (@pxref{Prompts}).  In particular,
+throwing an exception is akin to invoking an @dfn{escape continuation}
+(@pxref{Prompt Primitives, @code{call/ec}}).
+
 
 @node Catch
 @subsubsection Catching Exceptions
@@ -1130,13 +1187,13 @@ The @var{body_data} and @var{handler_data} parameters are passed to
 the respective calls so an application can communicate extra
 information to those functions.
 
-If the data consists of an @code{SCM} object, care should be taken
-that it isn't garbage collected while still required.  If the
-@code{SCM} is a local C variable, one way to protect it is to pass a
-pointer to that variable as the data parameter, since the C compiler
-will then know the value must be held on the stack.  Another way is to
-use @code{scm_remember_upto_here_1} (@pxref{Remembering During
-Operations}).
+If the data consists of an @code{SCM} object, care should be taken that
+it isn't garbage collected while still required.  If the @code{SCM} is a
+local C variable, one way to protect it is to pass a pointer to that
+variable as the data parameter, since the C compiler will then know the
+value must be held on the stack.  Another way is to use
+@code{scm_remember_upto_here_1} (@pxref{Foreign Object Memory
+Management}).
 @end deftypefn
 
 
@@ -1367,7 +1424,8 @@ Guile) formats using @code{display} and @code{~S} (was
 @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; If
-@var{key} is @code{out-of-range} or @code{wrong-type-arg},
+@var{key} is @code{out-of-range}, @code{wrong-type-arg},
+or @code{keyword-argument-error},
 it is a list containing the bad value; otherwise
 it will usually be @code{#f}.
 @end deffn