Libraries.html (12101B)
1 <html lang="en"> 2 <head> 3 <title>Libraries - klisp Reference Manual</title> 4 <meta http-equiv="Content-Type" content="text/html"> 5 <meta name="description" content="klisp Reference Manual"> 6 <meta name="generator" content="makeinfo 4.13"> 7 <link title="Top" rel="start" href="index.html#Top"> 8 <link rel="prev" href="Errors.html#Errors" title="Errors"> 9 <link rel="next" href="System.html#System" title="System"> 10 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11 <meta http-equiv="Content-Style-Type" content="text/css"> 12 <style type="text/css"><!-- 13 pre.display { font-family:inherit } 14 pre.format { font-family:inherit } 15 pre.smalldisplay { font-family:inherit; font-size:smaller } 16 pre.smallformat { font-family:inherit; font-size:smaller } 17 pre.smallexample { font-size:smaller } 18 pre.smalllisp { font-size:smaller } 19 span.sc { font-variant:small-caps } 20 span.roman { font-family:serif; font-weight:normal; } 21 span.sansserif { font-family:sans-serif; font-weight:normal; } 22 --></style> 23 <link rel="stylesheet" type="text/css" href="css/style.css"> 24 </head> 25 <body> 26 <div class="node"> 27 <a name="Libraries"></a> 28 <p> 29 Next: <a rel="next" accesskey="n" href="System.html#System">System</a>, 30 Previous: <a rel="previous" accesskey="p" href="Errors.html#Errors">Errors</a>, 31 Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a> 32 <hr> 33 </div> 34 35 <!-- node-name, next, previous, up --> 36 <h2 class="chapter">21 Libraries</h2> 37 38 <p><a name="index-libraries-395"></a> 39 Libraries provide a way to organize klisp code with a clean & clear 40 interface to the rest of the program. They are first class objects 41 (as all manipulable entities in Kernel, and according to the 42 guidelines in the Kernel report). A library has list of exported 43 symbols and values for those symbols (generally combiners but may be 44 any object). The library type is encapsulated. 45 46 <p>In addition there's a mechanism to refer to library objects by name 47 (where a name is actually a unique list of symbols and numbers), with 48 the ability to register new libraries, get the library object from a 49 name, unregister libraries, etc. 50 51 <p>These two ways of working with libraries conform the low level API to 52 libraries and are orthogonal to each other. They are provided to 53 allow klisp programs to construct their own interface to library 54 definition and use, and to respect the guidelines and spirit of the 55 Kernel Report. 56 57 <p>There's also a higher level API that is a combination of the lower level 58 APIs and behaves more like traditional module systems. This is 59 probably what most klisp programs will use. This API consist of the 60 <code>$provide-library!</code> operative to define (and register) new 61 libraries and the <code>$import-library!</code> operative to extract 62 bindings out of existing libraries. This allows various forms of 63 controlling which bindings are extracted from the libraries and allows 64 various forms of renaming. It can be used both in the body of 65 libraries or in the top level. 66 67 <p>No association is made by klisp between source files and libraries. 68 For a possible mechanism to handle this see <code>require</code> in the 69 ports module. Also no special meaning is assigned to the library 70 names. This could be used by an even higher level API, for example to 71 map to version numbers and/or to the underlying filesystem. 72 73 <p>SOURCE NOTE: This is mostly an adaptation from the r7rs draft of 74 scheme. There's no mention of libraries in the Kernel Report, but 75 they were deemed important for klisp in order to share and distribute 76 code with a common interface. A number of adaptations were made to 77 the scheme version to sit more comfortably with the Kernel way of 78 doing things (first class status, exposing of the library register, 79 etc). 80 81 <div class="defun"> 82 — Applicative: <b>library?</b> (<var>library? . objects</var>)<var><a name="index-library_003f-396"></a></var><br> 83 <blockquote><p>The primitive type predicate for type library. 84 <code>library?</code> returns true iff all the objects in <code>objects</code> 85 are of type library. 86 87 <p>NOTE: This is part of the low level API to libraries. It won't be 88 needed to writers or users of libraries that stick to the higher level 89 API (i.e. <code>$provide-library!</code> & <code>$import-library!</code>). 90 </p></blockquote></div> 91 92 <div class="defun"> 93 — Applicative: <b>make-library</b> (<var>make-library bindings</var>)<var><a name="index-make_002dlibrary-397"></a></var><br> 94 <blockquote><p><code>bindings</code> should be an acyclic list of <code>(symbol . value)</code> 95 pairs. Each symbol may only occur once in the list. 96 97 <p>Constructs a new library object with the passed <code>bindings</code> as 98 exported objects. 99 100 <p>NOTE: This is part of the low level API to libraries, writers of 101 libraries are encouraged to use <code>$provide-library!</code> to define 102 their libraries. 103 </p></blockquote></div> 104 105 <div class="defun"> 106 — Applicative: <b>get-library-export-list</b> (<var>get-library-export-list library</var>)<var><a name="index-get_002dlibrary_002dexport_002dlist-398"></a></var><br> 107 — Applicative: <b>get-library-environment</b> (<var>get-library-environment library</var>)<var><a name="index-get_002dlibrary_002denvironment-399"></a></var><br> 108 <blockquote><p><code>get-library-export-list</code> returns the list of symbols exported 109 from the passed library. <code>get-library-environment</code> returns a 110 fresh empty environment whose parent has all exported symbols of the 111 library bound to the exported objects. 112 113 <p>NOTE: This is part of the low level API to libraries, users of 114 libraries are encouraged to use <code>$import-library!</code> to get 115 bindings out of libraries (and into the current environment). 116 </p></blockquote></div> 117 118 <div class="defun"> 119 — Operative: <b>$registered-library?</b> (<var>$registered-library? name</var>)<var><a name="index-g_t_0024registered_002dlibrary_003f-400"></a></var><br> 120 — Operative: <b>$get-registered-library</b> (<var>$get-registered-library name</var>)<var><a name="index-g_t_0024get_002dregistered_002dlibrary-401"></a></var><br> 121 — Operative: <b>$register-library!</b> (<var>$register-library! name library</var>)<var><a name="index-g_t_0024register_002dlibrary_0021-402"></a></var><br> 122 — Operative: <b>$unregister-library!</b> (<var>$unregister-library! name</var>)<var><a name="index-g_t_0024unregister_002dlibrary_0021-403"></a></var><br> 123 <blockquote><p><code>name</code> should a an acyclic list of symbols and exact non-negative 124 integers. Two registered libraries can't have the same name (in the 125 sense of <code>equal?</code>). 126 127 <p>These operatives control the library registry that maps names to 128 libraries. 129 130 <p>Predicate <code>$registered-library?</code> returns true iff a 131 library named <code>name</code> is already registered. 132 <code>get-registered-library</code> returns the library object associated 133 with <code>name</code> (or throws an error if no library named <code>name</code> 134 is registered). <code>$register-library!</code> registers <code>library</code> 135 with name <code>name</code> (throws an error if <code>name</code> is already 136 registered. <code>$unregister-library!</code> removes the library 137 registered as <code>name</code> from the library register (throws an error 138 if no such library was registered). 139 140 <p>NOTE: This is part of the low level API to libraries, users & writers 141 of libraries are encouraged to use <code>$provide-library!</code> to create 142 & register new libraries. 143 </p></blockquote></div> 144 145 <div class="defun"> 146 — Operative: <b>$provide-library!</b> (<var>$provide-library! name exports . body</var>)<var><a name="index-g_t_0024provide_002dlibrary_0021-404"></a></var><br> 147 — Operative: <b>$import-library!</b> (<var>$import-library! . imports</var>)<var><a name="index-g_t_0024import_002dlibrary_0021-405"></a></var><br> 148 <blockquote><p><code>name</code> should be as for <code>register-library!</code> and not already 149 registered. <code>exports</code> should be a list of <code>(#:export 150 <export-spec> ...)</code>. Where <code><export spec></code> is either: 151 <ul> 152 <li><code>symbol</code> 153 <li><code>(#:rename internal-symbol external-symbol)</code> 154 </ul> 155 156 <p>A lone symbol has the same semantics as the pair with that symbol in 157 both internal and external positions. No symbol can appear more than once as external. 158 <code>body</code> should be an acyclic list of expressions. <code>imports</code> 159 should be a list like <code>(<import-spec> ...)</code> where 160 <code><import-spec></code> is either 161 <ul> 162 <li><code><name></code> 163 <li><code>(#:only <import-spec> symbol ...)</code> 164 <li><code>(#:except <import-spec> symbol ...)</code> 165 <li><code>(#:prefix <import-spec> symbol)</code> 166 <li><code>(#:rename <import-spec> (orig-symbol new-symbol) ...)</code> 167 </ul> 168 169 <p>These two operatives conform the higher level API for klisp 170 libraries. They are what most users of klisp (both writers and users 171 of libraries) will use. 172 173 <p>Operative <code>$provide-library!</code> creates and register a library with 174 name <code>name</code> and exported symbols obtained from the <code>exports</code> list and 175 values prepared by the <code>body</code>. First a child of the dynamic 176 environment is created. Then, <code>body</code> is evaluated sequentially 177 as if by <code>$sequence</code> in that environment. Next a new library is 178 created with a list of exported bindings that use the external symbols 179 in <code>exports</code> as names and the values bound by the corresponding 180 internal symbols in the created environment, as values. If a lone 181 symbol is used in <code>exports</code> it is used both as internal and 182 external symbol for that binding. Lastly, the new library object is 183 registered as <code>name</code>. This mechanism more or less follows the 184 idea of operative <code>$provide!</code> from the Kernel Report, but it also 185 allows for renaming. 186 187 <p>Operative <code>$import-library!</code> imports to the current environment 188 any combination of bindings from any number of named libraries, while 189 allowing renaming of said bindings. It can be used in any context, as 190 any other Kernel expression. <code>$import-library!</code> looks for the 191 named libraries and then extracts & renames the specified bindings 192 according to each <code><import-spec></code> and defines them (in the sense 193 of <code>$define!</code> and <code>$set!</code>) in the current dynamic 194 environment. The set of bindings to import are generated in a 195 recursive manner. This allows a great deal of control of the imported 196 bindings and their names. The semantics for the set of bindings 197 generated by the various <code><import-spec></code>s are as follows: 198 <ul> 199 <li><code><name></code>: All bindings from library <code>name</code>. 200 <li><code>(#:only <import-spec> symbol ...)</code>: Only the named bindings from 201 the set of bindings in <code><import-spec></code>. 202 <li><code>(#:except <import-spec> symbol ...)</code>: All bindings from the set 203 in <code><import-spec></code> except those named in the list. 204 <li><code>(#:prefix <import-spec> symbol)</code>: All bindings from the set in 205 <code><import-spec></code> but renamed by prefixing each one with the 206 specified prefix <code>symbol</code>. 207 <li><code>(#:rename <import-spec> (orig-symbol new-symbol) ...)</code>: 208 All bindings from the set in <code><import-spec></code> but renaming all 209 <code>orig-symbol</code> to the corresponding <code>new-symbol</code>. 210 </ul> 211 212 <p>If two values are tried to be imported with the same name, they are 213 checked for <code>eq?</code>-ness, if they are deemed <code>eq?</code> to each 214 other they are imported, otherwise <code>$import-library!</code> throws an 215 error. This helps catch name collisions while allowing to reexport 216 bindings from used libraries without conflict. 217 </p></blockquote></div> 218 219 <!-- *-texinfo-*- --> 220 </body></html> 221