Ports.html (33702B)
1 <html lang="en"> 2 <head> 3 <title>Ports - 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="Characters.html#Characters" title="Characters"> 9 <link rel="next" href="Vectors.html#Vectors" title="Vectors"> 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="Ports"></a> 28 <p> 29 Next: <a rel="next" accesskey="n" href="Vectors.html#Vectors">Vectors</a>, 30 Previous: <a rel="previous" accesskey="p" href="Characters.html#Characters">Characters</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">17 Ports</h2> 37 38 <p><a name="index-ports-293"></a> 39 A port is an object that mediates data from an input or to a 40 destination. In the former case, the port is an input port, in the 41 latter case, an output port. The data itself can consist of either 42 characters or bytes. In the former case the port is a textual port 43 and in the latter case, a binary port. 44 45 <p>There are three textual ports open, binded by dynamic variables, one 46 for standard input, output, and error. 47 48 <!-- TODO add xref to equal? & eq? --> 49 <p>Although ports are not considered immutable, none of the operations on 50 ports described in this section constitute mutation. Ports are 51 <code>equal?</code> iff <code>eq?</code>. The port type is encapsulated. 52 53 <p>An auxiliary data type used to signal the end of file was reached is 54 <code>eof</code>. The eof type consists of a single immutable value, having 55 an output only external representation (so that it can never be the 56 normal result of a call to read). The eof type is encapsulated. 57 58 <p>SOURCE NOTE: the eof type is not in the Kernel report, it is used in 59 klisp and was taken from r7rs. 60 61 <div class="defun"> 62 — Applicative: <b>port?</b> (<var>port? . objects</var>)<var><a name="index-port_003f-294"></a></var><br> 63 <blockquote><p>The primitive type predicate for type port. <code>port?</code> returns 64 true iff all the objects in <code>objects</code> are of type port. 65 </p></blockquote></div> 66 67 <div class="defun"> 68 — Applicative: <b>input-port?</b> (<var>input-port? . objects</var>)<var><a name="index-input_002dport_003f-295"></a></var><br> 69 — Applicative: <b>output-port?</b> (<var>output-port? . objects</var>)<var><a name="index-output_002dport_003f-296"></a></var><br> 70 <blockquote><p>Applicative <code>input-port?</code> is a predicate that returns true unless 71 one or more of its arguments is not an input port. Applicative 72 <code>output-port?</code> is a predicate that returns true unless one or 73 more of its arguments is not an output port. 74 75 <p>Every port must be admitted by at least one of these two predicates. 76 </p></blockquote></div> 77 78 <div class="defun"> 79 — Applicative: <b>textual-port?</b> (<var>textual-port? . objects</var>)<var><a name="index-textual_002dport_003f-297"></a></var><br> 80 — Applicative: <b>binary-port?</b> (<var>binary-port? . objects</var>)<var><a name="index-binary_002dport_003f-298"></a></var><br> 81 <blockquote><p>Applicative <code>textual-port?</code> is a predicate that returns true 82 unless one or more of its arguments is not a textual port. 83 Applicative <code>binary-port?</code> is a predicate that returns true 84 unless one or more of its arguments is not a binary port. 85 86 <p>Every port must be admitted by at least one of these two predicates. 87 88 <p>SOURCE NOTE: this is missing from Kernel, it is taken from r7rs. 89 </p></blockquote></div> 90 91 <div class="defun"> 92 — Applicative: <b>file-port?</b> (<var>file-port? . objects</var>)<var><a name="index-file_002dport_003f-299"></a></var><br> 93 — Applicative: <b>string-port?</b> (<var>string-port? . objects</var>)<var><a name="index-string_002dport_003f-300"></a></var><br> 94 — Applicative: <b>bytevector-port?</b> (<var>bytevector-port? . objects</var>)<var><a name="index-bytevector_002dport_003f-301"></a></var><br> 95 <blockquote><p>These applictives are predicates that returns true unless one or more 96 of its arguments is not a file, string or bytevector port, 97 repectively. 98 99 <p>Every port in klisp is be admitted by exactly one of these predicates. 100 101 <p>SOURCE NOTE: this is missing from Kernel, but convenient in the face 102 of the different port types admited by klisp. 103 </p></blockquote></div> 104 105 <div class="defun"> 106 — Applicative: <b>port-open?</b> (<var>port-open? port</var>)<var><a name="index-port_002dopen_003f-302"></a></var><br> 107 <blockquote><p>Applicative <code>port-open?</code> returns true iff <code>port</code> is still 108 open. 109 110 <p>SOURCE NOTE: this is taken from r7rs. 111 </p></blockquote></div> 112 113 <div class="defun"> 114 — Applicative: <b>with-input-from-file</b> (<var>with-input-from-file string combiner</var>)<var><a name="index-with_002dinput_002dfrom_002dfile-303"></a></var><br> 115 — Applicative: <b>with-output-to-file</b> (<var>with-output-to-file string combiner</var>)<var><a name="index-with_002doutput_002dto_002dfile-304"></a></var><br> 116 — Applicative: <b>with-error-to-file</b> (<var>with-error-to-file string combiner</var>)<var><a name="index-with_002derror_002dto_002dfile-305"></a></var><br> 117 <blockquote><!-- add xref get-current-input-port/get-current-output-port --> 118 <p>These three applicatives open the file named in <code>string</code> for 119 textual input or output, an invoke the binder of either the 120 input-port, the output-port or the error-port keyed dynamic variables 121 respectively with the opened port & the passed <code>combiner</code> (this 122 means that the combiner is called in a fresh, empty dynamic 123 environment). When/if the binder normally returns, the port is 124 closed. The result of the applicatives <code>with-input-from-file</code> 125 and <code>with-output-from-file</code> is inert. 126 127 <p>SOURCE NOTE: The first two are enumerated in the Kernel report but 128 the text is still missing. The third applicative is from r7rs. 129 </p></blockquote></div> 130 131 <div class="defun"> 132 — 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> 133 — 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> 134 — 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> 135 <blockquote><p>These are the accessors for the input-port, output-port, and 136 error-port keyed dynamic variables repectively. 137 <!-- add xref to with-input-from-file, etc --> 138 <!-- add xref and text for these dynamic vars --> 139 140 <p>SOURCE NOTE: The first two are enumerated in the Kernel report but the 141 text is still missing. The third applicative is from r7rs. 142 </p></blockquote></div> 143 144 <div class="defun"> 145 — Applicative: <b>open-input-file</b> (<var>open-input-file string</var>)<var><a name="index-open_002dinput_002dfile-309"></a></var><br> 146 — 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> 147 <blockquote><p><code>string</code> should be the name/path for an existing file. 148 149 <p>Applicative <code>open-input-file</code> creates and returns a textual input 150 port associated with the file represented with <code>string</code>. 151 Applicative <code>open-binary-input-file</code> creates and returns a binary 152 input port associated with the file represented with <code>string</code>. 153 In either case, if the file can't be opened (e.g. because it doesn't 154 exists, or there's a permissions problem), an error is signaled. 155 156 <p>SOURCE NOTE: <code>open-input-file</code> is enumerated in the Kernel report 157 but the text is still missing. <code>open-binary-input-file</code> is from 158 r7rs. 159 </p></blockquote></div> 160 161 <div class="defun"> 162 — Applicative: <b>open-output-file</b> (<var>open-output-file string</var>)<var><a name="index-open_002doutput_002dfile-311"></a></var><br> 163 — 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> 164 <blockquote><p><code>string</code> should be the name/path for an existing file. 165 166 <p>Applicative <code>open-output-file</code> creates and returns a textual 167 output port associated with the file represented with <code>string</code>. 168 Applicative <code>open-binary-output-file</code> creates and returns a 169 binary output port associated with the file represented with 170 <code>string</code>. In either case, if the file can't be opened (e.g. if 171 there's a permissions problem), an error is signaled. 172 173 <p>In klisp, for now, applicative <code>open-output-file</code> and 174 <code>open-binary-output-file</code> truncate the file if it already exists, 175 but that could change later (i.e. like in Scheme the behaviour should 176 be considered unspecified). 177 178 <p>SOURCE NOTE: <code>open-output-file</code> is enumerated in the Kernel 179 report but the text is still missing. <code>open-binary-output-file</code> 180 is from r7rs. 181 </p></blockquote></div> 182 183 <div class="defun"> 184 — Applicative: <b>open-input-string</b> (<var>open-output-string string</var>)<var><a name="index-open_002dinput_002dstring-313"></a></var><br> 185 — Applicative: <b>open-input-bytevector</b> (<var>open-output-bytevector bytevector</var>)<var><a name="index-open_002dinput_002dbytevector-314"></a></var><br> 186 <blockquote><p>These applicative return a fresh input port that reads characters or 187 unsigned bytes from the passed sequence. 188 189 <p>SOURCE NOTE: These are taken from r7rs. 190 </p></blockquote></div> 191 192 <div class="defun"> 193 — Applicative: <b>open-output-string</b> (<var>open-output-string</var>)<var><a name="index-open_002doutput_002dstring-315"></a></var><br> 194 <blockquote><p>Applicative <code>open-output-string</code> returns a fresh textual 195 output port that accumulates characters. The accumulated data can 196 <!-- TODO add xref --> 197 be obtained via applicative <code>get-output-string</code>. 198 199 <p>SOURCE NOTE: This is taken from r7rs. 200 </p></blockquote></div> 201 202 <div class="defun"> 203 — Applicative: <b>open-output-bytevector</b> (<var>open-output-bytevector</var>)<var><a name="index-open_002doutput_002dbytevector-316"></a></var><br> 204 <blockquote><p>Applicative <code>open-output-bytevector</code> returns a fresh binary 205 output port that accumulates unsigned bytes. The accumulated data can 206 <!-- TODO add xref --> 207 be obtained via applicative <code>get-output-bytevector</code>. 208 209 <p>SOURCE NOTE: This is taken from r7rs. 210 </p></blockquote></div> 211 212 <div class="defun"> 213 — Applicative: <b>close-input-file</b> (<var>close-input-file input-port</var>)<var><a name="index-close_002dinput_002dfile-317"></a></var><br> 214 — Applicative: <b>close-output-file</b> (<var>close-output-file output-port</var>)<var><a name="index-close_002doutput_002dfile-318"></a></var><br> 215 <blockquote><p>These applicatives close the port argument, so that no more 216 input/output may be performed on them, and the resources can be freed. 217 If the port was already closed these applicatives have no effect. 218 219 <p>The result returned by applicatives <code>close-input-file</code> and 220 <code>close-output-file</code> is inert. 221 222 <p>SOURCE NOTE: this is enumerated in the Kernel report but the text is 223 still missing. There's probably a name error here. These should 224 probably be called close-input-port & close-output-port. 225 </p></blockquote></div> 226 227 <div class="defun"> 228 — Applicative: <b>close-input-port</b> (<var>close-input-port input-port</var>)<var><a name="index-close_002dinput_002dport-319"></a></var><br> 229 — Applicative: <b>close-output-port</b> (<var>close-output-port output-port</var>)<var><a name="index-close_002doutput_002dport-320"></a></var><br> 230 — Applicative: <b>close-port</b> (<var>close-port port</var>)<var><a name="index-close_002dport-321"></a></var><br> 231 <blockquote><p>These applicatives close the port argument, so that no more 232 input/output may be performed on them, and the resources can be freed. 233 If the port was already closed these applicatives have no effect. If 234 at some time klisp provided input/output ports these could be used to 235 selectively close only one direction of the port. 236 237 <p>The result returned by applicatives <code>close-input-port</code>, 238 <code>close-output-port</code>, and <code>close-port</code> is inert. 239 240 <p>SOURCE NOTE: this is from r7rs. The equivalent <code>close-input-file</code> 241 and <code>close-output-file</code> are probably name errors and only 242 retained here till the draft standard rectifies them. 243 </p></blockquote></div> 244 245 <div class="defun"> 246 — Applicative: <b>get-output-string</b> (<var>get-output-string port</var>)<var><a name="index-get_002doutput_002dstring-322"></a></var><br> 247 <blockquote><p><code>port</code> should be a string output port. 248 249 <p>Applicative <code>get-output-string</code> returns a freshly created mutable 250 string representing the characters accumulated in <code>port</code> so far. 251 <code>port</code> can be either open or closed. 252 253 <p>SOURCE NOTE: This is taken from r7rs. 254 </p></blockquote></div> 255 256 <div class="defun"> 257 — Applicative: <b>get-output-bytevector</b> (<var>get-output-bytevector port</var>)<var><a name="index-get_002doutput_002dbytevector-323"></a></var><br> 258 <blockquote><p><code>port</code> should be a bytevector output port. 259 260 <p>Applicative <code>get-output-bytevector</code> returns a freshly created mutable 261 bytevector representing the unsigned bytes accumulated in <code>port</code> 262 so far. 263 <code>port</code> can be either open or closed. 264 265 <p>SOURCE NOTE: This is taken from r7rs. 266 </p></blockquote></div> 267 268 <div class="defun"> 269 — Applicative: <b>read</b> (<var>read </var>[<var>port</var>])<var><a name="index-read-324"></a></var><br> 270 <blockquote><p>If the <code>port</code> optional argument is not specified, then the value 271 of the <code>input-port</code> keyed dynamic variable is used. If the port 272 is closed, an error is signaled. The port should be a textual input 273 port. 274 275 <p>Applicative <code>read</code> reads & returns the next parseable object from 276 the given port, or the <code>eof</code> if no objects remain. If 277 <code>read</code> finds and unparseable object in the port, an error is 278 signaled. In that case, the remaining position in the port is 279 unspecified. 280 281 <p>SOURCE NOTE: this is enumerated in the Kernel report but the text is 282 still missing. 283 </p></blockquote></div> 284 285 <div class="defun"> 286 — Applicative: <b>write</b> (<var>write object </var>[<var>port</var>])<var><a name="index-write-325"></a></var><br> 287 <blockquote><p>If the <code>port</code> optional argument is not specified, then the value 288 of the <code>output-port</code> keyed dynamic variable is used. If the port 289 is closed, an error is signaled. The port should be a textual output 290 port. 291 292 <!-- TODO add xref to external representation --> 293 <p>Applicative <code>write</code> writes an external representation of 294 <code>object</code> to the specified port. This may be an output-only 295 representation that can't be read by applicative <code>read</code> in cases 296 where the type of <code>object</code> doen't have a parseable external 297 representation (e.g. combiners and environments). The result returned 298 by <code>write</code> is inert. <code>write</code> is guaranteed to terminate 299 even in the case of objects with shared or cyclic structure. In those 300 cases <code>write</code> will use special syntax to preserve sharing info. 301 <!-- TODO add section and xref on sharing external representation --> 302 303 <p>SOURCE NOTE: this is enumerated in the Kernel report but the text is 304 still missing. 305 </p></blockquote></div> 306 307 <div class="defun"> 308 — Applicative: <b>write-simple</b> (<var>write-simple object </var>[<var>port</var>])<var><a name="index-write_002dsimple-326"></a></var><br> 309 <blockquote><p>Applicative <code>write-simple</code> is like <code>write</code> except that it 310 doesn't write sharing info. It will hang if handed a cyclic structure. 311 312 <p>SOURCE NOTE: this is taken from r7rs. 313 </p></blockquote></div> 314 315 <div class="defun"> 316 — Applicative: <b>eof-object?</b> (<var>eof-object? . objects</var>)<var><a name="index-eof_002dobject_003f-327"></a></var><br> 317 <blockquote><p>The primitive type predicate for type eof. <code>eof-object?</code> 318 returns true iff all the objects in <code>objects</code> are of type eof. 319 320 <p>SOURCE NOTE: This is not in the report, the idea is from Scheme. The 321 <code>eof-object?</code> name is also from Scheme, but this will probably be 322 changed to just <code>eof?</code>, for consistency with the other primitive 323 type predicates. 324 </p></blockquote></div> 325 326 <div class="defun"> 327 — Applicative: <b>newline</b> (<var>newline </var>[<var>port</var>])<var><a name="index-newline-328"></a></var><br> 328 <blockquote><p>If the <code>port</code> optional argument is not specified, then the value 329 of the <code>output-port</code> keyed dynamic variable is used. If the port 330 is closed, an error is signaled. The port should be a textual output 331 port. 332 333 <p>Applicative <code>newline</code> writes a newline to the specified port. 334 The result returned by <code>newline</code> is inert. 335 336 <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme. 337 </p></blockquote></div> 338 339 <div class="defun"> 340 — Applicative: <b>display</b> (<var>display object </var>[<var>port</var>])<var><a name="index-display-329"></a></var><br> 341 <blockquote><p>If the <code>port</code> optional argument is not specified, then the value 342 of the <code>output-port</code> keyed dynamic variable is used. If the port 343 is not a textual output port, or is closed, an error is signaled. 344 345 <p>Applicative <code>display</code> behaves like <code>write</code> except that 346 strings are not enclosed in double quotes and no character is escaped 347 within those strings and character objects are output as if by 348 <code>write-char</code> instead of <code>write</code>. The result returned by 349 <code>display</code> is inert. 350 351 <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme. 352 </p></blockquote></div> 353 354 <div class="defun"> 355 — Applicative: <b>read-line</b> (<var>read-line </var>[<var>port</var>])<var><a name="index-read_002dline-330"></a></var><br> 356 <blockquote><p>If the <code>port</code> optional argument is not specified, then the value 357 of the <code>input-port</code> keyed dynamic variable is used. If the port 358 is closed or if it is not a textual input port, an error is signaled. 359 360 <p>Applicative <code>read-line</code> 361 362 <p>SOURCE NOTE: this is taken from r7rs. 363 </p></blockquote></div> 364 365 <div class="defun"> 366 — 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> 367 <blockquote><p>If the <code>port</code> optional argument is not specified, then the value 368 of the <code>output-port</code> keyed dynamic variable is used. If the port 369 is closed or if it is not an output port, an error is signaled. 370 371 <p>Applicative <code>flush-output-port</code> flushes any buffered data in the 372 output port to the underlying object (file, socket, pipe, memory 373 sector, device, etc). The result returned by <code>flush-output-port</code> 374 is inert. 375 376 <p>SOURCE NOTE: this is missing from Kernel, it is taken from r7rs. 377 </p></blockquote></div> 378 379 <div class="defun"> 380 — Applicative: <b>write-char</b> (<var>write-char char </var>[<var>port</var>])<var><a name="index-write_002dchar-332"></a></var><br> 381 <blockquote><p>If the <code>port</code> optional argument is not specified, then the 382 value of the <code>output-port</code> keyed dynamic variable is used. If the 383 port is closed, an error is signaled. The port should be a textual 384 output port. 385 386 <p>Applicative <code>write-char</code> writes the <code>char</code> character (not 387 an external representation of the character) to the specified port. 388 The result returned by <code>write-char</code> is inert. 389 390 <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme. 391 </p></blockquote></div> 392 393 <div class="defun"> 394 — Applicative: <b>read-char</b> (<var>read-char </var>[<var>port</var>])<var><a name="index-read_002dchar-333"></a></var><br> 395 <blockquote><p>If the <code>port</code> optional argument is not specified, then the value 396 of the <code>input-port</code> keyed dynamic variable is used. If the port 397 is closed, an error is signaled. The port should be a textual input 398 port. 399 400 <p>Applicative <code>read-char</code> reads and returns a character (not an 401 external representation of a character) from the specified port, or an 402 <code>eof</code> if the end of file was reached. 403 404 <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme. 405 </p></blockquote></div> 406 407 <div class="defun"> 408 — Applicative: <b>peek-char</b> (<var>peek-char </var>[<var>port</var>])<var><a name="index-peek_002dchar-334"></a></var><br> 409 <blockquote><p>If the <code>port</code> optional argument is not specified, then the value 410 of the <code>input-port</code> keyed dynamic variable is used. If the port 411 is closed, an error is signaled. The port should be a textual input 412 port. 413 414 <p>Applicative <code>peek-char</code> reads and returns a character (not an 415 external representation of a character) from the specified port, or an 416 <code>eof</code> if the end of file was reached. The position of the port 417 remains unchanged so that new call to <code>peek-char</code> or 418 <code>read-char</code> on the same port return the same character. 419 420 <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme. 421 </p></blockquote></div> 422 423 <div class="defun"> 424 — Applicative: <b>char-ready?</b> (<var>char-ready? </var>[<var>port</var>])<var><a name="index-char_002dready_003f-335"></a></var><br> 425 <blockquote><p>If the <code>port</code> optional argument is not specified, then the value 426 of the <code>input-port</code> keyed dynamic variable is used. If the port 427 is closed, an error is signaled. The port should be a textual input 428 port. 429 430 <p>Predicate <code>char-ready?</code> checks to see if a character is available 431 in the specified port. If it returns true, then a <code>read-char</code> or 432 <code>peek-char</code> on that port is guaranteed not to block/hang. For 433 now in klisp this is hardcoded to <code>#t</code> because the code to do 434 this is non-portable. 435 436 <p>SOURCE NOTE: this is missing from Kernel, it is taken from Scheme. 437 </p></blockquote></div> 438 439 <div class="defun"> 440 — Applicative: <b>write-u8</b> (<var>write-u8 u8 </var>[<var>port</var>])<var><a name="index-write_002du8-336"></a></var><br> 441 <blockquote><p>If the <code>port</code> optional argument is not specified, then the 442 value of the <code>output-port</code> keyed dynamic variable is used. If the 443 port is closed, an error is signaled. The port should be a binary 444 output port. 445 446 <p>Applicative <code>write-u8</code> writes the byte represented by the 447 unsigned integer <code>u8</code>, that should be between 0 and 255 inclusive, 448 (not an external representation of byte) to the specified port. The 449 result returned by <code>write-u8</code> is inert. 450 451 <p>SOURCE NOTE: this is missing from Kernel, it is taken from r7rs. 452 </p></blockquote></div> 453 454 <div class="defun"> 455 — Applicative: <b>read-u8</b> (<var>read-u8 </var>[<var>port</var>])<var><a name="index-read_002du8-337"></a></var><br> 456 <blockquote><p>If the <code>port</code> optional argument is not specified, then the value 457 of the <code>input-port</code> keyed dynamic variable is used. If the port 458 is closed, an error is signaled. The port should be a binary input 459 port. 460 461 <p>Applicative <code>read-u8</code> reads and returns a byte as an exact 462 unsigned integer between 0 and 255 inclusive (not an external 463 representation of a byte) from the specified port, or an <code>eof</code> if 464 the end of file was reached. 465 466 <p>SOURCE NOTE: this is missing from Kernel, it is taken from r7rs. 467 </p></blockquote></div> 468 469 <div class="defun"> 470 — Applicative: <b>peek-u8</b> (<var>peek-u8 </var>[<var>port</var>])<var><a name="index-peek_002du8-338"></a></var><br> 471 <blockquote><p>If the <code>port</code> optional argument is not specified, then the 472 value of the <code>input-port</code> keyed dynamic variable is used. If the 473 port is closed, an error is signaled. The port should be a binary 474 input port. 475 476 <p>Applicative <code>peek-u8</code> reads and returns a byte as an exact 477 unsigned integer between 0 and 255 inclusive (not an external 478 representation of a byte) from the specified port, or an <code>eof</code> if 479 the end of file was reached. The position of the port remains 480 unchanged so that new call to <code>peek-u8</code> or <code>read-u8</code> on the 481 same port return the same byte. 482 483 <p>SOURCE NOTE: this is missing from Kernel, it is taken from r7rs. 484 </p></blockquote></div> 485 486 <div class="defun"> 487 — Applicative: <b>u8-ready?</b> (<var>u8-ready? </var>[<var>port</var>])<var><a name="index-u8_002dready_003f-339"></a></var><br> 488 <blockquote><p>If the <code>port</code> optional argument is not specified, then the 489 value of the <code>input-port</code> keyed dynamic variable is used. If the 490 port is closed, an error is signaled. The port should be a binary 491 input port. 492 493 <p>Predicate <code>u8-ready?</code> checks to see if a byte is 494 available in the specified port. If it returns true, then a 495 <code>read-u8</code> or <code>peek-u8</code> on that port is guaranteed not to 496 block/hang. For now in klisp this is hardcoded to <code>#t</code> because 497 the code to do this is non-portable. 498 499 <p>SOURCE NOTE: this is missing from Kernel, it is taken from r7rs. 500 </p></blockquote></div> 501 502 <div class="defun"> 503 — 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> 504 — 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> 505 <blockquote><p>These applicatives open file named in <code>string</code> for textual 506 input/output respectively and call their <code>combiner</code> argument in a 507 fresh empty environment passing it as a sole operand the opened port. 508 When/if the combiner normally returns a value the port is closed and 509 that value is returned as the result of the applicative. 510 511 <p>SOURCE NOTE: this is enumerated in the Kernel report but the text is 512 still missing. 513 </p></blockquote></div> 514 515 <div class="defun"> 516 — Applicative: <b>load</b> (<var>load string</var>)<var><a name="index-load-342"></a></var><br> 517 <blockquote><!-- TODO add xref, open/input, read --> 518 <p>Applicative <code>load</code> opens the file named <code>string</code> for textual 519 input; reads immutable objects from the file until the end of the file 520 is reached; evaluates those objects consecutively in the created 521 environment. The result from applicative <code>load</code> is inert. 522 523 <p>Notice that if <code>string</code> is a relative path it is looked in the 524 current directory (whatever that means in your OS, normally the 525 directory from which the interpreted was run or the directory where 526 the interpreter executable lives). klisp doesn't track the directory 527 from which the current code was read, so there's in principle no way 528 to load a file in the same directory as the currently executing code 529 with a relative path. See <code>find-required-filename</code> for a way to 530 look for a file in a number of directories. 531 532 <p>SOURCE NOTE: load is enumerated in the Kernel report, but the 533 description is not there yet. This seems like a sane way to define 534 it, taking the description of <code>get-module</code> that there is in the 535 report. The one detail that I think is still open, is whether to 536 return <code>#inert</code> (as is the case with klisp currently) or rather 537 return the value of the last evaluation. 538 </p></blockquote></div> 539 540 <div class="defun"> 541 — Applicative: <b>require</b> (<var>require string</var>)<var><a name="index-require-343"></a></var><br> 542 <blockquote><p>Applicative <code>require</code> looks for <code>string</code> following the 543 algorithm described in applicative <code>find-required-filename</code>. If 544 an appropriate file can't be found, and error is signaled. Otherwise, 545 the file is opened for textual input; immutable objects are read and 546 acumulated until the end of file is found; those objects are evaluated 547 in a fresh standard environment; the results of evaluation are 548 discarded and the result from applicative <code>require</code> is inert. 549 550 <p>Applicative <code>require</code> also register <code>string</code> (as via 551 applicative <code>register-requirement!</code>) so that subsequent calls to 552 <code>require</code> with exactly the same <code>string</code> will not cause any 553 search or evaluation. The mechanism used for this can also be 554 manipulated directly by the programmer via applicatives 555 <code>registered-requirement?</code>, <code>register-requirement!</code>, 556 <code>unregister-requirement!</code>, and <code>find-required-filename</code>. 557 <!-- TODO add xref to fresh standard environment --> 558 559 <p>Applicative <code>require</code> is useful to load klisp libraries. 560 561 <p>SOURCE NOTE: require is taken from lua and r7rs. 562 </p></blockquote></div> 563 564 <div class="defun"> 565 — Applicative: <b>registered-requirement?</b> (<var>registered-requirement? string</var>)<var><a name="index-registered_002drequirement_003f-344"></a></var><br> 566 — Applicative: <b>register-requirement!</b> (<var>register-requirement! string</var>)<var><a name="index-register_002drequirement_0021-345"></a></var><br> 567 — Applicative: <b>unregister-requirement!</b> (<var>unregister-requirement! string</var>)<var><a name="index-unregister_002drequirement_0021-346"></a></var><br> 568 — Applicative: <b>find-required-filename</b> (<var>find-required-filename string</var>)<var><a name="index-find_002drequired_002dfilename-347"></a></var><br> 569 <blockquote><p><code>string</code> should be non-empty. 570 571 <p>These applicatives control the underlying facilities used by 572 <code>require</code> to register already required files. Predicate 573 <code>registered-requirement?</code> returns true iff <code>string</code> is 574 already registered. <code>register-requirement!</code> marks <code>string</code> 575 as registered (throws an error if it was already registered). 576 <code>unregister-requirement!</code> marks <code>string</code> as not being 577 registered (throws an error if it wasn't registered). 578 <code>find-required-filename</code> looks for an appropriate file for 579 <code>string</code> using the algorithm described below. 580 581 <p>filename search in controlled by environment variable 582 <code>KLISP_PATH</code>. This environment variable should be a list of 583 templates separated with semicolons (“;”). Each template is a 584 string that may contain embedded question mark characters (“?”) to 585 be replaced with <code>string</code>. After replacements, each template 586 represents the path to a file. All templates are probed in order, and 587 the first to name an existing readable file is returned. If no 588 template corresponds to an existing readable file, an error is 589 signaled. 590 591 <p>NOTE: in the future there will be some mechanism to alter the search 592 algorithm dinamically, in the meantime this environment variable is 593 the only way to customize it. 594 595 <p>SOURCE NOTE: this is not in Kernel, they are supplied per guideline 596 G1b of the report (extensibility), so that klisp programs can easily 597 duplicate the behaviour of <code>require</code> 598 </p></blockquote></div> 599 600 <div class="defun"> 601 — Applicative: <b>get-module</b> (<var>get-module string </var>[<var>environment</var>])<var><a name="index-get_002dmodule-348"></a></var><br> 602 <blockquote><!-- TODO add xref standard-environment, open/input, read --> 603 <p>Applicative <code>get-module</code> creates a fresh standard environment; 604 opens the file named <code>string</code> for textual input; reads objects 605 from the file until the end of the file is reached; evaluates those 606 objects consecutively in the created environment; and, lastly, returns 607 the created environment. If the optional argument <code>environment</code> 608 is specified, the freshly created standard environment is augmented, 609 prior to evaluating read expressions, by binding symbol 610 <code>module-parameters</code> to the <code>environment</code> argument. 611 </p></blockquote></div> 612 613 <!-- *-texinfo-*- --> 614 </body></html> 615