commit 5db885c480d8af3137cf1e381e12172b335c02aa
parent 211a9e758dc70ef09d6cb75243ab0401af6f6a8f
Author: Andres Navarro <canavarro82@gmail.com>
Date: Thu, 2 Jun 2011 20:40:49 -0300
Completed module continuations in the manual (TODO put some continuation content in the intro).
Diffstat:
11 files changed, 589 insertions(+), 24 deletions(-)
diff --git a/manual/html/Characters.html b/manual/html/Characters.html
@@ -34,7 +34,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<!-- node-name, next, previous, up -->
<h2 class="chapter">15 Characters</h2>
-<p><a name="index-characters-134"></a>
+<p><a name="index-characters-145"></a>
<!-- *-texinfo-*- -->
</body></html>
diff --git a/manual/html/Continuations.html b/manual/html/Continuations.html
@@ -35,6 +35,198 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<h2 class="chapter">9 Continuations</h2>
<p><a name="index-continuations-126"></a>
+ A continuation is a plan for all future computation, parameterized
+by a value to be provided, and contingent on the states of all mutable
+data structures (which notably may include environments). When the
+Kernel evaluator is invoked, the invoker provides a continuation to
+which the result of the evaluation will normally be returned.
+
+ <p>For example, when <code>$if</code> evaluates its test operand, the
+continuation provided for the result expects to be given a boolean
+value; and, depending on which boolean it gets, it will evaluate
+either the consequent or the alternative operand as a tail context —
+that is, the continuation provided for the result of evaluating the
+selected operand is the same continuation that was provided for the
+result of the call to <code>$if</code>.
+
+ <p>A Kernel program may sometimes capture a continuation; that is,
+acquire a reference to it as a first-class object. The basic means of
+continuation capture is applicative <code>call/cc</code>. Given a
+first-class continuation <code>c</code>, a combiner can be constructed that
+will abnormally pass its operand tree to <code>c</code> (as opposed to the
+<!-- TODO add xref to abnormal pass -->
+normal return of values to continuations). In the simplest case, the
+abnormally passed value arrives at <code>c</code> as if it had been normally
+returned to <code>c</code>. In general, continuations bypassed by the
+abnormal pass may have entry/exit guards attached to them, and these
+guards can intercept the abnormal pass before it reaches <code>c</code>.
+Each entry/exit guard consists of a selector continuation, which
+designates which abnormal passes the guard will intercept, and an
+interceptor applicative that performs the interception when selected.
+<!-- TODO add xref to guard-continuation, continuation->applicative -->
+<!-- and abnormal pass -->
+
+ <p>Continuations are immutable, and are <code>equal?</code> iff <code>eq?</code>.
+The continuation type is encapsulated.
+
+<!-- TODO add dynamic extent & guard selection/interception to the intro -->
+<div class="defun">
+— Applicative: <b>continuation?</b> (<var>continuation? . objects</var>)<var><a name="index-continuation_003f-127"></a></var><br>
+<blockquote><p> The primitive type predicate for type continuation.
+<code>continuation?</code> returns true iff all the objects in
+<code>objects</code> are of type continuation.
+</p></blockquote></div>
+
+<div class="defun">
+— Applicative: <b>call/cc</b> (<var>call/cc combiner</var>)<var><a name="index-call_002fcc-128"></a></var><br>
+<blockquote><p> Calls <code>combiner</code> in the dynamic environment as a tail context,
+passing as sole operand to it the continuation to which <code>call/cc</code>
+would normally return its result. (That is, constructs such a
+combination and evaluates it in the dynamic environment.)
+<!-- TODO add xref Cf. operative $let/cc , §7.3.2. -->
+</p></blockquote></div>
+
+<div class="defun">
+— Applicative: <b>extend-continuation</b> (<var>extend-continuation continuation applicative </var>[<var>environment</var>])<var><a name="index-extend_002dcontinuation-129"></a></var><br>
+<blockquote><p> The <code>extend-continuation</code> applicative constructs and returns a
+new child of <code>continuation</code> that, when it normally receives a
+value v, calls the underlying combiner of <code>applicative</code> with
+dynamic environment <code>environment</code> (or an empty environment if
+none was specified) and operand tree <code>v</code>, the result of the call
+normally to be returned to <code>continuation</code>.
+
+ <p>The following equivalnece defines the short version:
+ <pre class="example"> (extend-continuation c a) ==
+ (extend-continuation c a (make-environment))
+</pre>
+ </blockquote></div>
+
+<div class="defun">
+— Applicative: <b>guard-continuation</b> (<var>guard-continuation entry-guards continuation exit-guards</var>)<var><a name="index-guard_002dcontinuation-130"></a></var><br>
+<blockquote><p> <code>entry-guards</code> and <code>exit-guards</code> should each be a list of
+clauses; each clause should be a list of length two, whose first
+element is a continuation, and whose second element is an applicative
+whose underlying combiner is operative.
+
+ <p>Applicative <code>guard-continuation</code> constructs two continuations:
+a child of continuation, called the <code>outer continuation</code>; and a
+child of the <code>outer continuation</code>, called the <code>inner
+continuation</code>. The <code>inner continuation</code> is returned as the
+result of the call to <code>guard-continuation</code>.
+
+ <p>When the <code>inner continuation</code> normally receives a value, it
+passes the value normally to the <code>outer continuation</code>; and when
+the <code>outer continuation</code> normally receives a value, it passes the
+value normally to <code>continuation</code>. Thus, in the absence of
+abnormal passing, the inner and outer continuations each have the same
+behavior as <code>continuation</code>.
+
+ <p>The two elements of each guard clause are called, respectively, the
+<code>selector</code> and the <code>interceptor</code>. The <code>selector</code>
+continuation is used in deciding whether to intercept a given abnormal
+pass, and the <code>interceptor</code> applicative is called to perform
+<!-- TODO add xref to selection and interception -->
+customized action when interception occurs.
+
+ <!-- TODO add xref to evaluation structure -->
+ <p>At the beginning of the call to <code>guard-continuation</code>, internal
+copies are made of the evaluation structures of <code>entry-guards</code>
+and <code>exit-guards</code>, so that the selectors and interceptors
+contained in the arguments at that time remain fixed thereafter,
+independent of any subsequent mutations to the arguments.
+</p></blockquote></div>
+
+<div class="defun">
+— Applicative: <b>continuation->applicative</b> (<var>continuation->applicative continuation</var>)<var><a name="index-continuation_002d_003eapplicative-131"></a></var><br>
+<blockquote><p> Returns an applicative whose underlying operative abnormally passes
+its operand tree to <code>continuation</code>, thus: A series of
+interceptors are selected to handle the abnormal pass, and a
+continuation is derived that will normally perform all the
+interceptions in sequence and pass some value to the destination of
+the originally abnormal pass. The operand tree is then normally
+passed to the derived continuation.
+<!-- TODO add xref to selection and interception -->
+</p></blockquote></div>
+
+<div class="defun">
+— Variable: <b>root-continuation</b><var><a name="index-root_002dcontinuation-132"></a></var><br>
+<blockquote><p> This continuation is the ancestor of all other continuations. When
+it normally receives a value, it terminates the Kernel session. (For
+example, if the system is running a read-eval-print loop, it exits the
+loop.)
+<!-- TODO add xref Cf. applicative exit, §7.3.4. -->
+</p></blockquote></div>
+
+<div class="defun">
+— Variable: <b>error-continuation</b><var><a name="index-error_002dcontinuation-133"></a></var><br>
+<blockquote><p> The dynamic extent of this continuation is mutually disjoint from
+the dynamic extent in which Kernel computation usually occurs (such as
+the dynamic extent in which the Kernel system would run a
+read-eval-print loop).
+
+ <p>When this continuation normally receives a value, it provides a
+diagnostic message to the user of the Kernel system, on the assumption
+that the received value is an attempt to describe some error that
+aborted a computation; and then resumes operation of the Kernel system
+at some point that is outside of all user-defined computation. (For
+example, if the system is running a read-eval-print loop, operation
+may resume by continuing from the top of the loop.)
+
+ <p>The diagnostic message is not made available to any Kernel
+computation, and is therefore permitted to contain information that
+violates abstractions within the system.
+
+ <!-- TODO add details about klisp error messages -->
+ <p>When an error is signaled during a Kernel computation, the signaling
+action consists of an abnormal pass to some continuation in the
+dynamic extent of <code>error-continuation</code>.
+</p></blockquote></div>
+
+<div class="defun">
+— Applicative: <b>apply-continuation</b> (<var>apply-continuation continuation object</var>)<var><a name="index-apply_002dcontinuation-134"></a></var><br>
+<blockquote><p> Applicative <code>apply-continuation</code> converts its first argument to
+an applicative as if by <code>continuation->applicative</code>, and then
+applies it as usual.
+
+ <p>That is:
+ <pre class="example"> (apply-continuation continuation object) ==
+ (apply (continuation->applicative continuation) object)
+</pre>
+ </blockquote></div>
+
+<div class="defun">
+— Operative: <b>(</b><var>$let/cc <symbol> . <objects></var>)<var><a name="index-g_t_0028-135"></a></var><br>
+<blockquote><p> A child environment <code>e</code> of the dynamic environment is created,
+containing a binding of <code><symbol></code> to the continuation to which
+the result of the call to <code>$let/cc</code> should normally return; then,
+the subexpressions of <code><objects></code> are evaluated in <code>e</code> from
+left to right, with the last (if any) evaluated as a tail context, or
+if <code><objects></code> is empty the result is inert.
+
+ <p>That is:
+ <pre class="example"> ($let/cc symbol . objects) ==
+ (call/cc ($lambda (symbol) . objects))
+</pre>
+ </blockquote></div>
+
+<div class="defun">
+— Applicative: <b>guard-dynamic-extent</b> (<var>guard-dynamic-extent entry-guards combiner exit-guards</var>)<var><a name="index-guard_002ddynamic_002dextent-136"></a></var><br>
+<blockquote><p> This applicative extends the current continuation with the specified
+guards, and calls <code>combiner</code> in the dynamic extent of the new
+continuation, with no operands and the dynamic environment of the call
+to <code>guard-dynamic-extent</code>.
+</p></blockquote></div>
+
+<div class="defun">
+— Applicative: <b>exit</b> (<var>exit</var>)<var><a name="index-exit-137"></a></var><br>
+<blockquote><!-- TODO add xref -->
+ <p>Applicative <code>exit</code> initiates an abnormal transfer of
+<code>#inert</code> to <code>root-continuation</code>.
+
+ <p>That is:
+ <pre class="example"> (exit ) == (apply-continuation root-continuation #inert)
+</pre>
+ </blockquote></div>
<!-- *-texinfo-*- -->
</body></html>
diff --git a/manual/html/Encapsulations.html b/manual/html/Encapsulations.html
@@ -34,7 +34,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<!-- node-name, next, previous, up -->
<h2 class="chapter">10 Encapsulations</h2>
-<p><a name="index-encapsulations-127"></a>
+<p><a name="index-encapsulations-138"></a>
<!-- *-texinfo-*- -->
</body></html>
diff --git a/manual/html/Index.html b/manual/html/Index.html
@@ -54,6 +54,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Control.html#index-g_t_0024sequence-30"><code>$sequence</code></a>: <a href="Control.html#Control">Control</a></li>
<li><a href="Environments.html#index-g_t_0024set_0021-111"><code>$set!</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Combiners.html#index-g_t_0024vau-119"><code>$vau</code></a>: <a href="Combiners.html#Combiners">Combiners</a></li>
+<li><a href="Continuations.html#index-g_t_0028-135"><code>(</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
<li><a href="Environments.html#index-g_t_0028-110"><code>(</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Booleans.html#index-and_003f-15"><code>and?</code></a>: <a href="Booleans.html#Booleans">Booleans</a></li>
<li><a href="Pairs-and-lists.html#index-append-81"><code>append</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
@@ -62,6 +63,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Combiners.html#index-applicative_003f-118"><code>applicative?</code></a>: <a href="Combiners.html#Combiners">Combiners</a></li>
<li><a href="Combiners.html#index-applicatives-115">applicatives</a>: <a href="Combiners.html#Combiners">Combiners</a></li>
<li><a href="Combiners.html#index-apply-123"><code>apply</code></a>: <a href="Combiners.html#Combiners">Combiners</a></li>
+<li><a href="Continuations.html#index-apply_002dcontinuation-134"><code>apply-continuation</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
<li><a href="Pairs-and-lists.html#index-assoc-84"><code>assoc</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-assq-91"><code>assq</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Booleans.html#index-boolean_003f-13"><code>boolean?</code></a>: <a href="Booleans.html#Booleans">Booleans</a></li>
@@ -80,6 +82,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Pairs-and-lists.html#index-cadddr-66"><code>cadddr</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-caddr-54"><code>caddr</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-cadr-48"><code>cadr</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
+<li><a href="Continuations.html#index-call_002fcc-128"><code>call/cc</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
<li><a href="Pairs-and-lists.html#index-car-45"><code>car</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-cdaaar-67"><code>cdaaar</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-cdaadr-68"><code>cdaadr</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
@@ -96,10 +99,12 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Pairs-and-lists.html#index-cdddr-58"><code>cdddr</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-cddr-50"><code>cddr</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-cdr-46"><code>cdr</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
-<li><a href="Characters.html#index-characters-134">characters</a>: <a href="Characters.html#Characters">Characters</a></li>
+<li><a href="Characters.html#index-characters-145">characters</a>: <a href="Characters.html#Characters">Characters</a></li>
<li><a href="Combiners.html#index-combiner_003f-125"><code>combiner?</code></a>: <a href="Combiners.html#Combiners">Combiners</a></li>
<li><a href="Combiners.html#index-combiners-114">combiners</a>: <a href="Combiners.html#Combiners">Combiners</a></li>
<li><a href="Pairs-and-lists.html#index-cons-39"><code>cons</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
+<li><a href="Continuations.html#index-continuation_002d_003eapplicative-131"><code>continuation->applicative</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
+<li><a href="Continuations.html#index-continuation_003f-127"><code>continuation?</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
<li><a href="Continuations.html#index-continuations-126">continuations</a>: <a href="Continuations.html#Continuations">Continuations</a></li>
<li><a href="Control.html#index-control-26">control</a>: <a href="Control.html#Control">Control</a></li>
<li><a href="Pairs-and-lists.html#index-copy_002des-90"><code>copy-es</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
@@ -108,7 +113,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Format-of-Descriptions.html#index-description-format-7">description format</a>: <a href="Format-of-Descriptions.html#Format-of-Descriptions">Format of Descriptions</a></li>
<li><a href="Evaluation-Notation.html#index-documentation-notation-4">documentation notation</a>: <a href="Evaluation-Notation.html#Evaluation-Notation">Evaluation Notation</a></li>
<li><a href="Pairs-and-lists.html#index-empty-list-35">empty list</a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
-<li><a href="Encapsulations.html#index-encapsulations-127">encapsulations</a>: <a href="Encapsulations.html#Encapsulations">Encapsulations</a></li>
+<li><a href="Encapsulations.html#index-encapsulations-138">encapsulations</a>: <a href="Encapsulations.html#Encapsulations">Encapsulations</a></li>
<li><a href="Pairs-and-lists.html#index-encycle_0021-77"><code>encycle!</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Environments.html#index-environment_003f-95"><code>environment?</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Environments.html#index-environments-93">environments</a>: <a href="Environments.html#Environments">Environments</a></li>
@@ -116,8 +121,11 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Equivalence.html#index-equal_003f-21"><code>equal?</code></a>: <a href="Equivalence.html#Equivalence">Equivalence</a></li>
<li><a href="Equivalence.html#index-equivalence-19">equivalence</a>: <a href="Equivalence.html#Equivalence">Equivalence</a></li>
<li><a href="Error-Messages.html#index-error-message-notation-6">error message notation</a>: <a href="Error-Messages.html#Error-Messages">Error Messages</a></li>
+<li><a href="Continuations.html#index-error_002dcontinuation-133"><code>error-continuation</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
<li><a href="Environments.html#index-eval-97"><code>eval</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Evaluation-Notation.html#index-evaluation-notation-3">evaluation notation</a>: <a href="Evaluation-Notation.html#Evaluation-Notation">Evaluation Notation</a></li>
+<li><a href="Continuations.html#index-exit-137"><code>exit</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
+<li><a href="Continuations.html#index-extend_002dcontinuation-129"><code>extend-continuation</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
<li><a href="Pairs-and-lists.html#index-filter-83"><code>filter</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-finite_002dlist_003f-86"><code>finite-list?</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Some-Terms.html#index-fonts-2">fonts</a>: <a href="Some-Terms.html#Some-Terms">Some Terms</a></li>
@@ -125,14 +133,16 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Control.html#index-for_002deach-32"><code>for-each</code></a>: <a href="Control.html#Control">Control</a></li>
<li><a href="Environments.html#index-get_002dcurrent_002denvironment-102"><code>get-current-environment</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Pairs-and-lists.html#index-get_002dlist_002dmetrics-75"><code>get-list-metrics</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
+<li><a href="Continuations.html#index-guard_002dcontinuation-130"><code>guard-continuation</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
+<li><a href="Continuations.html#index-guard_002ddynamic_002dextent-136"><code>guard-dynamic-extent</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
<li><a href="Environments.html#index-ignore-94">ignore</a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Environments.html#index-ignore_003f-96"><code>ignore?</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Control.html#index-inert-27">inert</a>: <a href="Control.html#Control">Control</a></li>
<li><a href="Control.html#index-inert_003f-28"><code>inert?</code></a>: <a href="Control.html#Control">Control</a></li>
<li><a href="Kernel-History.html#index-Kernel-history-1">Kernel history</a>: <a href="Kernel-History.html#Kernel-History">Kernel History</a></li>
-<li><a href="Keyed-Variables.html#index-keyed-dynamic-variables-130">keyed dynamic variables</a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
-<li><a href="Keyed-Variables.html#index-keyed-static-variables-131">keyed static variables</a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
-<li><a href="Keyed-Variables.html#index-keyed-variables-129">keyed variables</a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
+<li><a href="Keyed-Variables.html#index-keyed-dynamic-variables-141">keyed dynamic variables</a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
+<li><a href="Keyed-Variables.html#index-keyed-static-variables-142">keyed static variables</a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
+<li><a href="Keyed-Variables.html#index-keyed-variables-140">keyed variables</a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
<li><a href="Pairs-and-lists.html#index-length-79"><code>length</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-list-43"><code>list</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-list_002a-44"><code>list*</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
@@ -149,7 +159,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Pairs-and-lists.html#index-nil-34">nil</a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Booleans.html#index-not_003f-14"><code>not?</code></a>: <a href="Booleans.html#Booleans">Booleans</a></li>
<li><a href="Pairs-and-lists.html#index-null_003f-38"><code>null?</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
-<li><a href="Numbers.html#index-numbers-132">numbers</a>: <a href="Numbers.html#Numbers">Numbers</a></li>
+<li><a href="Numbers.html#index-numbers-143">numbers</a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="A-Sample-Applicative-Description.html#index-object-descriptions-10">object descriptions</a>: <a href="A-Sample-Applicative-Description.html#A-Sample-Applicative-Description">A Sample Applicative Description</a></li>
<li><a href="A-Sample-Applicative-Description.html#index-operative-descriptions-9">operative descriptions</a>: <a href="A-Sample-Applicative-Description.html#A-Sample-Applicative-Description">A Sample Applicative Description</a></li>
<li><a href="Combiners.html#index-operative_003f-117"><code>operative?</code></a>: <a href="Combiners.html#Combiners">Combiners</a></li>
@@ -157,14 +167,15 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Booleans.html#index-or_003f-16"><code>or?</code></a>: <a href="Booleans.html#Booleans">Booleans</a></li>
<li><a href="Pairs-and-lists.html#index-pair_003f-37"><code>pair?</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-pairs-33">pairs</a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
-<li><a href="Ports.html#index-ports-135">ports</a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-ports-146">ports</a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Printing-Notation.html#index-printing-notation-5">printing notation</a>: <a href="Printing-Notation.html#Printing-Notation">Printing Notation</a></li>
-<li><a href="Promises.html#index-promises-128">promises</a>: <a href="Promises.html#Promises">Promises</a></li>
+<li><a href="Promises.html#index-promises-139">promises</a>: <a href="Promises.html#Promises">Promises</a></li>
<li><a href="Pairs-and-lists.html#index-reduce-88"><code>reduce</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
+<li><a href="Continuations.html#index-root_002dcontinuation-132"><code>root-continuation</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
<li><a href="Pairs-and-lists.html#index-set_002dcar_0021-40"><code>set-car!</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-set_002dcdr_0021-41"><code>set-cdr!</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Symbols.html#index-string_002d_003esymbol-25"><code>string->symbol</code></a>: <a href="Symbols.html#Symbols">Symbols</a></li>
-<li><a href="Strings.html#index-strings-133">strings</a>: <a href="Strings.html#Strings">Strings</a></li>
+<li><a href="Strings.html#index-strings-144">strings</a>: <a href="Strings.html#Strings">Strings</a></li>
<li><a href="Symbols.html#index-symbol_002d_003estring-24"><code>symbol->string</code></a>: <a href="Symbols.html#Symbols">Symbols</a></li>
<li><a href="Symbols.html#index-symbol_003f-23"><code>symbol?</code></a>: <a href="Symbols.html#Symbols">Symbols</a></li>
<li><a href="Symbols.html#index-symbols-22">symbols</a>: <a href="Symbols.html#Symbols">Symbols</a></li>
diff --git a/manual/html/Keyed-Variables.html b/manual/html/Keyed-Variables.html
@@ -34,7 +34,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<!-- node-name, next, previous, up -->
<h2 class="chapter">12 Keyed Variables</h2>
-<p><a name="index-keyed-variables-129"></a><a name="index-keyed-dynamic-variables-130"></a><a name="index-keyed-static-variables-131"></a>
+<p><a name="index-keyed-variables-140"></a><a name="index-keyed-dynamic-variables-141"></a><a name="index-keyed-static-variables-142"></a>
<!-- *-texinfo-*- -->
</body></html>
diff --git a/manual/html/Numbers.html b/manual/html/Numbers.html
@@ -34,7 +34,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<!-- node-name, next, previous, up -->
<h2 class="chapter">13 Numbers</h2>
-<p><a name="index-numbers-132"></a>
+<p><a name="index-numbers-143"></a>
<!-- *-texinfo-*- -->
</body></html>
diff --git a/manual/html/Ports.html b/manual/html/Ports.html
@@ -34,7 +34,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<!-- node-name, next, previous, up -->
<h2 class="chapter">16 Ports</h2>
-<p><a name="index-ports-135"></a>
+<p><a name="index-ports-146"></a>
<!-- appendices -->
<!-- TODO -->
diff --git a/manual/html/Promises.html b/manual/html/Promises.html
@@ -34,7 +34,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<!-- node-name, next, previous, up -->
<h2 class="chapter">11 Promises</h2>
-<p><a name="index-promises-128"></a>
+<p><a name="index-promises-139"></a>
<!-- *-texinfo-*- -->
</body></html>
diff --git a/manual/html/Strings.html b/manual/html/Strings.html
@@ -34,7 +34,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<!-- node-name, next, previous, up -->
<h2 class="chapter">14 Strings</h2>
-<p><a name="index-strings-133"></a>
+<p><a name="index-strings-144"></a>
<!-- *-texinfo-*- -->
</body></html>
diff --git a/manual/klisp.info b/manual/klisp.info
@@ -1209,6 +1209,168 @@ File: klisp.info, Node: Continuations, Next: Encapsulations, Prev: Combiners,
9 Continuations
***************
+A continuation is a plan for all future computation, parameterized by a
+value to be provided, and contingent on the states of all mutable data
+structures (which notably may include environments). When the Kernel
+evaluator is invoked, the invoker provides a continuation to which the
+result of the evaluation will normally be returned.
+
+ For example, when `$if' evaluates its test operand, the continuation
+provided for the result expects to be given a boolean value; and,
+depending on which boolean it gets, it will evaluate either the
+consequent or the alternative operand as a tail context — that is, the
+continuation provided for the result of evaluating the selected operand
+is the same continuation that was provided for the result of the call
+to `$if'.
+
+ A Kernel program may sometimes capture a continuation; that is,
+acquire a reference to it as a first-class object. The basic means of
+continuation capture is applicative `call/cc'. Given a first-class
+continuation `c', a combiner can be constructed that will abnormally
+pass its operand tree to `c' (as opposed to the normal return of values
+to continuations). In the simplest case, the abnormally passed value
+arrives at `c' as if it had been normally returned to `c'. In general,
+continuations bypassed by the abnormal pass may have entry/exit guards
+attached to them, and these guards can intercept the abnormal pass
+before it reaches `c'. Each entry/exit guard consists of a selector
+continuation, which designates which abnormal passes the guard will
+intercept, and an interceptor applicative that performs the
+interception when selected.
+
+ Continuations are immutable, and are `equal?' iff `eq?'. The
+continuation type is encapsulated.
+
+ -- Applicative: continuation? (continuation? . objects)
+ The primitive type predicate for type continuation.
+ `continuation?' returns true iff all the objects in `objects' are
+ of type continuation.
+
+ -- Applicative: call/cc (call/cc combiner)
+ Calls `combiner' in the dynamic environment as a tail context,
+ passing as sole operand to it the continuation to which `call/cc'
+ would normally return its result. (That is, constructs such a
+ combination and evaluates it in the dynamic environment.)
+
+ -- Applicative: extend-continuation (extend-continuation continuation
+ applicative [environment])
+ The `extend-continuation' applicative constructs and returns a new
+ child of `continuation' that, when it normally receives a value v,
+ calls the underlying combiner of `applicative' with dynamic
+ environment `environment' (or an empty environment if none was
+ specified) and operand tree `v', the result of the call normally
+ to be returned to `continuation'.
+
+ The following equivalnece defines the short version:
+ (extend-continuation c a) ==
+ (extend-continuation c a (make-environment))
+
+ -- Applicative: guard-continuation (guard-continuation entry-guards
+ continuation exit-guards)
+ `entry-guards' and `exit-guards' should each be a list of clauses;
+ each clause should be a list of length two, whose first element is
+ a continuation, and whose second element is an applicative whose
+ underlying combiner is operative.
+
+ Applicative `guard-continuation' constructs two continuations: a
+ child of continuation, called the `outer continuation'; and a
+ child of the `outer continuation', called the `inner
+ continuation'. The `inner continuation' is returned as the result
+ of the call to `guard-continuation'.
+
+ When the `inner continuation' normally receives a value, it passes
+ the value normally to the `outer continuation'; and when the
+ `outer continuation' normally receives a value, it passes the
+ value normally to `continuation'. Thus, in the absence of abnormal
+ passing, the inner and outer continuations each have the same
+ behavior as `continuation'.
+
+ The two elements of each guard clause are called, respectively, the
+ `selector' and the `interceptor'. The `selector' continuation is
+ used in deciding whether to intercept a given abnormal pass, and
+ the `interceptor' applicative is called to perform customized
+ action when interception occurs.
+
+ At the beginning of the call to `guard-continuation', internal
+ copies are made of the evaluation structures of `entry-guards' and
+ `exit-guards', so that the selectors and interceptors contained in
+ the arguments at that time remain fixed thereafter, independent of
+ any subsequent mutations to the arguments.
+
+ -- Applicative: continuation->applicative (continuation->applicative
+ continuation)
+ Returns an applicative whose underlying operative abnormally passes
+ its operand tree to `continuation', thus: A series of interceptors
+ are selected to handle the abnormal pass, and a continuation is
+ derived that will normally perform all the interceptions in
+ sequence and pass some value to the destination of the originally
+ abnormal pass. The operand tree is then normally passed to the
+ derived continuation.
+
+ -- Variable: root-continuation
+ This continuation is the ancestor of all other continuations. When
+ it normally receives a value, it terminates the Kernel session.
+ (For example, if the system is running a read-eval-print loop, it
+ exits the loop.)
+
+ -- Variable: error-continuation
+ The dynamic extent of this continuation is mutually disjoint from
+ the dynamic extent in which Kernel computation usually occurs
+ (such as the dynamic extent in which the Kernel system would run a
+ read-eval-print loop).
+
+ When this continuation normally receives a value, it provides a
+ diagnostic message to the user of the Kernel system, on the
+ assumption that the received value is an attempt to describe some
+ error that aborted a computation; and then resumes operation of
+ the Kernel system at some point that is outside of all
+ user-defined computation. (For example, if the system is running a
+ read-eval-print loop, operation may resume by continuing from the
+ top of the loop.)
+
+ The diagnostic message is not made available to any Kernel
+ computation, and is therefore permitted to contain information that
+ violates abstractions within the system.
+
+ When an error is signaled during a Kernel computation, the
+ signaling action consists of an abnormal pass to some continuation
+ in the dynamic extent of `error-continuation'.
+
+ -- Applicative: apply-continuation (apply-continuation continuation
+ object)
+ Applicative `apply-continuation' converts its first argument to an
+ applicative as if by `continuation->applicative', and then applies
+ it as usual.
+
+ That is:
+ (apply-continuation continuation object) ==
+ (apply (continuation->applicative continuation) object)
+
+ -- Operative: ($let/cc <symbol> . <objects>)
+ A child environment `e' of the dynamic environment is created,
+ containing a binding of `<symbol>' to the continuation to which
+ the result of the call to `$let/cc' should normally return; then,
+ the subexpressions of `<objects>' are evaluated in `e' from left
+ to right, with the last (if any) evaluated as a tail context, or
+ if `<objects>' is empty the result is inert.
+
+ That is:
+ ($let/cc symbol . objects) ==
+ (call/cc ($lambda (symbol) . objects))
+
+ -- Applicative: guard-dynamic-extent (guard-dynamic-extent
+ entry-guards combiner exit-guards)
+ This applicative extends the current continuation with the
+ specified guards, and calls `combiner' in the dynamic extent of
+ the new continuation, with no operands and the dynamic environment
+ of the call to `guard-dynamic-extent'.
+
+ -- Applicative: exit (exit)
+ Applicative `exit' initiates an abnormal transfer of `#inert' to
+ `root-continuation'.
+
+ That is:
+ (exit ) == (apply-continuation root-continuation #inert)
+
File: klisp.info, Node: Encapsulations, Next: Promises, Prev: Continuations, Up: Top
@@ -1279,6 +1441,7 @@ Index
* $sequence: Control. (line 23)
* $set!: Environments. (line 182)
* $vau: Combiners. (line 26)
+* ( <1>: Continuations. (line 143)
* (: Environments. (line 174)
* and?: Booleans. (line 20)
* append: Pairs and lists. (line 208)
@@ -1288,6 +1451,7 @@ Index
* applicative?: Combiners. (line 21)
* applicatives: Combiners. (line 6)
* apply: Combiners. (line 83)
+* apply-continuation: Continuations. (line 134)
* assoc: Pairs and lists. (line 252)
* assq: Pairs and lists. (line 333)
* boolean?: Booleans. (line 12)
@@ -1306,6 +1470,7 @@ Index
* cadddr: Pairs and lists. (line 108)
* caddr: Pairs and lists. (line 96)
* cadr: Pairs and lists. (line 90)
+* call/cc: Continuations. (line 43)
* car: Pairs and lists. (line 85)
* cdaaar: Pairs and lists. (line 109)
* cdaadr: Pairs and lists. (line 110)
@@ -1326,6 +1491,8 @@ Index
* combiner?: Combiners. (line 120)
* combiners: Combiners. (line 6)
* cons: Pairs and lists. (line 35)
+* continuation->applicative: Continuations. (line 95)
+* continuation?: Continuations. (line 38)
* continuations: Continuations. (line 6)
* control: Control. (line 6)
* copy-es: Pairs and lists. (line 321)
@@ -1343,8 +1510,11 @@ Index
* equal?: Equivalence. (line 16)
* equivalence: Equivalence. (line 6)
* error message notation: Error Messages. (line 6)
+* error-continuation: Continuations. (line 110)
* eval: Environments. (line 32)
* evaluation notation: Evaluation Notation. (line 6)
+* exit: Continuations. (line 162)
+* extend-continuation: Continuations. (line 50)
* filter: Pairs and lists. (line 239)
* finite-list?: Pairs and lists. (line 261)
* fonts: Some Terms. (line 13)
@@ -1353,6 +1523,8 @@ Index
* for-each: Control. (line 42)
* get-current-environment: Environments. (line 114)
* get-list-metrics: Pairs and lists. (line 123)
+* guard-continuation: Continuations. (line 63)
+* guard-dynamic-extent: Continuations. (line 156)
* ignore: Environments. (line 6)
* ignore?: Environments. (line 28)
* inert: Control. (line 6)
@@ -1391,6 +1563,7 @@ Index
* printing notation: Printing Notation. (line 6)
* promises: Promises. (line 6)
* reduce: Pairs and lists. (line 270)
+* root-continuation: Continuations. (line 104)
* set-car!: Pairs and lists. (line 41)
* set-cdr!: Pairs and lists. (line 42)
* string->symbol: Symbols. (line 20)
@@ -1425,13 +1598,13 @@ Node: Pairs and lists21741
Node: Environments38764
Node: Combiners48971
Node: Continuations55007
-Node: Encapsulations55133
-Node: Promises55262
-Node: Keyed Variables55381
-Node: Numbers55507
-Node: Strings55616
-Node: Characters55720
-Node: Ports55828
-Node: Index55924
+Node: Encapsulations63181
+Node: Promises63310
+Node: Keyed Variables63429
+Node: Numbers63555
+Node: Strings63664
+Node: Characters63768
+Node: Ports63876
+Node: Index63972
End Tag Table
diff --git a/manual/src/continuations.texi b/manual/src/continuations.texi
@@ -7,3 +7,192 @@
@chapter Continuations
@cindex continuations
+ A continuation is a plan for all future computation, parameterized
+by a value to be provided, and contingent on the states of all mutable
+data structures (which notably may include environments). When the
+Kernel evaluator is invoked, the invoker provides a continuation to
+which the result of the evaluation will normally be returned.
+
+ For example, when @code{$if} evaluates its test operand, the
+continuation provided for the result expects to be given a boolean
+value; and, depending on which boolean it gets, it will evaluate
+either the consequent or the alternative operand as a tail context —
+that is, the continuation provided for the result of evaluating the
+selected operand is the same continuation that was provided for the
+result of the call to @code{$if}.
+
+ A Kernel program may sometimes capture a continuation; that is,
+acquire a reference to it as a first-class object. The basic means of
+continuation capture is applicative @code{call/cc}. Given a
+first-class continuation @code{c}, a combiner can be constructed that
+will abnormally pass its operand tree to @code{c} (as opposed to the
+@c TODO add xref to abnormal pass
+normal return of values to continuations). In the simplest case, the
+abnormally passed value arrives at @code{c} as if it had been normally
+returned to @code{c}. In general, continuations bypassed by the
+abnormal pass may have entry/exit guards attached to them, and these
+guards can intercept the abnormal pass before it reaches @code{c}.
+Each entry/exit guard consists of a selector continuation, which
+designates which abnormal passes the guard will intercept, and an
+interceptor applicative that performs the interception when selected.
+@c TODO add xref to guard-continuation, continuation->applicative
+@c and abnormal pass
+
+ Continuations are immutable, and are @code{equal?} iff @code{eq?}.
+The continuation type is encapsulated.
+
+@c TODO add dynamic extent & guard selection/interception to the intro
+@deffn Applicative continuation? (continuation? . objects)
+ The primitive type predicate for type continuation.
+@code{continuation?} returns true iff all the objects in
+@code{objects} are of type continuation.
+@end deffn
+
+@deffn Applicative call/cc (call/cc combiner)
+ Calls @code{combiner} in the dynamic environment as a tail context,
+passing as sole operand to it the continuation to which @code{call/cc}
+would normally return its result. (That is, constructs such a
+combination and evaluates it in the dynamic environment.)
+@c TODO add xref Cf. operative $let/cc , §7.3.2.
+@end deffn
+
+@deffn Applicative extend-continuation (extend-continuation continuation applicative [environment])
+ The @code{extend-continuation} applicative constructs and returns a
+new child of @code{continuation} that, when it normally receives a
+value v, calls the underlying combiner of @code{applicative} with
+dynamic environment @code{environment} (or an empty environment if
+none was specified) and operand tree @code{v}, the result of the call
+normally to be returned to @code{continuation}.
+
+ The following equivalnece defines the short version:
+@example
+(extend-continuation c a) @equiv{}
+ (extend-continuation c a (make-environment))
+@end example
+@end deffn
+
+@deffn Applicative guard-continuation (guard-continuation entry-guards continuation exit-guards)
+ @code{entry-guards} and @code{exit-guards} should each be a list of
+clauses; each clause should be a list of length two, whose first
+element is a continuation, and whose second element is an applicative
+whose underlying combiner is operative.
+
+ Applicative @code{guard-continuation} constructs two continuations:
+a child of continuation, called the @code{outer continuation}; and a
+child of the @code{outer continuation}, called the @code{inner
+continuation}. The @code{inner continuation} is returned as the
+result of the call to @code{guard-continuation}.
+
+ When the @code{inner continuation} normally receives a value, it
+passes the value normally to the @code{outer continuation}; and when
+the @code{outer continuation} normally receives a value, it passes the
+value normally to @code{continuation}. Thus, in the absence of
+abnormal passing, the inner and outer continuations each have the same
+behavior as @code{continuation}.
+
+ The two elements of each guard clause are called, respectively, the
+@code{selector} and the @code{interceptor}. The @code{selector}
+continuation is used in deciding whether to intercept a given abnormal
+pass, and the @code{interceptor} applicative is called to perform
+@c TODO add xref to selection and interception
+customized action when interception occurs.
+
+@c TODO add xref to evaluation structure
+At the beginning of the call to @code{guard-continuation}, internal
+copies are made of the evaluation structures of @code{entry-guards}
+and @code{exit-guards}, so that the selectors and interceptors
+contained in the arguments at that time remain fixed thereafter,
+independent of any subsequent mutations to the arguments.
+@end deffn
+
+@deffn Applicative continuation->applicative (continuation->applicative continuation)
+ Returns an applicative whose underlying operative abnormally passes
+its operand tree to @code{continuation}, thus: A series of
+interceptors are selected to handle the abnormal pass, and a
+continuation is derived that will normally perform all the
+interceptions in sequence and pass some value to the destination of
+the originally abnormal pass. The operand tree is then normally
+passed to the derived continuation.
+@c TODO add xref to selection and interception
+@end deffn
+
+@defvar root-continuation
+ This continuation is the ancestor of all other continuations. When
+it normally receives a value, it terminates the Kernel session. (For
+example, if the system is running a read-eval-print loop, it exits the
+loop.)
+@c TODO add xref Cf. applicative exit, §7.3.4.
+@end defvar
+
+@defvar error-continuation
+ The dynamic extent of this continuation is mutually disjoint from
+the dynamic extent in which Kernel computation usually occurs (such as
+the dynamic extent in which the Kernel system would run a
+read-eval-print loop).
+
+ When this continuation normally receives a value, it provides a
+diagnostic message to the user of the Kernel system, on the assumption
+that the received value is an attempt to describe some error that
+aborted a computation; and then resumes operation of the Kernel system
+at some point that is outside of all user-defined computation. (For
+example, if the system is running a read-eval-print loop, operation
+may resume by continuing from the top of the loop.)
+
+ The diagnostic message is not made available to any Kernel
+computation, and is therefore permitted to contain information that
+violates abstractions within the system.
+
+@c TODO add details about klisp error messages
+ When an error is signaled during a Kernel computation, the signaling
+action consists of an abnormal pass to some continuation in the
+dynamic extent of @code{error-continuation}.
+@end defvar
+
+@deffn Applicative apply-continuation (apply-continuation continuation object)
+ Applicative @code{apply-continuation} converts its first argument to
+an applicative as if by @code{continuation->applicative}, and then
+applies it as usual.
+
+ That is:
+@example
+(apply-continuation continuation object) @equiv{}
+ (apply (continuation->applicative continuation) object)
+@end example
+@end deffn
+
+@deffn Operative ($let/cc <symbol> . <objects>)
+ A child environment @code{e} of the dynamic environment is created,
+containing a binding of @code{<symbol>} to the continuation to which
+the result of the call to @code{$let/cc} should normally return; then,
+the subexpressions of @code{<objects>} are evaluated in @code{e} from
+left to right, with the last (if any) evaluated as a tail context, or
+if @code{<objects>} is empty the result is inert.
+
+ That is:
+@example
+($let/cc symbol . objects) @equiv{}
+ (call/cc ($lambda (symbol) . objects))
+@end example
+@end deffn
+
+@deffn Applicative guard-dynamic-extent (guard-dynamic-extent entry-guards combiner exit-guards)
+ This applicative extends the current continuation with the specified
+guards, and calls @code{combiner} in the dynamic extent of the new
+continuation, with no operands and the dynamic environment of the call
+to @code{guard-dynamic-extent}.
+@end deffn
+
+@deffn Applicative exit (exit)
+@c TODO add xref
+ Applicative @code{exit} initiates an abnormal transfer of
+@code{#inert} to @code{root-continuation}.
+
+ That is:
+@example
+(exit ) @equiv{} (apply-continuation root-continuation #inert)
+@end example
+@end deffn
+
+
+
+
