commit f300b3cc18d514dcf41edfdd01d0dd7534c74eb7
parent dc4601d7152e9944baca0fe1d2b21d47abbba4c1
Author: Andres Navarro <canavarro82@gmail.com>
Date: Wed, 16 Nov 2011 17:36:50 -0300
Updated port section of the manual. Terminology: changed "character port" to "textual port", as in r6rs and will be in the next draft of r7rs.
Diffstat:
8 files changed, 556 insertions(+), 259 deletions(-)
diff --git a/manual/html/Alphabetical-Index.html b/manual/html/Alphabetical-Index.html
@@ -55,7 +55,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="Ports.html#index-g_t_0028-261"><code>(</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-g_t_0028-263"><code>(</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-g_t_0028-179"><code>(</code></a>: <a href="Numbers.html#Numbers">Numbers</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>
@@ -81,6 +81,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<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="Numbers.html#index-atan-209"><code>atan</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
+<li><a href="Ports.html#index-binary_002dport_003f-262"><code>binary-port?</code></a>: <a href="Ports.html#Ports">Ports</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="Pairs-and-lists.html#index-caaaar-59"><code>caaaar</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
@@ -97,8 +98,8 @@ 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="Ports.html#index-call_002dwith_002dinput_002dfile-271"><code>call-with-input-file</code></a>: <a href="Ports.html#Ports">Ports</a></li>
-<li><a href="Ports.html#index-call_002dwith_002doutput_002dfile-272"><code>call-with-output-file</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-call_002dwith_002dinput_002dfile-280"><code>call-with-input-file</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-call_002dwith_002doutput_002dfile-281"><code>call-with-output-file</code></a>: <a href="Ports.html#Ports">Ports</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>
@@ -160,7 +161,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<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>
-<li><a href="Ports.html#index-eof_002dobject_003f-275"><code>eof-object?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-eof_002dobject_003f-284"><code>eof-object?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Equivalence.html#index-eq_003f-20"><code>eq?</code></a>: <a href="Equivalence.html#Equivalence">Equivalence</a></li>
<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>
@@ -185,7 +186,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Numbers.html#index-gcd-183"><code>gcd</code></a>: <a href="Numbers.html#Numbers">Numbers</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="Ports.html#index-get_002dmodule-274"><code>get-module</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-get_002dmodule-283"><code>get-module</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-get_002dreal_002dexact_002dbounds-185"><code>get-real-exact-bounds</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-get_002dreal_002dexact_002dprimary-187"><code>get-real-exact-primary</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-get_002dreal_002dinternal_002dbounds-184"><code>get-real-internal-bounds</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
@@ -214,7 +215,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Pairs-and-lists.html#index-list_002dref-80"><code>list-ref</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_002dtail-76"><code>list-tail</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-lists-36">lists</a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
-<li><a href="Ports.html#index-load-273"><code>load</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-load-282"><code>load</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-log-203"><code>log</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<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>
@@ -241,8 +242,10 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Numbers.html#index-numerator-194"><code>numerator</code></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="Numbers.html#index-odd_003f-177"><code>odd?</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
-<li><a href="Ports.html#index-open_002dinput_002dfile-265"><code>open-input-file</code></a>: <a href="Ports.html#Ports">Ports</a></li>
-<li><a href="Ports.html#index-open_002doutput_002dfile-266"><code>open-output-file</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-open_002dbinary_002dinput_002dfile-270"><code>open-binary-input-file</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-open_002dbinary_002doutput_002dfile-272"><code>open-binary-output-file</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-open_002dinput_002dfile-269"><code>open-input-file</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-open_002doutput_002dfile-271"><code>open-output-file</code></a>: <a href="Ports.html#Ports">Ports</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>
<li><a href="Combiners.html#index-operatives-116">operatives</a>: <a href="Combiners.html#Combiners">Combiners</a></li>
@@ -258,7 +261,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Promises.html#index-promises-140">promises</a>: <a href="Promises.html#Promises">Promises</a></li>
<li><a href="Numbers.html#index-rational_003f-153"><code>rational?</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-rationalize-200"><code>rationalize</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
-<li><a href="Ports.html#index-read-269"><code>read</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-read-278"><code>read</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-real_002d_003eexact-190"><code>real->exact</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-real_002d_003einexact-189"><code>real->inexact</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-real_003f-154"><code>real?</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
@@ -298,6 +301,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<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>
<li><a href="Numbers.html#index-tan-206"><code>tan</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
+<li><a href="Ports.html#index-textual_002dport_003f-261"><code>textual-port?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-truncate-198"><code>truncate</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-undefined_003f-159"><code>undefined?</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Combiners.html#index-unwrap-121"><code>unwrap</code></a>: <a href="Combiners.html#Combiners">Combiners</a></li>
diff --git a/manual/html/Ports.html b/manual/html/Ports.html
@@ -35,9 +35,14 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<h2 class="chapter">16 Ports</h2>
<p><a name="index-ports-257"></a>
- A port is an object that mediates character-based input from a
-source or character-based output to a destination. In the former case,
-the port is an input port, in the latter case, an output port.
+ A port is an object that mediates data from an input or to a
+destination. In the former case, the port is an input port, in the
+latter case, an output port. The data itself can consist of either
+characters or bytes. In the former case the port is a textual port
+and in the latter case, a binary port.
+
+ <p>There are three textual ports open, binded by dynamic variables, one
+for standard input, output, and error.
<!-- TODO add xref to equal? & eq? -->
<p>Although ports are not considered immutable, none of the operations
@@ -45,7 +50,7 @@ on ports described in this section constitute mutation. Ports are
<code>equal?</code> iff <code>eq?</code>. The port type is encapsulated.
<p>An auxiliary data type used to signal the end of file was reached is
-eof. The eof type consists of a single immutable value, having
+<code>eof</code>. The eof type consists of a single immutable value, having
an output only external representation (so that it can never be the
normal result of a call to read). The eof type is encapsulated.
@@ -63,77 +68,96 @@ returns true iff all the objects in <code>objects</code> are of type port.
— Applicative: <b>output-port?</b> (<var>output-port? . objects</var>)<var><a name="index-output_002dport_003f-260"></a></var><br>
<blockquote><p> Applicative <code>input-port?</code> is a predicate that returns true
unless one or more of its arguments is not an input port. Applicative
-output-port? is a predicate that returns true unless one or more of
-its arguments is not an output port.
+<code>output-port?</code> is a predicate that returns true unless one or
+more of its arguments is not an output port.
<p>Every port must be admitted by at least one of these two predicates.
</p></blockquote></div>
<div class="defun">
-— with-input-from-file: <b>(</b><var>with-input-from-file string combiner</var>)<var><a name="index-g_t_0028-261"></a></var><br>
-— with-output-to-file: <b>(</b><var>with-output-to-file string combiner</var>)<var><a name="index-g_t_0028-262"></a></var><br>
-<blockquote><!-- add xref get-current-input-port/get-current-output-port -->
- <p>These two applicatives open the file named in <code>string</code> for
-input or output, an invoke the binder of the input-port & output-port
-keyed dynamic variables respectively with the opened port & the passed
-<code>combiner</code> (this means that the combiner is called in a fresh, empty
-dynamic environment). When/if the binder normally returns, the port is closed.
-The result of the applicatives <code>with-input-from-file</code> and
-<code>with-output-from-file</code> is inert.
+— Applicative: <b>textual-port?</b> (<var>textual-port? . objects</var>)<var><a name="index-textual_002dport_003f-261"></a></var><br>
+— Applicative: <b>binary-port?</b> (<var>binary-port? . objects</var>)<var><a name="index-binary_002dport_003f-262"></a></var><br>
+<blockquote><p> Applicative <code>textual-port?</code> is a predicate that returns true
+unless one or more of its arguments is not a textual port. Applicative
+<code>binary-port?</code> is a predicate that returns true unless one or more of
+its arguments is not a binary port.
- <p>SOURCE NOTE: this is enumerated in the Kernel report but the text is
-still missing. In the new scheme report there's also a third
-error-port variable. It is very likely that that will be added to the
-klisp implementation in the near future.
+ <p>Every port must be admitted by at least one of these two predicates.
+
+ <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+</p></blockquote></div>
+
+<div class="defun">
+— with-input-from-file: <b>(</b><var>with-input-from-file string combiner</var>)<var><a name="index-g_t_0028-263"></a></var><br>
+— with-output-to-file: <b>(</b><var>with-output-to-file string combiner</var>)<var><a name="index-g_t_0028-264"></a></var><br>
+— with-error-to-file: <b>(</b><var>with-error-to-file string combiner</var>)<var><a name="index-g_t_0028-265"></a></var><br>
+<blockquote><!-- add xref get-current-input-port/get-current-output-port -->
+ <p>These three applicatives open the file named in <code>string</code> for
+textual input or output, an invoke the binder of either the
+input-port, the output-port or the error-port keyed dynamic variables
+respectively with the opened port & the passed <code>combiner</code> (this
+means that the combiner is called in a fresh, empty dynamic
+environment). When/if the binder normally returns, the port is
+closed. The result of the applicatives <code>with-input-from-file</code>
+and <code>with-output-from-file</code> is inert.
+
+ <p>SOURCE NOTE: The first two are enumerated in the Kernel report but
+the text is still missing. The third applicative is from Scheme.
</p></blockquote></div>
<div class="defun">
-— get-current-input-port: <b>(</b><var>get-current-input-port</var>)<var><a name="index-g_t_0028-263"></a></var><br>
-— get-current-output-port: <b>(</b><var>get-current-output-port</var>)<var><a name="index-g_t_0028-264"></a></var><br>
-<blockquote><p> These are the accessors for the input-port and output-port keyed
-dynamic variables repectively.
+— get-current-input-port: <b>(</b><var>get-current-input-port</var>)<var><a name="index-g_t_0028-266"></a></var><br>
+— get-current-output-port: <b>(</b><var>get-current-output-port</var>)<var><a name="index-g_t_0028-267"></a></var><br>
+— get-current-error-port: <b>(</b><var>get-current-error-port</var>)<var><a name="index-g_t_0028-268"></a></var><br>
+<blockquote><p> These are the accessors for the input-port, output-port, and
+error-port keyed dynamic variables repectively.
<!-- add xref to with-input-from-file, etc -->
<!-- add xref and text for these dynamic vars -->
- <p>SOURCE NOTE: this is enumerated in the Kernel report but the text is
-still missing. In the new scheme report there's also a third
-error-port variable. It is very likely that that will be added to the
-klisp implementation in the near future.
+ <p>SOURCE NOTE: The first two are enumerated in the Kernel report but
+the text is still missing. The third applicative is from Scheme.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>open-input-file</b> (<var>open-input-file string</var>)<var><a name="index-open_002dinput_002dfile-265"></a></var><br>
+— Applicative: <b>open-input-file</b> (<var>open-input-file string</var>)<var><a name="index-open_002dinput_002dfile-269"></a></var><br>
+— Applicative: <b>open-binary-input-file</b> (<var>open-binary-input-file string</var>)<var><a name="index-open_002dbinary_002dinput_002dfile-270"></a></var><br>
<blockquote><p> <code>string</code> should be the name/path for an existing file.
- <p>Applicative <code>open-input-file</code> creates and returns an input port
-associated with the file represented with <code>string</code>. If the file
-can't be opened (e.g. because it doesn't exists, or there's a
-permissions problem), an error is signaled.
+ <p>Applicative <code>open-input-file</code> creates and returns a textual
+input port associated with the file represented with <code>string</code>.
+Applicative <code>open-binary-input-file</code> creates and returns a binary
+input port associated with the file represented with <code>string</code>.
+In either case, if the file can't be opened (e.g. because it doesn't
+exists, or there's a permissions problem), an error is signaled.
- <p>SOURCE NOTE: this is enumerated in the Kernel report but the text is
-still missing.
+ <p>SOURCE NOTE: open-input-file is enumerated in the Kernel report but
+the text is still missing. open-binary-input-file is from Scheme.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>open-output-file</b> (<var>open-output-file string</var>)<var><a name="index-open_002doutput_002dfile-266"></a></var><br>
+— Applicative: <b>open-output-file</b> (<var>open-output-file string</var>)<var><a name="index-open_002doutput_002dfile-271"></a></var><br>
+— Applicative: <b>open-binary-output-file</b> (<var>open-binary-output-file string</var>)<var><a name="index-open_002dbinary_002doutput_002dfile-272"></a></var><br>
<blockquote><p> <code>string</code> should be the name/path for an existing file.
- <p>Applicative <code>open-output-file</code> creates and returns an output
-port associated with the file represented with <code>string</code>. If the
-file can't be opened (e.g. if there's a permissions problem), an error
-is signaled.
+ <p>Applicative <code>open-output-file</code> creates and returns a textual
+output port associated with the file represented with <code>string</code>.
+Applicative <code>open-binary-output-file</code> creates and returns a
+binary output port associated with the file represented with
+<code>string</code>. In either case, if the file can't be opened (e.g. if
+there's a permissions problem), an error is signaled.
- <p>In klisp, for now, applicative <code>open-output-file</code> truncates the
-file if it already exists, but that could change later (i.e. like in
-scheme the behaviour should be considered unspecified).
+ <p>In klisp, for now, applicative <code>open-output-file</code> and
+<code>open-binary-output-file</code> truncate the file if it already exists,
+but that could change later (i.e. like in Scheme the behaviour should
+be considered unspecified).
- <p>SOURCE NOTE: this is enumerated in the Kernel report but the text is
-still missing.
+ <p>SOURCE NOTE: open-output-file is enumerated in the Kernel report but
+the text is still missing. open-binary-output-file is from Scheme.
</p></blockquote></div>
<div class="defun">
-— close-input-file: <b>(</b><var>close-input-file input-port</var>)<var><a name="index-g_t_0028-267"></a></var><br>
-— close-output-file: <b>(</b><var>close-output-file output-port</var>)<var><a name="index-g_t_0028-268"></a></var><br>
+— close-input-file: <b>(</b><var>close-input-file input-port</var>)<var><a name="index-g_t_0028-273"></a></var><br>
+— close-output-file: <b>(</b><var>close-output-file output-port</var>)<var><a name="index-g_t_0028-274"></a></var><br>
<blockquote><p> These applicatives close the port argument, so that no more
input/output may be performed on them, and the resources can be
freed. If the port was already closed these applicatives have no
@@ -148,13 +172,31 @@ probably be called close-input-port & close-output-port.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>read</b> (<var>read </var>[<var>input-port</var>])<var><a name="index-read-269"></a></var><br>
+— close-input-port: <b>(</b><var>close-input-port input-port</var>)<var><a name="index-g_t_0028-275"></a></var><br>
+— close-output-port: <b>(</b><var>close-output-port output-port</var>)<var><a name="index-g_t_0028-276"></a></var><br>
+— close-port: <b>(</b><var>close-port port</var>)<var><a name="index-g_t_0028-277"></a></var><br>
+<blockquote><p> These applicatives close the port argument, so that no more
+input/output may be performed on them, and the resources can be
+freed. If the port was already closed these applicatives have no
+effect. If at some time klisp provided input/ouput ports these could
+be used to selectively close only one direction of the port.
+
+ <p>The result returned by applicatives <code>close-input-port</code>,
+<code>close-output-port</code>, and <code>close-port</code> is inert.
+
+ <p>SOURCE NOTE: this is from Scheme. The equivalent
+<code>close-input-file</code> and <code>close-output-file</code> are probably name
+errors and only retained here till the draft standard rectifies them
+</p></blockquote></div>
+
+<div class="defun">
+— Applicative: <b>read</b> (<var>read </var>[<var>textual-input-port</var>])<var><a name="index-read-278"></a></var><br>
<blockquote><p> If the <code>port</code> optional argument is not specified, then the
value of the <code>input-port</code> keyed dynamic variable is used. If the
port is closed, an error is signaled.
<p>Applicative <code>read</code> reads & returns the next parseable object
-from the given port, or the eof object if no objects remain. If
+from the given port, or the <code>eof</code> if no objects remain. If
<code>read</code> finds and unparseable object in the port, an error is
signaled. In that case, the remaining position in the port is
unspecified.
@@ -164,7 +206,7 @@ still missing.
</p></blockquote></div>
<div class="defun">
-— write: <b>(</b><var>write object </var>[<var>port</var>])<var><a name="index-g_t_0028-270"></a></var><br>
+— write: <b>(</b><var>write object </var>[<var>textual-output-port</var>])<var><a name="index-g_t_0028-279"></a></var><br>
<blockquote><p> If the <code>port</code> optional argument is not specified, then the
value of the <code>output-port</code> keyed dynamic variable is used. If the
port is closed, an error is signaled.
@@ -182,25 +224,25 @@ still missing.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>call-with-input-file</b> (<var>call-with-input-file string combiner</var>)<var><a name="index-call_002dwith_002dinput_002dfile-271"></a></var><br>
-— Applicative: <b>call-with-output-file</b> (<var>call-with-output-file string combiner</var>)<var><a name="index-call_002dwith_002doutput_002dfile-272"></a></var><br>
-<blockquote><p> These applicatives open file named in <code>string</code> and call their
-<code>combiner</code> argument in a fresh empty environment passing it as a
-sole operand the opened port. When/if the combiner normally returns a
-value the port is closed and that value is returned as the result of
-the applicative.
+— Applicative: <b>call-with-input-file</b> (<var>call-with-input-file string combiner</var>)<var><a name="index-call_002dwith_002dinput_002dfile-280"></a></var><br>
+— Applicative: <b>call-with-output-file</b> (<var>call-with-output-file string combiner</var>)<var><a name="index-call_002dwith_002doutput_002dfile-281"></a></var><br>
+<blockquote><p> These applicatives open file named in <code>string</code> for textual
+input/output respectively and call their <code>combiner</code> argument in a
+fresh empty environment passing it as a sole operand the opened port.
+When/if the combiner normally returns a value the port is closed and
+that value is returned as the result of the applicative.
<p>SOURCE NOTE: this is enumerated in the Kernel report but the text is
still missing.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>load</b> (<var>load string</var>)<var><a name="index-load-273"></a></var><br>
+— Applicative: <b>load</b> (<var>load string</var>)<var><a name="index-load-282"></a></var><br>
<blockquote><!-- TODO add xref, open/input, read -->
- <p>Applicative <code>load</code> opens for input a file named <code>string</code>;
-reads objects from the file until the end of the file is reached;
-evaluates those objects consecutively in the created environment. The
-result from applicative <code>load</code> is inert.
+ <p>Applicative <code>load</code> opens the file named <code>string</code> for
+textual input; reads objects from the file until the end of the file
+is reached; evaluates those objects consecutively in the created
+environment. The result from applicative <code>load</code> is inert.
<p>SOURCE NOTE: load is enumerated in the Kernel report, but the
description is not there yet. This seems like a sane way to define
@@ -211,51 +253,51 @@ return the value of the last evaluation.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>get-module</b> (<var>get-module string </var>[<var>environment</var>])<var><a name="index-get_002dmodule-274"></a></var><br>
+— Applicative: <b>get-module</b> (<var>get-module string </var>[<var>environment</var>])<var><a name="index-get_002dmodule-283"></a></var><br>
<blockquote><!-- TODO add xref standard-environment, open/input, read -->
<p>Applicative <code>get-module</code> creates a fresh standard environment;
-opens for input a file named <code>string</code>; reads objects from the
-file until the end of the file is reached; evaluates those objects
-consecutively in the created environment; and, lastly, returns the
-created environment. If the optional argument <code>environment</code> is
-specified, the freshly created standard environment is augmented,
+opens the file named <code>string</code> for textual input; reads objects
+from the file until the end of the file is reached; evaluates those
+objects consecutively in the created environment; and, lastly, returns
+the created environment. If the optional argument <code>environment</code>
+is specified, the freshly created standard environment is augmented,
prior to evaluating read expressions, by binding symbol
<code>module-parameters</code> to the <code>environment</code> argument.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>eof-object?</b> (<var>eof-object? . objects</var>)<var><a name="index-eof_002dobject_003f-275"></a></var><br>
+— Applicative: <b>eof-object?</b> (<var>eof-object? . objects</var>)<var><a name="index-eof_002dobject_003f-284"></a></var><br>
<blockquote><p> The primitive type predicate for type eof. <code>eof-object?</code>
returns true iff all the objects in <code>objects</code> are of type eof.
<p>SOURCE NOTE: This is not in the report, the idea is from Scheme.
-The <code>eof-object?</code> name is also from scheme, but this will
+The <code>eof-object?</code> name is also from Scheme, but this will
probably be changed to just <code>eof?</code>, for consistency with the other
primitive type predicates.
</p></blockquote></div>
<div class="defun">
-— read-char: <b>(</b><var>read-char </var>[<var>port</var>])<var><a name="index-g_t_0028-276"></a></var><br>
+— read-char: <b>(</b><var>read-char </var>[<var>textual-input-port</var>])<var><a name="index-g_t_0028-285"></a></var><br>
<blockquote><p> If the <code>port</code> optional argument is not specified, then the
value of the <code>input-port</code> keyed dynamic variable is used. If the
port is closed, an error is signaled.
<p>Applicative <code>read-char</code> reads and returns a character (not
an external representation of a character) from the specified port, or
-an eof if the end of file was reached.
+an <code>eof</code> if the end of file was reached.
<p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
</p></blockquote></div>
<div class="defun">
-— peek-char: <b>(</b><var>peek-char </var>[<var>port</var>])<var><a name="index-g_t_0028-277"></a></var><br>
+— peek-char: <b>(</b><var>peek-char </var>[<var>textual-input-port</var>])<var><a name="index-g_t_0028-286"></a></var><br>
<blockquote><p> If the <code>port</code> optional argument is not specified, then the
value of the <code>input-port</code> keyed dynamic variable is used. If the
port is closed, an error is signaled.
<p>Applicative <code>peek-char</code> reads and returns a character (not
an external representation of a character) from the specified port, or
-an eof if the end of file was reached. The position of the port
+an <code>eof</code> if the end of file was reached. The position of the port
remains unchanged so that new call to <code>peek-char</code> or
<code>read-char</code> on the same port return the same character.
@@ -263,7 +305,7 @@ remains unchanged so that new call to <code>peek-char</code> or
</p></blockquote></div>
<div class="defun">
-— char-ready?: <b>(</b><var>char-ready? </var>[<var>port</var>])<var><a name="index-g_t_0028-278"></a></var><br>
+— char-ready?: <b>(</b><var>char-ready? </var>[<var>textual-input-port</var>])<var><a name="index-g_t_0028-287"></a></var><br>
<blockquote><p> If the <code>port</code> optional argument is not specified, then the
value of the <code>input-port</code> keyed dynamic variable is used. If the
port is closed, an error is signaled.
@@ -278,7 +320,7 @@ the code to do this is non-portable.
</p></blockquote></div>
<div class="defun">
-— write-char: <b>(</b><var>write-char char </var>[<var>port</var>])<var><a name="index-g_t_0028-279"></a></var><br>
+— write-char: <b>(</b><var>write-char char </var>[<var>textual-output-port</var>])<var><a name="index-g_t_0028-288"></a></var><br>
<blockquote><p> If the <code>port</code> optional argument is not specified, then the
value of the <code>output-port</code> keyed dynamic variable is used. If the
port is closed, an error is signaled.
@@ -291,7 +333,7 @@ The result returned by <code>write-char</code> is inert.
</p></blockquote></div>
<div class="defun">
-— newline: <b>(</b><var>newline </var>[<var>port</var>])<var><a name="index-g_t_0028-280"></a></var><br>
+— newline: <b>(</b><var>newline </var>[<var>textal-ouput-port</var>])<var><a name="index-g_t_0028-289"></a></var><br>
<blockquote><p> If the <code>port</code> optional argument is not specified, then the
value of the <code>output-port</code> keyed dynamic variable is used. If the
port is closed, an error is signaled.
@@ -303,7 +345,7 @@ The result returned by <code>newline</code> is inert.
</p></blockquote></div>
<div class="defun">
-— display: <b>(</b><var>display object </var>[<var>port</var>])<var><a name="index-g_t_0028-281"></a></var><br>
+— display: <b>(</b><var>display object </var>[<var>textual-output-port</var>])<var><a name="index-g_t_0028-290"></a></var><br>
<blockquote><p> If the <code>port</code> optional argument is not specified, then the
value of the <code>output-port</code> keyed dynamic variable is used. If the
port is closed, an error is signaled.
@@ -318,7 +360,66 @@ within those strings and character objects are output as if by
</p></blockquote></div>
<div class="defun">
-— flush-output-port: <b>(</b><var>flush-output-port </var>[<var>port</var>])<var><a name="index-g_t_0028-282"></a></var><br>
+— read-u8: <b>(</b><var>read-u8 </var>[<var>textual-input-port</var>])<var><a name="index-g_t_0028-291"></a></var><br>
+<blockquote><p> If the <code>port</code> optional argument is not specified, then the
+value of the <code>input-port</code> keyed dynamic variable is used. If the
+port is closed, an error is signaled.
+
+ <p>Applicative <code>read-u8</code> reads and returns a byte as an exact
+unsigned integer between 0 and 255 inclusive (not an external
+representation of a byte) from the specified port, or an <code>eof</code> if
+the end of file was reached.
+
+ <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+</p></blockquote></div>
+
+<div class="defun">
+— peek-u8: <b>(</b><var>peek-u8 </var>[<var>textual-input-port</var>])<var><a name="index-g_t_0028-292"></a></var><br>
+<blockquote><p> If the <code>port</code> optional argument is not specified, then the
+value of the <code>input-port</code> keyed dynamic variable is used. If the
+port is closed, an error is signaled.
+
+ <p>Applicative <code>peek-u8</code> reads and returns a byte as an exact
+unsigned integer between 0 and 255 inclusive (not an external
+representation of a byte) from the specified port, or an <code>eof</code> if
+the end of file was reached. The position of the port remains
+unchanged so that new call to <code>peek-u8</code> or <code>read-u8</code> on the
+same port return the same byte.
+
+ <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+</p></blockquote></div>
+
+<div class="defun">
+— u8-ready?: <b>(</b><var>u8-ready? </var>[<var>textual-input-port</var>])<var><a name="index-g_t_0028-293"></a></var><br>
+<blockquote><p> If the <code>port</code> optional argument is not specified, then the
+value of the <code>input-port</code> keyed dynamic variable is used. If the
+port is closed, an error is signaled.
+
+ <p>Predicate <code>u8-ready?</code> checks to see if a byte is
+available in the specified port. If it returns true, then a
+<code>read-u8</code> or <code>peek-u8</code> on that port is guaranteed not to
+block/hang. For now in klisp this is hardcoded to <code>#t</code> because
+the code to do this is non-portable.
+
+ <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+</p></blockquote></div>
+
+<div class="defun">
+— write-u8: <b>(</b><var>write-u8 u8 </var>[<var>textual-output-port</var>])<var><a name="index-g_t_0028-294"></a></var><br>
+<blockquote><p> If the <code>port</code> optional argument is not specified, then the
+value of the <code>output-port</code> keyed dynamic variable is used. If the
+port is closed, an error is signaled.
+
+ <p>Applicative <code>write-u8</code> writes the byte represented by the
+unsigned integer <code>u8</code>, that should be between 0 and 255 inclusive,
+(not an external representation of byte) to the specified port. The
+result returned by <code>write-u8</code> is inert.
+
+ <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+</p></blockquote></div>
+
+<div class="defun">
+— flush-output-port: <b>(</b><var>flush-output-port </var>[<var>output-port</var>])<var><a name="index-g_t_0028-295"></a></var><br>
<blockquote><p> If the <code>port</code> optional argument is not specified, then the
value of the <code>output-port</code> keyed dynamic variable is used. If
the <code>port</code> is closed or if it is not an output port, an error is
@@ -332,7 +433,7 @@ output port to the underlying file or device. The result returned by
</p></blockquote></div>
<div class="defun">
-— file-exists?: <b>(</b><var>file-exists? string</var>)<var><a name="index-g_t_0028-283"></a></var><br>
+— file-exists?: <b>(</b><var>file-exists? string</var>)<var><a name="index-g_t_0028-296"></a></var><br>
<blockquote><p> <code>string</code> should be the name/path for a file.
<p>Predicate <code>file-exists?</code> checks to see if a file named
@@ -342,7 +443,7 @@ output port to the underlying file or device. The result returned by
</p></blockquote></div>
<div class="defun">
-— delete-file: <b>(</b><var>delete-file string</var>)<var><a name="index-g_t_0028-284"></a></var><br>
+— delete-file: <b>(</b><var>delete-file string</var>)<var><a name="index-g_t_0028-297"></a></var><br>
<blockquote><p> <code>string</code> should be the name/path for an existing file.
<p>Applicative <code>delete-file</code> deletes the file named <code>string</code>.
@@ -353,7 +454,7 @@ result returned by <code>delete-file</code> is inert.
</p></blockquote></div>
<div class="defun">
-— rename-file: <b>(</b><var>rename-file string1 string2</var>)<var><a name="index-g_t_0028-285"></a></var><br>
+— rename-file: <b>(</b><var>rename-file string1 string2</var>)<var><a name="index-g_t_0028-298"></a></var><br>
<blockquote><p> <code>string1</code> should be the name/path for an existing file,
<code>string2</code> should be the name/path for a non existing file.
diff --git a/manual/klisp.info b/manual/klisp.info
@@ -2135,16 +2135,21 @@ File: klisp.info, Node: Ports, Next: Alphabetical Index, Prev: Characters, U
16 Ports
********
-A port is an object that mediates character-based input from a source
-or character-based output to a destination. In the former case, the
-port is an input port, in the latter case, an output port.
+A port is an object that mediates data from an input or to a
+destination. In the former case, the port is an input port, in the
+latter case, an output port. The data itself can consist of either
+characters or bytes. In the former case the port is a textual port and
+in the latter case, a binary port.
+
+ There are three textual ports open, binded by dynamic variables, one
+for standard input, output, and error.
Although ports are not considered immutable, none of the operations
on ports described in this section constitute mutation. Ports are
`equal?' iff `eq?'. The port type is encapsulated.
An auxiliary data type used to signal the end of file was reached is
-eof. The eof type consists of a single immutable value, having an
+`eof'. The eof type consists of a single immutable value, having an
output only external representation (so that it can never be the normal
result of a call to read). The eof type is encapsulated.
@@ -2159,62 +2164,82 @@ klisp and was taken from Scheme.
-- Applicative: output-port? (output-port? . objects)
Applicative `input-port?' is a predicate that returns true unless
one or more of its arguments is not an input port. Applicative
- output-port? is a predicate that returns true unless one or more of
- its arguments is not an output port.
+ `output-port?' is a predicate that returns true unless one or more
+ of its arguments is not an output port.
Every port must be admitted by at least one of these two
predicates.
+ -- Applicative: textual-port? (textual-port? . objects)
+ -- Applicative: binary-port? (binary-port? . objects)
+ Applicative `textual-port?' is a predicate that returns true
+ unless one or more of its arguments is not a textual port.
+ Applicative `binary-port?' is a predicate that returns true unless
+ one or more of its arguments is not a binary port.
+
+ Every port must be admitted by at least one of these two
+ predicates.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+
-- with-input-from-file: (with-input-from-file string combiner)
-- with-output-to-file: (with-output-to-file string combiner)
- These two applicatives open the file named in `string' for input
- or output, an invoke the binder of the input-port & output-port
- keyed dynamic variables respectively with the opened port & the
- passed `combiner' (this means that the combiner is called in a
- fresh, empty dynamic environment). When/if the binder normally
- returns, the port is closed. The result of the applicatives
+ -- with-error-to-file: (with-error-to-file string combiner)
+ These three applicatives open the file named in `string' for
+ textual input or output, an invoke the binder of either the
+ input-port, the output-port or the error-port keyed dynamic
+ variables respectively with the opened port & the passed
+ `combiner' (this means that the combiner is called in a fresh,
+ empty dynamic environment). When/if the binder normally returns,
+ the port is closed. The result of the applicatives
`with-input-from-file' and `with-output-from-file' is inert.
- SOURCE NOTE: this is enumerated in the Kernel report but the text
- is still missing. In the new scheme report there's also a third
- error-port variable. It is very likely that that will be added to
- the klisp implementation in the near future.
+ SOURCE NOTE: The first two are enumerated in the Kernel report but
+ the text is still missing. The third applicative is from Scheme.
-- get-current-input-port: (get-current-input-port)
-- get-current-output-port: (get-current-output-port)
- These are the accessors for the input-port and output-port keyed
- dynamic variables repectively.
+ -- get-current-error-port: (get-current-error-port)
+ These are the accessors for the input-port, output-port, and
+ error-port keyed dynamic variables repectively.
- SOURCE NOTE: this is enumerated in the Kernel report but the text
- is still missing. In the new scheme report there's also a third
- error-port variable. It is very likely that that will be added to
- the klisp implementation in the near future.
+ SOURCE NOTE: The first two are enumerated in the Kernel report but
+ the text is still missing. The third applicative is from Scheme.
-- Applicative: open-input-file (open-input-file string)
+ -- Applicative: open-binary-input-file (open-binary-input-file string)
`string' should be the name/path for an existing file.
- Applicative `open-input-file' creates and returns an input port
- associated with the file represented with `string'. If the file
- can't be opened (e.g. because it doesn't exists, or there's a
- permissions problem), an error is signaled.
+ Applicative `open-input-file' creates and returns a textual input
+ port associated with the file represented with `string'.
+ Applicative `open-binary-input-file' creates and returns a binary
+ input port associated with the file represented with `string'. In
+ either case, if the file can't be opened (e.g. because it doesn't
+ exists, or there's a permissions problem), an error is signaled.
- SOURCE NOTE: this is enumerated in the Kernel report but the text
- is still missing.
+ SOURCE NOTE: open-input-file is enumerated in the Kernel report but
+ the text is still missing. open-binary-input-file is from Scheme.
-- Applicative: open-output-file (open-output-file string)
+ -- Applicative: open-binary-output-file (open-binary-output-file
+ string)
`string' should be the name/path for an existing file.
- Applicative `open-output-file' creates and returns an output port
- associated with the file represented with `string'. If the file
- can't be opened (e.g. if there's a permissions problem), an error
- is signaled.
+ Applicative `open-output-file' creates and returns a textual
+ output port associated with the file represented with `string'.
+ Applicative `open-binary-output-file' creates and returns a binary
+ output port associated with the file represented with `string'.
+ In either case, if the file can't be opened (e.g. if there's a
+ permissions problem), an error is signaled.
- In klisp, for now, applicative `open-output-file' truncates the
- file if it already exists, but that could change later (i.e. like
- in scheme the behaviour should be considered unspecified).
+ In klisp, for now, applicative `open-output-file' and
+ `open-binary-output-file' truncate the file if it already exists,
+ but that could change later (i.e. like in Scheme the behaviour
+ should be considered unspecified).
- SOURCE NOTE: this is enumerated in the Kernel report but the text
- is still missing.
+ SOURCE NOTE: open-output-file is enumerated in the Kernel report
+ but the text is still missing. open-binary-output-file is from
+ Scheme.
-- close-input-file: (close-input-file input-port)
-- close-output-file: (close-output-file output-port)
@@ -2230,20 +2255,37 @@ klisp and was taken from Scheme.
is still missing. There's probably a name error here. These
should probably be called close-input-port & close-output-port.
- -- Applicative: read (read [input-port])
+ -- close-input-port: (close-input-port input-port)
+ -- close-output-port: (close-output-port output-port)
+ -- close-port: (close-port port)
+ These applicatives close the port argument, so that no more
+ input/output may be performed on them, and the resources can be
+ freed. If the port was already closed these applicatives have no
+ effect. If at some time klisp provided input/ouput ports these
+ could be used to selectively close only one direction of the port.
+
+ The result returned by applicatives `close-input-port',
+ `close-output-port', and `close-port' is inert.
+
+ SOURCE NOTE: this is from Scheme. The equivalent
+ `close-input-file' and `close-output-file' are probably name
+ errors and only retained here till the draft standard rectifies
+ them
+
+ -- Applicative: read (read [textual-input-port])
If the `port' optional argument is not specified, then the value
of the `input-port' keyed dynamic variable is used. If the port
is closed, an error is signaled.
Applicative `read' reads & returns the next parseable object from
- the given port, or the eof object if no objects remain. If `read'
+ the given port, or the `eof' if no objects remain. If `read'
finds and unparseable object in the port, an error is signaled.
In that case, the remaining position in the port is unspecified.
SOURCE NOTE: this is enumerated in the Kernel report but the text
is still missing.
- -- write: (write object [port])
+ -- write: (write object [textual-output-port])
If the `port' optional argument is not specified, then the value
of the `output-port' keyed dynamic variable is used. If the port
is closed, an error is signaled.
@@ -2262,20 +2304,20 @@ klisp and was taken from Scheme.
combiner)
-- Applicative: call-with-output-file (call-with-output-file string
combiner)
- These applicatives open file named in `string' and call their
- `combiner' argument in a fresh empty environment passing it as a
- sole operand the opened port. When/if the combiner normally
- returns a value the port is closed and that value is returned as
- the result of the applicative.
+ These applicatives open file named in `string' for textual
+ input/output respectively and call their `combiner' argument in a
+ fresh empty environment passing it as a sole operand the opened
+ port. When/if the combiner normally returns a value the port is
+ closed and that value is returned as the result of the applicative.
SOURCE NOTE: this is enumerated in the Kernel report but the text
is still missing.
-- Applicative: load (load string)
- Applicative `load' opens for input a file named `string'; reads
- objects from the file until the end of the file is reached;
- evaluates those objects consecutively in the created environment.
- The result from applicative `load' is inert.
+ Applicative `load' opens the file named `string' for textual
+ input; reads objects from the file until the end of the file is
+ reached; evaluates those objects consecutively in the created
+ environment. The result from applicative `load' is inert.
SOURCE NOTE: load is enumerated in the Kernel report, but the
description is not there yet. This seems like a sane way to define
@@ -2286,48 +2328,48 @@ klisp and was taken from Scheme.
-- Applicative: get-module (get-module string [environment])
Applicative `get-module' creates a fresh standard environment;
- opens for input a file named `string'; reads objects from the file
- until the end of the file is reached; evaluates those objects
- consecutively in the created environment; and, lastly, returns the
- created environment. If the optional argument `environment' is
- specified, the freshly created standard environment is augmented,
- prior to evaluating read expressions, by binding symbol
- `module-parameters' to the `environment' argument.
+ opens the file named `string' for textual input; reads objects
+ from the file until the end of the file is reached; evaluates those
+ objects consecutively in the created environment; and, lastly,
+ returns the created environment. If the optional argument
+ `environment' is specified, the freshly created standard
+ environment is augmented, prior to evaluating read expressions, by
+ binding symbol `module-parameters' to the `environment' argument.
-- Applicative: eof-object? (eof-object? . objects)
The primitive type predicate for type eof. `eof-object?' returns
true iff all the objects in `objects' are of type eof.
SOURCE NOTE: This is not in the report, the idea is from Scheme.
- The `eof-object?' name is also from scheme, but this will probably
+ The `eof-object?' name is also from Scheme, but this will probably
be changed to just `eof?', for consistency with the other
primitive type predicates.
- -- read-char: (read-char [port])
+ -- read-char: (read-char [textual-input-port])
If the `port' optional argument is not specified, then the value
of the `input-port' keyed dynamic variable is used. If the port
is closed, an error is signaled.
Applicative `read-char' reads and returns a character (not an
external representation of a character) from the specified port, or
- an eof if the end of file was reached.
+ an `eof' if the end of file was reached.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
- -- peek-char: (peek-char [port])
+ -- peek-char: (peek-char [textual-input-port])
If the `port' optional argument is not specified, then the value
of the `input-port' keyed dynamic variable is used. If the port
is closed, an error is signaled.
Applicative `peek-char' reads and returns a character (not an
external representation of a character) from the specified port, or
- an eof if the end of file was reached. The position of the port
+ an `eof' if the end of file was reached. The position of the port
remains unchanged so that new call to `peek-char' or `read-char'
on the same port return the same character.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
- -- char-ready?: (char-ready? [port])
+ -- char-ready?: (char-ready? [textual-input-port])
If the `port' optional argument is not specified, then the value
of the `input-port' keyed dynamic variable is used. If the port
is closed, an error is signaled.
@@ -2340,7 +2382,7 @@ klisp and was taken from Scheme.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
- -- write-char: (write-char char [port])
+ -- write-char: (write-char char [textual-output-port])
If the `port' optional argument is not specified, then the value
of the `output-port' keyed dynamic variable is used. If the port
is closed, an error is signaled.
@@ -2351,7 +2393,7 @@ klisp and was taken from Scheme.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
- -- newline: (newline [port])
+ -- newline: (newline [textal-ouput-port])
If the `port' optional argument is not specified, then the value
of the `output-port' keyed dynamic variable is used. If the port
is closed, an error is signaled.
@@ -2361,7 +2403,7 @@ klisp and was taken from Scheme.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
- -- display: (display object [port])
+ -- display: (display object [textual-output-port])
If the `port' optional argument is not specified, then the value
of the `output-port' keyed dynamic variable is used. If the port
is closed, an error is signaled.
@@ -2374,7 +2416,58 @@ klisp and was taken from Scheme.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
- -- flush-output-port: (flush-output-port [port])
+ -- read-u8: (read-u8 [textual-input-port])
+ If the `port' optional argument is not specified, then the value
+ of the `input-port' keyed dynamic variable is used. If the port
+ is closed, an error is signaled.
+
+ Applicative `read-u8' reads and returns a byte as an exact
+ unsigned integer between 0 and 255 inclusive (not an external
+ representation of a byte) from the specified port, or an `eof' if
+ the end of file was reached.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+
+ -- peek-u8: (peek-u8 [textual-input-port])
+ If the `port' optional argument is not specified, then the value
+ of the `input-port' keyed dynamic variable is used. If the port
+ is closed, an error is signaled.
+
+ Applicative `peek-u8' reads and returns a byte as an exact
+ unsigned integer between 0 and 255 inclusive (not an external
+ representation of a byte) from the specified port, or an `eof' if
+ the end of file was reached. The position of the port remains
+ unchanged so that new call to `peek-u8' or `read-u8' on the same
+ port return the same byte.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+
+ -- u8-ready?: (u8-ready? [textual-input-port])
+ If the `port' optional argument is not specified, then the value
+ of the `input-port' keyed dynamic variable is used. If the port
+ is closed, an error is signaled.
+
+ Predicate `u8-ready?' checks to see if a byte is available in the
+ specified port. If it returns true, then a `read-u8' or `peek-u8'
+ on that port is guaranteed not to block/hang. For now in klisp
+ this is hardcoded to `#t' because the code to do this is
+ non-portable.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+
+ -- write-u8: (write-u8 u8 [textual-output-port])
+ If the `port' optional argument is not specified, then the value
+ of the `output-port' keyed dynamic variable is used. If the port
+ is closed, an error is signaled.
+
+ Applicative `write-u8' writes the byte represented by the unsigned
+ integer `u8', that should be between 0 and 255 inclusive, (not an
+ external representation of byte) to the specified port. The
+ result returned by `write-u8' is inert.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+
+ -- flush-output-port: (flush-output-port [output-port])
If the `port' optional argument is not specified, then the value
of the `output-port' keyed dynamic variable is used. If the
`port' is closed or if it is not an output port, an error is
@@ -2447,7 +2540,7 @@ Index
* $sequence: Control. (line 23)
* $set!: Environments. (line 182)
* $vau: Combiners. (line 26)
-* ( <1>: Ports. (line 37)
+* ( <1>: Ports. (line 54)
* ( <2>: Numbers. (line 193)
* ( <3>: Continuations. (line 143)
* (: Environments. (line 174)
@@ -2474,6 +2567,7 @@ Index
* assoc: Pairs and lists. (line 252)
* assq: Pairs and lists. (line 333)
* atan: Numbers. (line 386)
+* binary-port?: Ports. (line 43)
* boolean?: Booleans. (line 12)
* booleans: Booleans. (line 6)
* caaaar: Pairs and lists. (line 101)
@@ -2490,8 +2584,8 @@ Index
* cadddr: Pairs and lists. (line 108)
* caddr: Pairs and lists. (line 96)
* cadr: Pairs and lists. (line 90)
-* call-with-input-file: Ports. (line 131)
-* call-with-output-file: Ports. (line 133)
+* call-with-input-file: Ports. (line 173)
+* call-with-output-file: Ports. (line 175)
* call/cc: Continuations. (line 43)
* car: Pairs and lists. (line 85)
* cdaaar: Pairs and lists. (line 109)
@@ -2554,7 +2648,7 @@ Index
* encycle!: Pairs and lists. (line 158)
* environment?: Environments. (line 23)
* environments: Environments. (line 6)
-* eof-object?: Ports. (line 166)
+* eof-object?: Ports. (line 208)
* eq?: Equivalence. (line 12)
* equal?: Equivalence. (line 16)
* equivalence: Equivalence. (line 6)
@@ -2580,7 +2674,7 @@ Index
* gcd: Numbers. (line 207)
* get-current-environment: Environments. (line 114)
* get-list-metrics: Pairs and lists. (line 123)
-* get-module: Ports. (line 156)
+* get-module: Ports. (line 198)
* get-real-exact-bounds: Numbers. (line 233)
* get-real-exact-primary: Numbers. (line 252)
* get-real-internal-bounds: Numbers. (line 232)
@@ -2593,7 +2687,7 @@ Index
* inert: Control. (line 6)
* inert?: Control. (line 11)
* inexact?: Numbers. (line 83)
-* input-port?: Ports. (line 27)
+* input-port?: Ports. (line 32)
* integer->char: Characters. (line 59)
* integer?: Numbers. (line 61)
* Kernel history: Kernel History. (line 6)
@@ -2609,7 +2703,7 @@ Index
* list-ref: Pairs and lists. (line 198)
* list-tail: Pairs and lists. (line 147)
* lists: Pairs and lists. (line 6)
-* load: Ports. (line 143)
+* load: Ports. (line 185)
* log: Numbers. (line 376)
* make-encapsulation-type: Encapsulations. (line 12)
* make-environment: Environments. (line 36)
@@ -2637,17 +2731,19 @@ Index
* object descriptions: A Sample Applicative Description.
(line 6)
* odd?: Numbers. (line 185)
-* open-input-file: Ports. (line 62)
-* open-output-file: Ports. (line 73)
+* open-binary-input-file: Ports. (line 79)
+* open-binary-output-file: Ports. (line 94)
+* open-input-file: Ports. (line 78)
+* open-output-file: Ports. (line 92)
* operative descriptions: A Sample Applicative Description.
(line 6)
* operative?: Combiners. (line 16)
* operatives: Combiners. (line 6)
* or?: Booleans. (line 24)
-* output-port?: Ports. (line 28)
+* output-port?: Ports. (line 33)
* pair?: Pairs and lists. (line 27)
* pairs: Pairs and lists. (line 6)
-* port?: Ports. (line 23)
+* port?: Ports. (line 28)
* ports: Ports. (line 6)
* positive?: Numbers. (line 177)
* printing notation: Printing Notation. (line 6)
@@ -2655,7 +2751,7 @@ Index
* promises: Promises. (line 6)
* rational?: Numbers. (line 66)
* rationalize: Numbers. (line 340)
-* read: Ports. (line 102)
+* read: Ports. (line 144)
* real->exact: Numbers. (line 286)
* real->inexact: Numbers. (line 285)
* real?: Numbers. (line 71)
@@ -2695,6 +2791,7 @@ Index
* symbol?: Symbols. (line 12)
* symbols: Symbols. (line 6)
* tan: Numbers. (line 381)
+* textual-port?: Ports. (line 42)
* truncate: Numbers. (line 326)
* undefined?: Numbers. (line 91)
* unwrap: Combiners. (line 72)
@@ -2733,6 +2830,6 @@ Node: Numbers72249
Node: Strings91748
Node: Characters97095
Node: Ports99805
-Node: Alphabetical Index112780
+Node: Alphabetical Index117409
End Tag Table
diff --git a/manual/src/ports.texi b/manual/src/ports.texi
@@ -7,9 +7,14 @@
@chapter Ports
@cindex ports
- A port is an object that mediates character-based input from a
-source or character-based output to a destination. In the former case,
-the port is an input port, in the latter case, an output port.
+ A port is an object that mediates data from an input or to a
+destination. In the former case, the port is an input port, in the
+latter case, an output port. The data itself can consist of either
+characters or bytes. In the former case the port is a textual port
+and in the latter case, a binary port.
+
+ There are three textual ports open, binded by dynamic variables, one
+for standard input, output, and error.
@c TODO add xref to equal? & eq?
Although ports are not considered immutable, none of the operations
@@ -17,7 +22,7 @@ on ports described in this section constitute mutation. Ports are
@code{equal?} iff @code{eq?}. The port type is encapsulated.
An auxiliary data type used to signal the end of file was reached is
-eof. The eof type consists of a single immutable value, having
+@code{eof}. The eof type consists of a single immutable value, having
an output only external representation (so that it can never be the
normal result of a call to read). The eof type is encapsulated.
@@ -33,68 +38,86 @@ returns true iff all the objects in @code{objects} are of type port.
@deffnx Applicative output-port? (output-port? . objects)
Applicative @code{input-port?} is a predicate that returns true
unless one or more of its arguments is not an input port. Applicative
-output-port? is a predicate that returns true unless one or more of
-its arguments is not an output port.
+@code{output-port?} is a predicate that returns true unless one or
+more of its arguments is not an output port.
Every port must be admitted by at least one of these two predicates.
@end deffn
+@deffn Applicative textual-port? (textual-port? . objects)
+@deffnx Applicative binary-port? (binary-port? . objects)
+ Applicative @code{textual-port?} is a predicate that returns true
+unless one or more of its arguments is not a textual port. Applicative
+@code{binary-port?} is a predicate that returns true unless one or more of
+its arguments is not a binary port.
+
+ Every port must be admitted by at least one of these two predicates.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+@end deffn
+
@deffn with-input-from-file (with-input-from-file string combiner)
@deffnx with-output-to-file (with-output-to-file string combiner)
+@deffnx with-error-to-file (with-error-to-file string combiner)
@c add xref get-current-input-port/get-current-output-port
- These two applicatives open the file named in @code{string} for
-input or output, an invoke the binder of the input-port & output-port
-keyed dynamic variables respectively with the opened port & the passed
-@code{combiner} (this means that the combiner is called in a fresh, empty
-dynamic environment). When/if the binder normally returns, the port is closed.
-The result of the applicatives @code{with-input-from-file} and
-@code{with-output-from-file} is inert.
-
- SOURCE NOTE: this is enumerated in the Kernel report but the text is
-still missing. In the new scheme report there's also a third
-error-port variable. It is very likely that that will be added to the
-klisp implementation in the near future.
+ These three applicatives open the file named in @code{string} for
+textual input or output, an invoke the binder of either the
+input-port, the output-port or the error-port keyed dynamic variables
+respectively with the opened port & the passed @code{combiner} (this
+means that the combiner is called in a fresh, empty dynamic
+environment). When/if the binder normally returns, the port is
+closed. The result of the applicatives @code{with-input-from-file}
+and @code{with-output-from-file} is inert.
+
+ SOURCE NOTE: The first two are enumerated in the Kernel report but
+the text is still missing. The third applicative is from Scheme.
@end deffn
@deffn get-current-input-port (get-current-input-port)
@deffnx get-current-output-port (get-current-output-port)
- These are the accessors for the input-port and output-port keyed
-dynamic variables repectively.
+@deffnx get-current-error-port (get-current-error-port)
+ These are the accessors for the input-port, output-port, and
+error-port keyed dynamic variables repectively.
@c add xref to with-input-from-file, etc
@c add xref and text for these dynamic vars
- SOURCE NOTE: this is enumerated in the Kernel report but the text is
-still missing. In the new scheme report there's also a third
-error-port variable. It is very likely that that will be added to the
-klisp implementation in the near future.
+ SOURCE NOTE: The first two are enumerated in the Kernel report but
+the text is still missing. The third applicative is from Scheme.
@end deffn
@deffn Applicative open-input-file (open-input-file string)
+@deffnx Applicative open-binary-input-file (open-binary-input-file string)
@code{string} should be the name/path for an existing file.
- Applicative @code{open-input-file} creates and returns an input port
-associated with the file represented with @code{string}. If the file
-can't be opened (e.g. because it doesn't exists, or there's a
-permissions problem), an error is signaled.
+ Applicative @code{open-input-file} creates and returns a textual
+input port associated with the file represented with @code{string}.
+Applicative @code{open-binary-input-file} creates and returns a binary
+input port associated with the file represented with @code{string}.
+In either case, if the file can't be opened (e.g. because it doesn't
+exists, or there's a permissions problem), an error is signaled.
- SOURCE NOTE: this is enumerated in the Kernel report but the text is
-still missing.
+ SOURCE NOTE: open-input-file is enumerated in the Kernel report but
+the text is still missing. open-binary-input-file is from Scheme.
@end deffn
@deffn Applicative open-output-file (open-output-file string)
+@deffnx Applicative open-binary-output-file (open-binary-output-file string)
@code{string} should be the name/path for an existing file.
- Applicative @code{open-output-file} creates and returns an output
-port associated with the file represented with @code{string}. If the
-file can't be opened (e.g. if there's a permissions problem), an error
-is signaled.
+ Applicative @code{open-output-file} creates and returns a textual
+output port associated with the file represented with @code{string}.
+Applicative @code{open-binary-output-file} creates and returns a
+binary output port associated with the file represented with
+@code{string}. In either case, if the file can't be opened (e.g. if
+there's a permissions problem), an error is signaled.
- In klisp, for now, applicative @code{open-output-file} truncates the
-file if it already exists, but that could change later (i.e. like in
-scheme the behaviour should be considered unspecified).
+ In klisp, for now, applicative @code{open-output-file} and
+@code{open-binary-output-file} truncate the file if it already exists,
+but that could change later (i.e. like in Scheme the behaviour should
+be considered unspecified).
- SOURCE NOTE: this is enumerated in the Kernel report but the text is
-still missing.
+ SOURCE NOTE: open-output-file is enumerated in the Kernel report but
+the text is still missing. open-binary-output-file is from Scheme.
@end deffn
@deffn close-input-file (close-input-file input-port)
@@ -112,13 +135,30 @@ still missing. There's probably a name error here. These should
probably be called close-input-port & close-output-port.
@end deffn
-@deffn Applicative read (read [input-port])
+@deffn close-input-port (close-input-port input-port)
+@deffnx close-output-port (close-output-port output-port)
+@deffnx close-port (close-port port)
+ These applicatives close the port argument, so that no more
+input/output may be performed on them, and the resources can be
+freed. If the port was already closed these applicatives have no
+effect. If at some time klisp provided input/ouput ports these could
+be used to selectively close only one direction of the port.
+
+ The result returned by applicatives @code{close-input-port},
+@code{close-output-port}, and @code{close-port} is inert.
+
+ SOURCE NOTE: this is from Scheme. The equivalent
+@code{close-input-file} and @code{close-output-file} are probably name
+errors and only retained here till the draft standard rectifies them
+@end deffn
+
+@deffn Applicative read (read [textual-input-port])
If the @code{port} optional argument is not specified, then the
value of the @code{input-port} keyed dynamic variable is used. If the
port is closed, an error is signaled.
Applicative @code{read} reads & returns the next parseable object
-from the given port, or the eof object if no objects remain. If
+from the given port, or the @code{eof} if no objects remain. If
@code{read} finds and unparseable object in the port, an error is
signaled. In that case, the remaining position in the port is
unspecified.
@@ -127,7 +167,7 @@ unspecified.
still missing.
@end deffn
-@deffn write (write object [port])
+@deffn write (write object [textual-output-port])
If the @code{port} optional argument is not specified, then the
value of the @code{output-port} keyed dynamic variable is used. If the
port is closed, an error is signaled.
@@ -147,11 +187,11 @@ still missing.
@deffn Applicative call-with-input-file (call-with-input-file string combiner)
@deffnx Applicative call-with-output-file (call-with-output-file string combiner)
- These applicatives open file named in @code{string} and call their
-@code{combiner} argument in a fresh empty environment passing it as a
-sole operand the opened port. When/if the combiner normally returns a
-value the port is closed and that value is returned as the result of
-the applicative.
+ These applicatives open file named in @code{string} for textual
+input/output respectively and call their @code{combiner} argument in a
+fresh empty environment passing it as a sole operand the opened port.
+When/if the combiner normally returns a value the port is closed and
+that value is returned as the result of the applicative.
SOURCE NOTE: this is enumerated in the Kernel report but the text is
still missing.
@@ -159,10 +199,10 @@ still missing.
@deffn Applicative load (load string)
@c TODO add xref, open/input, read
- Applicative @code{load} opens for input a file named @code{string};
-reads objects from the file until the end of the file is reached;
-evaluates those objects consecutively in the created environment. The
-result from applicative @code{load} is inert.
+ Applicative @code{load} opens the file named @code{string} for
+textual input; reads objects from the file until the end of the file
+is reached; evaluates those objects consecutively in the created
+environment. The result from applicative @code{load} is inert.
SOURCE NOTE: load is enumerated in the Kernel report, but the
description is not there yet. This seems like a sane way to define
@@ -175,11 +215,11 @@ return the value of the last evaluation.
@deffn Applicative get-module (get-module string [environment])
@c TODO add xref standard-environment, open/input, read
Applicative @code{get-module} creates a fresh standard environment;
-opens for input a file named @code{string}; reads objects from the
-file until the end of the file is reached; evaluates those objects
-consecutively in the created environment; and, lastly, returns the
-created environment. If the optional argument @code{environment} is
-specified, the freshly created standard environment is augmented,
+opens the file named @code{string} for textual input; reads objects
+from the file until the end of the file is reached; evaluates those
+objects consecutively in the created environment; and, lastly, returns
+the created environment. If the optional argument @code{environment}
+is specified, the freshly created standard environment is augmented,
prior to evaluating read expressions, by binding symbol
@code{module-parameters} to the @code{environment} argument.
@end deffn
@@ -189,38 +229,38 @@ prior to evaluating read expressions, by binding symbol
returns true iff all the objects in @code{objects} are of type eof.
SOURCE NOTE: This is not in the report, the idea is from Scheme.
-The @code{eof-object?} name is also from scheme, but this will
+The @code{eof-object?} name is also from Scheme, but this will
probably be changed to just @code{eof?}, for consistency with the other
primitive type predicates.
@end deffn
-@deffn read-char (read-char [port])
+@deffn read-char (read-char [textual-input-port])
If the @code{port} optional argument is not specified, then the
value of the @code{input-port} keyed dynamic variable is used. If the
port is closed, an error is signaled.
Applicative @code{read-char} reads and returns a character (not
an external representation of a character) from the specified port, or
-an eof if the end of file was reached.
+an @code{eof} if the end of file was reached.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
@end deffn
-@deffn peek-char (peek-char [port])
+@deffn peek-char (peek-char [textual-input-port])
If the @code{port} optional argument is not specified, then the
value of the @code{input-port} keyed dynamic variable is used. If the
port is closed, an error is signaled.
Applicative @code{peek-char} reads and returns a character (not
an external representation of a character) from the specified port, or
-an eof if the end of file was reached. The position of the port
+an @code{eof} if the end of file was reached. The position of the port
remains unchanged so that new call to @code{peek-char} or
@code{read-char} on the same port return the same character.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
@end deffn
-@deffn char-ready? (char-ready? [port])
+@deffn char-ready? (char-ready? [textual-input-port])
If the @code{port} optional argument is not specified, then the
value of the @code{input-port} keyed dynamic variable is used. If the
port is closed, an error is signaled.
@@ -234,7 +274,7 @@ the code to do this is non-portable.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
@end deffn
-@deffn write-char (write-char char [port])
+@deffn write-char (write-char char [textual-output-port])
If the @code{port} optional argument is not specified, then the
value of the @code{output-port} keyed dynamic variable is used. If the
port is closed, an error is signaled.
@@ -246,7 +286,7 @@ The result returned by @code{write-char} is inert.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
@end deffn
-@deffn newline (newline [port])
+@deffn newline (newline [textal-ouput-port])
If the @code{port} optional argument is not specified, then the
value of the @code{output-port} keyed dynamic variable is used. If the
port is closed, an error is signaled.
@@ -257,7 +297,7 @@ The result returned by @code{newline} is inert.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
@end deffn
-@deffn display (display object [port])
+@deffn display (display object [textual-output-port])
If the @code{port} optional argument is not specified, then the
value of the @code{output-port} keyed dynamic variable is used. If the
port is closed, an error is signaled.
@@ -271,7 +311,62 @@ within those strings and character objects are output as if by
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
@end deffn
-@deffn flush-output-port (flush-output-port [port])
+@deffn read-u8 (read-u8 [textual-input-port])
+ If the @code{port} optional argument is not specified, then the
+value of the @code{input-port} keyed dynamic variable is used. If the
+port is closed, an error is signaled.
+
+ Applicative @code{read-u8} reads and returns a byte as an exact
+unsigned integer between 0 and 255 inclusive (not an external
+representation of a byte) from the specified port, or an @code{eof} if
+the end of file was reached.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+@end deffn
+
+@deffn peek-u8 (peek-u8 [textual-input-port])
+ If the @code{port} optional argument is not specified, then the
+value of the @code{input-port} keyed dynamic variable is used. If the
+port is closed, an error is signaled.
+
+ Applicative @code{peek-u8} reads and returns a byte as an exact
+unsigned integer between 0 and 255 inclusive (not an external
+representation of a byte) from the specified port, or an @code{eof} if
+the end of file was reached. The position of the port remains
+unchanged so that new call to @code{peek-u8} or @code{read-u8} on the
+same port return the same byte.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+@end deffn
+
+@deffn u8-ready? (u8-ready? [textual-input-port])
+ If the @code{port} optional argument is not specified, then the
+value of the @code{input-port} keyed dynamic variable is used. If the
+port is closed, an error is signaled.
+
+ Predicate @code{u8-ready?} checks to see if a byte is
+available in the specified port. If it returns true, then a
+@code{read-u8} or @code{peek-u8} on that port is guaranteed not to
+block/hang. For now in klisp this is hardcoded to @code{#t} because
+the code to do this is non-portable.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+@end deffn
+
+@deffn write-u8 (write-u8 u8 [textual-output-port])
+ If the @code{port} optional argument is not specified, then the
+value of the @code{output-port} keyed dynamic variable is used. If the
+port is closed, an error is signaled.
+
+ Applicative @code{write-u8} writes the byte represented by the
+unsigned integer @code{u8}, that should be between 0 and 255 inclusive,
+(not an external representation of byte) to the specified port. The
+result returned by @code{write-u8} is inert.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+@end deffn
+
+@deffn flush-output-port (flush-output-port [output-port])
If the @code{port} optional argument is not specified, then the
value of the @code{output-port} keyed dynamic variable is used. If
the @code{port} is closed or if it is not an output port, an error is
diff --git a/src/kgports.c b/src/kgports.c
@@ -172,8 +172,8 @@ void read(klisp_State *K, TValue *xparams, TValue ptree, TValue denv)
if (!kport_is_input(port)) {
klispE_throw_simple(K, "the port should be an input port");
return;
- } else if (!kport_is_character(port)) {
- klispE_throw_simple(K, "the port should be a character port");
+ } else if (!kport_is_textual(port)) {
+ klispE_throw_simple(K, "the port should be a textual port");
return;
} else if (kport_is_closed(port)) {
klispE_throw_simple(K, "the port is already closed");
@@ -201,8 +201,8 @@ void write(klisp_State *K, TValue *xparams, TValue ptree, TValue denv)
if (!kport_is_output(port)) {
klispE_throw_simple(K, "the port should be an output port");
return;
- } else if (!kport_is_character(port)) {
- klispE_throw_simple(K, "the port should be a character port");
+ } else if (!kport_is_textual(port)) {
+ klispE_throw_simple(K, "the port should be a textual port");
return;
} else if (kport_is_closed(port)) {
klispE_throw_simple(K, "the port is already closed");
@@ -231,8 +231,8 @@ void newline(klisp_State *K, TValue *xparams, TValue ptree, TValue denv)
if (!kport_is_output(port)) {
klispE_throw_simple(K, "the port should be an output port");
return;
- } else if (!kport_is_character(port)) {
- klispE_throw_simple(K, "the port should be a character port");
+ } else if (!kport_is_textual(port)) {
+ klispE_throw_simple(K, "the port should be a textual port");
return;
} else if (kport_is_closed(port)) {
klispE_throw_simple(K, "the port is already closed");
@@ -259,8 +259,8 @@ void write_char(klisp_State *K, TValue *xparams, TValue ptree, TValue denv)
if (!kport_is_output(port)) {
klispE_throw_simple(K, "the port should be an output port");
return;
- } else if (!kport_is_character(port)) {
- klispE_throw_simple(K, "the port should be a character port");
+ } else if (!kport_is_textual(port)) {
+ klispE_throw_simple(K, "the port should be a textual port");
return;
} else if (kport_is_closed(port)) {
klispE_throw_simple(K, "the port is already closed");
@@ -292,8 +292,8 @@ void read_peek_char(klisp_State *K, TValue *xparams, TValue ptree,
if (!kport_is_input(port)) {
klispE_throw_simple(K, "the port should be an input port");
return;
- } else if (!kport_is_character(port)) {
- klispE_throw_simple(K, "the port should be a character port");
+ } else if (!kport_is_textual(port)) {
+ klispE_throw_simple(K, "the port should be a textual port");
return;
} else if (kport_is_closed(port)) {
klispE_throw_simple(K, "the port is already closed");
@@ -329,8 +329,8 @@ void char_readyp(klisp_State *K, TValue *xparams, TValue ptree, TValue denv)
if (!kport_is_input(port)) {
klispE_throw_simple(K, "the port should be an input port");
return;
- } else if (!kport_is_character(port)) {
- klispE_throw_simple(K, "the port should be a character port");
+ } else if (!kport_is_textual(port)) {
+ klispE_throw_simple(K, "the port should be a textual port");
return;
} else if (kport_is_closed(port)) {
klispE_throw_simple(K, "the port is already closed");
@@ -684,8 +684,8 @@ void display(klisp_State *K, TValue *xparams, TValue ptree, TValue denv)
if (!kport_is_output(port)) {
klispE_throw_simple(K, "the port should be an output port");
return;
- } else if (!kport_is_character(port)) {
- klispE_throw_simple(K, "the port should be a character port");
+ } else if (!kport_is_textual(port)) {
+ klispE_throw_simple(K, "the port should be a textual port");
return;
} else if (kport_is_closed(port)) {
klispE_throw_simple(K, "the port is already closed");
@@ -799,11 +799,11 @@ void kinit_ports_ground_env(klisp_State *K)
p2tv(kis_input_port));
add_applicative(K, ground_env, "output-port?", ftypep, 2, symbol,
p2tv(kis_output_port));
- /* 15.1.? binary-port?, character-port? */
+ /* 15.1.? binary-port?, textual-port? */
add_applicative(K, ground_env, "binary-port?", ftypep, 2, symbol,
p2tv(kis_binary_port));
- add_applicative(K, ground_env, "character-port?", ftypep, 2, symbol,
- p2tv(kis_character_port));
+ add_applicative(K, ground_env, "textual-port?", ftypep, 2, symbol,
+ p2tv(kis_textual_port));
/* 15.1.3 with-input-from-file, with-ouput-to-file */
/* 15.1.? with-error-to-file */
diff --git a/src/kobject.c b/src/kobject.c
@@ -83,9 +83,9 @@ bool kis_binary_port(TValue o)
return ttisport(o) && kport_is_binary(o);
}
-bool kis_character_port(TValue o)
+bool kis_textual_port(TValue o)
{
- return ttisport(o) && kport_is_character(o);
+ return ttisport(o) && kport_is_textual(o);
}
int32_t klispO_log2 (uint32_t x) {
diff --git a/src/kobject.h b/src/kobject.h
@@ -792,7 +792,7 @@ int32_t kmark_count;
#define K_FLAG_OUTPUT_PORT 0x01
#define K_FLAG_INPUT_PORT 0x02
#define K_FLAG_CLOSED_PORT 0x04
-/* At least for now ports are either binary or character */
+/* At least for now ports are either binary or textual */
#define K_FLAG_BINARY_PORT 0x08
#define kport_set_input(o_) (tv_get_kflags(o_) |= K_FLAG_INPUT_PORT)
@@ -804,7 +804,7 @@ int32_t kmark_count;
#define kport_is_output(o_) ((tv_get_kflags(o_) & K_FLAG_OUTPUT_PORT) != 0)
#define kport_is_closed(o_) ((tv_get_kflags(o_) & K_FLAG_CLOSED_PORT) != 0)
#define kport_is_binary(o_) ((tv_get_kflags(o_) & K_FLAG_BINARY_PORT) != 0)
-#define kport_is_character(o_) ((tv_get_kflags(o_) & K_FLAG_BINARY_PORT) == 0)
+#define kport_is_textual(o_) ((tv_get_kflags(o_) & K_FLAG_BINARY_PORT) == 0)
#define K_FLAG_WEAK_KEYS 0x01
#define K_FLAG_WEAK_VALUES 0x02
@@ -820,7 +820,7 @@ int32_t kmark_count;
bool kis_input_port(TValue o);
bool kis_output_port(TValue o);
bool kis_binary_port(TValue o);
-bool kis_character_port(TValue o);
+bool kis_textual_port(TValue o);
/* Macro to test the most basic equality on TValues */
#define tv_equal(tv1_, tv2_) ((tv1_).raw == (tv2_).raw)
diff --git a/src/kwrite.c b/src/kwrite.c
@@ -424,7 +424,7 @@ void kwrite_simple(klisp_State *K, TValue obj)
case K_TPORT:
/* TODO try to get the filename */
kw_printf(K, "#[%s %s port",
- kport_is_binary? "binary" : "character",
+ kport_is_binary(obj)? "binary" : "textual",
kport_is_input(obj)? "input" : "output");
#if KTRACK_NAMES
if (khas_name(obj)) {
