7.6.2.16 rnrs io ports

Guile’s binary and textual port interface was heavily inspired by R6RS, so many R6RS port interfaces are documented elsewhere. Note that R6RS ports are not disjoint from Guile’s native ports, so Guile-specific procedures will work on ports created using the R6RS API, and vice versa. Also note that in Guile, all ports are both textual and binary. See Input and Output, for more on Guile’s core port API. The R6RS ports module wraps Guile’s I/O routines in a helper that will translate native Guile exceptions to R6RS conditions; See I/O Conditions, for more. See R6RS File Ports, for documentation on the R6RS file port interface.

Note: The implementation of this R6RS API is not complete yet.

Scheme Procedure: eof-object? obj

See Binary I/O, for documentation.

Scheme Procedure: eof-object

Return the end-of-file (EOF) object.

(eof-object? (eof-object))
⇒ #t
Scheme Procedure: port? obj
Scheme Procedure: input-port? obj
Scheme Procedure: output-port? obj
Scheme Procedure: call-with-port port proc

See Ports, for documentation.

Scheme Procedure: port-transcoder port

Return a transcoder associated with the encoding of port. See Encoding, and See Transcoders.

Scheme Procedure: binary-port? port

Return #t if port appears to be a binary port, else return #f. Note that Guile does not currently distinguish between binary and textual ports, so this predicate is not a reliable indicator of whether the port was created as a binary port. Currently, it returns #t if and only if the port encoding is “ISO-8859-1”, because Guile uses this encoding when creating a binary port. See Encoding, for more details.

Scheme Procedure: textual-port? port

Return #t if port appears to be a textual port, else return #f. Note that Guile does not currently distinguish between binary and textual ports, so this predicate is not a reliable indicator of whether the port was created as a textual port. Currently, it always returns #t, because all ports can be used for textual I/O in Guile. See Encoding, for more details.

Scheme Procedure: transcoded-port binary-port transcoder

The transcoded-port procedure returns a new textual port with the specified transcoder. Otherwise the new textual port’s state is largely the same as that of binary-port. If binary-port is an input port, the new textual port will be an input port and will transcode the bytes that have not yet been read from binary-port. If binary-port is an output port, the new textual port will be an output port and will transcode output characters into bytes that are written to the byte sink represented by binary-port.

As a side effect, however, transcoded-port closes binary-port in a special way that allows the new textual port to continue to use the byte source or sink represented by binary-port, even though binary-port itself is closed and cannot be used by the input and output operations described in this chapter.

Scheme Procedure: port-position port

Equivalent to (seek port 0 SEEK_CUR). See Random Access.

Scheme Procedure: port-has-port-position? port

Return #t is port supports port-position.

Scheme Procedure: set-port-position! port offset

Equivalent to (seek port offset SEEK_SET). See Random Access.

Scheme Procedure: port-has-set-port-position!? port

Return #t is port supports set-port-position!.

Scheme Procedure: port-eof? input-port

Equivalent to (eof-object? (lookahead-u8 input-port)).

Scheme Procedure: standard-input-port
Scheme Procedure: standard-output-port
Scheme Procedure: standard-error-port

Returns a fresh binary input port connected to standard input, or a binary output port connected to the standard output or standard error, respectively. Whether the port supports the port-position and set-port-position! operations is implementation-dependent.

Scheme Procedure: current-input-port
Scheme Procedure: current-output-port
Scheme Procedure: current-error-port

See Default Ports for Input, Output and Errors.

Scheme Procedure: open-bytevector-input-port bv [transcoder]
Scheme Procedure: open-bytevector-output-port [transcoder]

See Bytevector Ports.

Scheme Procedure: make-custom-binary-input-port id read! get-position set-position! close
Scheme Procedure: make-custom-binary-output-port id write! get-position set-position! close
Scheme Procedure: make-custom-binary-input/output-port id read! write! get-position set-position! close

See Custom Ports.

Scheme Procedure: make-custom-textual-input-port id read! get-position set-position! close
Scheme Procedure: make-custom-textual-output-port id write! get-position set-position! close
Scheme Procedure: make-custom-textual-input/output-port id read! write! get-position set-position! close

See Custom Ports.

Scheme Procedure: get-u8 port
Scheme Procedure: lookahead-u8 port
Scheme Procedure: get-bytevector-n port count
Scheme Procedure: get-bytevector-n! port bv start count
Scheme Procedure: get-bytevector-some port
Scheme Procedure: get-bytevector-all port
Scheme Procedure: put-u8 port octet
Scheme Procedure: put-bytevector port bv [start [count]]

See Binary I/O.

Scheme Procedure: get-char textual-input-port
Scheme Procedure: lookahead-char textual-input-port
Scheme Procedure: get-string-n textual-input-port count
Scheme Procedure: get-string-n! textual-input-port string start count
Scheme Procedure: get-string-all textual-input-port
Scheme Procedure: get-line textual-input-port
Scheme Procedure: put-char port char
Scheme Procedure: put-string port string [start [count]]

See Textual I/O.

Scheme Procedure: get-datum textual-input-port count

Reads an external representation from textual-input-port and returns the datum it represents. The get-datum procedure returns the next datum that can be parsed from the given textual-input-port, updating textual-input-port to point exactly past the end of the external representation of the object.

Any interlexeme space (comment or whitespace, see Scheme Syntax: Standard and Guile Extensions) in the input is first skipped. If an end of file occurs after the interlexeme space, the end-of-file object is returned.

If a character inconsistent with an external representation is encountered in the input, an exception with condition types &lexical and &i/o-read is raised. Also, if the end of file is encountered after the beginning of an external representation, but the external representation is incomplete and therefore cannot be parsed, an exception with condition types &lexical and &i/o-read is raised.

Scheme Procedure: put-datum textual-output-port datum

datum should be a datum value. The put-datum procedure writes an external representation of datum to textual-output-port. The specific external representation is implementation-dependent. However, whenever possible, an implementation should produce a representation for which get-datum, when reading the representation, will return an object equal (in the sense of equal?) to datum.

Note: Not all datums may allow producing an external representation for which get-datum will produce an object that is equal to the original. Specifically, NaNs contained in datum may make this impossible.

Note: The put-datum procedure merely writes the external representation, but no trailing delimiter. If put-datum is used to write several subsequent external representations to an output port, care should be taken to delimit them properly so they can be read back in by subsequent calls to get-datum.

Scheme Procedure: flush-output-port port

See Buffering, for documentation on force-output.