Ports represent input and output devices. To Scheme, an input port is a Scheme object that can deliver data upon command, while an output port is a Scheme object that can accept data. Whether the input and output port types are disjoint is implementation-dependent.
Different port types operate on different data. Scheme implementations are required to support textual ports and binary ports, but may also provide other port types.
A textual port supports reading or writing of individual characters from
or to a backing store containing characters using read-char and
write-char below, and it supports operations defined in terms of
characters, such as read and write.
A binary port supports reading or writing of individual bytes from or to
a backing store containing bytes using read-u8 and write-u8
below, as well as operations defined in terms of bytes. Whether the
textual and binary port types are disjoint is implementation-dependent.
Ports can be used to access files, devices, and similar things on the host system on which the Scheme program is running.
(call-with-port port proc) ¶It is an error if proc does not accept one argument.
The call-with-port procedure calls proc with port as an
argument. If proc returns, then the port is closed automatically
and the values yielded by the proc are returned. If proc
does not return, then the port must not be closed automatically unless
it is possible to prove that the port will never again be used for a
read or write operation.
Rationale: Because Scheme’s escape procedures have unlimited extent, it is possible to escape from the current continuation but later to resume it. If implementations were permitted to close the port on any escape from the current continuation, then it would be impossible to write portable code using both
call-with-current-continuationandcall-with-port.
(call-with-input-file string proc) ¶(call-with-output-file string proc) ¶It is an error if proc does not accept one argument.
These procedures obtain a textual port obtained by opening the named
file for input or output as if by open-input-file or
open-output-file. The port and proc are then passed to a
procedure equivalent to call-with-port.
(input-port? obj) ¶(output-port? obj) ¶(textual-port? obj) ¶(binary-port? obj) ¶(port? obj) ¶These procedures return #t if obj is an input port, output
port, textual port, binary port, or any kind of port, respectively.
Otherwise they return #f.
(input-port-open? port) ¶(output-port-open? port) ¶Returns #t if port is still open and capable of performing
input or output, respectively, and #f otherwise.
(current-input-port) ¶(current-output-port) ¶(current-error-port) ¶Returns the current default input port, output port, or error port (an output port), respectively. These procedures are parameter objects, which can be overridden with parameterize (see Dynamic bindings). The initial bindings for these are implementation-defined textual ports.
(with-input-from-file string thunk) ¶(with-output-to-file string thunk) ¶The file is opened for input or output as if by open-input-file or
open-output-file, and the new port is made to be the value returned
by current-input-port or current-output-port (as used by
(read), (write obj), and so forth). The thunk is
then called with no arguments. When the thunk returns, the port
is closed and the previous default is restored. It is an error if
thunk does not accept zero arguments. Both procedures return the
values yielded by thunk. If an escape procedure is used to escape
from the continuation of these procedures, they behave exactly as if the
current input or output port had been bound dynamically with
parameterize.
(open-input-file string) ¶(open-binary-input-file string) ¶Takes a string for an existing file and returns a textual input
port or binary input port that is capable of delivering data from the
file. If the file does not exist or cannot be opened, an error that
satisfies file-error? is signaled.
(open-output-file string) ¶(open-binary-output-file string) ¶Takes a string naming an output file to be created and returns a
textual output port or binary output port that is capable of writing
data to a new file by that name. If a file with the given name already
exists, the effect is unspecified. If the file cannot be opened, an
error that satisfies file-error? is signaled.
(close-port port) ¶(close-input-port port) ¶(close-output-port port) ¶Closes the resource associated with port, rendering the port
incapable of delivering or accepting data. It is an error to apply the
last two procedures to a port which is not an input or output port,
respectively. Scheme implementations may provide ports which are
simultaneously input and output ports, such as sockets; the
close-input-port and close-output-port procedures can then be
used to close the input and output sides of the port independently.
These routines have no effect if the port has already been closed.
(open-input-string string) ¶Takes a string and returns a textual input port that delivers characters from the string. If the string is modified, the effect is unspecified.
(open-output-string) ¶Returns a textual output port that will accumulate characters for
retrieval by get-output-string.
(get-output-string port) ¶It is an error if port was not created with
open-output-string.
Returns a string consisting of the characters that have been output to the port so far in the order they were output. If the result string is modified, the effect is unspecified.
(parameterize ((current-output-port (open-output-string))) (display "piece") (display " by piece ") (display "by piece.") (newline) (get-output-string (current-output-port))) ⇒ "piece by piece by piece.\n"
(open-input-bytevector bytevector) ¶Takes a bytevector and returns a binary input port that delivers bytes from the bytevector.
(open-output-bytevector) ¶Returns a binary output port that will accumulate bytes for retrieval by
get-output-bytevector.
(get-output-bytevector port) ¶It is an error if port was not created with
open-output-bytevector.
Returns a bytevector consisting of the bytes that have been output to the port so far in the order they were output.