r7rs-small-texinfo

R7RS-small Scheme converted to Texinfo.
git clone https://kaka.farm/~git/r7rs-small-texinfo
Log | Files | Refs | README | LICENSE

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