Next: stdlib io port binary input, Previous: stdlib io port io ports, Up: stdlib io port [Index]
An input port allows the reading of an infinite sequence of bytes or characters punctuated by end–of–file objects. An input port connected to a finite data source ends in an infinite sequence of end–of–file objects.
It is unspecified whether a character encoding consisting of several
bytes may have an end of file between the bytes. If, for example,
get-char raises an &i/o-decoding exception because the
character encoding at the port’s position is incomplete up to the next
end of file, a subsequent call to get-char may successfully
decode a character if bytes completing the encoding are available after
the end of file.
Return #t if the argument is an input port (or a combined input and
output port), and returns #f otherwise.
Return #t if the lookahead-u8 procedure (if input-port
is a binary port) or the lookahead-char procedure (if
input-port is a textual port) would return the end–of–file
object, and #f otherwise. The operation may block indefinitely if
no data is available but the port cannot be determined to be at end of
file.
maybe-transcoder must be either a transcoder or #f.
The open-file-input-port procedure returns an input port for the
named file. The file-options and maybe-transcoder arguments
are optional.
The file-options argument, which may determine various aspects of
the returned port, defaults to the value of (file-options).
The buffer-mode argument, if supplied, must be one of the symbols
that name a buffer mode. The buffer-mode argument defaults to
block.
If maybe-transcoder is a transcoder, it becomes the transcoder associated with the returned port.
If maybe-transcoder is #f or absent, the port will be a
binary port and will support the port-position and
set-port-position! operations. Otherwise the port will be a
textual port, and whether it supports the port-position and
set-port-position! operations is implementation–dependent (and
possibly transcoder–dependent).
maybe-transcoder must be either a transcoder or #f.
The open-bytevector-input-port procedure returns an input port
whose bytes are drawn from bytevector. If transcoder is
specified, it becomes the transcoder associated with the returned port.
If maybe-transcoder is #f or absent, the port will be a
binary port and will support the port-position and
set-port-position! operations. Otherwise the port will be a
textual port, and whether it supports the port-position and
set-port-position! operations will be implementation–dependent
(and possibly transcoder–dependent).
If bytevector is modified after open-bytevector-input-port
has been called, the effect on the returned port is unspecified.
Return a textual input port whose characters are drawn from
string. The port may or may not have an associated transcoder; if
it does, the transcoder is implementation–dependent. The port should
support the port-position and set-port-position!
operations.
If string is modified after open-string-input-port has been
called, the effect on the returned port is unspecified.
Return a fresh binary input port connected to standard input. Whether
the port supports the port-position and set-port-position!
operations is implementation–dependent.
This returns a default textual port for input. Normally, this default
port is associated with standard input, but can be dynamically
re–assigned using the with-input-from-file procedure from the
(rnrs io simple (6)) library. The port may or may not have an
associated transcoder; if it does, the transcoder is
implementation–dependent.
Return a newly created binary input port whose byte source is an
arbitrary algorithm represented by the read! procedure. id
must be a string naming the new port, provided for informational
purposes only. read! must be a procedure and should behave as
specified below; it will be called by operations that perform binary
input.
Each of the remaining arguments may be #f; if any of those
arguments is not #f, it must be a procedure and should behave as
specified below.
(read! bytevector start count)start will be a non–negative exact integer object, count will be a positive exact integer object, and bytevector will be a bytevector whose length is at least start+count.
The read! procedure should obtain up to count bytes from the byte source, and should write those bytes into bytevector starting at index start. The read! procedure should return an exact integer object. This integer object should represent the number of bytes that it has read. To indicate an end of file, the read! procedure should write no bytes and return 0.
(get-position)The get-position procedure (if supplied) should return an exact
integer object representing the current position of the input port. If
not supplied, the custom port will not support the port-position
operation.
(set-position! pos)pos will be a non–negative exact integer object. The
set-position! procedure (if supplied) should set the position of
the input port to pos. If not supplied, the custom port will not
support the set-port-position! operation.
(close)The close procedure (if supplied) should perform any actions that are necessary when the input port is closed.
Implementation responsibilities: The implementation must check the return values of read! and get-position only when it actually calls them as part of an I/O operation requested by the program. The implementation is not required to check that these procedures otherwise behave as described. If they do not, however, the behavior of the resulting port is unspecified.
Return a newly created textual input port whose character source is an arbitrary algorithm represented by the read! procedure. id must be a string naming the new port, provided for informational purposes only. read! must be a procedure and should behave as specified below; it will be called by operations that perform textual input.
Each of the remaining arguments may be #f; if any of those
arguments is not #f, it must be a procedure and should behave as
specified below.
(read! string start count)start will be a non–negative exact integer object, count will be a positive exact integer object, and string will be a string whose length is at least start+count.
The read! procedure should obtain up to count characters from the character source, and should write those characters into string starting at index start. The read! procedure should return an exact integer object representing the number of characters that it has written. To indicate an end of file, the read! procedure should write no bytes and return 0.
(get-position)The get-position procedure (if supplied) should return a single
value. The return value should represent the current position of the
input port. If not supplied, the custom port will not support the
port-position operation.
(set-position! pos)The set-position! procedure (if supplied) should set the position
of the input port to pos if pos is the return value of a
call to get-position. If not supplied, the custom port will not
support the set-port-position! operation.
(close)The close procedure (if supplied) should perform any actions that are necessary when the input port is closed.
The port may or may not have an an associated transcoder; if it does, the transcoder is implementation–dependent.
Implementation responsibilities: The implementation must check the return values of read! and get-position only when it actually calls them as part of an I/O operation requested by the program. The implementation is not required to check that these procedures otherwise behave as described. If they do not, however, the behavior of the resulting port is unspecified.
Next: stdlib io port binary input, Previous: stdlib io port io ports, Up: stdlib io port [Index]