commit ce52e31de4a29305137089047e8ca68237b72b3e
parent 4d907354d4f578ad59e4a23ba1abd1dcaece311a
Author: Andres Navarro <canavarro82@gmail.com>
Date: Fri, 3 Jun 2011 14:07:10 -0300
Completed the keyed variables modules in the manual.
Diffstat:
8 files changed, 211 insertions(+), 17 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-150"></a>
+<p><a name="index-characters-152"></a>
<!-- *-texinfo-*- -->
</body></html>
diff --git a/manual/html/Index.html b/manual/html/Index.html
@@ -100,7 +100,7 @@ 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-150">characters</a>: <a href="Characters.html#Characters">Characters</a></li>
+<li><a href="Characters.html#index-characters-152">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>
@@ -143,7 +143,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<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-146">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-147">keyed static variables</a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
+<li><a href="Keyed-Variables.html#index-keyed-static-variables-148">keyed static variables</a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
<li><a href="Keyed-Variables.html#index-keyed-variables-145">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>
@@ -155,6 +155,8 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Encapsulations.html#index-make_002dencapsulation_002dtype-139"><code>make-encapsulation-type</code></a>: <a href="Encapsulations.html#Encapsulations">Encapsulations</a></li>
<li><a href="Environments.html#index-make_002denvironment-98"><code>make-environment</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Environments.html#index-make_002dkernel_002dstandard_002denvironment-103"><code>make-kernel-standard-environment</code></a>: <a href="Environments.html#Environments">Environments</a></li>
+<li><a href="Keyed-Variables.html#index-make_002dkeyed_002ddynamic_002dvariable-147"><code>make-keyed-dynamic-variable</code></a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
+<li><a href="Keyed-Variables.html#index-make_002dkeyed_002dstatic_002dvariable-149"><code>make-keyed-static-variable</code></a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
<li><a href="Combiners.html#index-map-124"><code>map</code></a>: <a href="Combiners.html#Combiners">Combiners</a></li>
<li><a href="Pairs-and-lists.html#index-map-78"><code>map</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-member_003f-85"><code>member?</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
@@ -163,7 +165,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-148">numbers</a>: <a href="Numbers.html#Numbers">Numbers</a></li>
+<li><a href="Numbers.html#index-numbers-150">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>
@@ -171,7 +173,7 @@ 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-151">ports</a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-ports-153">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-promise_003f-141"><code>promise?</code></a>: <a href="Promises.html#Promises">Promises</a></li>
<li><a href="Promises.html#index-promises-140">promises</a>: <a href="Promises.html#Promises">Promises</a></li>
@@ -180,7 +182,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<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-149">strings</a>: <a href="Strings.html#Strings">Strings</a></li>
+<li><a href="Strings.html#index-strings-151">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>
@@ -244,6 +246,10 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a name="toc_Encapsulations" href="Encapsulations.html#Encapsulations">10 Encapsulations</a>
<li><a name="toc_Promises" href="Promises.html#Promises">11 Promises</a>
<li><a name="toc_Keyed-Variables" href="Keyed-Variables.html#Keyed-Variables">12 Keyed Variables</a>
+<ul>
+<li><a href="Keyed-Variables.html#Keyed-Variables">12.1 Keyed Dynamic Variables</a>
+<li><a href="Keyed-Variables.html#Keyed-Variables">12.2 Keyed Static Variables</a>
+</li></ul>
<li><a name="toc_Numbers" href="Numbers.html#Numbers">13 Numbers</a>
<li><a name="toc_Strings" href="Strings.html#Strings">14 Strings</a>
<li><a name="toc_Characters" href="Characters.html#Characters">15 Characters</a>
diff --git a/manual/html/Keyed-Variables.html b/manual/html/Keyed-Variables.html
@@ -34,7 +34,72 @@ 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-145"></a><a name="index-keyed-dynamic-variables-146"></a><a name="index-keyed-static-variables-147"></a>
+<p><a name="index-keyed-variables-145"></a>
+ A keyed variable is a device that associates a non-symbolic key (in
+the form of an accessor applicative) with a value depending on the
+context in which lookup occurs. Kernel provides two types of keyed
+variables: dynamic & static. Keyed Dynamic Variables use the dynamic
+extent as context and Keyed Static Variables use the dynamic
+environment.
+
+<h3 class="section">12.1 Keyed Dynamic Variables</h3>
+
+<p><a name="index-keyed-dynamic-variables-146"></a><!-- add cf xref static -->
+<!-- TODO add xref to dynamic extent -->
+ A keyed dynamic variable is a device that associates a non-symbolic
+key (in the form of an accessor applicative) with a value depending on
+the dynamic extent in which lookup occurs.
+
+<div class="defun">
+— Applicative: <b>make-keyed-dynamic-variable</b> (<var>make-keyed-dynamic-variable</var>)<var><a name="index-make_002dkeyed_002ddynamic_002dvariable-147"></a></var><br>
+<blockquote><p> Returns a list of the form <code>(b a)</code>, where <code>b</code> and <code>a</code>
+are applicatives, as follows. Each call to
+<code>make-keyed-dynamic-variable</code> returns different <code>b</code> and
+<code>a</code>.
+
+ <ul>
+<li><code>b</code> is an applicative that takes two arguments, the second of
+which must be a combiner. It calls its second argument with no
+operands (nil operand tree) in a fresh empty environment, and returns
+the result.
+
+ <li><code>a</code> is an applicative that takes zero arguments. If the call to
+<code>a</code> occurs within the dynamic extent of a call to <code>b</code>, then
+<code>a</code> returns the value of the first argument passed to <code>b</code> in
+the smallest enclosing dynamic extent of a call to <code>b</code>. If the
+call to <code>a</code> is not within the dynamic extent of any call to
+<code>b</code>, an error is signaled.
+</ul>
+ </p></blockquote></div>
+
+<h3 class="section">12.2 Keyed Static Variables</h3>
+
+<p><a name="index-keyed-static-variables-148"></a> A keyed static variable is a device that binds data in an
+environment by a non-symbolic key, where the key is an accessor
+applicative.
+<!-- add cf xref dynamic -->
+
+<div class="defun">
+— Applicative: <b>make-keyed-static-variable</b> (<var>make-keyed-static-variable</var>)<var><a name="index-make_002dkeyed_002dstatic_002dvariable-149"></a></var><br>
+<blockquote><p> Returns a list of the form <code>(b a)</code>, where <code>b</code> and <code>a</code>
+are applicatives, as follows. Each call to <code>make-keyed-static-variable</code>
+returns different <code>b</code> and <code>a</code>.
+
+ <ul>
+<li><code>b</code> is an applicative that takes two arguments, the second of
+which must be an environment. It constructs and returns a
+child-environment of its second argument, with initially no local
+bindings.
+
+ <li><code>a</code> is an applicative that takes zero arguments. If the dynamic
+environment <code>e</code> of the call to a has an improper ancestor that
+was constructed by a call to <code>b</code>, then a returns the value of the
+first argument passed to <code>b</code> in the first such environment
+encountered by a depth-first traversal of the improper ancestors of
+<code>e</code>. If <code>e</code> has no improper ancestors constructed via
+<code>b</code>, an error is signaled.
+</ul>
+ </p></blockquote></div>
<!-- *-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-148"></a>
+<p><a name="index-numbers-150"></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-151"></a>
+<p><a name="index-ports-153"></a>
<!-- appendices -->
<!-- TODO -->
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-149"></a>
+<p><a name="index-strings-151"></a>
<!-- *-texinfo-*- -->
</body></html>
diff --git a/manual/klisp.info b/manual/klisp.info
@@ -1504,6 +1504,61 @@ File: klisp.info, Node: Keyed Variables, Next: Numbers, Prev: Promises, Up:
12 Keyed Variables
******************
+A keyed variable is a device that associates a non-symbolic key (in the
+form of an accessor applicative) with a value depending on the context
+in which lookup occurs. Kernel provides two types of keyed variables:
+dynamic & static. Keyed Dynamic Variables use the dynamic extent as
+context and Keyed Static Variables use the dynamic environment.
+
+12.1 Keyed Dynamic Variables
+============================
+
+A keyed dynamic variable is a device that associates a non-symbolic key
+(in the form of an accessor applicative) with a value depending on the
+dynamic extent in which lookup occurs.
+
+ -- Applicative: make-keyed-dynamic-variable
+ (make-keyed-dynamic-variable)
+ Returns a list of the form `(b a)', where `b' and `a' are
+ applicatives, as follows. Each call to
+ `make-keyed-dynamic-variable' returns different `b' and `a'.
+
+ * `b' is an applicative that takes two arguments, the second of
+ which must be a combiner. It calls its second argument with
+ no operands (nil operand tree) in a fresh empty environment,
+ and returns the result.
+
+ * `a' is an applicative that takes zero arguments. If the call
+ to `a' occurs within the dynamic extent of a call to `b', then
+ `a' returns the value of the first argument passed to `b' in
+ the smallest enclosing dynamic extent of a call to `b'. If the
+ call to `a' is not within the dynamic extent of any call to
+ `b', an error is signaled.
+
+12.2 Keyed Static Variables
+===========================
+
+A keyed static variable is a device that binds data in an environment
+by a non-symbolic key, where the key is an accessor applicative.
+
+ -- Applicative: make-keyed-static-variable (make-keyed-static-variable)
+ Returns a list of the form `(b a)', where `b' and `a' are
+ applicatives, as follows. Each call to
+ `make-keyed-static-variable' returns different `b' and `a'.
+
+ * `b' is an applicative that takes two arguments, the second of
+ which must be an environment. It constructs and returns a
+ child-environment of its second argument, with initially no
+ local bindings.
+
+ * `a' is an applicative that takes zero arguments. If the
+ dynamic environment `e' of the call to a has an improper
+ ancestor that was constructed by a call to `b', then a
+ returns the value of the first argument passed to `b' in the
+ first such environment encountered by a depth-first traversal
+ of the improper ancestors of `e'. If `e' has no improper
+ ancestors constructed via `b', an error is signaled.
+
File: klisp.info, Node: Numbers, Next: Strings, Prev: Keyed Variables, Up: Top
@@ -1647,8 +1702,8 @@ Index
* inert: Control. (line 6)
* inert?: Control. (line 11)
* Kernel history: Kernel History. (line 6)
-* keyed dynamic variables: Keyed Variables. (line 6)
-* keyed static variables: Keyed Variables. (line 6)
+* keyed dynamic variables: Keyed Variables. (line 15)
+* keyed static variables: Keyed Variables. (line 40)
* keyed variables: Keyed Variables. (line 6)
* length: Pairs and lists. (line 191)
* list: Pairs and lists. (line 72)
@@ -1660,6 +1715,8 @@ Index
* make-encapsulation-type: Encapsulations. (line 12)
* make-environment: Environments. (line 36)
* make-kernel-standard-environment: Environments. (line 119)
+* make-keyed-dynamic-variable: Keyed Variables. (line 21)
+* make-keyed-static-variable: Keyed Variables. (line 44)
* map <1>: Combiners. (line 96)
* map: Pairs and lists. (line 169)
* member?: Pairs and lists. (line 257)
@@ -1721,10 +1778,10 @@ Node: Continuations55810
Node: Encapsulations63984
Node: Promises65437
Node: Keyed Variables69360
-Node: Numbers69486
-Node: Strings69595
-Node: Characters69699
-Node: Ports69807
-Node: Index69903
+Node: Numbers72131
+Node: Strings72240
+Node: Characters72344
+Node: Ports72452
+Node: Index72548
End Tag Table
diff --git a/manual/src/keyed_vars.texi b/manual/src/keyed_vars.texi
@@ -6,5 +6,71 @@
@chapter Keyed Variables
@cindex keyed variables
+
+ A keyed variable is a device that associates a non-symbolic key (in
+the form of an accessor applicative) with a value depending on the
+context in which lookup occurs. Kernel provides two types of keyed
+variables: dynamic & static. Keyed Dynamic Variables use the dynamic
+extent as context and Keyed Static Variables use the dynamic
+environment.
+
+@section Keyed Dynamic Variables
@cindex keyed dynamic variables
+@c add cf xref static
+@c TODO add xref to dynamic extent
+ A keyed dynamic variable is a device that associates a non-symbolic
+key (in the form of an accessor applicative) with a value depending on
+the dynamic extent in which lookup occurs.
+
+@deffn Applicative make-keyed-dynamic-variable (make-keyed-dynamic-variable)
+ Returns a list of the form @code{(b a)}, where @code{b} and @code{a}
+are applicatives, as follows. Each call to
+@code{make-keyed-dynamic-variable} returns different @code{b} and
+@code{a}.
+
+@itemize @bullet
+@item
+@code{b} is an applicative that takes two arguments, the second of
+which must be a combiner. It calls its second argument with no
+operands (nil operand tree) in a fresh empty environment, and returns
+the result.
+
+@item
+@code{a} is an applicative that takes zero arguments. If the call to
+@code{a} occurs within the dynamic extent of a call to @code{b}, then
+@code{a} returns the value of the first argument passed to @code{b} in
+the smallest enclosing dynamic extent of a call to @code{b}. If the
+call to @code{a} is not within the dynamic extent of any call to
+@code{b}, an error is signaled.
+@end itemize
+@end deffn
+
+@section Keyed Static Variables
@cindex keyed static variables
+ A keyed static variable is a device that binds data in an
+environment by a non-symbolic key, where the key is an accessor
+applicative.
+@c add cf xref dynamic
+
+@deffn Applicative make-keyed-static-variable (make-keyed-static-variable)
+ Returns a list of the form @code{(b a)}, where @code{b} and @code{a}
+are applicatives, as follows. Each call to @code{make-keyed-static-variable}
+returns different @code{b} and @code{a}.
+
+@itemize @bullet
+@item
+@code{b} is an applicative that takes two arguments, the second of
+which must be an environment. It constructs and returns a
+child-environment of its second argument, with initially no local
+bindings.
+
+@item
+@code{a} is an applicative that takes zero arguments. If the dynamic
+environment @code{e} of the call to a has an improper ancestor that
+was constructed by a call to @code{b}, then a returns the value of the
+first argument passed to @code{b} in the first such environment
+encountered by a depth-first traversal of the improper ancestors of
+@code{e}. If @code{e} has no improper ancestors constructed via
+@code{b}, an error is signaled.
+@end itemize
+@end deffn
