commit 8e5278c3eed890555a0f93fe03d634da4639e02f
parent 7653584b1f91b51ab54dc874b8987202406b8286
Author: Andres Navarro <canavarro82@gmail.com>
Date: Tue, 27 Dec 2011 01:02:48 -0300
Updated the ports manual chapter.
Diffstat:
7 files changed, 944 insertions(+), 668 deletions(-)
diff --git a/TODO b/TODO
@@ -1,8 +1,6 @@
* Release 0.3
** Documentation:
*** update the manual with the current features
-**** complete sections
-- Ports
**** Add missing sections
- vector
- bytevector
@@ -65,12 +63,17 @@
*** add static qualifiers (especially in all kg*.c files)
*** add const qualifiers where sensible
** fix:
-*** fix char-ready? and u8-ready? (r7rs)
+- fix char-ready? and u8-ready? (r7rs)
- Probably need a thread per port
** reader/writer
-*** syntax support for complex numbers (Kernel report)
-*** unicode support
-*** add case sensitive option / compiler flag
+- syntax support for complex numbers (Kernel report)
+- unicode support
+- add case sensitive option / compiler flag
+*** add new external representations
+- vectors
+- bytevectors
+- errors
+- others(?)
** features
*** r7rs
- add optional arguments to all versions of fill!
@@ -119,6 +122,8 @@
- Clean up the structure of the documentation
- a little on the indexes
- add sections for general concepts (tail context, dynamic extent, etc)
+ - find a way to inline function documentation in the c source code
+ (check to see how emacs does this for elisp)
*** README
- Add README files to all directories
*** man page
diff --git a/doc/html/Alphabetical-Index.html b/doc/html/Alphabetical-Index.html
@@ -104,8 +104,8 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Pairs-and-lists.html#index-cadddr-74"><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-62"><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-56"><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-325"><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-326"><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-340"><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-341"><code>call-with-output-file</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Continuations.html#index-call_002fcc-143"><code>call/cc</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
<li><a href="Pairs-and-lists.html#index-car-53"><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-75"><code>cdaaar</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
@@ -137,7 +137,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Characters.html#index-char_002dfoldcase-287"><code>char-foldcase</code></a>: <a href="Characters.html#Characters">Characters</a></li>
<li><a href="Characters.html#index-char_002dlower_002dcase_003f-282"><code>char-lower-case?</code></a>: <a href="Characters.html#Characters">Characters</a></li>
<li><a href="Characters.html#index-char_002dnumeric_003f-279"><code>char-numeric?</code></a>: <a href="Characters.html#Characters">Characters</a></li>
-<li><a href="Ports.html#index-char_002dready_003f-333"><code>char-ready?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-char_002dready_003f-335"><code>char-ready?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Characters.html#index-char_002dtitle_002dcase_003f-283"><code>char-title-case?</code></a>: <a href="Characters.html#Characters">Characters</a></li>
<li><a href="Characters.html#index-char_002dtitlecase-286"><code>char-titlecase</code></a>: <a href="Characters.html#Characters">Characters</a></li>
<li><a href="Characters.html#index-char_002dupcase-284"><code>char-upcase</code></a>: <a href="Characters.html#Characters">Characters</a></li>
@@ -166,11 +166,10 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Pairs-and-lists.html#index-copy_002des_002dimmutable_0021-50"><code>copy-es-immutable!</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Numbers.html#index-cos-225"><code>cos</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Pairs-and-lists.html#index-countable_002dlist_003f-98"><code>countable-list?</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
-<li><a href="Ports.html#index-delete_002dfile-343"><code>delete-file</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-denominator-213"><code>denominator</code></a>: <a href="Numbers.html#Numbers">Numbers</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="Characters.html#index-digit_002d_003echar-292"><code>digit->char</code></a>: <a href="Characters.html#Characters">Characters</a></li>
-<li><a href="Ports.html#index-display-336"><code>display</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-display-329"><code>display</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-div-187"><code>div</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-div_002dand_002dmod-189"><code>div-and-mod</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-div0-190"><code>div0</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
@@ -181,7 +180,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Pairs-and-lists.html#index-encycle_0021-88"><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-106"><code>environment?</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Environments.html#index-environments-104">environments</a>: <a href="Environments.html#Environments">Environments</a></li>
-<li><a href="Ports.html#index-eof_002dobject_003f-330"><code>eof-object?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-eof_002dobject_003f-327"><code>eof-object?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Equivalence.html#index-eq_003f-21"><code>eq?</code></a>: <a href="Equivalence.html#Equivalence">Equivalence</a></li>
<li><a href="Equivalence.html#index-equal_003f-22"><code>equal?</code></a>: <a href="Equivalence.html#Equivalence">Equivalence</a></li>
<li><a href="Equivalence.html#index-equivalence-20">equivalence</a>: <a href="Equivalence.html#Equivalence">Equivalence</a></li>
@@ -197,13 +196,13 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Numbers.html#index-exp-222"><code>exp</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-expt-221"><code>expt</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Continuations.html#index-extend_002dcontinuation-144"><code>extend-continuation</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
-<li><a href="Ports.html#index-file_002dexists_003f-342"><code>file-exists?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Ports.html#index-file_002dport_003f-299"><code>file-port?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Pairs-and-lists.html#index-filter-94"><code>filter</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
+<li><a href="Ports.html#index-find_002drequired_002dfilename-347"><code>find-required-filename</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Pairs-and-lists.html#index-finite_002dlist_003f-97"><code>finite-list?</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Numbers.html#index-finite_003f-173"><code>finite?</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-floor-214"><code>floor</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
-<li><a href="Ports.html#index-flush_002doutput_002dport-341"><code>flush-output-port</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-flush_002doutput_002dport-331"><code>flush-output-port</code></a>: <a href="Ports.html#Ports">Ports</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-33"><code>for-each</code></a>: <a href="Control.html#Control">Control</a></li>
@@ -214,7 +213,9 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Ports.html#index-get_002dcurrent_002dinput_002dport-306"><code>get-current-input-port</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Ports.html#index-get_002dcurrent_002doutput_002dport-307"><code>get-current-output-port</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Pairs-and-lists.html#index-get_002dlist_002dmetrics-86"><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-329"><code>get-module</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-get_002dmodule-348"><code>get-module</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-get_002doutput_002dbytevector-323"><code>get-output-bytevector</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-get_002doutput_002dstring-322"><code>get-output-string</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-get_002dreal_002dexact_002dbounds-203"><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-205"><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-202"><code>get-real-internal-bounds</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
@@ -247,7 +248,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Pairs-and-lists.html#index-list_002dref-91"><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-87"><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-42">lists</a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
-<li><a href="Ports.html#index-load-327"><code>load</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-load-342"><code>load</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-log-223"><code>log</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Encapsulations.html#index-make_002dencapsulation_002dtype-154"><code>make-encapsulation-type</code></a>: <a href="Encapsulations.html#Encapsulations">Encapsulations</a></li>
<li><a href="Environments.html#index-make_002denvironment-109"><code>make-environment</code></a>: <a href="Environments.html#Environments">Environments</a></li>
@@ -269,7 +270,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Pairs-and-lists.html#index-mutable_002dpair_003f-46"><code>mutable-pair?</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Strings.html#index-mutable_002dstring_003f-235"><code>mutable-string?</code></a>: <a href="Strings.html#Strings">Strings</a></li>
<li><a href="Numbers.html#index-negative_003f-194"><code>negative?</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
-<li><a href="Ports.html#index-newline-335"><code>newline</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-newline-328"><code>newline</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Pairs-and-lists.html#index-nil-40">nil</a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Booleans.html#index-not_003f-15"><code>not?</code></a>: <a href="Booleans.html#Booleans">Booleans</a></li>
<li><a href="Pairs-and-lists.html#index-null_003f-44"><code>null?</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
@@ -294,7 +295,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Ports.html#index-output_002dport_003f-296"><code>output-port?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Pairs-and-lists.html#index-pair_003f-43"><code>pair?</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-pairs-39">pairs</a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
-<li><a href="Ports.html#index-peek_002dchar-332"><code>peek-char</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-peek_002dchar-334"><code>peek-char</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Ports.html#index-peek_002du8-338"><code>peek-u8</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Ports.html#index-port_002dopen_003f-302"><code>port-open?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Ports.html#index-port_003f-294"><code>port?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
@@ -305,15 +306,17 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Promises.html#index-promises-155">promises</a>: <a href="Promises.html#Promises">Promises</a></li>
<li><a href="Numbers.html#index-rational_003f-171"><code>rational?</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-rationalize-218"><code>rationalize</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
-<li><a href="Ports.html#index-read-322"><code>read</code></a>: <a href="Ports.html#Ports">Ports</a></li>
-<li><a href="Ports.html#index-read_002dchar-331"><code>read-char</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-read-324"><code>read</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-read_002dchar-333"><code>read-char</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-read_002dline-330"><code>read-line</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Ports.html#index-read_002du8-337"><code>read-u8</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-real_002d_003eexact-208"><code>real->exact</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-real_002d_003einexact-207"><code>real->inexact</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-real_003f-172"><code>real?</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Pairs-and-lists.html#index-reduce-99"><code>reduce</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
-<li><a href="Ports.html#index-rename_002dfile-344"><code>rename-file</code></a>: <a href="Ports.html#Ports">Ports</a></li>
-<li><a href="Ports.html#index-require-328"><code>require</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-register_002drequirement_0021-345"><code>register-requirement!</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-registered_002drequirement_003f-344"><code>registered-requirement?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-require-343"><code>require</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Pairs-and-lists.html#index-reverse-85"><code>reverse</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Numbers.html#index-robust_003f-176"><code>robust?</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Continuations.html#index-root_002dcontinuation-147"><code>root-continuation</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
@@ -365,6 +368,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Ports.html#index-u8_002dready_003f-339"><code>u8-ready?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-u8_003f-170"><code>u8?</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Numbers.html#index-undefined_003f-177"><code>undefined?</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
+<li><a href="Ports.html#index-unregister_002drequirement_0021-346"><code>unregister-requirement!</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Combiners.html#index-unwrap-133"><code>unwrap</code></a>: <a href="Combiners.html#Combiners">Combiners</a></li>
<li><a href="Strings.html#index-vector_002d_003estring-259"><code>vector->string</code></a>: <a href="Strings.html#Strings">Strings</a></li>
<li><a href="Control.html#index-vector_002dfor_002deach-35"><code>vector-for-each</code></a>: <a href="Control.html#Control">Control</a></li>
@@ -374,10 +378,10 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Ports.html#index-with_002doutput_002dto_002dfile-304"><code>with-output-to-file</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-with_002dstrict_002darithmetic-209"><code>with-strict-arithmetic</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Combiners.html#index-wrap-132"><code>wrap</code></a>: <a href="Combiners.html#Combiners">Combiners</a></li>
-<li><a href="Ports.html#index-write-323"><code>write</code></a>: <a href="Ports.html#Ports">Ports</a></li>
-<li><a href="Ports.html#index-write_002dchar-334"><code>write-char</code></a>: <a href="Ports.html#Ports">Ports</a></li>
-<li><a href="Ports.html#index-write_002dsimple-324"><code>write-simple</code></a>: <a href="Ports.html#Ports">Ports</a></li>
-<li><a href="Ports.html#index-write_002du8-340"><code>write-u8</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-write-325"><code>write</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-write_002dchar-332"><code>write-char</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-write_002dsimple-326"><code>write-simple</code></a>: <a href="Ports.html#Ports">Ports</a></li>
+<li><a href="Ports.html#index-write_002du8-336"><code>write-u8</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-zero_003f-186"><code>zero?</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
</ul><!-- Print the tables of contents -->
diff --git a/doc/html/Ports.html b/doc/html/Ports.html
@@ -35,7 +35,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<h2 class="chapter">17 Ports</h2>
<p><a name="index-ports-293"></a>
- A port is an object that mediates data from an input or to a
+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
@@ -45,8 +45,8 @@ and in the latter case, a binary port.
for standard input, output, and error.
<!-- TODO add xref to equal? & eq? -->
- <p>Although ports are not considered immutable, none of the operations
-on ports described in this section constitute mutation. Ports are
+ <p>Although ports are not considered immutable, none of the operations 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
@@ -59,15 +59,15 @@ klisp and was taken from r7rs.
<div class="defun">
— Applicative: <b>port?</b> (<var>port? . objects</var>)<var><a name="index-port_003f-294"></a></var><br>
-<blockquote><p> The primitive type predicate for type port. <code>port?</code>
-returns true iff all the objects in <code>objects</code> are of type port.
+<blockquote><p>The primitive type predicate for type port. <code>port?</code> returns
+true iff all the objects in <code>objects</code> are of type port.
</p></blockquote></div>
<div class="defun">
— Applicative: <b>input-port?</b> (<var>input-port? . objects</var>)<var><a name="index-input_002dport_003f-295"></a></var><br>
— Applicative: <b>output-port?</b> (<var>output-port? . objects</var>)<var><a name="index-output_002dport_003f-296"></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
+<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
<code>output-port?</code> is a predicate that returns true unless one or
more of its arguments is not an output port.
@@ -77,10 +77,10 @@ more of its arguments is not an output port.
<div class="defun">
— Applicative: <b>textual-port?</b> (<var>textual-port? . objects</var>)<var><a name="index-textual_002dport_003f-297"></a></var><br>
— Applicative: <b>binary-port?</b> (<var>binary-port? . objects</var>)<var><a name="index-binary_002dport_003f-298"></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.
+<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>Every port must be admitted by at least one of these two predicates.
@@ -92,17 +92,21 @@ its arguments is not a binary port.
— Applicative: <b>string-port?</b> (<var>string-port? . objects</var>)<var><a name="index-string_002dport_003f-300"></a></var><br>
— Applicative: <b>bytevector-port?</b> (<var>bytevector-port? . objects</var>)<var><a name="index-bytevector_002dport_003f-301"></a></var><br>
<blockquote><p>These applictives are predicates that returns true unless one or more
-of its arguments is not file, string or bytevector port, repectively.
+of its arguments is not a file, string or bytevector port,
+repectively.
<p>Every port in klisp is be admitted by exactly one of these predicates.
- <p>SOURCE NOTE: this is missing from Kernel.
+ <p>SOURCE NOTE: this is missing from Kernel, but convenient in the face
+of the different port types admited by klisp.
</p></blockquote></div>
<div class="defun">
— Applicative: <b>port-open?</b> (<var>port-open? port</var>)<var><a name="index-port_002dopen_003f-302"></a></var><br>
<blockquote><p>Applicative <code>port-open?</code> returns true iff <code>port</code> is still
-open.
+open.
+
+ <p>SOURCE NOTE: this is taken from r7rs.
</p></blockquote></div>
<div class="defun">
@@ -120,42 +124,43 @@ 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.
+the text is still missing. The third applicative is from r7rs.
</p></blockquote></div>
<div class="defun">
— Applicative: <b>get-current-input-port</b> (<var>get-current-input-port</var>)<var><a name="index-get_002dcurrent_002dinput_002dport-306"></a></var><br>
— Applicative: <b>get-current-output-port</b> (<var>get-current-output-port</var>)<var><a name="index-get_002dcurrent_002doutput_002dport-307"></a></var><br>
— Applicative: <b>get-current-error-port</b> (<var>get-current-error-port</var>)<var><a name="index-get_002dcurrent_002derror_002dport-308"></a></var><br>
-<blockquote><p> These are the accessors for the input-port, output-port, and
+<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: The first two are enumerated in the Kernel report but
-the text is still missing. The third applicative is from Scheme.
+ <p>SOURCE NOTE: The first two are enumerated in the Kernel report but the
+text is still missing. The third applicative is from r7rs.
</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-309"></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-310"></a></var><br>
-<blockquote><p> <code>string</code> should be the name/path for an existing file.
+<blockquote><p><code>string</code> should be the name/path for an existing file.
- <p>Applicative <code>open-input-file</code> creates and returns a textual
-input port associated with the file represented with <code>string</code>.
+ <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: open-input-file is enumerated in the Kernel report but
-the text is still missing. open-binary-input-file is from r7rs.
+ <p>SOURCE NOTE: <code>open-input-file</code> is enumerated in the Kernel report
+but the text is still missing. <code>open-binary-input-file</code> is from
+r7rs.
</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-311"></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-312"></a></var><br>
-<blockquote><p> <code>string</code> should be the name/path for an existing file.
+<blockquote><p><code>string</code> should be the name/path for an existing file.
<p>Applicative <code>open-output-file</code> creates and returns a textual
output port associated with the file represented with <code>string</code>.
@@ -169,8 +174,9 @@ there's a permissions problem), an error is signaled.
but that could change later (i.e. like in Scheme the behaviour should
be considered unspecified).
- <p>SOURCE NOTE: open-output-file is enumerated in the Kernel report but
-the text is still missing. open-binary-output-file is from r7rs.
+ <p>SOURCE NOTE: <code>open-output-file</code> is enumerated in the Kernel
+report but the text is still missing. <code>open-binary-output-file</code>
+is from r7rs.
</p></blockquote></div>
<div class="defun">
@@ -184,22 +190,30 @@ unsigned bytes from the passed sequence.
<div class="defun">
— Applicative: <b>open-output-string</b> (<var>open-output-string</var>)<var><a name="index-open_002doutput_002dstring-315"></a></var><br>
+<blockquote><p>Applicative <code>open-output-string</code> returns a fresh textual
+output port that accumulates characters. The accumulated data can
+<!-- TODO add xref -->
+be obtained via applicative <code>get-output-string</code>.
+
+ <p>SOURCE NOTE: This is taken from r7rs.
+</p></blockquote></div>
+
+<div class="defun">
— Applicative: <b>open-output-bytevector</b> (<var>open-output-bytevector</var>)<var><a name="index-open_002doutput_002dbytevector-316"></a></var><br>
-<blockquote><p>These applicative return a fresh output port that accumulates
-characters or unsigned bytes. The accumulated data can be obtained
-via applicatives <code>get-ouput-string</code> and
-<code>get-output-bytevector</code>, respectively.
+<blockquote><p>Applicative <code>open-output-bytevector</code> returns a fresh binary
+output port that accumulates unsigned bytes. The accumulated data can
+<!-- TODO add xref -->
+be obtained via applicative <code>get-output-bytevector</code>.
- <p>SOURCE NOTE: This are taken from r7rs.
+ <p>SOURCE NOTE: This is taken from r7rs.
</p></blockquote></div>
<div class="defun">
— Applicative: <b>close-input-file</b> (<var>close-input-file input-port</var>)<var><a name="index-close_002dinput_002dfile-317"></a></var><br>
— Applicative: <b>close-output-file</b> (<var>close-output-file output-port</var>)<var><a name="index-close_002doutput_002dfile-318"></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.
+<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.
<p>The result returned by applicatives <code>close-input-file</code> and
<code>close-output-file</code> is inert.
@@ -213,28 +227,52 @@ probably be called close-input-port & close-output-port.
— Applicative: <b>close-input-port</b> (<var>close-input-port input-port</var>)<var><a name="index-close_002dinput_002dport-319"></a></var><br>
— Applicative: <b>close-output-port</b> (<var>close-output-port output-port</var>)<var><a name="index-close_002doutput_002dport-320"></a></var><br>
— Applicative: <b>close-port</b> (<var>close-port port</var>)<var><a name="index-close_002dport-321"></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.
+<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/output 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 r7rs. 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>SOURCE NOTE: this is from r7rs. 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-322"></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.
+— Applicative: <b>get-output-string</b> (<var>get-output-string port</var>)<var><a name="index-get_002doutput_002dstring-322"></a></var><br>
+<blockquote><p><code>port</code> should be a string output port.
+
+ <p>Applicative <code>get-output-string</code> returns a freshly created mutable
+string representing the characters accumulated in <code>port</code> so far.
+<code>port</code> can be either open or closed.
+
+ <p>SOURCE NOTE: This is taken from r7rs.
+</p></blockquote></div>
+
+<div class="defun">
+— Applicative: <b>get-output-bytevector</b> (<var>get-output-bytevector port</var>)<var><a name="index-get_002doutput_002dbytevector-323"></a></var><br>
+<blockquote><p><code>port</code> should be a bytevector output port.
+
+ <p>Applicative <code>get-output-bytevector</code> returns a freshly created mutable
+bytevector representing the unsigned bytes accumulated in <code>port</code>
+so far.
+<code>port</code> can be either open or closed.
+
+ <p>SOURCE NOTE: This is taken from r7rs.
+</p></blockquote></div>
+
+<div class="defun">
+— Applicative: <b>read</b> (<var>read </var>[<var>port</var>])<var><a name="index-read-324"></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. The port should be a textual input
+port.
- <p>Applicative <code>read</code> reads & returns the next parseable object
-from the given port, or the <code>eof</code> if no objects remain. If
+ <p>Applicative <code>read</code> reads & returns the next parseable object 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.
@@ -244,10 +282,11 @@ still missing.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>write</b> (<var>write object </var>[<var>textual-output-port</var>])<var><a name="index-write-323"></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.
+— Applicative: <b>write</b> (<var>write object </var>[<var>port</var>])<var><a name="index-write-325"></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. The port should be a textual output
+port.
<!-- TODO add xref to external representation -->
<p>Applicative <code>write</code> writes an external representation of
@@ -255,180 +294,183 @@ port is closed, an error is signaled.
representation that can't be read by applicative <code>read</code> in cases
where the type of <code>object</code> doen't have a parseable external
representation (e.g. combiners and environments). The result returned
-by <code>write</code> is inert.
+by <code>write</code> is inert. <code>write</code> is guaranteed to terminate
+even in the case of objects with shared or cyclic structure. In those
+cases <code>write</code> will use special syntax to preserve sharing info.
+<!-- TODO add section and xref on sharing external representation -->
<p>SOURCE NOTE: this is enumerated in the Kernel report but the text is
still missing.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>write-simple</b> (<var>write-simple object </var>[<var>port</var>])<var><a name="index-write_002dsimple-324"></a></var><br>
+— Applicative: <b>write-simple</b> (<var>write-simple object </var>[<var>port</var>])<var><a name="index-write_002dsimple-326"></a></var><br>
<blockquote><p>Applicative <code>write-simple</code> is like <code>write</code> except that it
-doesn't write sharing info. It will hang if handed a cyclic structure.
+doesn't write sharing info. It will hang if handed a cyclic structure.
+
+ <p>SOURCE NOTE: this is taken from r7rs.
</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-325"></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-326"></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.
+— Applicative: <b>eof-object?</b> (<var>eof-object? . objects</var>)<var><a name="index-eof_002dobject_003f-327"></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 enumerated in the Kernel report but the text is
-still missing.
+ <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 probably be
+changed to just <code>eof?</code>, for consistency with the other primitive
+type predicates.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>load</b> (<var>load string</var>)<var><a name="index-load-327"></a></var><br>
-<blockquote><!-- TODO add xref, open/input, read -->
- <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.
+— Applicative: <b>newline</b> (<var>newline </var>[<var>port</var>])<var><a name="index-newline-328"></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. The port should be a textual output
+port.
- <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
-it, taking the description of <code>get-module</code> that there is in the
-report. The one detail that I think is still open, is whether to
-return <code>#inert</code> (as is the case with klisp currently) or rather
-return the value of the last evaluation.
+ <p>Applicative <code>newline</code> writes a newline to the specified port.
+The result returned by <code>newline</code> is inert.
+
+ <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>require</b><var><a name="index-require-328"></a></var><br>
-<blockquote><p>TODO
-</p></blockquote></div>
+— Applicative: <b>display</b> (<var>display object </var>[<var>port</var>])<var><a name="index-display-329"></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 not a textual output port, or is closed, an error is signaled.
- <p>TODO
+ <p>Applicative <code>display</code> behaves like <code>write</code> except that
+strings are not enclosed in double quotes and no character is escaped
+within those strings and character objects are output as if by
+<code>write-char</code> instead of <code>write</code>. The result returned by
+<code>display</code> is inert.
-<div class="defun">
-— Applicative: <b>get-module</b> (<var>get-module string </var>[<var>environment</var>])<var><a name="index-get_002dmodule-329"></a></var><br>
-<blockquote><!-- TODO add xref standard-environment, open/input, read -->
- <p>Applicative <code>get-module</code> creates a fresh standard environment;
-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>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>eof-object?</b> (<var>eof-object? . objects</var>)<var><a name="index-eof_002dobject_003f-330"></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.
+— Applicative: <b>read-line</b> (<var>read-line </var>[<var>port</var>])<var><a name="index-read_002dline-330"></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 or if it is not a textual input port, an error is signaled.
+
+ <p>Applicative <code>read-line</code>
- <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
-probably be changed to just <code>eof?</code>, for consistency with the other
-primitive type predicates.
+ <p>SOURCE NOTE: this is taken from r7rs.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>read-char</b> (<var>read-char </var>[<var>textual-input-port</var>])<var><a name="index-read_002dchar-331"></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.
+— Applicative: <b>flush-output-port</b> (<var>flush-output-port </var>[<var>port</var>])<var><a name="index-flush_002doutput_002dport-331"></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 or if it is not an output port, 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 <code>eof</code> if the end of file was reached.
+ <p>Applicative <code>flush-output-port</code> flushes any buffered data in the
+output port to the underlying object (file, socket, pipe, memory
+sector, device, etc). The result returned by <code>flush-output-port</code>
+is inert.
- <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+ <p>SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>peek-char</b> (<var>peek-char </var>[<var>textual-input-port</var>])<var><a name="index-peek_002dchar-332"></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.
+— Applicative: <b>write-char</b> (<var>write-char char </var>[<var>port</var>])<var><a name="index-write_002dchar-332"></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. The port should be a textual
+output port.
- <p>Applicative <code>peek-char</code> reads and returns a character (not
-an external representation of a character) 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-char</code> or
-<code>read-char</code> on the same port return the same character.
+ <p>Applicative <code>write-char</code> writes the <code>char</code> character (not
+an external representation of the character) to the specified port.
+The result returned by <code>write-char</code> is inert.
<p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>char-ready?</b> (<var>char-ready? </var>[<var>textual-input-port</var>])<var><a name="index-char_002dready_003f-333"></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.
+— Applicative: <b>read-char</b> (<var>read-char </var>[<var>port</var>])<var><a name="index-read_002dchar-333"></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. The port should be a textual input
+port.
- <p>Predicate <code>char-ready?</code> checks to see if a character is
-available in the specified port. If it returns true, then a
-<code>read-char</code> or <code>peek-char</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>Applicative <code>read-char</code> reads and returns a character (not an
+external representation of a character) 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">
-— Applicative: <b>write-char</b> (<var>write-char char </var>[<var>textual-output-port</var>])<var><a name="index-write_002dchar-334"></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.
+— Applicative: <b>peek-char</b> (<var>peek-char </var>[<var>port</var>])<var><a name="index-peek_002dchar-334"></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. The port should be a textual input
+port.
- <p>Applicative <code>write-char</code> writes the <code>char</code> character (not
-an external representation of the character) to the specified port.
-The result returned by <code>write-char</code> is inert.
+ <p>Applicative <code>peek-char</code> reads and returns a character (not an
+external representation of a character) 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-char</code> or
+<code>read-char</code> on the same port return the same character.
<p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>newline</b> (<var>newline </var>[<var>textal-ouput-port</var>])<var><a name="index-newline-335"></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.
+— Applicative: <b>char-ready?</b> (<var>char-ready? </var>[<var>port</var>])<var><a name="index-char_002dready_003f-335"></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. The port should be a textual input
+port.
- <p>Applicative <code>newline</code> writes a newline to the specified port.
-The result returned by <code>newline</code> is inert.
+ <p>Predicate <code>char-ready?</code> checks to see if a character is available
+in the specified port. If it returns true, then a <code>read-char</code> or
+<code>peek-char</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">
-— Applicative: <b>display</b> (<var>display object </var>[<var>textual-output-port</var>])<var><a name="index-display-336"></a></var><br>
-<blockquote><p> If the <code>port</code> optional argument is not specified, then the
+— Applicative: <b>write-u8</b> (<var>write-u8 u8 </var>[<var>port</var>])<var><a name="index-write_002du8-336"></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.
+port is closed, an error is signaled. The port should be a binary
+output port.
- <p>Applicative <code>display</code> behaves like <code>write</code> except that
-strings are not enclosed in double quotes and no character is escaped
-within those strings and character objects are output as if by
-<code>write-char</code> instead of <code>read</code>. The result returned by
-<code>display</code> is inert.
+ <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>SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>read-u8</b> (<var>read-u8 </var>[<var>textual-input-port</var>])<var><a name="index-read_002du8-337"></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.
+— Applicative: <b>read-u8</b> (<var>read-u8 </var>[<var>port</var>])<var><a name="index-read_002du8-337"></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. The port should be a binary input
+port.
<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>SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>peek-u8</b> (<var>peek-u8 </var>[<var>textual-input-port</var>])<var><a name="index-peek_002du8-338"></a></var><br>
-<blockquote><p> If the <code>port</code> optional argument is not specified, then the
+— Applicative: <b>peek-u8</b> (<var>peek-u8 </var>[<var>port</var>])<var><a name="index-peek_002du8-338"></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.
+port is closed, an error is signaled. The port should be a binary
+input port.
<p>Applicative <code>peek-u8</code> reads and returns a byte as an exact
unsigned integer between 0 and 255 inclusive (not an external
@@ -437,14 +479,15 @@ 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>SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>u8-ready?</b> (<var>u8-ready? </var>[<var>textual-input-port</var>])<var><a name="index-u8_002dready_003f-339"></a></var><br>
-<blockquote><p> If the <code>port</code> optional argument is not specified, then the
+— Applicative: <b>u8-ready?</b> (<var>u8-ready? </var>[<var>port</var>])<var><a name="index-u8_002dready_003f-339"></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.
+port is closed, an error is signaled. The port should be a binary
+input port.
<p>Predicate <code>u8-ready?</code> checks to see if a byte is
available in the specified port. If it returns true, then a
@@ -452,70 +495,109 @@ available in the specified port. If it returns true, then a
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">
-— Applicative: <b>write-u8</b> (<var>write-u8 u8 </var>[<var>textual-output-port</var>])<var><a name="index-write_002du8-340"></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>SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>flush-output-port</b> (<var>flush-output-port </var>[<var>output-port</var>])<var><a name="index-flush_002doutput_002dport-341"></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
-signaled.
-
- <p>Applicative <code>flush-ouput-port</code> flushes any buffered data in the
-output port to the underlying file or device. The result returned by
-<code>flush-output-port</code> is inert.
+— Applicative: <b>call-with-input-file</b> (<var>call-with-input-file string combiner</var>)<var><a name="index-call_002dwith_002dinput_002dfile-340"></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-341"></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 missing from Kernel, it is taken from r7rs Scheme.
+ <p>SOURCE NOTE: this is enumerated in the Kernel report but the text is
+still missing.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>file-exists?</b> (<var>file-exists? string</var>)<var><a name="index-file_002dexists_003f-342"></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
-<code>string</code> exists.
+— Applicative: <b>load</b> (<var>load string</var>)<var><a name="index-load-342"></a></var><br>
+<blockquote><!-- TODO add xref, open/input, read -->
+ <p>Applicative <code>load</code> opens the file named <code>string</code> for textual
+input; reads immutable 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: this is missing from Kernel, it is taken from r7rs Scheme.
+ <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
+it, taking the description of <code>get-module</code> that there is in the
+report. The one detail that I think is still open, is whether to
+return <code>#inert</code> (as is the case with klisp currently) or rather
+return the value of the last evaluation.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>delete-file</b> (<var>delete-file string</var>)<var><a name="index-delete_002dfile-343"></a></var><br>
-<blockquote><p> <code>string</code> should be the name/path for an existing file.
+— Applicative: <b>require</b> (<var>require string</var>)<var><a name="index-require-343"></a></var><br>
+<blockquote><p>Applicative <code>require</code> looks for <code>string</code> following the
+algorithm described in applicative <code>find-required-filename</code>. If
+an appropriate file can't be found, and error is signaled. Otherwise,
+the file is opened for textual input; immutable objects are read and
+acumulated until the end of file is found; those objects are evaluated
+in a fresh standard environment; the results of evaluation are
+discarded and the result from applicative <code>require</code> is inert.
+
+ <p>Applicative <code>require</code> also register <code>string</code> (as via
+applicative <code>register-requirement!</code>) so that subsequent calls to
+<code>require</code> with exactly the same <code>string</code> will not cause any
+search or evaluation. The mechanism used for this can also be
+manipulated directly by the programmer via applicatives
+<code>registered-requirement?</code>, <code>register-requirement!</code>,
+<code>unregister-requirement!</code>, and <code>find-required-filename</code>.
+<!-- TODO add xref to fresh standard environment -->
+
+ <p>Applicative <code>require</code> is useful to load klisp libraries.
+
+ <p>SOURCE NOTE: require is taken from lua and r7rs.
+</p></blockquote></div>
+
+<div class="defun">
+— Applicative: <b>registered-requirement?</b> (<var>registered-requirement? string</var>)<var><a name="index-registered_002drequirement_003f-344"></a></var><br>
+— Applicative: <b>register-requirement!</b> (<var>register-requirement! string</var>)<var><a name="index-register_002drequirement_0021-345"></a></var><br>
+— Applicative: <b>unregister-requirement!</b> (<var>unregister-requirement! string</var>)<var><a name="index-unregister_002drequirement_0021-346"></a></var><br>
+— Applicative: <b>find-required-filename</b> (<var>find-required-filename string</var>)<var><a name="index-find_002drequired_002dfilename-347"></a></var><br>
+<blockquote><p><code>string</code> should be non-empty.
+
+ <p>These applicatives control the underlying facilities used by
+<code>require</code> to register already required files. Predicate
+<code>registered-requirement?</code> returns true iff <code>string</code> is
+already registered. <code>register-requirement!</code> marks <code>string</code>
+as registered (throws an error if it was already registered).
+<code>unregister-requirement!</code> marks <code>string</code> as not being
+registered (throws an error if it wasn't registered).
+<code>find-required-filename</code> looks for an appropriate file for
+<code>string</code> using the algorithm described below.
+
+ <p>filename search in controlled by environment variable
+<code>KLISP_PATH</code>. This environment variable should be a list of
+templates separated with semicolons (“;”). Each template is a
+string that may contain embedded question mark characters (“?”) to
+be replaced with <code>string</code>. After replacements, each template
+represents the path to a file. All templates are probed in order, and
+the first to name an existing readable file is returned. If no
+template corresponds to an existing readable file, an error is
+signaled.
- <p>Applicative <code>delete-file</code> deletes the file named <code>string</code>.
-If it doesn't exists or can't be deleted, an error is signaled. The
-result returned by <code>delete-file</code> is inert.
+ <p>NOTE: in the future there will be some mechanism to alter the search
+algorithm dinamically, in the meantime this environment variable is
+the only way to customize it.
- <p>SOURCE NOTE: this is missing from Kernel, it is taken from r7rs Scheme.
+ <p>SOURCE NOTE: this is not in Kernel, they are supplied per guideline
+G1b of the report (extensibility), so that klisp programs can easily
+duplicate the behaviour of <code>require</code>
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>rename-file</b> (<var>rename-file string1 string2</var>)<var><a name="index-rename_002dfile-344"></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.
-
- <p>Applicative <code>rename-file</code> renames the file named <code>string1</code>
-to <code>string2</code>. If the file doesn't exists or can't be renamed for
-any reason, an error is signaled. The result returned by
-<code>rename-file</code> is inert.
-
- <p>SOURCE NOTE: this is missing from Kernel AND Scheme, it is taken
-from C, being quite similar to <code>delete-file</code>.
+— Applicative: <b>get-module</b> (<var>get-module string </var>[<var>environment</var>])<var><a name="index-get_002dmodule-348"></a></var><br>
+<blockquote><!-- TODO add xref standard-environment, open/input, read -->
+ <p>Applicative <code>get-module</code> creates a fresh standard environment;
+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>
<!-- appendices -->
diff --git a/doc/klisp.info b/doc/klisp.info
@@ -2545,7 +2545,7 @@ result of a call to read). The eof type is encapsulated.
klisp and was taken from r7rs.
-- Applicative: port? (port? . objects)
- The primitive type predicate for type port. `port?' returns true
+ The primitive type predicate for type port. `port?' returns true
iff all the objects in `objects' are of type port.
-- Applicative: input-port? (input-port? . objects)
@@ -2574,17 +2574,20 @@ klisp and was taken from r7rs.
-- Applicative: string-port? (string-port? . objects)
-- Applicative: bytevector-port? (bytevector-port? . objects)
These applictives are predicates that returns true unless one or
- more of its arguments is not file, string or bytevector port,
+ more of its arguments is not a file, string or bytevector port,
repectively.
Every port in klisp is be admitted by exactly one of these
predicates.
- SOURCE NOTE: this is missing from Kernel.
+ SOURCE NOTE: this is missing from Kernel, but convenient in the
+ face of the different port types admited by klisp.
-- Applicative: port-open? (port-open? port)
Applicative `port-open?' returns true iff `port' is still open.
+ SOURCE NOTE: this is taken from r7rs.
+
-- Applicative: with-input-from-file (with-input-from-file string
combiner)
-- Applicative: with-output-to-file (with-output-to-file string
@@ -2600,7 +2603,7 @@ klisp and was taken from r7rs.
`with-input-from-file' and `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.
+ the text is still missing. The third applicative is from r7rs.
-- Applicative: get-current-input-port (get-current-input-port)
-- Applicative: get-current-output-port (get-current-output-port)
@@ -2609,7 +2612,7 @@ klisp and was taken from r7rs.
error-port keyed dynamic variables repectively.
SOURCE NOTE: The first two are enumerated in the Kernel report but
- the text is still missing. The third applicative is from Scheme.
+ the text is still missing. The third applicative is from r7rs.
-- Applicative: open-input-file (open-input-file string)
-- Applicative: open-binary-input-file (open-binary-input-file string)
@@ -2622,8 +2625,9 @@ klisp and was taken from r7rs.
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: open-input-file is enumerated in the Kernel report but
- the text is still missing. open-binary-input-file is from r7rs.
+ SOURCE NOTE: `open-input-file' is enumerated in the Kernel report
+ but the text is still missing. `open-binary-input-file' is from
+ r7rs.
-- Applicative: open-output-file (open-output-file string)
-- Applicative: open-binary-output-file (open-binary-output-file
@@ -2642,8 +2646,8 @@ klisp and was taken from r7rs.
but that could change later (i.e. like in Scheme the behaviour
should be considered unspecified).
- SOURCE NOTE: open-output-file is enumerated in the Kernel report
- but the text is still missing. open-binary-output-file is from
+ SOURCE NOTE: `open-output-file' is enumerated in the Kernel report
+ but the text is still missing. `open-binary-output-file' is from
r7rs.
-- Applicative: open-input-string (open-output-string string)
@@ -2655,13 +2659,18 @@ klisp and was taken from r7rs.
SOURCE NOTE: These are taken from r7rs.
-- Applicative: open-output-string (open-output-string)
+ Applicative `open-output-string' returns a fresh textual output
+ port that accumulates characters. The accumulated data can be
+ obtained via applicative `get-output-string'.
+
+ SOURCE NOTE: This is taken from r7rs.
+
-- Applicative: open-output-bytevector (open-output-bytevector)
- These applicative return a fresh output port that accumulates
- characters or unsigned bytes. The accumulated data can be obtained
- via applicatives `get-ouput-string' and `get-output-bytevector',
- respectively.
+ Applicative `open-output-bytevector' returns a fresh binary output
+ port that accumulates unsigned bytes. The accumulated data can be
+ obtained via applicative `get-output-bytevector'.
- SOURCE NOTE: This are taken from r7rs.
+ SOURCE NOTE: This is taken from r7rs.
-- Applicative: close-input-file (close-input-file input-port)
-- Applicative: close-output-file (close-output-file output-port)
@@ -2683,7 +2692,7 @@ klisp and was taken from r7rs.
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
+ effect. If at some time klisp provided input/output ports these
could be used to selectively close only one direction of the port.
The result returned by applicatives `close-input-port',
@@ -2691,12 +2700,31 @@ klisp and was taken from r7rs.
SOURCE NOTE: this is from r7rs. The equivalent `close-input-file'
and `close-output-file' are probably name errors and only retained
- here till the draft standard rectifies them
+ here till the draft standard rectifies them.
+
+ -- Applicative: get-output-string (get-output-string port)
+ `port' should be a string output port.
+
+ Applicative `get-output-string' returns a freshly created mutable
+ string representing the characters accumulated in `port' so far.
+ `port' can be either open or closed.
+
+ SOURCE NOTE: This is taken from r7rs.
+
+ -- Applicative: get-output-bytevector (get-output-bytevector port)
+ `port' should be a bytevector output port.
- -- Applicative: read (read [textual-input-port])
+ Applicative `get-output-bytevector' returns a freshly created
+ mutable bytevector representing the unsigned bytes accumulated in
+ `port' so far. `port' can be either open or closed.
+
+ SOURCE NOTE: This is taken from r7rs.
+
+ -- Applicative: read (read [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.
+ is closed, an error is signaled. The port should be a textual
+ input port.
Applicative `read' reads & returns the next parseable object from
the given port, or the `eof' if no objects remain. If `read'
@@ -2706,17 +2734,20 @@ klisp and was taken from r7rs.
SOURCE NOTE: this is enumerated in the Kernel report but the text
is still missing.
- -- Applicative: write (write object [textual-output-port])
+ -- Applicative: write (write object [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.
+ is closed, an error is signaled. The port should be a textual
+ output port.
Applicative `write' writes an external representation of `object'
to the specified port. This may be an output-only representation
that can't be read by applicative `read' in cases where the type
of `object' doen't have a parseable external representation (e.g.
combiners and environments). The result returned by `write' is
- inert.
+ inert. `write' is guaranteed to terminate even in the case of
+ objects with shared or cyclic structure. In those cases `write'
+ will use special syntax to preserve sharing info.
SOURCE NOTE: this is enumerated in the Kernel report but the text
is still missing.
@@ -2725,46 +2756,7 @@ klisp and was taken from r7rs.
Applicative `write-simple' is like `write' except that it doesn't
write sharing info. It will hang if handed a cyclic structure.
- -- Applicative: call-with-input-file (call-with-input-file string
- combiner)
- -- Applicative: call-with-output-file (call-with-output-file string
- combiner)
- 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 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
- it, taking the description of `get-module' that there is in the
- report. The one detail that I think is still open, is whether to
- return `#inert' (as is the case with klisp currently) or rather
- return the value of the last evaluation.
-
- -- Applicative: require
- TODO
-
- TODO
-
- -- Applicative: get-module (get-module string [environment])
- Applicative `get-module' creates a fresh standard environment;
- 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.
+ SOURCE NOTE: this is taken from r7rs.
-- Applicative: eof-object? (eof-object? . objects)
The primitive type predicate for type eof. `eof-object?' returns
@@ -2772,50 +2764,60 @@ klisp and was taken from r7rs.
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
- be changed to just `eof?', for consistency with the other
- primitive type predicates.
+ be changed to just `eof?', for consistency with the other primitive
+ type predicates.
- -- Applicative: read-char (read-char [textual-input-port])
+ -- Applicative: newline (newline [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.
+ of the `output-port' keyed dynamic variable is used. If the port
+ is closed, an error is signaled. The port should be a textual
+ output port.
- 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.
+ Applicative `newline' writes a newline to the specified port. The
+ result returned by `newline' is inert.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
- -- Applicative: peek-char (peek-char [textual-input-port])
+ -- Applicative: display (display object [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.
+ of the `output-port' keyed dynamic variable is used. If the port
+ is not a textual output port, or 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
- remains unchanged so that new call to `peek-char' or `read-char'
- on the same port return the same character.
+ Applicative `display' behaves like `write' except that strings are
+ not enclosed in double quotes and no character is escaped within
+ those strings and character objects are output as if by
+ `write-char' instead of `write'. The result returned by `display'
+ is inert.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
- -- Applicative: char-ready? (char-ready? [textual-input-port])
+ -- Applicative: read-line (read-line [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.
+ is closed or if it is not a textual input port, an error is
+ signaled.
- Predicate `char-ready?' checks to see if a character is available
- in the specified port. If it returns true, then a `read-char' or
- `peek-char' 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.
+ Applicative `read-line'
- SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+ SOURCE NOTE: this is taken from r7rs.
+
+ -- Applicative: flush-output-port (flush-output-port [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 signaled.
+
+ Applicative `flush-output-port' flushes any buffered data in the
+ output port to the underlying object (file, socket, pipe, memory
+ sector, device, etc). The result returned by `flush-output-port'
+ is inert.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
- -- Applicative: write-char (write-char char [textual-output-port])
+ -- Applicative: write-char (write-char char [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.
+ is closed, an error is signaled. The port should be a textual
+ output port.
Applicative `write-char' writes the `char' character (not an
external representation of the character) to the specified port.
@@ -2823,45 +2825,77 @@ klisp and was taken from r7rs.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
- -- Applicative: newline (newline [textal-ouput-port])
+ -- Applicative: read-char (read-char [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.
+ of the `input-port' keyed dynamic variable is used. If the port
+ is closed, an error is signaled. The port should be a textual
+ input port.
- Applicative `newline' writes a newline to the specified port. The
- result returned by `newline' is inert.
+ 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.
SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
- -- Applicative: display (display object [textual-output-port])
+ -- Applicative: peek-char (peek-char [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.
+ of the `input-port' keyed dynamic variable is used. If the port
+ is closed, an error is signaled. The port should be a textual
+ input port.
- Applicative `display' behaves like `write' except that strings are
- not enclosed in double quotes and no character is escaped within
- those strings and character objects are output as if by
- `write-char' instead of `read'. The result returned by `display'
- is inert.
+ 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 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.
+
+ -- Applicative: char-ready? (char-ready? [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. The port should be a textual
+ input port.
+
+ Predicate `char-ready?' checks to see if a character is available
+ in the specified port. If it returns true, then a `read-char' or
+ `peek-char' 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.
- -- Applicative: read-u8 (read-u8 [textual-input-port])
+ -- Applicative: write-u8 (write-u8 u8 [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. The port should be a binary
+ output port.
+
+ 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 r7rs.
+
+ -- Applicative: read-u8 (read-u8 [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.
+ is closed, an error is signaled. The port should be a binary input
+ port.
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.
+ SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
- -- Applicative: peek-u8 (peek-u8 [textual-input-port])
+ -- Applicative: peek-u8 (peek-u8 [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.
+ is closed, an error is signaled. The port should be a binary
+ input port.
Applicative `peek-u8' reads and returns a byte as an exact
unsigned integer between 0 and 255 inclusive (not an external
@@ -2870,12 +2904,13 @@ klisp and was taken from r7rs.
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.
+ SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
- -- Applicative: u8-ready? (u8-ready? [textual-input-port])
+ -- Applicative: u8-ready? (u8-ready? [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.
+ is closed, an error is signaled. The port should be a binary
+ input port.
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'
@@ -2883,63 +2918,101 @@ klisp and was taken from r7rs.
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.
-
- -- Applicative: 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.
+ SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
- -- Applicative: 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
- signaled.
+ -- Applicative: call-with-input-file (call-with-input-file string
+ combiner)
+ -- Applicative: call-with-output-file (call-with-output-file string
+ combiner)
+ 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.
- Applicative `flush-ouput-port' flushes any buffered data in the
- output port to the underlying file or device. The result returned
- by `flush-output-port' is inert.
+ SOURCE NOTE: this is enumerated in the Kernel report but the text
+ is still missing.
- SOURCE NOTE: this is missing from Kernel, it is taken from r7rs
- Scheme.
+ -- Applicative: load (load string)
+ Applicative `load' opens the file named `string' for textual
+ input; reads immutable 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: file-exists? (file-exists? string)
- `string' should be the name/path for a file.
+ SOURCE NOTE: load is enumerated in the Kernel report, but the
+ description is not there yet. This seems like a sane way to define
+ it, taking the description of `get-module' that there is in the
+ report. The one detail that I think is still open, is whether to
+ return `#inert' (as is the case with klisp currently) or rather
+ return the value of the last evaluation.
- Predicate `file-exists?' checks to see if a file named `string'
- exists.
+ -- Applicative: require (require string)
+ Applicative `require' looks for `string' following the algorithm
+ described in applicative `find-required-filename'. If an
+ appropriate file can't be found, and error is signaled. Otherwise,
+ the file is opened for textual input; immutable objects are read
+ and acumulated until the end of file is found; those objects are
+ evaluated in a fresh standard environment; the results of
+ evaluation are discarded and the result from applicative `require'
+ is inert.
- SOURCE NOTE: this is missing from Kernel, it is taken from r7rs
- Scheme.
+ Applicative `require' also register `string' (as via applicative
+ `register-requirement!') so that subsequent calls to `require'
+ with exactly the same `string' will not cause any search or
+ evaluation. The mechanism used for this can also be manipulated
+ directly by the programmer via applicatives
+ `registered-requirement?', `register-requirement!',
+ `unregister-requirement!', and `find-required-filename'.
- -- Applicative: delete-file (delete-file string)
- `string' should be the name/path for an existing file.
+ Applicative `require' is useful to load klisp libraries.
- Applicative `delete-file' deletes the file named `string'. If it
- doesn't exists or can't be deleted, an error is signaled. The
- result returned by `delete-file' is inert.
+ SOURCE NOTE: require is taken from lua and r7rs.
- SOURCE NOTE: this is missing from Kernel, it is taken from r7rs
- Scheme.
+ -- Applicative: registered-requirement? (registered-requirement?
+ string)
+ -- Applicative: register-requirement! (register-requirement! string)
+ -- Applicative: unregister-requirement! (unregister-requirement!
+ string)
+ -- Applicative: find-required-filename (find-required-filename string)
+ `string' should be non-empty.
+
+ These applicatives control the underlying facilities used by
+ `require' to register already required files. Predicate
+ `registered-requirement?' returns true iff `string' is already
+ registered. `register-requirement!' marks `string' as registered
+ (throws an error if it was already registered).
+ `unregister-requirement!' marks `string' as not being registered
+ (throws an error if it wasn't registered).
+ `find-required-filename' looks for an appropriate file for
+ `string' using the algorithm described below.
+
+ filename search in controlled by environment variable
+ `KLISP_PATH'. This environment variable should be a list of
+ templates separated with semicolons (";"). Each template is a
+ string that may contain embedded question mark characters ("?") to
+ be replaced with `string'. After replacements, each template
+ represents the path to a file. All templates are probed in order,
+ and the first to name an existing readable file is returned. If no
+ template corresponds to an existing readable file, an error is
+ signaled.
- -- Applicative: rename-file (rename-file string1 string2)
- `string1' should be the name/path for an existing file, `string2'
- should be the name/path for a non existing file.
+ NOTE: in the future there will be some mechanism to alter the
+ search algorithm dinamically, in the meantime this environment
+ variable is the only way to customize it.
- Applicative `rename-file' renames the file named `string1' to
- `string2'. If the file doesn't exists or can't be renamed for any
- reason, an error is signaled. The result returned by `rename-file'
- is inert.
+ SOURCE NOTE: this is not in Kernel, they are supplied per guideline
+ G1b of the report (extensibility), so that klisp programs can
+ easily duplicate the behaviour of `require'
- SOURCE NOTE: this is missing from Kernel AND Scheme, it is taken
- from C, being quite similar to `delete-file'.
+ -- Applicative: get-module (get-module string [environment])
+ Applicative `get-module' creates a fresh standard environment;
+ 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.
File: klisp.info, Node: Alphabetical Index, Next: (dir), Prev: Ports, Up: Top
@@ -3020,8 +3093,8 @@ Index
* cadddr: Pairs and lists. (line 118)
* caddr: Pairs and lists. (line 106)
* cadr: Pairs and lists. (line 100)
-* call-with-input-file: Ports. (line 210)
-* call-with-output-file: Ports. (line 212)
+* call-with-input-file: Ports. (line 405)
+* call-with-output-file: Ports. (line 407)
* call/cc: Continuations. (line 43)
* car: Pairs and lists. (line 95)
* cdaaar: Pairs and lists. (line 119)
@@ -3053,7 +3126,7 @@ Index
* char-foldcase: Characters. (line 61)
* char-lower-case?: Characters. (line 50)
* char-numeric?: Characters. (line 44)
-* char-ready?: Ports. (line 283)
+* char-ready?: Ports. (line 335)
* char-title-case?: Characters. (line 51)
* char-titlecase: Characters. (line 60)
* char-upcase: Characters. (line 58)
@@ -3066,11 +3139,11 @@ Index
* char>?: Characters. (line 30)
* char?: Characters. (line 23)
* characters: Characters. (line 6)
-* close-input-file: Ports. (line 147)
-* close-input-port: Ports. (line 161)
-* close-output-file: Ports. (line 148)
-* close-output-port: Ports. (line 162)
-* close-port: Ports. (line 163)
+* close-input-file: Ports. (line 156)
+* close-input-port: Ports. (line 170)
+* close-output-file: Ports. (line 157)
+* close-output-port: Ports. (line 171)
+* close-port: Ports. (line 172)
* combiner?: Combiners. (line 134)
* combiners: Combiners. (line 6)
* cons: Pairs and lists. (line 45)
@@ -3082,12 +3155,11 @@ Index
* copy-es-immutable!: Pairs and lists. (line 59)
* cos: Numbers. (line 405)
* countable-list?: Pairs and lists. (line 307)
-* delete-file: Ports. (line 403)
* denominator: Numbers. (line 330)
* description format: Format of Descriptions.
(line 6)
* digit->char: Characters. (line 92)
-* display: Ports. (line 317)
+* display: Ports. (line 262)
* div: Numbers. (line 164)
* div-and-mod: Numbers. (line 166)
* div0: Numbers. (line 178)
@@ -3098,7 +3170,7 @@ Index
* encycle!: Pairs and lists. (line 196)
* environment?: Environments. (line 23)
* environments: Environments. (line 6)
-* eof-object?: Ports. (line 250)
+* eof-object?: Ports. (line 242)
* eq?: Equivalence. (line 12)
* equal?: Equivalence. (line 16)
* equivalence: Equivalence. (line 6)
@@ -3114,13 +3186,13 @@ Index
* exp: Numbers. (line 402)
* expt: Numbers. (line 397)
* extend-continuation: Continuations. (line 50)
-* file-exists?: Ports. (line 394)
* file-port?: Ports. (line 54)
* filter: Pairs and lists. (line 277)
+* find-required-filename: Ports. (line 457)
* finite-list?: Pairs and lists. (line 303)
* finite?: Numbers. (line 90)
* floor: Numbers. (line 339)
-* flush-output-port: Ports. (line 381)
+* flush-output-port: Ports. (line 285)
* fonts: Some Terms. (line 13)
* foo: A Sample Applicative Description.
(line 15)
@@ -3128,11 +3200,13 @@ Index
* force: Promises. (line 35)
* gcd: Numbers. (line 222)
* get-current-environment: Environments. (line 114)
-* get-current-error-port: Ports. (line 88)
-* get-current-input-port: Ports. (line 86)
-* get-current-output-port: Ports. (line 87)
+* get-current-error-port: Ports. (line 91)
+* get-current-input-port: Ports. (line 89)
+* get-current-output-port: Ports. (line 90)
* get-list-metrics: Pairs and lists. (line 161)
-* get-module: Ports. (line 240)
+* get-module: Ports. (line 488)
+* get-output-bytevector: Ports. (line 195)
+* get-output-string: Ports. (line 186)
* get-real-exact-bounds: Numbers. (line 248)
* get-real-exact-primary: Numbers. (line 267)
* get-real-internal-bounds: Numbers. (line 247)
@@ -3165,7 +3239,7 @@ Index
* list-ref: Pairs and lists. (line 236)
* list-tail: Pairs and lists. (line 185)
* lists: Pairs and lists. (line 6)
-* load: Ports. (line 222)
+* load: Ports. (line 417)
* log: Numbers. (line 403)
* make-encapsulation-type: Encapsulations. (line 12)
* make-environment: Environments. (line 36)
@@ -3187,7 +3261,7 @@ Index
* mutable-pair?: Pairs and lists. (line 36)
* mutable-string?: Strings. (line 52)
* negative?: Numbers. (line 193)
-* newline: Ports. (line 307)
+* newline: Ports. (line 251)
* nil: Pairs and lists. (line 6)
* not?: Booleans. (line 16)
* null?: Pairs and lists. (line 31)
@@ -3198,14 +3272,14 @@ Index
* object descriptions: A Sample Applicative Description.
(line 6)
* odd?: Numbers. (line 200)
-* open-binary-input-file: Ports. (line 96)
-* open-binary-output-file: Ports. (line 111)
-* open-input-bytevector: Ports. (line 132)
-* open-input-file: Ports. (line 95)
-* open-input-string: Ports. (line 130)
-* open-output-bytevector: Ports. (line 139)
-* open-output-file: Ports. (line 109)
-* open-output-string: Ports. (line 138)
+* open-binary-input-file: Ports. (line 99)
+* open-binary-output-file: Ports. (line 115)
+* open-input-bytevector: Ports. (line 136)
+* open-input-file: Ports. (line 98)
+* open-input-string: Ports. (line 134)
+* open-output-bytevector: Ports. (line 149)
+* open-output-file: Ports. (line 113)
+* open-output-string: Ports. (line 142)
* operative descriptions: A Sample Applicative Description.
(line 6)
* operative?: Combiners. (line 16)
@@ -3214,9 +3288,9 @@ Index
* output-port?: Ports. (line 33)
* pair?: Pairs and lists. (line 27)
* pairs: Pairs and lists. (line 6)
-* peek-char: Ports. (line 270)
-* peek-u8: Ports. (line 342)
-* port-open?: Ports. (line 66)
+* peek-char: Ports. (line 321)
+* peek-u8: Ports. (line 375)
+* port-open?: Ports. (line 67)
* port?: Ports. (line 28)
* ports: Ports. (line 6)
* positive?: Numbers. (line 192)
@@ -3225,15 +3299,17 @@ Index
* promises: Promises. (line 6)
* rational?: Numbers. (line 81)
* rationalize: Numbers. (line 355)
-* read: Ports. (line 177)
-* read-char: Ports. (line 259)
-* read-u8: Ports. (line 330)
+* read: Ports. (line 204)
+* read-char: Ports. (line 309)
+* read-line: Ports. (line 275)
+* read-u8: Ports. (line 362)
* real->exact: Numbers. (line 301)
* real->inexact: Numbers. (line 300)
* real?: Numbers. (line 86)
* reduce: Pairs and lists. (line 312)
-* rename-file: Ports. (line 413)
-* require: Ports. (line 235)
+* register-requirement!: Ports. (line 454)
+* registered-requirement?: Ports. (line 453)
+* require: Ports. (line 430)
* reverse: Pairs and lists. (line 150)
* robust?: Numbers. (line 102)
* root-continuation: Continuations. (line 104)
@@ -3282,22 +3358,23 @@ Index
* tan: Numbers. (line 406)
* textual-port?: Ports. (line 42)
* truncate: Numbers. (line 341)
-* u8-ready?: Ports. (line 356)
+* u8-ready?: Ports. (line 390)
* u8?: Numbers. (line 73)
* undefined?: Numbers. (line 106)
+* unregister-requirement!: Ports. (line 456)
* unwrap: Combiners. (line 72)
* vector->string: Strings. (line 132)
* vector-for-each: Control. (line 54)
* vector-map: Combiners. (line 121)
-* with-error-to-file: Ports. (line 73)
-* with-input-from-file: Ports. (line 70)
-* with-output-to-file: Ports. (line 72)
+* with-error-to-file: Ports. (line 76)
+* with-input-from-file: Ports. (line 73)
+* with-output-to-file: Ports. (line 75)
* with-strict-arithmetic: Numbers. (line 313)
* wrap: Combiners. (line 68)
-* write: Ports. (line 190)
-* write-char: Ports. (line 296)
-* write-simple: Ports. (line 205)
-* write-u8: Ports. (line 369)
+* write: Ports. (line 218)
+* write-char: Ports. (line 297)
+* write-simple: Ports. (line 236)
+* write-u8: Ports. (line 349)
* zero?: Numbers. (line 158)
@@ -3334,6 +3411,6 @@ Node: Numbers82491
Node: Strings104945
Node: Characters112206
Node: Ports116852
-Node: Alphabetical Index136300
+Node: Alphabetical Index140004
End Tag Table
diff --git a/doc/src/ports.texi b/doc/src/ports.texi
@@ -7,21 +7,21 @@
@chapter Ports
@cindex ports
- A port is an object that mediates data from an input or to a
+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.
+and in the latter case, a binary port.
- There are three textual ports open, binded by dynamic variables, one
+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
-on ports described in this section constitute mutation. Ports are
+Although ports are not considered immutable, none of the operations 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
+An auxiliary data type used to signal the end of file was reached is
@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.
@@ -30,53 +30,57 @@ SOURCE NOTE: the eof type is not in the Kernel report, it is used in
klisp and was taken from r7rs.
@deffn Applicative port? (port? . objects)
- The primitive type predicate for type port. @code{port?}
-returns true iff all the objects in @code{objects} are of type port.
+The primitive type predicate for type port. @code{port?} returns
+true iff all the objects in @code{objects} are of type port.
@end deffn
@deffn Applicative input-port? (input-port? . objects)
@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
+Applicative @code{input-port?} is a predicate that returns true unless
+one or more of its arguments is not an input port. Applicative
@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.
+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.
+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.
+Every port must be admitted by at least one of these two predicates.
- SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
+SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
@end deffn
@deffn Applicative file-port? (file-port? . objects)
@deffnx Applicative string-port? (string-port? . objects)
@deffnx Applicative bytevector-port? (bytevector-port? . objects)
These applictives are predicates that returns true unless one or more
-of its arguments is not file, string or bytevector port, repectively.
+of its arguments is not a file, string or bytevector port,
+repectively.
- Every port in klisp is be admitted by exactly one of these predicates.
+Every port in klisp is be admitted by exactly one of these predicates.
- SOURCE NOTE: this is missing from Kernel.
+SOURCE NOTE: this is missing from Kernel, but convenient in the face
+of the different port types admited by klisp.
@end deffn
@deffn Applicative port-open? (port-open? port)
Applicative @code{port-open?} returns true iff @code{port} is still
open.
+
+SOURCE NOTE: this is taken from r7rs.
@end deffn
@deffn Applicative with-input-from-file (with-input-from-file string combiner)
@deffnx Applicative with-output-to-file (with-output-to-file string combiner)
@deffnx Applicative with-error-to-file (with-error-to-file string combiner)
@c add xref get-current-input-port/get-current-output-port
- These three applicatives open the file named in @code{string} for
+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
@@ -85,55 +89,57 @@ 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.
+SOURCE NOTE: The first two are enumerated in the Kernel report but
+the text is still missing. The third applicative is from r7rs.
@end deffn
@deffn Applicative get-current-input-port (get-current-input-port)
@deffnx Applicative get-current-output-port (get-current-output-port)
@deffnx Applicative get-current-error-port (get-current-error-port)
- These are the accessors for the input-port, output-port, and
+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: The first two are enumerated in the Kernel report but
-the text is still missing. The third applicative is from Scheme.
+SOURCE NOTE: The first two are enumerated in the Kernel report but the
+text is still missing. The third applicative is from r7rs.
@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.
+@code{string} should be the name/path for an existing file.
- Applicative @code{open-input-file} creates and returns a textual
-input port associated with the file represented with @code{string}.
+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: open-input-file is enumerated in the Kernel report but
-the text is still missing. open-binary-input-file is from r7rs.
+SOURCE NOTE: @code{open-input-file} is enumerated in the Kernel report
+but the text is still missing. @code{open-binary-input-file} is from
+r7rs.
@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.
+@code{string} should be the name/path for an existing file.
- Applicative @code{open-output-file} creates and returns a textual
+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.
+there's a permissions problem), an error is signaled.
- In klisp, for now, applicative @code{open-output-file} and
+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: open-output-file is enumerated in the Kernel report but
-the text is still missing. open-binary-output-file is from r7rs.
+SOURCE NOTE: @code{open-output-file} is enumerated in the Kernel
+report but the text is still missing. @code{open-binary-output-file}
+is from r7rs.
@end deffn
@deffn Applicative open-input-string (open-output-string string)
@@ -141,30 +147,37 @@ the text is still missing. open-binary-output-file is from r7rs.
These applicative return a fresh input port that reads characters or
unsigned bytes from the passed sequence.
- SOURCE NOTE: These are taken from r7rs.
+SOURCE NOTE: These are taken from r7rs.
@end deffn
@deffn Applicative open-output-string (open-output-string)
-@deffnx Applicative open-output-bytevector (open-output-bytevector)
-These applicative return a fresh output port that accumulates
-characters or unsigned bytes. The accumulated data can be obtained
-via applicatives @code{get-ouput-string} and
-@code{get-output-bytevector}, respectively.
+Applicative @code{open-output-string} returns a fresh textual
+output port that accumulates characters. The accumulated data can
+@c TODO add xref
+be obtained via applicative @code{get-output-string}.
+
+SOURCE NOTE: This is taken from r7rs.
+@end deffn
- SOURCE NOTE: This are taken from r7rs.
+@deffn Applicative open-output-bytevector (open-output-bytevector)
+Applicative @code{open-output-bytevector} returns a fresh binary
+output port that accumulates unsigned bytes. The accumulated data can
+@c TODO add xref
+be obtained via applicative @code{get-output-bytevector}.
+
+SOURCE NOTE: This is taken from r7rs.
@end deffn
@deffn Applicative close-input-file (close-input-file input-port)
@deffnx Applicative close-output-file (close-output-file output-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.
+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.
- The result returned by applicatives @code{close-input-file} and
+The result returned by applicatives @code{close-input-file} and
@code{close-output-file} is inert.
- SOURCE NOTE: this is enumerated in the Kernel report but the text is
+SOURCE NOTE: this is enumerated in the Kernel report but the text is
still missing. There's probably a name error here. These should
probably be called close-input-port & close-output-port.
@end deffn
@@ -172,48 +185,73 @@ probably be called close-input-port & close-output-port.
@deffn Applicative close-input-port (close-input-port input-port)
@deffnx Applicative close-output-port (close-output-port output-port)
@deffnx Applicative 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.
+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/output ports these could be used to
+selectively close only one direction of the port.
- The result returned by applicatives @code{close-input-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 r7rs. 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
+SOURCE NOTE: this is from r7rs. 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.
+@deffn Applicative get-output-string (get-output-string port)
+@code{port} should be a string output port.
+
+Applicative @code{get-output-string} returns a freshly created mutable
+string representing the characters accumulated in @code{port} so far.
+@code{port} can be either open or closed.
- Applicative @code{read} reads & returns the next parseable object
-from the given port, or the @code{eof} if no objects remain. If
+SOURCE NOTE: This is taken from r7rs.
+@end deffn
+
+@deffn Applicative get-output-bytevector (get-output-bytevector port)
+@code{port} should be a bytevector output port.
+
+Applicative @code{get-output-bytevector} returns a freshly created mutable
+bytevector representing the unsigned bytes accumulated in @code{port}
+so far.
+@code{port} can be either open or closed.
+
+SOURCE NOTE: This is taken from r7rs.
+@end deffn
+
+@deffn Applicative read (read [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. The port should be a textual input
+port.
+
+Applicative @code{read} reads & returns the next parseable object 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.
- SOURCE NOTE: this is enumerated in the Kernel report but the text is
+SOURCE NOTE: this is enumerated in the Kernel report but the text is
still missing.
@end deffn
-@deffn Applicative 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.
+@deffn Applicative write (write object [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. The port should be a textual output
+port.
@c TODO add xref to external representation
- Applicative @code{write} writes an external representation of
+Applicative @code{write} writes an external representation of
@code{object} to the specified port. This may be an output-only
representation that can't be read by applicative @code{read} in cases
where the type of @code{object} doen't have a parseable external
representation (e.g. combiners and environments). The result returned
-by @code{write} is inert.
-
+by @code{write} is inert. @code{write} is guaranteed to terminate
+even in the case of objects with shared or cyclic structure. In those
+cases @code{write} will use special syntax to preserve sharing info.
+@c TODO add section and xref on sharing external representation
SOURCE NOTE: this is enumerated in the Kernel report but the text is
still missing.
@@ -222,236 +260,281 @@ still missing.
@deffn Applicative write-simple (write-simple object [port])
Applicative @code{write-simple} is like @code{write} except that it
doesn't write sharing info. It will hang if handed a cyclic structure.
+
+SOURCE NOTE: this is taken from r7rs.
@end deffn
-@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} 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.
+@deffn Applicative eof-object? (eof-object? . objects)
+The primitive type predicate for type eof. @code{eof-object?}
+returns true iff all the objects in @code{objects} are of type eof.
- SOURCE NOTE: this is enumerated in the Kernel report but the text is
-still missing.
+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 probably be
+changed to just @code{eof?}, for consistency with the other primitive
+type predicates.
@end deffn
-@deffn Applicative load (load string)
-@c TODO add xref, open/input, read
- 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.
+@deffn Applicative newline (newline [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. The port should be a textual output
+port.
- SOURCE NOTE: load is enumerated in the Kernel report, but the
-description is not there yet. This seems like a sane way to define
-it, taking the description of @code{get-module} that there is in the
-report. The one detail that I think is still open, is whether to
-return @code{#inert} (as is the case with klisp currently) or rather
-return the value of the last evaluation.
-@end deffn
+Applicative @code{newline} writes a newline to the specified port.
+The result returned by @code{newline} is inert.
-@deffn Applicative require
-TODO
+SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
@end deffn
-TODO
-@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 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.
+@deffn Applicative display (display object [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 not a textual output port, or is closed, an error is signaled.
+
+Applicative @code{display} behaves like @code{write} except that
+strings are not enclosed in double quotes and no character is escaped
+within those strings and character objects are output as if by
+@code{write-char} instead of @code{write}. The result returned by
+@code{display} is inert.
+
+SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
@end deffn
-@deffn Applicative eof-object? (eof-object? . objects)
- The primitive type predicate for type eof. @code{eof-object?}
-returns true iff all the objects in @code{objects} are of type eof.
+@deffn Applicative read-line (read-line [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 or if it is not a textual input port, an error is signaled.
+
+Applicative @code{read-line}
- 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
-probably be changed to just @code{eof?}, for consistency with the other
-primitive type predicates.
+SOURCE NOTE: this is taken from r7rs.
@end deffn
-@deffn Applicative 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.
+@deffn Applicative flush-output-port (flush-output-port [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 or if it is not an output port, 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 @code{eof} if the end of file was reached.
+Applicative @code{flush-output-port} flushes any buffered data in the
+output port to the underlying object (file, socket, pipe, memory
+sector, device, etc). The result returned by @code{flush-output-port}
+is inert.
- SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
@end deffn
-@deffn Applicative 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 @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.
+@deffn Applicative write-char (write-char char [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. The port should be a textual
+output port.
- SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
+Applicative @code{write-char} writes the @code{char} character (not
+an external representation of the character) to the specified port.
+The result returned by @code{write-char} is inert.
+
+SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
@end deffn
-@deffn Applicative 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.
- Predicate @code{char-ready?} checks to see if a character is
-available in the specified port. If it returns true, then a
-@code{read-char} or @code{peek-char} 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.
+@deffn Applicative read-char (read-char [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. The port should be a textual input
+port.
+
+Applicative @code{read-char} reads and returns a character (not an
+external representation of a character) 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.
+SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
@end deffn
-@deffn Applicative 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.
+@deffn Applicative peek-char (peek-char [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. The port should be a textual input
+port.
- Applicative @code{write-char} writes the @code{char} character (not
-an external representation of the character) to the specified port.
-The result returned by @code{write-char} is inert.
+Applicative @code{peek-char} reads and returns a character (not an
+external representation of a character) 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-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.
+SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
@end deffn
-@deffn Applicative 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.
+@deffn Applicative char-ready? (char-ready? [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. The port should be a textual input
+port.
- Applicative @code{newline} writes a newline to the specified port.
-The result returned by @code{newline} is inert.
+Predicate @code{char-ready?} checks to see if a character is available
+in the specified port. If it returns true, then a @code{read-char} or
+@code{peek-char} 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.
+SOURCE NOTE: this is missing from Kernel, it is taken from Scheme.
@end deffn
-@deffn Applicative display (display object [textual-output-port])
- If the @code{port} optional argument is not specified, then the
+
+@deffn Applicative write-u8 (write-u8 u8 [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.
+port is closed, an error is signaled. The port should be a binary
+output port.
- Applicative @code{display} behaves like @code{write} except that
-strings are not enclosed in double quotes and no character is escaped
-within those strings and character objects are output as if by
-@code{write-char} instead of @code{read}. The result returned by
-@code{display} is inert.
+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.
+SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
@end deffn
-@deffn Applicative 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.
+@deffn Applicative read-u8 (read-u8 [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. The port should be a binary input
+port.
- Applicative @code{read-u8} reads and returns a byte as an exact
+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.
+SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
@end deffn
-@deffn Applicative peek-u8 (peek-u8 [textual-input-port])
- If the @code{port} optional argument is not specified, then the
+@deffn Applicative peek-u8 (peek-u8 [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.
+port is closed, an error is signaled. The port should be a binary
+input port.
- Applicative @code{peek-u8} reads and returns a byte as an exact
+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.
+SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
@end deffn
-@deffn Applicative u8-ready? (u8-ready? [textual-input-port])
- If the @code{port} optional argument is not specified, then the
+@deffn Applicative u8-ready? (u8-ready? [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.
+port is closed, an error is signaled. The port should be a binary
+input port.
- Predicate @code{u8-ready?} checks to see if a byte is
+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 Applicative 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.
+SOURCE NOTE: this is missing from Kernel, it is taken from r7rs.
@end deffn
-@deffn Applicative 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
-signaled.
-
- Applicative @code{flush-ouput-port} flushes any buffered data in the
-output port to the underlying file or device. The result returned by
-@code{flush-output-port} is inert.
+@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} 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 missing from Kernel, it is taken from r7rs Scheme.
+SOURCE NOTE: this is enumerated in the Kernel report but the text is
+still missing.
@end deffn
-@deffn Applicative file-exists? (file-exists? string)
- @code{string} should be the name/path for a file.
-
- Predicate @code{file-exists?} checks to see if a file named
-@code{string} exists.
+@deffn Applicative load (load string)
+@c TODO add xref, open/input, read
+Applicative @code{load} opens the file named @code{string} for textual
+input; reads immutable 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: this is missing from Kernel, it is taken from r7rs Scheme.
+SOURCE NOTE: load is enumerated in the Kernel report, but the
+description is not there yet. This seems like a sane way to define
+it, taking the description of @code{get-module} that there is in the
+report. The one detail that I think is still open, is whether to
+return @code{#inert} (as is the case with klisp currently) or rather
+return the value of the last evaluation.
@end deffn
-@deffn Applicative delete-file (delete-file string)
- @code{string} should be the name/path for an existing file.
+@deffn Applicative require (require string)
+Applicative @code{require} looks for @code{string} following the
+algorithm described in applicative @code{find-required-filename}. If
+an appropriate file can't be found, and error is signaled. Otherwise,
+the file is opened for textual input; immutable objects are read and
+acumulated until the end of file is found; those objects are evaluated
+in a fresh standard environment; the results of evaluation are
+discarded and the result from applicative @code{require} is inert.
+
+Applicative @code{require} also register @code{string} (as via
+applicative @code{register-requirement!}) so that subsequent calls to
+@code{require} with exactly the same @code{string} will not cause any
+search or evaluation. The mechanism used for this can also be
+manipulated directly by the programmer via applicatives
+@code{registered-requirement?}, @code{register-requirement!},
+@code{unregister-requirement!}, and @code{find-required-filename}.
+@c TODO add xref to fresh standard environment
+
+Applicative @code{require} is useful to load klisp libraries.
+
+SOURCE NOTE: require is taken from lua and r7rs.
+@end deffn
+
+@deffn Applicative registered-requirement? (registered-requirement? string)
+@deffnx Applicative register-requirement! (register-requirement! string)
+@deffnx Applicative unregister-requirement! (unregister-requirement! string)
+@deffnx Applicative find-required-filename (find-required-filename string)
+@code{string} should be non-empty.
+
+These applicatives control the underlying facilities used by
+@code{require} to register already required files. Predicate
+@code{registered-requirement?} returns true iff @code{string} is
+already registered. @code{register-requirement!} marks @code{string}
+as registered (throws an error if it was already registered).
+@code{unregister-requirement!} marks @code{string} as not being
+registered (throws an error if it wasn't registered).
+@code{find-required-filename} looks for an appropriate file for
+@code{string} using the algorithm described below.
+
+filename search in controlled by environment variable
+@code{KLISP_PATH}. This environment variable should be a list of
+templates separated with semicolons (``;''). Each template is a
+string that may contain embedded question mark characters (``?'') to
+be replaced with @code{string}. After replacements, each template
+represents the path to a file. All templates are probed in order, and
+the first to name an existing readable file is returned. If no
+template corresponds to an existing readable file, an error is
+signaled.
- Applicative @code{delete-file} deletes the file named @code{string}.
-If it doesn't exists or can't be deleted, an error is signaled. The
-result returned by @code{delete-file} is inert.
+NOTE: in the future there will be some mechanism to alter the search
+algorithm dinamically, in the meantime this environment variable is
+the only way to customize it.
- SOURCE NOTE: this is missing from Kernel, it is taken from r7rs Scheme.
+SOURCE NOTE: this is not in Kernel, they are supplied per guideline
+G1b of the report (extensibility), so that klisp programs can easily
+duplicate the behaviour of @code{require}
@end deffn
-@deffn Applicative rename-file (rename-file string1 string2)
- @code{string1} should be the name/path for an existing file,
-@code{string2} should be the name/path for a non existing file.
-
- Applicative @code{rename-file} renames the file named @code{string1}
-to @code{string2}. If the file doesn't exists or can't be renamed for
-any reason, an error is signaled. The result returned by
-@code{rename-file} is inert.
-
- SOURCE NOTE: this is missing from Kernel AND Scheme, it is taken
-from C, being quite similar to @code{delete-file}.
+@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 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
diff --git a/doc/src/system.texi b/doc/src/system.texi
@@ -0,0 +1,31 @@
+@deffn Applicative file-exists? (file-exists? string)
+ @code{string} should be the name/path for a file.
+
+ Predicate @code{file-exists?} checks to see if a file named
+@code{string} exists.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from r7rs Scheme.
+@end deffn
+
+@deffn Applicative delete-file (delete-file string)
+ @code{string} should be the name/path for an existing file.
+
+ Applicative @code{delete-file} deletes the file named @code{string}.
+If it doesn't exists or can't be deleted, an error is signaled. The
+result returned by @code{delete-file} is inert.
+
+ SOURCE NOTE: this is missing from Kernel, it is taken from r7rs Scheme.
+@end deffn
+
+@deffn Applicative rename-file (rename-file string1 string2)
+ @code{string1} should be the name/path for an existing file,
+@code{string2} should be the name/path for a non existing file.
+
+ Applicative @code{rename-file} renames the file named @code{string1}
+to @code{string2}. If the file doesn't exists or can't be renamed for
+any reason, an error is signaled. The result returned by
+@code{rename-file} is inert.
+
+ SOURCE NOTE: this is missing from Kernel AND Scheme, it is taken
+from C, being quite similar to @code{delete-file}.
+@end deffn
diff --git a/src/kgports.c b/src/kgports.c
@@ -1277,12 +1277,13 @@ void kinit_ports_ground_env(klisp_State *K)
/* 15.1.6 close-input-file, close-output-file */
/* ASK John: should this be called close-input-port & close-ouput-port
- like in r5rs? that doesn't seem consistent with open thou */
+ like in r5rs? */
add_applicative(K, ground_env, "close-input-file", close_file, 1,
b2tv(false));
add_applicative(K, ground_env, "close-output-file", close_file, 1,
b2tv(true));
- /* 15.1.? Use the r7rs names, in preparation for other kind of ports */
+ /* 15.1.? Use the r7rs names, this has more sense in the face of
+ the different port types available in klisp */
add_applicative(K, ground_env, "close-input-port", close_port, 2,
b2tv(true), b2tv(false));
add_applicative(K, ground_env, "close-output-port", close_port, 2,
@@ -1359,13 +1360,6 @@ void kinit_ports_ground_env(klisp_State *K)
find_required_filename, 0);
/* 15.2.3 get-module */
add_applicative(K, ground_env, "get-module", get_module, 0);
- /* 15.2.? display */
- add_applicative(K, ground_env, "display", display, 0);
-
- /* 15.1.? read-line */
- add_applicative(K, ground_env, "read-line", read_line, 0);
- /* 15.1.? flush-output-port */
- add_applicative(K, ground_env, "flush-output-port", flush, 0);
/*
* That's all there is in the report combined with r5rs and r7rs scheme.
