commit 38e25e17874ca8ebc41902dc46d494efe73c156b
parent b4fef6372f6691b4baf598a4eb6414f696155bc6
Author: Andres Navarro <canavarro82@gmail.com>
Date: Tue, 31 May 2011 13:45:33 -0300
Added control module to the manual. Added some text to the intro to specify that in the equivalence examples the names stand for the first class combiners, not the symbols.
Diffstat:
10 files changed, 191 insertions(+), 42 deletions(-)
diff --git a/manual/html/Evaluation-Notation.html b/manual/html/Evaluation-Notation.html
@@ -51,5 +51,11 @@ equivalences:
<pre class="example"> (list* arg1) == arg1
(list* arg1 . more-args) == (cons arg1 (list* . more-args))
</pre>
+ <p>Notice that in these kind of examples the applicatives or operatives
+referred to are the first class values and not the symbols bound to
+them in the ground environment. This definition would hold even if
+<code>cons</code> or <code>list*</code> were redefined in the current dynamic
+environment.
+
</body></html>
diff --git a/manual/html/Index.html b/manual/html/Index.html
@@ -5,7 +5,7 @@
<meta name="description" content="klisp Reference Manual">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
-<link rel="prev" href="Symbols.html#Symbols" title="Symbols">
+<link rel="prev" href="Control.html#Control" title="Control">
<link rel="next" href="../index.html#dir" title="(dir)">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
@@ -26,7 +26,7 @@
<a name="Index"></a>
<p>
Next: <a rel="next" accesskey="n" href="../index.html#dir">(dir)</a>,
-Previous: <a rel="previous" accesskey="p" href="Symbols.html#Symbols">Symbols</a>,
+Previous: <a rel="previous" accesskey="p" href="Control.html#Control">Control</a>,
Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<hr>
</div>
@@ -36,11 +36,15 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<ul class="index-fn" compact>
<li><a href="Booleans.html#index-g_t_0024and_003f-17"><code>$and?</code></a>: <a href="Booleans.html#Booleans">Booleans</a></li>
+<li><a href="Control.html#index-g_t_0024cond-30"><code>$cond</code></a>: <a href="Control.html#Control">Control</a></li>
+<li><a href="Control.html#index-g_t_0024if-28"><code>$if</code></a>: <a href="Control.html#Control">Control</a></li>
<li><a href="Booleans.html#index-g_t_0024or_003f-18"><code>$or?</code></a>: <a href="Booleans.html#Booleans">Booleans</a></li>
+<li><a href="Control.html#index-g_t_0024sequence-29"><code>$sequence</code></a>: <a href="Control.html#Control">Control</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="A-Sample-Applicative-Description.html#index-applicative-descriptions-8">applicative descriptions</a>: <a href="A-Sample-Applicative-Description.html#A-Sample-Applicative-Description">A Sample Applicative Description</a></li>
<li><a href="Booleans.html#index-boolean_003f-13"><code>boolean?</code></a>: <a href="Booleans.html#Booleans">Booleans</a></li>
<li><a href="Booleans.html#index-booleans-12">booleans</a>: <a href="Booleans.html#Booleans">Booleans</a></li>
+<li><a href="Control.html#index-control-26">control</a>: <a href="Control.html#Control">Control</a></li>
<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="Equivalence.html#index-eq_003f-20"><code>eq?</code></a>: <a href="Equivalence.html#Equivalence">Equivalence</a></li>
@@ -50,6 +54,8 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<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="Some-Terms.html#index-fonts-2">fonts</a>: <a href="Some-Terms.html#Some-Terms">Some Terms</a></li>
<li><a href="A-Sample-Applicative-Description.html#index-foo-11"><code>foo</code></a>: <a href="A-Sample-Applicative-Description.html#A-Sample-Applicative-Description">A Sample Applicative Description</a></li>
+<li><a href="Control.html#index-for_002deach-31"><code>for-each</code></a>: <a href="Control.html#Control">Control</a></li>
+<li><a href="Control.html#index-inert_003f-27"><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="Booleans.html#index-not_003f-14"><code>not?</code></a>: <a href="Booleans.html#Booleans">Booleans</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>
@@ -70,6 +76,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Index.html#toc_Booleans">2 Booleans</a></li>
<li><a href="Index.html#toc_Equivalence">3 Equivalence</a></li>
<li><a href="Index.html#toc_Symbols">4 Symbols</a></li>
+<li><a href="Index.html#toc_Control">5 Control</a></li>
<li><a href="Index.html#toc_Index">Index</a></li>
</ul>
</div>
@@ -98,6 +105,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a name="toc_Booleans" href="Booleans.html#Booleans">2 Booleans</a>
<li><a name="toc_Equivalence" href="Equivalence.html#Equivalence">3 Equivalence</a>
<li><a name="toc_Symbols" href="Symbols.html#Symbols">4 Symbols</a>
+<li><a name="toc_Control" href="Control.html#Control">5 Control</a>
<li><a name="toc_Index" href="Index.html#Index">Index</a>
</li></ul>
</div>
diff --git a/manual/html/index.html b/manual/html/index.html
@@ -41,8 +41,9 @@ Up: <a rel="up" accesskey="u" href="../index.html#dir">(dir)</a>
<li><a accesskey="4" href="Equivalence.html#Equivalence">Equivalence</a>: Equivalence under mutation & Equivalence up to
mutation module features.
<li><a accesskey="5" href="Symbols.html#Symbols">Symbols</a>: Symbol module features.
+<li><a accesskey="6" href="Control.html#Control">Control</a>: Control module features.
<!-- TODO complete -->
-<li><a accesskey="6" href="Index.html#Index">Index</a>: Index including concepts, functions, variables,
+<li><a accesskey="7" href="Index.html#Index">Index</a>: Index including concepts, functions, variables,
and other terms.
<!-- Appendices -->
diff --git a/manual/klisp.info b/manual/klisp.info
@@ -30,6 +30,7 @@ in part.
* Equivalence:: Equivalence under mutation & Equivalence up to
mutation module features.
* Symbols:: Symbol module features.
+* Control:: Control module features.
* Index:: Index including concepts, functions, variables,
and other terms.
@@ -239,6 +240,10 @@ equivalent. This is notated with `=='. For example, the semantics of
applicative list* can be defined by following equivalences:
(list* arg1) == arg1
(list* arg1 . more-args) == (cons arg1 (list* . more-args))
+ Notice that in these kind of examples the applicatives or operatives
+referred to are the first class values and not the symbols bound to
+them in the ground environment. This definition would hold even if
+`cons' or `list*' were redefined in the current dynamic environment.
File: klisp.info, Node: Printing Notation, Next: Error Messages, Prev: Evaluation Notation, Up: Conventions
@@ -370,30 +375,30 @@ boolean type is encapsulated.
Applicative `or?' is a predicate that returns false unless one or
more of its arguments are true.
- -- Operative: $and? ($and? . list)
+ -- Operative: $and? ($and? . <list>)
The `$and?' operative performs a "short-circuit and" of its
operands. It evaluates them from left to right, until either an
operand evaluates to false, or the end of the list is reached. If
- the end of the list is reached (which is immediate if `list' is
+ the end of the list is reached (which is immediate if `<list>' is
`nil'), the operative returns true. If an operand evaluates to
false, no further operand evaluations are performed, and the
- operative returns false. If `list' is acyclic, and the last
+ operative returns false. If `<list>' is acyclic, and the last
operand is evaluated, it is evaluated as a tail context. If
- `list' is cyclic, an unbounded number of operand evaluations may be
- performed. If any of the operands evaluates to a non-boolean
+ `<list>' is cyclic, an unbounded number of operand evaluations may
+ be performed. If any of the operands evaluates to a non-boolean
value, an error is signaled (even if it's the last one).
- -- Operative: $or? ($or? . list)
+ -- Operative: $or? ($or? . <list>)
The `$or?' operative performs a "short-circuit or" of its
operands. It evaluates them from left to right, until either an
operand evaluates to true, or the end of the list is reached. If
- the end of the list is reached (which is immediate if `list' is
+ the end of the list is reached (which is immediate if `<list>' is
`nil'), the operative returns false. If an operand evaluates to
true, no further operand evaluations are performed, and the
- operative returns true. If `list' is acyclic, and the last
+ operative returns true. If `<list>' is acyclic, and the last
operand is evaluated, it is evaluated as a tail context. If
- `list' is cyclic, an unbounded number of operand evaluations may be
- performed. If any of the operands evaluates to a non-boolean
+ `<list>' is cyclic, an unbounded number of operand evaluations may
+ be performed. If any of the operands evaluates to a non-boolean
value, an error is signaled (even if it's the last one).
@@ -418,7 +423,7 @@ equivalence in the presence of mutation (`eq?').
would return true.
-File: klisp.info, Node: Symbols, Next: Index, Prev: Equivalence, Up: Top
+File: klisp.info, Node: Symbols, Next: Control, Prev: Equivalence, Up: Top
4 Symbols
*********
@@ -450,7 +455,59 @@ symbols with other external representations may be created.
R7RS Scheme.
-File: klisp.info, Node: Index, Next: (dir), Prev: Symbols, Up: Top
+File: klisp.info, Node: Control, Next: Index, Prev: Symbols, Up: Top
+
+5 Control
+*********
+
+The inert data type is provided for use with control combiners. It
+consists of a single immutable value, having external representation
+`#inert'. The inert type is encapsulated.
+
+ -- Applicative: inert? (inert? . objects)
+ The primitive type predicate for type inert. `inert?' returns true
+ iff all the objects in `objects' are of type inert.
+
+ -- Operative: $if ($if <test> <consequent> <alternative>)
+ The `$if' operative first evaluates `<test>' in the dynamic
+ environment. If the result is not of type boolean, an error is
+ signaled. If the result is true, `<consequent>' is then evaluated
+ in the dynamic environment as a tail context. Otherwise,
+ `<alternative>' is evaluated in the dynamic environment as a tail
+ context.
+
+ -- Operative: $sequence ($sequence . <objects>)
+ The `$sequence' operative evaluates the elements of the list
+ `<objects>' in the dynamic environment, one at a time from left to
+ right. If `<objects>' is a cyclic list, element evaluation
+ continues indefinitely, with elements in the cycle being evaluated
+ repeatedly. If `<objects>' is a nonempty finite list, its last
+ element is evaluated as a tail context. If `<objects>' is the
+ empty list, the result is inert.
+
+ -- Operative: $cond ($cond . <clauses>)
+ `<clauses>' should be a list of clause expressions, each of the
+ form `(<test> . <body>)', where body is a list of expressions.
+
+ The following equivalences define the behaviour of the `$cond'
+ operative:
+ ($cond) == #inert
+ ($cond (<test> . <body>) . <clauses>) ==
+ ($if <test> ($sequence . <body>) ($cond . <clauses>))
+
+ -- Applicative: for-each (for-each . lists)
+ `lists' must be a nonempty list of lists; if there are two or
+ more, they should all be the same length. If lists is empty, or if
+ all of its elements are not lists of the same length, an error is
+ signaled.
+
+ `for-each' behaves identically to `map', except that instead of
+ accumulating and returning a list of the results of the
+ element-wise applications, the results of the applications are
+ discarded and the result returned by `for-each' is inert.
+
+
+File: klisp.info, Node: Index, Next: (dir), Prev: Control, Up: Top
Index
*****
@@ -459,12 +516,16 @@ Index
* Menu:
* $and?: Booleans. (line 28)
+* $cond: Control. (line 32)
+* $if: Control. (line 15)
* $or?: Booleans. (line 41)
+* $sequence: Control. (line 23)
* and?: Booleans. (line 20)
* applicative descriptions: A Sample Applicative Description.
(line 6)
* boolean?: Booleans. (line 12)
* booleans: Booleans. (line 6)
+* control: Control. (line 6)
* description format: Format of Descriptions.
(line 6)
* documentation notation: Evaluation Notation. (line 6)
@@ -476,6 +537,8 @@ Index
* fonts: Some Terms. (line 13)
* foo: A Sample Applicative Description.
(line 15)
+* for-each: Control. (line 42)
+* inert?: Control. (line 11)
* Kernel history: Kernel History. (line 6)
* not?: Booleans. (line 16)
* object descriptions: A Sample Applicative Description.
@@ -493,21 +556,22 @@ Index
Tag Table:
Node: Top302
-Node: License1077
-Node: Introduction2748
-Node: Caveats5571
-Node: Kernel History6357
-Node: Conventions7802
-Node: Some Terms8473
-Node: Evaluation Notation9144
-Node: Printing Notation9888
-Node: Error Messages10364
-Node: Format of Descriptions11012
-Node: A Sample Applicative Description11576
-Node: Acknowledgements13236
-Node: Booleans13622
-Node: Equivalence16148
-Node: Symbols16941
-Node: Index18304
+Node: License1130
+Node: Introduction2801
+Node: Caveats5624
+Node: Kernel History6410
+Node: Conventions7855
+Node: Some Terms8526
+Node: Evaluation Notation9197
+Node: Printing Notation10218
+Node: Error Messages10694
+Node: Format of Descriptions11342
+Node: A Sample Applicative Description11906
+Node: Acknowledgements13566
+Node: Booleans13952
+Node: Equivalence16494
+Node: Symbols17287
+Node: Control18652
+Node: Index20959
End Tag Table
diff --git a/manual/src/booleans.texi b/manual/src/booleans.texi
@@ -33,31 +33,31 @@ or more of its arguments are false.
or more of its arguments are true.
@end deffn
-@deffn Operative $and? ($and? . list)
+@deffn Operative $and? ($and? . <list>)
The @code{$and?} operative performs a ``short-circuit and'' of its
operands. It evaluates them from left to right, until either an
operand evaluates to false, or the end of the list is reached. If the
-end of the list is reached (which is immediate if @code{list} is
+end of the list is reached (which is immediate if @code{<list>} is
@code{nil}), the operative returns true. If an operand evaluates to
false, no further operand evaluations are performed, and the operative
-returns false. If @code{list} is acyclic, and the last operand is
+returns false. If @code{<list>} is acyclic, and the last operand is
@c TODO cross ref tail-contect
-evaluated, it is evaluated as a tail context. If @code{list} is
+evaluated, it is evaluated as a tail context. If @code{<list>} is
cyclic, an unbounded number of operand evaluations may be
performed. If any of the operands evaluates to a non-boolean value, an
error is signaled (even if it's the last one).
@end deffn
-@deffn Operative $or? ($or? . list)
+@deffn Operative $or? ($or? . <list>)
The @code{$or?} operative performs a ``short-circuit or'' of its
operands. It evaluates them from left to right, until either an
operand evaluates to true, or the end of the list is reached. If the
-end of the list is reached (which is immediate if @code{list} is
+end of the list is reached (which is immediate if @code{<list>} is
@code{nil}), the operative returns false. If an operand evaluates to
true, no further operand evaluations are performed, and the operative
-returns true. If @code{list} is acyclic, and the last operand is
-@c TODO cross ref tail-contect
-evaluated, it is evaluated as a tail context. If @code{list} is
+returns true. If @code{<list>} is acyclic, and the last operand is
+@c TODO cross ref tail-context
+evaluated, it is evaluated as a tail context. If @code{<list>} is
cyclic, an unbounded number of operand evaluations may be
performed. If any of the operands evaluates to a non-boolean value, an
error is signaled (even if it's the last one).
diff --git a/manual/src/control.texi b/manual/src/control.texi
@@ -0,0 +1,63 @@
+@c -*-texinfo-*-
+@setfilename ../src/control
+
+@node Control, Index, Symbols, Top
+@comment node-name, next, previous, up
+
+@chapter Control
+@cindex control
+ The inert data type is provided for use with control combiners. It
+consists of a single immutable value, having external representation
+@code{#inert}. The inert type is encapsulated.
+
+@deffn Applicative inert? (inert? . objects)
+ The primitive type predicate for type inert. @code{inert?}
+returns true iff all the objects in @code{objects} are of type inert.
+@end deffn
+
+@deffn Operative $if ($if <test> <consequent> <alternative>)
+ The @code{$if} operative first evaluates @code{<test>} in the
+dynamic environment. If the result is not of type boolean, an error
+is signaled. If the result is true, @code{<consequent>} is then
+@c TODO add xref to tail context
+evaluated in the dynamic environment as a tail context. Otherwise,
+@code{<alternative>} is evaluated in the dynamic environment as a tail
+context.
+@end deffn
+
+@deffn Operative $sequence ($sequence . <objects>)
+The @code{$sequence} operative evaluates the elements of the list
+@code{<objects>} in the dynamic environment, one at a time from left
+to right. If @code{<objects>} is a cyclic list, element evaluation
+continues indefinitely, with elements in the cycle being evaluated
+repeatedly. If @code{<objects>} is a nonempty finite list, its last
+@c TODO add xref for tail context.
+element is evaluated as a tail context. If @code{<objects>} is the
+empty list, the result is inert.
+@end deffn
+
+@deffn Operative $cond ($cond . <clauses>)
+@code{<clauses>} should be a list of clause expressions, each of the
+form @code{(<test> . <body>)}, where body is a list of expressions.
+
+The following equivalences define
+the behaviour of the @code{$cond} operative:
+@example
+($cond) @equiv{} #inert
+($cond (<test> . <body>) . <clauses>) @equiv{}
+ ($if <test> ($sequence . <body>) ($cond . <clauses>))
+@end example
+@end deffn
+
+@deffn Applicative for-each (for-each . lists)
+@code{lists} must be a nonempty list of lists; if there are two or
+more, they should all be the same length. If lists is empty, or if all
+of its elements are not lists of the same length, an error is
+signaled.
+
+@c TODO add xref to map
+@code{for-each} behaves identically to @code{map}, except that instead
+of accumulating and returning a list of the results of the
+element-wise applications, the results of the applications are
+discarded and the result returned by @code{for-each} is inert.
+@end deffn
diff --git a/manual/src/index.texi b/manual/src/index.texi
@@ -2,7 +2,7 @@
@setfilename ../src/index
@c TODO correct prev node
-@node Index, (dir), Symbols, Top
+@node Index, (dir), Control, Top
@c this is from the elisp manual... Should read a little about this.
@unnumbered Index
diff --git a/manual/src/intro.texi b/manual/src/intro.texi
@@ -210,6 +210,11 @@ equivalences:
(list* arg1) @equiv{} arg1
(list* arg1 . more-args) @equiv{} (cons arg1 (list* . more-args))
@end example
+Notice that in these kind of examples the applicatives or operatives
+referred to are the first class values and not the symbols bound to
+them in the ground environment. This definition would hold even if
+@code{cons} or @code{list*} were redefined in the current dynamic
+environment.
@node Printing Notation, Error Messages, Evaluation Notation, Conventions
@subsection Printing Notation
diff --git a/manual/src/klisp.texi b/manual/src/klisp.texi
@@ -76,6 +76,7 @@ in part.
* Equivalence:: Equivalence under mutation & Equivalence up to
mutation module features.
* Symbols:: Symbol module features.
+* Control:: Control module features.
@c TODO complete
* Index:: Index including concepts, functions, variables,
and other terms.
@@ -90,6 +91,7 @@ mutation module features.
@include booleans.texi
@include equivalence.texi
@include symbols.texi
+@include control.texi
@c appendices
@c TODO
diff --git a/manual/src/symbols.texi b/manual/src/symbols.texi
@@ -1,7 +1,7 @@
@c -*-texinfo-*-
@setfilename ../src/symbols
-@node Symbols, Index, Equivalence, Top
+@node Symbols, Control, Equivalence, Top
@comment node-name, next, previous, up
@chapter Symbols
