Ports - MIT/GNU Scheme 9.2
Description: MIT/GNU Scheme 9.2

Next: File Ports, Previous: Input/Output, Up: Input/Output

### 14.1 Ports

Scheme uses ports for I/O. A port, which can be treated like any other Scheme object, serves as a source or sink for data. A port must be open before it can be read from or written to. The standard I/O port, `console-i/o-port`, is opened automatically when you start Scheme. When you use a file for input or output, you need to explicitly open and close a port to the file (with procedures described in this chapter). Additional procedures let you open ports to strings.

Many input procedures, such as `read-char` and `read`, read data from the current input port by default, or from a port that you specify. The current input port is initially `console-i/o-port`, but Scheme provides procedures that let you change the current input port to be a file or string.

Similarly, many output procedures, such as `write-char` and `display`, write data to the current output port by default, or to a port that you specify. The current output port is initially `console-i/o-port`, but Scheme provides procedures that let you change the current output port to be a file or string.

Nearly all ports read or write Unicode characters; the exceptions are those for which non-Unicode character coding has been specified.

Every port is either an input port, an output port, or both. The following predicates distinguish all of the possible cases.

— procedure: port? object

> Returns `#t` if object is a port, otherwise returns `#f`.

— procedure: input-port? object

> Returns `#t` if object is an input port, otherwise returns `#f`. Any object satisfying this predicate also satisfies `port?`.

— procedure: output-port? object

> Returns `#t` if object is an output port, otherwise returns `#f`. Any object satisfying this predicate also satisfies `port?`.

— procedure: i/o-port? object

> Returns `#t` if object is both an input port and an output port, otherwise returns `#f`. Any object satisfying this predicate also satisfies `port?`, `input-port?`, and `output-port?`.

— procedure: guarantee-port object
— procedure: guarantee-input-port object
— procedure: guarantee-output-port object
— procedure: guarantee-i/o-port object

> These procedures check the type of object, signalling an error of type
> `condition-type:wrong-type-argument` if it is not a port, input port, output port, or I/O port, respectively. Otherwise they return object.

The next five procedures return the runtime system's standard ports. All of the standard ports are dynamically bound by the REP loop; this means that when a new REP loop is started, for example by an error, each of these ports is dynamically bound to the I/O port of the REP loop. When the REP loop exits, the ports revert to their original values.

— procedure: current-input-port

> Returns the current input port. This is the default port used by many input procedures. Initially, `current-input-port` returns the value of `console-i/o-port`.

— procedure: current-output-port

> Returns the current output port. This is the default port used by many output procedures. Initially, `current-output-port` returns the value of `console-i/o-port`.

— procedure: notification-output-port

> Returns an output port suitable for generating “notifications”, that is, messages to the user that supply interesting information about the execution of a program. For example, the `load` procedure writes messages to this port informing the user that a file is being loaded. Initially, `notification-output-port` returns the value of `console-i/o-port`.

— procedure: trace-output-port

> Returns an output port suitable for generating “tracing” information about a program's execution. The output generated by the `trace` procedure is sent to this port. Initially, `trace-output-port` returns the value of `console-i/o-port`.

— procedure: interaction-i/o-port

> Returns an I/O port suitable for querying or prompting the user. The standard prompting procedures use this port by default (see Prompting). Initially, `interaction-i/o-port` returns the value of `console-i/o-port`.

— procedure: with-input-from-port input-port thunk
— procedure: with-output-to-port output-port thunk
— procedure: with-notification-output-port output-port thunk
— procedure: with-trace-output-port output-port thunk
— procedure: with-interaction-i/o-port i/o-port thunk

> Thunk must be a procedure of no arguments. Each of these procedures binds one of the standard ports to its first argument, calls thunk with no arguments, restores the port to its original value, and returns the result that was yielded by thunk. This temporary binding is performed the same way as dynamic binding of a variable, including the behavior in the presence of continuations (see Dynamic Binding).

> `with-input-from-port` binds the current input port, `with-output-to-port` binds the current output port, `with-notification-output-port` binds the “notification” output port, `with-trace-output-port` binds the “trace” output port, and `with-interaction-i/o-port` binds the “interaction” I/O port.

— procedure: set-current-input-port! input-port
— procedure: set-current-output-port! output-port
— procedure: set-notification-output-port! output-port
— procedure: set-trace-output-port! output-port
— procedure: set-interaction-i/o-port! i/o-port

> Each of these procedures alters the binding of one of the standard ports and returns an unspecified value. The binding that is modified corresponds to the name of the procedure.

— variable: console-i/o-port

> `console-i/o-port` is an I/O port that communicates with the “console”. Under unix, the console is the controlling terminal of the Scheme process. Under Windows, the console is the window that is created when Scheme starts up.

> This variable is rarely used; instead programs should use one of the standard ports defined above. This variable should not be modified.

— procedure: close-port port

> Closes port and returns an unspecified value. If port is a file port, the file is closed.

— procedure: close-input-port port

> Closes port and returns an unspecified value. Port must be an input port or an I/O port; if it is an I/O port, then only the input side of the port is closed.

— procedure: close-output-port port

> Closes port and returns an unspecified value. Port must be an output port or an I/O port; if it is an I/O port, then only the output side of the port is closed.