commit c2507a52027a6cb91cc5d7a5e5d3840ebe60cb98
parent 9b238a95f80c17c575b0d13887d3ebe1b5770a2b
Author: Andres Navarro <canavarro82@gmail.com>
Date: Fri, 24 Feb 2012 18:32:20 -0300
Added libraries section to the manual.
Diffstat:
12 files changed, 682 insertions(+), 70 deletions(-)
diff --git a/TODO b/TODO
@@ -4,7 +4,6 @@
**** Add missing sections
- vector
- bytevector
-- library
- error
** Test
*** Windows
diff --git a/doc/html/Alphabetical-Index.html b/doc/html/Alphabetical-Index.html
@@ -41,8 +41,10 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Control.html#index-g_t_0024cond-32"><code>$cond</code></a>: <a href="Control.html#Control">Control</a></li>
<li><a href="Environments.html#index-g_t_0024define_0021-110"><code>$define!</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Promises.html#index-g_t_0024delay-160"><code>$delay</code></a>: <a href="Promises.html#Promises">Promises</a></li>
+<li><a href="Libraries.html#index-g_t_0024get_002dregistered_002dlibrary-355"><code>$get-registered-library</code></a>: <a href="Libraries.html#Libraries">Libraries</a></li>
<li><a href="Control.html#index-g_t_0024if-30"><code>$if</code></a>: <a href="Control.html#Control">Control</a></li>
<li><a href="Environments.html#index-g_t_0024import_0021-125"><code>$import!</code></a>: <a href="Environments.html#Environments">Environments</a></li>
+<li><a href="Libraries.html#index-g_t_0024import_002dlibrary_0021-359"><code>$import-library!</code></a>: <a href="Libraries.html#Libraries">Libraries</a></li>
<li><a href="Combiners.html#index-g_t_0024lambda-134"><code>$lambda</code></a>: <a href="Combiners.html#Combiners">Combiners</a></li>
<li><a href="Promises.html#index-g_t_0024lazy-158"><code>$lazy</code></a>: <a href="Promises.html#Promises">Promises</a></li>
<li><a href="Environments.html#index-g_t_0024let-111"><code>$let</code></a>: <a href="Environments.html#Environments">Environments</a></li>
@@ -54,10 +56,14 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Environments.html#index-g_t_0024letrec_002a-117"><code>$letrec*</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Booleans.html#index-g_t_0024or_003f-19"><code>$or?</code></a>: <a href="Booleans.html#Booleans">Booleans</a></li>
<li><a href="Environments.html#index-g_t_0024provide_0021-124"><code>$provide!</code></a>: <a href="Environments.html#Environments">Environments</a></li>
+<li><a href="Libraries.html#index-g_t_0024provide_002dlibrary_0021-358"><code>$provide-library!</code></a>: <a href="Libraries.html#Libraries">Libraries</a></li>
+<li><a href="Libraries.html#index-g_t_0024register_002dlibrary_0021-356"><code>$register-library!</code></a>: <a href="Libraries.html#Libraries">Libraries</a></li>
+<li><a href="Libraries.html#index-g_t_0024registered_002dlibrary_003f-354"><code>$registered-library?</code></a>: <a href="Libraries.html#Libraries">Libraries</a></li>
<li><a href="Environments.html#index-g_t_0024remote_002deval-120"><code>$remote-eval</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Control.html#index-g_t_0024sequence-31"><code>$sequence</code></a>: <a href="Control.html#Control">Control</a></li>
<li><a href="Environments.html#index-g_t_0024set_0021-123"><code>$set!</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Control.html#index-g_t_0024unless-38"><code>$unless</code></a>: <a href="Control.html#Control">Control</a></li>
+<li><a href="Libraries.html#index-g_t_0024unregister_002dlibrary_0021-357"><code>$unregister-library!</code></a>: <a href="Libraries.html#Libraries">Libraries</a></li>
<li><a href="Combiners.html#index-g_t_0024vau-131"><code>$vau</code></a>: <a href="Combiners.html#Combiners">Combiners</a></li>
<li><a href="Control.html#index-g_t_0024when-37"><code>$when</code></a>: <a href="Control.html#Control">Control</a></li>
<li><a href="Numbers.html#index-g_t_002a-184"><code>*</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
@@ -166,8 +172,8 @@ 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="System.html#index-defined_002denvironment_002dvariable_003f-358"><code>defined-environment-variable?</code></a>: <a href="System.html#System">System</a></li>
-<li><a href="System.html#index-delete_002dfile-354"><code>delete-file</code></a>: <a href="System.html#System">System</a></li>
+<li><a href="System.html#index-defined_002denvironment_002dvariable_003f-369"><code>defined-environment-variable?</code></a>: <a href="System.html#System">System</a></li>
+<li><a href="System.html#index-delete_002dfile-365"><code>delete-file</code></a>: <a href="System.html#System">System</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>
@@ -198,7 +204,7 @@ 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="System.html#index-file_002dexists-353"><code>file-exists</code></a>: <a href="System.html#System">System</a></li>
+<li><a href="System.html#index-file_002dexists-364"><code>file-exists</code></a>: <a href="System.html#System">System</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>
@@ -214,13 +220,15 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Environments.html#index-get_002dcurrent_002denvironment-113"><code>get-current-environment</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Ports.html#index-get_002dcurrent_002derror_002dport-308"><code>get-current-error-port</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<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="System.html#index-get_002dcurrent_002djiffies-351"><code>get-current-jiffies</code></a>: <a href="System.html#System">System</a></li>
+<li><a href="System.html#index-get_002dcurrent_002djiffies-362"><code>get-current-jiffies</code></a>: <a href="System.html#System">System</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="System.html#index-get_002dcurrent_002dsecond-350"><code>get-current-second</code></a>: <a href="System.html#System">System</a></li>
-<li><a href="System.html#index-get_002denvironment_002dvariable-359"><code>get-environment-variable</code></a>: <a href="System.html#System">System</a></li>
-<li><a href="System.html#index-get_002denvironment_002dvariables-360"><code>get-environment-variables</code></a>: <a href="System.html#System">System</a></li>
-<li><a href="System.html#index-get_002dinterpreter_002darguments-357"><code>get-interpreter-arguments</code></a>: <a href="System.html#System">System</a></li>
-<li><a href="System.html#index-get_002djiffies_002dper_002dsecond-352"><code>get-jiffies-per-second</code></a>: <a href="System.html#System">System</a></li>
+<li><a href="System.html#index-get_002dcurrent_002dsecond-361"><code>get-current-second</code></a>: <a href="System.html#System">System</a></li>
+<li><a href="System.html#index-get_002denvironment_002dvariable-370"><code>get-environment-variable</code></a>: <a href="System.html#System">System</a></li>
+<li><a href="System.html#index-get_002denvironment_002dvariables-371"><code>get-environment-variables</code></a>: <a href="System.html#System">System</a></li>
+<li><a href="System.html#index-get_002dinterpreter_002darguments-368"><code>get-interpreter-arguments</code></a>: <a href="System.html#System">System</a></li>
+<li><a href="System.html#index-get_002djiffies_002dper_002dsecond-363"><code>get-jiffies-per-second</code></a>: <a href="System.html#System">System</a></li>
+<li><a href="Libraries.html#index-get_002dlibrary_002denvironment-353"><code>get-library-environment</code></a>: <a href="Libraries.html#Libraries">Libraries</a></li>
+<li><a href="Libraries.html#index-get_002dlibrary_002dexport_002dlist-352"><code>get-library-export-list</code></a>: <a href="Libraries.html#Libraries">Libraries</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-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>
@@ -229,7 +237,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<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>
<li><a href="Numbers.html#index-get_002dreal_002dinternal_002dprimary-204"><code>get-real-internal-primary</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
-<li><a href="System.html#index-get_002dscript_002darguments-356"><code>get-script-arguments</code></a>: <a href="System.html#System">System</a></li>
+<li><a href="System.html#index-get_002dscript_002darguments-367"><code>get-script-arguments</code></a>: <a href="System.html#System">System</a></li>
<li><a href="Numbers.html#index-get_002dstring_002darithmetic-210"><code>get-string-arithmetic</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Continuations.html#index-guard_002dcontinuation-145"><code>guard-continuation</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
<li><a href="Continuations.html#index-guard_002ddynamic_002dextent-151"><code>guard-dynamic-extent</code></a>: <a href="Continuations.html#Continuations">Continuations</a></li>
@@ -250,6 +258,8 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Keyed-Variables.html#index-keyed-variables-161">keyed variables</a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
<li><a href="Numbers.html#index-lcm-200"><code>lcm</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Pairs-and-lists.html#index-length-90"><code>length</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
+<li><a href="Libraries.html#index-libraries-349">libraries</a>: <a href="Libraries.html#Libraries">Libraries</a></li>
+<li><a href="Libraries.html#index-library_003f-350"><code>library?</code></a>: <a href="Libraries.html#Libraries">Libraries</a></li>
<li><a href="Pairs-and-lists.html#index-list-51"><code>list</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Pairs-and-lists.html#index-list_002a-52"><code>list*</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Strings.html#index-list_002d_003estring-257"><code>list->string</code></a>: <a href="Strings.html#Strings">Strings</a></li>
@@ -266,6 +276,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Environments.html#index-make_002dkernel_002dstandard_002denvironment-114"><code>make-kernel-standard-environment</code></a>: <a href="Environments.html#Environments">Environments</a></li>
<li><a href="Keyed-Variables.html#index-make_002dkeyed_002ddynamic_002dvariable-163"><code>make-keyed-dynamic-variable</code></a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
<li><a href="Keyed-Variables.html#index-make_002dkeyed_002dstatic_002dvariable-165"><code>make-keyed-static-variable</code></a>: <a href="Keyed-Variables.html#Keyed-Variables">Keyed Variables</a></li>
+<li><a href="Libraries.html#index-make_002dlibrary-351"><code>make-library</code></a>: <a href="Libraries.html#Libraries">Libraries</a></li>
<li><a href="Pairs-and-lists.html#index-make_002dlist-83"><code>make-list</code></a>: <a href="Pairs-and-lists.html#Pairs-and-lists">Pairs and lists</a></li>
<li><a href="Strings.html#index-make_002dstring-246"><code>make-string</code></a>: <a href="Strings.html#Strings">Strings</a></li>
<li><a href="Combiners.html#index-map-136"><code>map</code></a>: <a href="Combiners.html#Combiners">Combiners</a></li>
@@ -326,7 +337,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<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-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="System.html#index-rename_002dfile-355"><code>rename-file</code></a>: <a href="System.html#System">System</a></li>
+<li><a href="System.html#index-rename_002dfile-366"><code>rename-file</code></a>: <a href="System.html#System">System</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>
@@ -373,7 +384,7 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Symbols.html#index-symbol_002d_003estring-25"><code>symbol->string</code></a>: <a href="Symbols.html#Symbols">Symbols</a></li>
<li><a href="Symbols.html#index-symbol_003f-24"><code>symbol?</code></a>: <a href="Symbols.html#Symbols">Symbols</a></li>
<li><a href="Symbols.html#index-symbols-23">symbols</a>: <a href="Symbols.html#Symbols">Symbols</a></li>
-<li><a href="System.html#index-system-349">system</a>: <a href="System.html#System">System</a></li>
+<li><a href="System.html#index-system-360">system</a>: <a href="System.html#System">System</a></li>
<li><a href="Numbers.html#index-tan-226"><code>tan</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
<li><a href="Ports.html#index-textual_002dport_003f-297"><code>textual-port?</code></a>: <a href="Ports.html#Ports">Ports</a></li>
<li><a href="Numbers.html#index-truncate-216"><code>truncate</code></a>: <a href="Numbers.html#Numbers">Numbers</a></li>
@@ -418,7 +429,8 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a href="Alphabetical-Index.html#toc_Strings">15 Strings</a></li>
<li><a href="Alphabetical-Index.html#toc_Characters">16 Characters</a></li>
<li><a href="Alphabetical-Index.html#toc_Ports">17 Ports</a></li>
-<li><a href="Alphabetical-Index.html#toc_System">18 System</a></li>
+<li><a href="Alphabetical-Index.html#toc_Libraries">18 Libraries</a></li>
+<li><a href="Alphabetical-Index.html#toc_System">19 System</a></li>
<li><a href="Alphabetical-Index.html#toc_Alphabetical-Index">Index</a></li>
</ul>
</div>
@@ -471,7 +483,8 @@ Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<li><a name="toc_Strings" href="Strings.html#Strings">15 Strings</a>
<li><a name="toc_Characters" href="Characters.html#Characters">16 Characters</a>
<li><a name="toc_Ports" href="Ports.html#Ports">17 Ports</a>
-<li><a name="toc_System" href="System.html#System">18 System</a>
+<li><a name="toc_Libraries" href="Libraries.html#Libraries">18 Libraries</a>
+<li><a name="toc_System" href="System.html#System">19 System</a>
<li><a name="toc_Alphabetical-Index" href="Alphabetical-Index.html#Alphabetical-Index">Index</a>
</li></ul>
</div>
diff --git a/doc/html/Libraries.html b/doc/html/Libraries.html
@@ -0,0 +1,220 @@
+<html lang="en">
+<head>
+<title>Libraries - klisp Reference Manual</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="klisp Reference Manual">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="prev" href="Ports.html#Ports" title="Ports">
+<link rel="next" href="System.html#System" title="System">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+ pre.display { font-family:inherit }
+ pre.format { font-family:inherit }
+ pre.smalldisplay { font-family:inherit; font-size:smaller }
+ pre.smallformat { font-family:inherit; font-size:smaller }
+ pre.smallexample { font-size:smaller }
+ pre.smalllisp { font-size:smaller }
+ span.sc { font-variant:small-caps }
+ span.roman { font-family:serif; font-weight:normal; }
+ span.sansserif { font-family:sans-serif; font-weight:normal; }
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Libraries"></a>
+<p>
+Next: <a rel="next" accesskey="n" href="System.html#System">System</a>,
+Previous: <a rel="previous" accesskey="p" href="Ports.html#Ports">Ports</a>,
+Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
+<hr>
+</div>
+
+<!-- node-name, next, previous, up -->
+<h2 class="chapter">18 Libraries</h2>
+
+<p><a name="index-libraries-349"></a>
+Libraries provide a way to organize klisp code with a clean & clear
+interface to the rest of the program. They are first class objects
+(as all manipulable entities in Kernel, and according to the
+guidelines in the Kernel report). A library has list of exported
+symbols and values for those symbols (generally combiners but may be
+any object). The library type is encapsulated.
+
+ <p>In addition there's a mechanism to refer to library objects by name
+(where a name is actually a unique list of symbols and numbers), with
+the ability to register new libraries, get the library object from a
+name, unregister libraries, etc.
+
+ <p>These two ways of working with libraries conform the low level API to
+libraries and are orthogonal to each other. They are provided to
+allow klisp programs to construct their own interface to library
+definition and use, and to respect the guidelines and spirit of the
+Kernel Report.
+
+ <p>There's also a higher level API that is a combination of the lower level
+APIs and behaves more like traditional module systems. This is
+probably what most klisp programs will use. This API consist of the
+<code>$provide-library!</code> operative to define (and register) new
+libraries and the <code>$import-library!</code> operative to extract
+bindings out of existing libraries. This allows various forms of
+controlling which bindings are extracted from the libraries and allows
+various forms of renaming. It can be used both in the body of
+libraries or in the top level.
+
+ <p>No association is made by klisp between source files and libraries.
+For a possible mechanism to handle this see <code>require</code> in the
+ports module. Also no special meaning is assigned to the library
+names. This could be used by an even higher level API, for example to
+map to version numbers and/or to the underlying filesystem.
+
+ <p>SOURCE NOTE: This is mostly an adaptation from the r7rs draft of
+scheme. There's no mention of libraries in the Kernel Report, but
+they were deemed important for klisp in order to share and distribute
+code with a common interface. A number of adaptations were made to
+the scheme version to sit more comfortably with the Kernel way of
+doing things (first class status, exposing of the library register,
+etc).
+
+<div class="defun">
+— Applicative: <b>library?</b> (<var>library? . objects</var>)<var><a name="index-library_003f-350"></a></var><br>
+<blockquote><p>The primitive type predicate for type library.
+<code>library?</code> returns true iff all the objects in <code>objects</code>
+are of type library.
+
+ <p>NOTE: This is part of the low level API to libraries. It won't be
+needed to writers or users of libraries that stick to the higher level
+API (i.e. <code>$provide-library!</code> & <code>$import-library!</code>).
+</p></blockquote></div>
+
+<div class="defun">
+— Applicative: <b>make-library</b> (<var>make-library bindings</var>)<var><a name="index-make_002dlibrary-351"></a></var><br>
+<blockquote><p><code>bindings</code> should be an acyclic list of <code>(symbol . value)</code>
+pairs. Each symbol may only occur once in the list.
+
+ <p>Constructs a new library object with the passed <code>bindings</code> as
+exported objects.
+
+ <p>NOTE: This is part of the low level API to libraries, writers of
+libraries are encouraged to use <code>$provide-library!</code> to define
+their libraries.
+</p></blockquote></div>
+
+<div class="defun">
+— Applicative: <b>get-library-export-list</b> (<var>get-library-export-list library</var>)<var><a name="index-get_002dlibrary_002dexport_002dlist-352"></a></var><br>
+— Applicative: <b>get-library-environment</b> (<var>get-library-environment library</var>)<var><a name="index-get_002dlibrary_002denvironment-353"></a></var><br>
+<blockquote><p><code>get-library-export-list</code> returns the list of symbols exported
+from the passed library. <code>get-library-environment</code> returns a
+fresh empty environment whose parent has all exported symbols of the
+library bound to the exported objects.
+
+ <p>NOTE: This is part of the low level API to libraries, users of
+libraries are encouraged to use <code>$import-library!</code> to get
+bindings out of libraries (and into the current environment).
+</p></blockquote></div>
+
+<div class="defun">
+— Operative: <b>$registered-library?</b> (<var>$registered-library? name</var>)<var><a name="index-g_t_0024registered_002dlibrary_003f-354"></a></var><br>
+— Operative: <b>$get-registered-library</b> (<var>$get-registered-library name</var>)<var><a name="index-g_t_0024get_002dregistered_002dlibrary-355"></a></var><br>
+— Operative: <b>$register-library!</b> (<var>$register-library! name library</var>)<var><a name="index-g_t_0024register_002dlibrary_0021-356"></a></var><br>
+— Operative: <b>$unregister-library!</b> (<var>$unregister-library! name</var>)<var><a name="index-g_t_0024unregister_002dlibrary_0021-357"></a></var><br>
+<blockquote><p><code>name</code> should a an acyclic list of symbols and exact non-negative
+integers. Two registered libraries can't have the same name (in the
+sense of <code>equal?</code>).
+
+ <p>These operatives control the library registry that maps names to
+libraries.
+
+ <p>Predicate <code>$registered-library?</code> returns true iff a
+library named <code>name</code> is already registered.
+<code>get-registered-library</code> returns the library object associated
+with <code>name</code> (or throws an error if no library named <code>name</code>
+is registered). <code>$register-library!</code> registers <code>library</code>
+with name <code>name</code> (throws an error if <code>name</code> is already
+registered. <code>$unregister-library!</code> removes the library
+registered as <code>name</code> from the library register (throws an error
+if no such library was registered).
+
+ <p>NOTE: This is part of the low level API to libraries, users & writers
+of libraries are encouraged to use <code>$provide-library!</code> to create
+& register new libraries.
+</p></blockquote></div>
+
+<div class="defun">
+— Operative: <b>$provide-library!</b> (<var>$provide-library! name exports . body</var>)<var><a name="index-g_t_0024provide_002dlibrary_0021-358"></a></var><br>
+— Operative: <b>$import-library!</b> (<var>$import-library! . imports</var>)<var><a name="index-g_t_0024import_002dlibrary_0021-359"></a></var><br>
+<blockquote><p><code>name</code> should be as for <code>register-library!</code> and not already
+registered. <code>exports</code> should be a list of <code>(#:export
+<export-spec> ...)</code>. Where <code><export spec></code> is either:
+ <ul>
+<li><code>symbol</code>
+<li><code>(#:rename internal-symbol external-symbol)</code>
+</ul>
+
+ <p>A lone symbol has the same semantics as the pair with that symbol in
+both internal and external positions. No symbol can appear more than once as external.
+<code>body</code> should be an acyclic list of expressions. <code>exports</code>
+should be a list like <code>(<import-spec> ...)</code> where
+<code><import-spec></code> is either
+ <ul>
+<li><code><name></code>
+<li><code>(#:only <import-spec> symbol ...)</code>
+<li><code>(#:except <import-spec> symbol ...)</code>
+<li><code>(#:prefix <import-spec> symbol)</code>
+<li><code>(#:rename <import-spec> (orig-symbol new-symbol) ...)</code>
+</ul>
+
+ <p>These two operatives conform the higher level API for klisp
+libraries. They are what most users of klisp (both writers and users
+of libraries) will use.
+
+ <p>Operative <code>$provide-library!</code> creates and register a library with
+name <code>name</code> and exported symbols obtained from the <code>exports</code> list and
+values prepared by the <code>body</code>. First a child of the dynamic
+environment is created. Then, <code>body</code> is evaluated sequentially
+as if by <code>$sequence</code> in that environment. Next a new library is
+created with a list of exported bindings that use the external symbols
+in <code>exports</code> as names and the values bound by the corresponding
+internal symbols in the created environment, as values. If a lone
+symbol is used in <code>exports</code> it is used both as internal and
+external symbol for that binding. Lastly, the new library object is
+registered as <code>name</code>. This mechanism more or less follows the
+idea of operative <code>$provide!</code> from the Kernel Report, but it also
+allows for renaming.
+
+ <p>Operative <code>$import-library!</code> imports to the current environment
+any combination of bindings from any number of named libraries, while
+allowing renaming of said bindings. It can be used in any context, as
+any other Kernel expression. <code>$import-library!</code> looks for the
+named libraries and then extracts & renames the specified bindings
+according to each <code><import-spec></code> and defines them (in the sense
+of <code>$define!</code> and <code>$set!</code>) in the current dynamic
+environment. The set of bindings to import are generated in a
+recursive manner. This allows a great deal of control of the imported
+bindings and their names. The semantics for the set of bindings
+generated by the various <code><import-spec></code>s are as follows:
+ <ul>
+<li><code><name></code>: All bindings from library <code>name</code>.
+<li><code>(#:only <import-spec> symbol ...)</code>: Only the named bindings from
+the set of bindings in <code><import-spec></code>.
+<li><code>(#:except <import-spec> symbol ...)</code>: All bindings from the set
+in <code><import-spec></code> except those named in the list.
+<li><code>(#:prefix <import-spec> symbol)</code>: All bindings from the set in
+<code><import-spec></code> but renamed by prefixing each one with the
+specified prefix <code>symbol</code>.
+<li><code>(#:rename <import-spec> (orig-symbol new-symbol) ...)</code>:
+All bindings from the set in <code><import-spec></code> but renaming all
+<code>orig-symbol</code> to the corresponding <code>new-symbol</code>.
+</ul>
+
+ <p>If two values are tried to be imported with the same name, they are
+checked for <code>eq?</code>-ness, if they are deemed <code>eq?</code> to each
+other they are imported, otherwise <code>$import-library!</code> throws an
+error. This helps catch name collisions while allowing to reexport
+bindings from used libraries without conflict.
+</p></blockquote></div>
+
+<!-- *-texinfo-*- -->
+ </body></html>
+
diff --git a/doc/html/Ports.html b/doc/html/Ports.html
@@ -6,7 +6,7 @@
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="prev" href="Characters.html#Characters" title="Characters">
-<link rel="next" href="System.html#System" title="System">
+<link rel="next" href="Libraries.html#Libraries" title="Libraries">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
@@ -25,7 +25,7 @@
<div class="node">
<a name="Ports"></a>
<p>
-Next: <a rel="next" accesskey="n" href="System.html#System">System</a>,
+Next: <a rel="next" accesskey="n" href="Libraries.html#Libraries">Libraries</a>,
Previous: <a rel="previous" accesskey="p" href="Characters.html#Characters">Characters</a>,
Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<hr>
diff --git a/doc/html/System.html b/doc/html/System.html
@@ -5,7 +5,7 @@
<meta name="description" content="klisp Reference Manual">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
-<link rel="prev" href="Ports.html#Ports" title="Ports">
+<link rel="prev" href="Libraries.html#Libraries" title="Libraries">
<link rel="next" href="Alphabetical-Index.html#Alphabetical-Index" title="Alphabetical Index">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
@@ -26,22 +26,22 @@
<a name="System"></a>
<p>
Next: <a rel="next" accesskey="n" href="Alphabetical-Index.html#Alphabetical-Index">Alphabetical Index</a>,
-Previous: <a rel="previous" accesskey="p" href="Ports.html#Ports">Ports</a>,
+Previous: <a rel="previous" accesskey="p" href="Libraries.html#Libraries">Libraries</a>,
Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a>
<hr>
</div>
<!-- node-name, next, previous, up -->
-<h2 class="chapter">18 System</h2>
+<h2 class="chapter">19 System</h2>
-<p><a name="index-system-349"></a>
+<p><a name="index-system-360"></a>
Module System contains some useful features for interacting with the
host environment.
<p>SOURCE NOTE: most of these come from r7rs.
<div class="defun">
-— Applicative: <b>get-current-second</b> (<var>get-current-second</var>)<var><a name="index-get_002dcurrent_002dsecond-350"></a></var><br>
+— Applicative: <b>get-current-second</b> (<var>get-current-second</var>)<var><a name="index-get_002dcurrent_002dsecond-361"></a></var><br>
<blockquote><p>Applicative <code>get-current-second</code> returns the number of seconds
elapsed since the UNIX/POSIX epoch (that is midnight January 1st,
1970, UTC).
@@ -51,7 +51,7 @@ here.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>get-current-jiffies</b> (<var>get-current-jiffies</var>)<var><a name="index-get_002dcurrent_002djiffies-351"></a></var><br>
+— Applicative: <b>get-current-jiffies</b> (<var>get-current-jiffies</var>)<var><a name="index-get_002dcurrent_002djiffies-362"></a></var><br>
<blockquote><p>Applicative <code>get-current-jiffies</code> returns the number of jiffies
(fractions of a second) elapsed since an arbitrary epoch that may
change in each run of the klisp interpreter. Applicative
@@ -60,19 +60,19 @@ of a second a jiffy represents.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>get-jiffies-per-second</b> (<var>get-jiffies-per-second</var>)<var><a name="index-get_002djiffies_002dper_002dsecond-352"></a></var><br>
+— Applicative: <b>get-jiffies-per-second</b> (<var>get-jiffies-per-second</var>)<var><a name="index-get_002djiffies_002dper_002dsecond-363"></a></var><br>
<blockquote><p>Applicative <code>get-jiffies-per-second</code> returns a constant
representing the number of jiffies that correspond to one second.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>file-exists</b> (<var>file-exists string</var>)<var><a name="index-file_002dexists-353"></a></var><br>
+— Applicative: <b>file-exists</b> (<var>file-exists string</var>)<var><a name="index-file_002dexists-364"></a></var><br>
<blockquote><p>Predicate <code>file-exists?</code> checks to see if a file named
<code>string</code> exists.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>delete-file</b> (<var>delete-file string</var>)<var><a name="index-delete_002dfile-354"></a></var><br>
+— Applicative: <b>delete-file</b> (<var>delete-file string</var>)<var><a name="index-delete_002dfile-365"></a></var><br>
<blockquote><p><code>string</code> should be the name/path for an existing file.
<p>Applicative <code>delete-file</code> deletes the file named <code>string</code>.
@@ -81,7 +81,7 @@ result returned by <code>delete-file</code> is inert.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>rename-file</b> (<var>rename-file string1 string2</var>)<var><a name="index-rename_002dfile-355"></a></var><br>
+— Applicative: <b>rename-file</b> (<var>rename-file string1 string2</var>)<var><a name="index-rename_002dfile-366"></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.
@@ -95,8 +95,8 @@ quite similar to <code>delete-file</code>.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>get-script-arguments</b> (<var>get-script-arguments</var>)<var><a name="index-get_002dscript_002darguments-356"></a></var><br>
-— Applicative: <b>get-interpreter-arguments</b> (<var>get-interpreter-arguments</var>)<var><a name="index-get_002dinterpreter_002darguments-357"></a></var><br>
+— Applicative: <b>get-script-arguments</b> (<var>get-script-arguments</var>)<var><a name="index-get_002dscript_002darguments-367"></a></var><br>
+— Applicative: <b>get-interpreter-arguments</b> (<var>get-interpreter-arguments</var>)<var><a name="index-get_002dinterpreter_002darguments-368"></a></var><br>
<blockquote><p>These applicatives return respectively the script and interpreter
arguments. The script arguments are a list of the arguments passed to
the klisp interpreter starting from (and including) the script name.
@@ -107,20 +107,20 @@ name and arguments.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>defined-environment-variable?</b> (<var>defined-environment-variable? string</var>)<var><a name="index-defined_002denvironment_002dvariable_003f-358"></a></var><br>
+— Applicative: <b>defined-environment-variable?</b> (<var>defined-environment-variable? string</var>)<var><a name="index-defined_002denvironment_002dvariable_003f-369"></a></var><br>
<blockquote><p>Predicate <code>defined-environment-variable?</code> returns true iff
<code>string</code> represents a defined envrionment variable.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>get-environment-variable</b> (<var>get-environment-variable string</var>)<var><a name="index-get_002denvironment_002dvariable-359"></a></var><br>
+— Applicative: <b>get-environment-variable</b> (<var>get-environment-variable string</var>)<var><a name="index-get_002denvironment_002dvariable-370"></a></var><br>
<blockquote><p>Applicative <code>get-environment-variable</code> returns the value of the
environment variable represented by <code>string</code>. If <code>string</code>
doesn't represent a defined environment variable an error is signaled.
</p></blockquote></div>
<div class="defun">
-— Applicative: <b>get-environment-variables</b> (<var>get-environment-variables</var>)<var><a name="index-get_002denvironment_002dvariables-360"></a></var><br>
+— Applicative: <b>get-environment-variables</b> (<var>get-environment-variables</var>)<var><a name="index-get_002denvironment_002dvariables-371"></a></var><br>
<blockquote><!-- TODO xref to alist -->
<p>Applicative <code>get-environment-variable</code> returns an alist
representing the defined environment variables and their values. The
diff --git a/doc/html/index.html b/doc/html/index.html
@@ -53,6 +53,7 @@ Up: <a rel="up" accesskey="u" href="../index.html#dir">(dir)</a>
<li><a href="Strings.html#Strings">Strings</a>: Strings module features.
<li><a href="Characters.html#Characters">Characters</a>: Characters module features.
<li><a href="Ports.html#Ports">Ports</a>: Ports module features.
+<li><a href="Libraries.html#Libraries">Libraries</a>: Libraries module features.
<li><a href="System.html#System">System</a>: System module features.
<!-- TODO add error objs to both klisp and the manual -->
<li><a href="Alphabetical-Index.html#Alphabetical-Index">Alphabetical Index</a>: Index including concepts, functions, variables,
diff --git a/doc/klisp.info b/doc/klisp.info
@@ -56,6 +56,7 @@ the header "Permission to copy this report", that reads:
* Strings:: Strings module features.
* Characters:: Characters module features.
* Ports:: Ports module features.
+* Libraries:: Libraries module features.
* System:: System module features.
* Alphabetical Index:: Index including concepts, functions, variables,
and other terms.
@@ -2519,7 +2520,7 @@ features defined here were taken mostly from r7rs.
base argument.
-File: klisp.info, Node: Ports, Next: System, Prev: Characters, Up: Top
+File: klisp.info, Node: Ports, Next: Libraries, Prev: Characters, Up: Top
17 Ports
********
@@ -3026,9 +3027,186 @@ klisp and was taken from r7rs.
binding symbol `module-parameters' to the `environment' argument.
-File: klisp.info, Node: System, Next: Alphabetical Index, Prev: Ports, Up: Top
+File: klisp.info, Node: Libraries, Next: System, Prev: Ports, Up: Top
+
+18 Libraries
+************
+
+Libraries provide a way to organize klisp code with a clean & clear
+interface to the rest of the program. They are first class objects (as
+all manipulable entities in Kernel, and according to the guidelines in
+the Kernel report). A library has list of exported symbols and values
+for those symbols (generally combiners but may be any object). The
+library type is encapsulated.
+
+ In addition there's a mechanism to refer to library objects by name
+(where a name is actually a unique list of symbols and numbers), with
+the ability to register new libraries, get the library object from a
+name, unregister libraries, etc.
+
+ These two ways of working with libraries conform the low level API to
+libraries and are orthogonal to each other. They are provided to allow
+klisp programs to construct their own interface to library definition
+and use, and to respect the guidelines and spirit of the Kernel Report.
+
+ There's also a higher level API that is a combination of the lower
+level APIs and behaves more like traditional module systems. This is
+probably what most klisp programs will use. This API consist of the
+`$provide-library!' operative to define (and register) new libraries
+and the `$import-library!' operative to extract bindings out of
+existing libraries. This allows various forms of controlling which
+bindings are extracted from the libraries and allows various forms of
+renaming. It can be used both in the body of libraries or in the top
+level.
+
+ No association is made by klisp between source files and libraries.
+For a possible mechanism to handle this see `require' in the ports
+module. Also no special meaning is assigned to the library names. This
+could be used by an even higher level API, for example to map to
+version numbers and/or to the underlying filesystem.
+
+ SOURCE NOTE: This is mostly an adaptation from the r7rs draft of
+scheme. There's no mention of libraries in the Kernel Report, but they
+were deemed important for klisp in order to share and distribute code
+with a common interface. A number of adaptations were made to the
+scheme version to sit more comfortably with the Kernel way of doing
+things (first class status, exposing of the library register, etc).
+
+ -- Applicative: library? (library? . objects)
+ The primitive type predicate for type library. `library?' returns
+ true iff all the objects in `objects' are of type library.
+
+ NOTE: This is part of the low level API to libraries. It won't be
+ needed to writers or users of libraries that stick to the higher
+ level API (i.e. `$provide-library!' & `$import-library!').
+
+ -- Applicative: make-library (make-library bindings)
+ `bindings' should be an acyclic list of `(symbol . value)' pairs.
+ Each symbol may only occur once in the list.
+
+ Constructs a new library object with the passed `bindings' as
+ exported objects.
+
+ NOTE: This is part of the low level API to libraries, writers of
+ libraries are encouraged to use `$provide-library!' to define
+ their libraries.
+
+ -- Applicative: get-library-export-list (get-library-export-list
+ library)
+ -- Applicative: get-library-environment (get-library-environment
+ library)
+ `get-library-export-list' returns the list of symbols exported
+ from the passed library. `get-library-environment' returns a
+ fresh empty environment whose parent has all exported symbols of
+ the library bound to the exported objects.
+
+ NOTE: This is part of the low level API to libraries, users of
+ libraries are encouraged to use `$import-library!' to get bindings
+ out of libraries (and into the current environment).
+
+ -- Operative: $registered-library? ($registered-library? name)
+ -- Operative: $get-registered-library ($get-registered-library name)
+ -- Operative: $register-library! ($register-library! name library)
+ -- Operative: $unregister-library! ($unregister-library! name)
+ `name' should a an acyclic list of symbols and exact non-negative
+ integers. Two registered libraries can't have the same name (in
+ the sense of `equal?').
+
+ These operatives control the library registry that maps names to
+ libraries.
+
+ Predicate `$registered-library?' returns true iff a library named
+ `name' is already registered. `get-registered-library' returns
+ the library object associated with `name' (or throws an error if
+ no library named `name' is registered). `$register-library!'
+ registers `library' with name `name' (throws an error if `name' is
+ already registered. `$unregister-library!' removes the library
+ registered as `name' from the library register (throws an error if
+ no such library was registered).
+
+ NOTE: This is part of the low level API to libraries, users &
+ writers of libraries are encouraged to use `$provide-library!' to
+ create & register new libraries.
+
+ -- Operative: $provide-library! ($provide-library! name exports . body)
+ -- Operative: $import-library! ($import-library! . imports)
+ `name' should be as for `register-library!' and not already
+ registered. `exports' should be a list of `(#:export
+ <export-spec> ...)'. Where `<export spec>' is either:
+ * `symbol'
+
+ * `(#:rename internal-symbol external-symbol)'
+
+ A lone symbol has the same semantics as the pair with that symbol
+ in both internal and external positions. No symbol can appear
+ more than once as external. `body' should be an acyclic list of
+ expressions. `exports' should be a list like `(<import-spec>
+ ...)' where `<import-spec>' is either
+ * `<name>'
+
+ * `(#:only <import-spec> symbol ...)'
+
+ * `(#:except <import-spec> symbol ...)'
+
+ * `(#:prefix <import-spec> symbol)'
+
+ * `(#:rename <import-spec> (orig-symbol new-symbol) ...)'
+
+ These two operatives conform the higher level API for klisp
+ libraries. They are what most users of klisp (both writers and
+ users of libraries) will use.
+
+ Operative `$provide-library!' creates and register a library with
+ name `name' and exported symbols obtained from the `exports' list
+ and values prepared by the `body'. First a child of the dynamic
+ environment is created. Then, `body' is evaluated sequentially as
+ if by `$sequence' in that environment. Next a new library is
+ created with a list of exported bindings that use the external
+ symbols in `exports' as names and the values bound by the
+ corresponding internal symbols in the created environment, as
+ values. If a lone symbol is used in `exports' it is used both as
+ internal and external symbol for that binding. Lastly, the new
+ library object is registered as `name'. This mechanism more or
+ less follows the idea of operative `$provide!' from the Kernel
+ Report, but it also allows for renaming.
+
+ Operative `$import-library!' imports to the current environment
+ any combination of bindings from any number of named libraries,
+ while allowing renaming of said bindings. It can be used in any
+ context, as any other Kernel expression. `$import-library!' looks
+ for the named libraries and then extracts & renames the specified
+ bindings according to each `<import-spec>' and defines them (in
+ the sense of `$define!' and `$set!') in the current dynamic
+ environment. The set of bindings to import are generated in a
+ recursive manner. This allows a great deal of control of the
+ imported bindings and their names. The semantics for the set of
+ bindings generated by the various `<import-spec>'s are as follows:
+ * `<name>': All bindings from library `name'.
+
+ * `(#:only <import-spec> symbol ...)': Only the named bindings
+ from the set of bindings in `<import-spec>'.
+
+ * `(#:except <import-spec> symbol ...)': All bindings from the
+ set in `<import-spec>' except those named in the list.
+
+ * `(#:prefix <import-spec> symbol)': All bindings from the set
+ in `<import-spec>' but renamed by prefixing each one with the
+ specified prefix `symbol'.
+
+ * `(#:rename <import-spec> (orig-symbol new-symbol) ...)': All
+ bindings from the set in `<import-spec>' but renaming all
+ `orig-symbol' to the corresponding `new-symbol'.
+
+ If two values are tried to be imported with the same name, they are
+ checked for `eq?'-ness, if they are deemed `eq?' to each other
+ they are imported, otherwise `$import-library!' throws an error.
+ This helps catch name collisions while allowing to reexport
+ bindings from used libraries without conflict.
-18 System
+
+File: klisp.info, Node: System, Next: Alphabetical Index, Prev: Libraries, Up: Top
+
+19 System
*********
Module System contains some useful features for interacting with the
@@ -3120,8 +3298,10 @@ Index
* $cond: Control. (line 32)
* $define!: Environments. (line 49)
* $delay: Promises. (line 79)
+* $get-registered-library: Libraries. (line 80)
* $if: Control. (line 15)
* $import!: Environments. (line 217)
+* $import-library!: Libraries. (line 104)
* $lambda: Combiners. (line 76)
* $lazy: Promises. (line 43)
* $let: Environments. (line 89)
@@ -3133,10 +3313,14 @@ Index
* $letrec*: Environments. (line 144)
* $or?: Booleans. (line 42)
* $provide!: Environments. (line 201)
+* $provide-library!: Libraries. (line 103)
+* $register-library!: Libraries. (line 81)
+* $registered-library?: Libraries. (line 79)
* $remote-eval: Environments. (line 169)
* $sequence: Control. (line 23)
* $set!: Environments. (line 192)
* $unless: Control. (line 68)
+* $unregister-library!: Libraries. (line 82)
* $vau: Combiners. (line 26)
* $when: Control. (line 67)
* *: Numbers. (line 136)
@@ -3303,6 +3487,8 @@ Index
* get-environment-variables: System. (line 75)
* get-interpreter-arguments: System. (line 55)
* get-jiffies-per-second: System. (line 27)
+* get-library-environment: Libraries. (line 69)
+* get-library-export-list: Libraries. (line 67)
* get-list-metrics: Pairs and lists. (line 161)
* get-module: Ports. (line 498)
* get-output-bytevector: Ports. (line 195)
@@ -3332,6 +3518,8 @@ Index
* keyed variables: Keyed Variables. (line 6)
* lcm: Numbers. (line 221)
* length: Pairs and lists. (line 229)
+* libraries: Libraries. (line 6)
+* library?: Libraries. (line 47)
* list: Pairs and lists. (line 82)
* list*: Pairs and lists. (line 88)
* list->string: Strings. (line 130)
@@ -3348,6 +3536,7 @@ Index
* make-kernel-standard-environment: Environments. (line 119)
* make-keyed-dynamic-variable: Keyed Variables. (line 21)
* make-keyed-static-variable: Keyed Variables. (line 44)
+* make-library: Libraries. (line 55)
* make-list: Pairs and lists. (line 133)
* make-string: Strings. (line 78)
* map <1>: Combiners. (line 96)
@@ -3484,37 +3673,38 @@ Index
Tag Table:
Node: Top703
-Node: License2715
-Node: Introduction4397
-Node: Caveats7330
-Node: Kernel History8116
-Node: Conventions9561
-Node: Some Terms10232
-Node: Evaluation Notation10903
-Node: Printing Notation11924
-Node: Error Messages12400
-Node: Format of Descriptions13048
-Node: A Sample Applicative Description13612
-Node: Acknowledgements15375
-Node: Interpreter15761
-Ref: Command Line Options18061
-Ref: Interpreter Exit Status18995
-Node: Booleans20223
-Node: Equivalence22900
-Node: Symbols23693
-Node: Control25323
-Node: Pairs and lists29414
-Node: Environments48294
-Node: Combiners58967
-Node: Continuations65621
-Node: Encapsulations74164
-Node: Promises75617
-Node: Keyed Variables79772
-Node: Numbers82543
-Node: Strings104997
-Node: Characters112258
-Node: Ports116904
-Node: System140602
-Node: Alphabetical Index144096
+Node: License2770
+Node: Introduction4452
+Node: Caveats7385
+Node: Kernel History8171
+Node: Conventions9616
+Node: Some Terms10287
+Node: Evaluation Notation10958
+Node: Printing Notation11979
+Node: Error Messages12455
+Node: Format of Descriptions13103
+Node: A Sample Applicative Description13667
+Node: Acknowledgements15430
+Node: Interpreter15816
+Ref: Command Line Options18116
+Ref: Interpreter Exit Status19050
+Node: Booleans20278
+Node: Equivalence22955
+Node: Symbols23748
+Node: Control25378
+Node: Pairs and lists29469
+Node: Environments48349
+Node: Combiners59022
+Node: Continuations65676
+Node: Encapsulations74219
+Node: Promises75672
+Node: Keyed Variables79827
+Node: Numbers82598
+Node: Strings105052
+Node: Characters112313
+Node: Ports116959
+Node: Libraries140660
+Node: System149419
+Node: Alphabetical Index152917
End Tag Table
diff --git a/doc/src/Makefile b/doc/src/Makefile
@@ -10,7 +10,7 @@ srcs = klisp.texi index.texi \
promises.texi keyed_vars.texi \
numbers.texi strings.texi \
characters.texi ports.texi \
- system.texi
+ libraries.texi system.texi
#TODO add dvi/pdf output
#TODO check what happens with xrefs
diff --git a/doc/src/klisp.texi b/doc/src/klisp.texi
@@ -110,6 +110,7 @@ permission is granted to copy it in whole or in part without fee.
* Strings:: Strings module features.
* Characters:: Characters module features.
* Ports:: Ports module features.
+* Libraries:: Libraries module features.
* System:: System module features.
@c TODO add error objs to both klisp and the manual
* Alphabetical Index:: Index including concepts, functions, variables,
@@ -138,6 +139,7 @@ permission is granted to copy it in whole or in part without fee.
@include strings.texi
@include characters.texi
@include ports.texi
+@include libraries.texi
@include system.texi
@c appendices
diff --git a/doc/src/libraries.texi b/doc/src/libraries.texi
@@ -0,0 +1,187 @@
+@c -*-texinfo-*-
+@setfilename ../src/libraries
+
+@node Libraries, System, Ports, Top
+@comment node-name, next, previous, up
+
+@chapter Libraries
+@cindex libraries
+
+Libraries provide a way to organize klisp code with a clean & clear
+interface to the rest of the program. They are first class objects
+(as all manipulable entities in Kernel, and according to the
+guidelines in the Kernel report). A library has list of exported
+symbols and values for those symbols (generally combiners but may be
+any object). The library type is encapsulated.
+
+In addition there's a mechanism to refer to library objects by name
+(where a name is actually a unique list of symbols and numbers), with
+the ability to register new libraries, get the library object from a
+name, unregister libraries, etc.
+
+These two ways of working with libraries conform the low level API to
+libraries and are orthogonal to each other. They are provided to
+allow klisp programs to construct their own interface to library
+definition and use, and to respect the guidelines and spirit of the
+Kernel Report.
+
+There's also a higher level API that is a combination of the lower level
+APIs and behaves more like traditional module systems. This is
+probably what most klisp programs will use. This API consist of the
+@code{$provide-library!} operative to define (and register) new
+libraries and the @code{$import-library!} operative to extract
+bindings out of existing libraries. This allows various forms of
+controlling which bindings are extracted from the libraries and allows
+various forms of renaming. It can be used both in the body of
+libraries or in the top level.
+
+No association is made by klisp between source files and libraries.
+For a possible mechanism to handle this see @code{require} in the
+ports module. Also no special meaning is assigned to the library
+names. This could be used by an even higher level API, for example to
+map to version numbers and/or to the underlying filesystem.
+
+SOURCE NOTE: This is mostly an adaptation from the r7rs draft of
+scheme. There's no mention of libraries in the Kernel Report, but
+they were deemed important for klisp in order to share and distribute
+code with a common interface. A number of adaptations were made to
+the scheme version to sit more comfortably with the Kernel way of
+doing things (first class status, exposing of the library register,
+etc).
+
+@deffn Applicative library? (library? . objects)
+The primitive type predicate for type library.
+@code{library?} returns true iff all the objects in @code{objects}
+are of type library.
+
+NOTE: This is part of the low level API to libraries. It won't be
+needed to writers or users of libraries that stick to the higher level
+API (i.e. @code{$provide-library!} & @code{$import-library!}).
+@end deffn
+
+@deffn Applicative make-library (make-library bindings)
+@code{bindings} should be an acyclic list of @code{(symbol . value)}
+pairs. Each symbol may only occur once in the list.
+
+Constructs a new library object with the passed @code{bindings} as
+exported objects.
+
+NOTE: This is part of the low level API to libraries, writers of
+libraries are encouraged to use @code{$provide-library!} to define
+their libraries.
+@end deffn
+
+@deffn Applicative get-library-export-list (get-library-export-list library)
+@deffnx Applicative get-library-environment (get-library-environment library)
+@code{get-library-export-list} returns the list of symbols exported
+from the passed library. @code{get-library-environment} returns a
+fresh empty environment whose parent has all exported symbols of the
+library bound to the exported objects.
+
+NOTE: This is part of the low level API to libraries, users of
+libraries are encouraged to use @code{$import-library!} to get
+bindings out of libraries (and into the current environment).
+@end deffn
+
+@deffn Operative $registered-library? ($registered-library? name)
+@deffnx Operative $get-registered-library ($get-registered-library name)
+@deffnx Operative $register-library! ($register-library! name library)
+@deffnx Operative $unregister-library! ($unregister-library! name)
+@code{name} should a an acyclic list of symbols and exact non-negative
+integers. Two registered libraries can't have the same name (in the
+sense of @code{equal?}).
+
+These operatives control the library registry that maps names to
+libraries.
+
+Predicate @code{$registered-library?} returns true iff a
+library named @code{name} is already registered.
+@code{get-registered-library} returns the library object associated
+with @code{name} (or throws an error if no library named @code{name}
+is registered). @code{$register-library!} registers @code{library}
+with name @code{name} (throws an error if @code{name} is already
+registered. @code{$unregister-library!} removes the library
+registered as @code{name} from the library register (throws an error
+if no such library was registered).
+
+NOTE: This is part of the low level API to libraries, users & writers
+of libraries are encouraged to use @code{$provide-library!} to create
+& register new libraries.
+@end deffn
+
+@deffn Operative $provide-library! ($provide-library! name exports . body)
+@deffnx Operative $import-library! ($import-library! . imports)
+@code{name} should be as for @code{register-library!} and not already
+registered. @code{exports} should be a list of @code{(#:export
+<export-spec> ...)}. Where @code{<export spec>} is either:
+@itemize @bullet
+@item @code{symbol}
+@item @code{(#:rename internal-symbol external-symbol)}
+@end itemize
+
+A lone symbol has the same semantics as the pair with that symbol in
+both internal and external positions. No symbol can appear more than once as external.
+@code{body} should be an acyclic list of expressions. @code{exports}
+should be a list like @code{(<import-spec> ...)} where
+@code{<import-spec>} is either
+@itemize @bullet
+@item @code{<name>}
+@item @code{(#:only <import-spec> symbol ...)}
+@item @code{(#:except <import-spec> symbol ...)}
+@item @code{(#:prefix <import-spec> symbol)}
+@item @code{(#:rename <import-spec> (orig-symbol new-symbol) ...)}
+@end itemize
+
+These two operatives conform the higher level API for klisp
+libraries. They are what most users of klisp (both writers and users
+of libraries) will use.
+
+Operative @code{$provide-library!} creates and register a library with
+name @code{name} and exported symbols obtained from the @code{exports} list and
+values prepared by the @code{body}. First a child of the dynamic
+environment is created. Then, @code{body} is evaluated sequentially
+as if by @code{$sequence} in that environment. Next a new library is
+created with a list of exported bindings that use the external symbols
+in @code{exports} as names and the values bound by the corresponding
+internal symbols in the created environment, as values. If a lone
+symbol is used in @code{exports} it is used both as internal and
+external symbol for that binding. Lastly, the new library object is
+registered as @code{name}. This mechanism more or less follows the
+idea of operative @code{$provide!} from the Kernel Report, but it also
+allows for renaming.
+
+Operative @code{$import-library!} imports to the current environment
+any combination of bindings from any number of named libraries, while
+allowing renaming of said bindings. It can be used in any context, as
+any other Kernel expression. @code{$import-library!} looks for the
+named libraries and then extracts & renames the specified bindings
+according to each @code{<import-spec>} and defines them (in the sense
+of @code{$define!} and @code{$set!}) in the current dynamic
+environment. The set of bindings to import are generated in a
+recursive manner. This allows a great deal of control of the imported
+bindings and their names. The semantics for the set of bindings
+generated by the various @code{<import-spec>}s are as follows:
+@itemize @bullet
+@item
+@code{<name>}: All bindings from library @code{name}.
+@item
+@code{(#:only <import-spec> symbol ...)}: Only the named bindings from
+the set of bindings in @code{<import-spec>}.
+@item
+@code{(#:except <import-spec> symbol ...)}: All bindings from the set
+in @code{<import-spec>} except those named in the list.
+@item
+@code{(#:prefix <import-spec> symbol)}: All bindings from the set in
+@code{<import-spec>} but renamed by prefixing each one with the
+specified prefix @code{symbol}.
+@item @code{(#:rename <import-spec> (orig-symbol new-symbol) ...)}:
+All bindings from the set in @code{<import-spec>} but renaming all
+@code{orig-symbol} to the corresponding @code{new-symbol}.
+@end itemize
+
+If two values are tried to be imported with the same name, they are
+checked for @code{eq?}-ness, if they are deemed @code{eq?} to each
+other they are imported, otherwise @code{$import-library!} throws an
+error. This helps catch name collisions while allowing to reexport
+bindings from used libraries without conflict.
+@end deffn
diff --git a/doc/src/ports.texi b/doc/src/ports.texi
@@ -1,7 +1,7 @@
@c -*-texinfo-*-
@setfilename ../src/ports
-@node Ports, System, Characters, Top
+@node Ports, Libraries, Characters, Top
@comment node-name, next, previous, up
@chapter Ports
diff --git a/doc/src/system.texi b/doc/src/system.texi
@@ -1,7 +1,7 @@
@c -*-texinfo-*-
@setfilename ../src/system
-@node System, Alphabetical Index, Ports, Top
+@node System, Alphabetical Index, Libraries, Top
@comment node-name, next, previous, up
@chapter System
