input-and-output.texinfo (18990B)
1 @node Input and output 2 @section Input and output 3 4 @menu 5 * Ports:: 6 * Input:: 7 * Output:: 8 @end menu 9 10 @node Ports 11 @subsection Ports 12 13 @cindex port 14 15 Ports represent input and output devices. To Scheme, an input port is 16 a Scheme object that can deliver data upon command, while an output 17 port is a Scheme object that can accept data. Whether the input and 18 output port types are disjoint is implementation-dependent. 19 20 Different @define{port types} operate on different data. Scheme 21 implementations are required to support @define{textual ports} and 22 @define{binary ports}, but may also provide other port types. 23 24 A textual port supports reading or writing of individual characters 25 from or to a backing store containing characters using @code{read-char} 26 and @code{write-char} below, and it supports operations defined in 27 terms of characters, such as @code{read} and @code{write}. 28 29 A binary port supports reading or writing of individual bytes 30 from or to a backing store containing bytes using @code{read-u8} 31 and @code{write-u8} below, as well as operations defined in terms 32 of bytes. Whether the textual and binary port types are disjoint 33 is implementation-dependent. 34 35 Ports can be used to access files, devices, and similar things on 36 the host system on which the Scheme program is running. 37 38 @deffn procedure call-with-port port proc 39 40 It is an error if @var{proc} does not accept one argument. 41 42 The @code{call-with-port} procedure calls @var{proc} with @var{port} 43 as an argument. If @var{proc} returns, then the port is closed 44 automatically and the values yielded by the @var{proc} are returned. 45 If @var{proc} does not return, then the port must not be closed 46 automatically unless it is possible to prove that the port will never 47 again be used for a read or write operation. 48 49 @rationale{} 50 51 Because Scheme's escape procedures have unlimited extent, it 52 is possible to escape from the current continuation but later to 53 resume it. If implementations were permitted to close the port on any 54 escape from the current continuation, then it would be impossible to 55 write portable code using both @code{call-with-current-continuation} 56 and @code{call-with-port}. 57 58 @end deffn 59 60 @deffn {file library procedure} call-with-input-file string proc 61 @deffnx {file library procedure} call-with-output-file string proc 62 63 It is an error if @var{proc} does not accept one argument. 64 65 These procedures obtain a textual port obtained by opening the 66 named file for input or output as if by @code{open-input-file} or 67 @code{open-output-file}. The port and @var{proc} are then passed to 68 a procedure equivalent to @code{call-with-port}. 69 70 @end deffn 71 72 @deffn procedure input-port? obj 73 @deffnx procedure output-port? obj 74 @deffnx procedure textual-port? obj 75 @deffnx procedure binary-port? obj 76 @deffnx procedure port? obj 77 78 These procedures return @code{#t} if @var{obj} is an input port, output 79 port, textual port, binary port, or any kind of port, respectively. 80 Otherwise they return @code{#f}. 81 82 @end deffn 83 84 @deffn procedure input-port-open? port 85 @deffnx procedure output-port-open? port 86 87 Returns @code{#t} if @var{port} is still open and capable of performing 88 input or output, respectively, and @code{#f} otherwise. 89 90 @end deffn 91 92 @deffn procedure current-input-port 93 @deffnx procedure current-output-port 94 @deffnx procedure current-error-port 95 96 Returns the current default input port, output port, or error port (an 97 output port), respectively. These procedures are parameter objects, 98 which can be overridden with parameterize (see @ref{Dynamic bindings}). 99 The initial bindings for these are implementation-defined textual 100 ports. 101 102 @end deffn 103 104 @deffn {file library procedure} with-input-from-file string thunk 105 @deffnx {file library procedure} with-output-to-file string thunk 106 107 The file is opened for input or output as if by @code{open-input-file} 108 or @code{open-output-file}, and the new port is made to be the value 109 returned by @code{current-input-port} or @code{current-output-port} 110 (as used by @code{(read)}, @code{(write }@var{obj}@code{)}, and so 111 forth). The @var{thunk} is then called with no arguments. When the 112 @var{thunk} returns, the port is closed and the previous default 113 is restored. It is an error if @var{thunk} does not accept zero 114 arguments. Both procedures return the values yielded by @var{thunk}. 115 If an escape procedure is used to escape from the continuation of 116 these procedures, they behave exactly as if the current input or 117 output port had been bound dynamically with @code{parameterize}. 118 119 @end deffn 120 121 @deffn {file library procedure} open-input-file string 122 @deffnx {file library procedure} open-binary-input-file string 123 124 Takes a @var{string} for an existing file and returns a textual input 125 port or binary input port that is capable of delivering data from the 126 file. If the file does not exist or cannot be opened, an error that 127 satisfies @code{file-error?} is signaled. 128 129 @end deffn 130 131 @deffn {file library procedure} open-output-file string 132 @deffnx {file library procedure} open-binary-output-file string 133 134 Takes a @var{string} naming an output file to be created and returns a 135 textual output port or binary output port that is capable of writing 136 data to a new file by that name. If a file with the given name already 137 exists, the effect is unspecified. If the file cannot be opened, an 138 error that satisfies @code{file-error?} is signaled. 139 140 @end deffn 141 142 @deffn procedure close-port port 143 @deffnx procedure close-input-port port 144 @deffnx procedure close-output-port port 145 146 Closes the resource associated with @var{port}, rendering the 147 @var{port} incapable of delivering or accepting data. It is an error to 148 apply the last two procedures to a port which is not an input or output 149 port, respectively. Scheme implementations may provide ports which are 150 simultaneously input and output ports, such as sockets; the 151 @code{close-input-port} and @code{close-output-port} procedures can 152 then be used to close the input and output sides of the port 153 independently. 154 155 These routines have no effect if the @var{port} has already been closed. 156 157 @end deffn 158 159 @deffn procedure open-input-string string 160 161 Takes a string and returns a textual input port that delivers 162 characters from the string. If the @var{string} is modified, the effect 163 is unspecified. 164 165 @end deffn 166 167 @deffn procedure open-output-string 168 169 Returns a textual output port that will accumulate characters for 170 retrieval by @code{get-output-string}. 171 172 @end deffn 173 174 @deffn procedure get-output-string port 175 176 It is an error if @var{port} was not created with 177 @code{open-output-string}. 178 179 Returns a string consisting of the characters that have been output to 180 the port so far in the order they were output. If the result string is 181 modified, the effect is unspecified. 182 183 @lisp 184 (parameterize 185 ((current-output-port 186 (open-output-string))) 187 (display "piece") 188 (display " by piece ") 189 (display "by piece.") 190 (newline) 191 (get-output-string (current-output-port))) 192 193 @result{} "piece by piece by piece.\n" 194 @end lisp 195 @end deffn 196 197 @deffn procedure open-input-bytevector bytevector 198 199 Takes a @var{bytevector} and returns a binary input port that delivers 200 bytes from the @var{bytevector}. 201 202 @end deffn 203 204 @deffn procedure open-output-bytevector 205 206 Returns a binary output port that will accumulate bytes for retrieval 207 by @code{get-output-bytevector}. 208 209 @end deffn 210 211 @deffn procedure get-output-bytevector port 212 213 It is an error if @var{port} was not created with 214 @code{open-output-bytevector}. 215 216 Returns a bytevector consisting of the bytes that have been output to 217 the @var{port} so far in the order they were output. 218 219 @end deffn 220 221 @node Input 222 @subsection Input 223 224 If @var{port} is omitted from any input procedure, it defaults to the 225 value returned by @code{(current-input-port)}. It is an error to 226 attempt an input operation on a closed port. 227 228 @deffn {read library procedure} read 229 @deffnx {read library procedure} read port 230 231 The @code{read} procedure converts external representations of Scheme 232 objects into the objects themselves. That is, it is a parser for the 233 non-terminal @svar{datum} (see @ref{External representations formal,, 234 External representations} and @ref{Pairs and lists}). It returns the 235 next object parsable from the given textual input @var{port}, updating 236 @var{port} to point to the first character past the end of the external 237 representation of the object. 238 239 Implementations may support extended syntax to represent record types 240 or other types that do not have datum representations. 241 242 If an end of file is encountered in the input before any characters are 243 found that can begin an object, then an end-of-file object is returned. 244 The port remains open, and further attempts to read will also return an 245 end-of-file object. If an end of file is encountered after the 246 beginning of an object's external representation, but the external 247 representation is incomplete and therefore not parsable, an error that 248 satisfies @code{read-error?} is signaled. 249 250 @end deffn 251 252 @deffn procedure read-char 253 @deffnx procedure read-char port 254 255 Returns the next character available from the textual input @var{port}, 256 updating the @var{port} to point to the following character. If no more 257 characters are available, an end-of-file object is returned. 258 259 @end deffn 260 261 @deffn procedure peek-char 262 @deffnx procedure peek-char port 263 264 Returns the next character available from the textual input @var{port}, 265 but without updating the @var{port} to point to the following 266 character. If no more characters are available, an end-of-file object 267 is returned. 268 269 Note: The value returned by a call to @code{peek-char} is the same as 270 the value that would have been returned by a call to @code{read-char} 271 with the same @var{port}. The only difference is that the very next 272 call to @code{read-char} or @code{peek-char} on that @var{port} will 273 return the value returned by the preceding call to @code{peek-char}. 274 In particular, a call to @code{peek-char} on an interactive port 275 will hang waiting for input whenever a call to @code{read-char} 276 would have hung. 277 278 @end deffn 279 280 @deffn procedure read-line 281 @deffnx procedure read-line port 282 283 Returns the next line of text available from the textual input 284 @var{port}, updating the @var{port} to point to the following 285 character. If an end of line is read, a string containing all of the 286 text up to (but not including) the end of line is returned, and the 287 port is updated to point just past the end of line. If an end of file 288 is encountered before any end of line is read, but some characters have 289 been read, a string containing those characters is returned. If an end 290 of file is encountered before any characters are read, an end-of-file 291 object is returned. For the purpose of this procedure, an end of line 292 consists of either a linefeed character, a carriage return character, 293 or a sequence of a carriage return character followed by a linefeed 294 character. Implementations may also recognize other end of line 295 characters or sequences. 296 297 @end deffn 298 299 @deffn procedure eof-object? obj 300 301 Returns @code{#t} if @var{obj} is an end-of-file object, otherwise 302 returns @code{#f}. The precise set of end-of-file objects will vary 303 among implementations, but in any case no end-of-file object will 304 ever be an object that can be read in using @code{read}. 305 306 @end deffn 307 308 @deffn procedure eof-object 309 310 Returns an end-of-file object, not necessarily unique. 311 312 @end deffn 313 314 @deffn procedure char-ready? 315 @deffnx procedure char-ready? port 316 317 Returns @code{#t} if a character is ready on the textual input 318 @var{port} and returns @code{#f} otherwise. If @code{char-ready} 319 returns @code{#t} then the next @code{read-char} operation on the 320 given @var{port} is guaranteed not to hang. If the @var{port} is at 321 end of file then @code{char-ready?} returns @code{#t}. 322 323 @rationale{} 324 325 The @code{char-ready?} procedure exists to make it possible for 326 a program to accept characters from interactive ports without 327 getting stuck waiting for input. Any input editors associated with 328 such ports must ensure that characters whose existence has been 329 asserted by @code{char-ready?} cannot be removed from the input. 330 If @code{char-ready?} were to return @code{#f} at end of file, a port 331 at end of file would be indistinguishable from an interactive port 332 that has no ready characters. 333 334 @end deffn 335 336 @deffn procedure read-string k 337 @deffnx procedure read-string k port 338 339 Reads the next @var{k} characters, or as many as are available 340 before the end of file, from the textual input @var{port} into a 341 newly allocated string in left-to-right order and returns the string. 342 If no characters are available before the end of file, an end-of-file 343 object is returned. 344 345 @end deffn 346 347 @deffn procedure read-u8 348 @deffnx procedure read-u8 port 349 350 Returns the next byte available from the binary input @var{port}, 351 updating the @var{port} to point to the following byte. If no more 352 bytes are available, an end-of-file object is returned. 353 354 @end deffn 355 356 @deffn procedure peek-u8 357 @deffnx procedure peek-u8 port 358 359 Returns the next byte available from the binary input @var{port}, but 360 without updating the @var{port} to point to the following byte. If no 361 more bytes are available, an end-of-file object is returned. 362 363 @end deffn 364 365 @deffn procedure u8-ready? 366 @deffnx procedure u8-ready? port 367 368 Returns @code{#t} if a byte is ready on the binary input @var{port} 369 and returns @code{#f} otherwise. If @code{u8-ready?} returns @code{#t} 370 then the next @code{read-u8} operation on the given @var{port} is 371 guaranteed not to hang. If the @var{port} is at end of file then 372 @code{u8-ready?} returns @code{#t}. 373 374 @end deffn 375 376 @deffn procedure read-bytevector k 377 @deffnx procedure read-bytevector k port 378 379 Reads the next @var{k} bytes, or as many as are available before the 380 end of file, from the binary input @var{port} into a newly allocated 381 bytevector in left-to-right order and returns the bytevector. If no 382 bytes are available before the end of file, an end-of-file object 383 is returned. 384 385 @end deffn 386 387 @deffn procedure read-bytevector! bytevector 388 @deffnx procedure read-bytevector! bytevector port 389 @deffnx procedure read-bytevector! bytevector port start 390 @deffnx procedure read-bytevector! bytevector port start end 391 392 Reads the next @var{end} @minus{} @var{start} bytes, or as many as are 393 available before the end of file, from the binary input @var{port} into 394 @var{bytevector} in left-to-right order beginning at the @var{start} 395 position. If @var{end} is not supplied, reads until the end of 396 @var{bytevector} has been reached. If @var{start} is not supplied, 397 reads beginning at position 0. Returns the number of bytes read. If no 398 bytes are available, an end-of-file object is returned. 399 400 @end deffn 401 402 @node Output 403 @subsection Output 404 405 If @var{port} is omitted from any output procedure, it defaults to the 406 value returned by @code{(current-output-port)}. It is an error to 407 attempt an output operation on a closed port. 408 409 @deffn {write library procedure} write obj 410 @deffnx {write library procedure} write obj port 411 412 Writes a representation of @var{obj} to the given textual output 413 @var{port}. Strings that appear in the written representation are 414 enclosed in quotation marks, and within those strings backslash and 415 quotation mark characters are escaped by backslashes. Symbols that 416 contain non-ASCII characters are escaped with vertical lines. 417 Character objects are written using the @code{#\} notation. 418 419 If @var{obj} contains cycles which would cause an infinite loop 420 using the normal written representation, then at least the objects 421 that form part of the cycle must be represented using datum labels 422 as described in @ref{Datum labels}. Datum labels must not be used 423 if there are no cycles. 424 425 Implementations may support extended syntax to represent record types 426 or other types that do not have datum representations. 427 428 The @code{write} procedure returns an unspecified value. 429 430 @end deffn 431 432 @deffn {write library procedure} write-shared obj 433 @deffnx {write library procedure} write-shared obj port 434 435 The @code{write-shared} procedure is the same as @code{write}, except 436 that shared structure must be represented using datum labels for all 437 pairs and vectors that appear more than once in the output. 438 439 @end deffn 440 441 @deffn {write library procedure} write-simple obj 442 @deffnx {write library procedure} write-simple obj port 443 444 The @code{write-simple} procedure is the same as @code{write}, except 445 that shared structure is never represented using datum labels. This can 446 cause @code{write-simple} not to terminate if @var{obj} contains 447 circular structure. 448 449 @end deffn 450 451 @deffn {write library procedure} display obj 452 @deffnx {write library procedure} display obj port 453 454 Writes a representation of @var{obj} to the given textual output 455 @var{port}. Strings that appear in the written representation are 456 output as if by @code{write-string} instead of by @code{write}. 457 Symbols are not escaped. Character objects appear in the 458 representation as if written by @code{write-char} instead of by 459 @code{write}. 460 461 The @code{display} representation of other objects is unspecified. 462 However, @code{display} must not loop forever on self-referencing 463 pairs, vectors, or records. Thus if the normal @code{write} 464 representation is used, datum labels are needed to represent cycles 465 as in @code{write}. 466 467 Implementations may support extended syntax to represent record types 468 or other types that do not have datum representations. 469 470 The @code{display} procedure returns an unspecified value. 471 472 @rationale{} 473 474 The @code{write} procedure is intended for producing machine-readable 475 output and @code{display} for producing human-readable output. 476 477 @end deffn 478 479 @deffn procedure newline 480 @deffnx procedure newline port 481 482 Writes an end of line to textual output @var{port}. Exactly how this is 483 done differs from one operating system to another. Returns an 484 unspecified value. 485 486 @end deffn 487 488 @deffn procedure write-char char 489 @deffnx procedure write-char char port 490 491 Writes the character @var{char} (not an external representation of the 492 character) to the given textual output @var{port} and returns an 493 unspecified value. 494 495 @end deffn 496 497 @deffn procedure write-string string 498 @deffnx procedure write-string string port 499 @deffnx procedure write-string string port start 500 @deffnx procedure write-string string port start end 501 502 Writes the characters of @var{string} from @var{start} to @var{end} in 503 left-to-right order to the textual output @var{port}. 504 505 @end deffn 506 507 @deffn procedure write-u8 byte 508 @deffnx procedure write-u8 byte port 509 510 Writes the @var{byte} to the given binary output @var{port} and returns 511 an unspecified value. 512 513 @end deffn 514 515 @deffn procedure write-bytevector bytevector 516 @deffnx procedure write-bytevector bytevector port 517 @deffnx procedure write-bytevector bytevector port start 518 @deffnx procedure write-bytevector bytevector port start end 519 520 Writes the bytes of @var{bytevector} from @var{start} to @var{end} in 521 left-to-right order to the binary output @var{port}. 522 523 @end deffn 524 525 @deffn procedure flush-output-port 526 @deffnx procedure flush-output-port port 527 528 Flushes any buffered output from the buffer of @var{port} to the 529 underlying file or device and returns an unspecified value. 530 531 @end deffn