6.14.4 Textual I/O

This section describes Guile’s core textual I/O operations on characters and strings. See Binary I/O, for input and output of bytes and bytevectors. See Encoding, for more on how characters relate to bytes. To read general S-expressions from ports, See Scheme Read. See Scheme Write, for interfaces that write generic Scheme datums.

To use these routines, first include the textual I/O module:

(use-modules (ice-9 textual-ports))

Note that although this module’s name suggests that textual ports are some different kind of port, that’s not the case: all ports in Guile are both binary and textual ports.

Scheme Procedure: get-char input-port

Reads from input-port, blocking as necessary, until a complete character is available from input-port, or until an end of file is reached.

If a complete character is available before the next end of file, get-char returns that character and updates the input port to point past the character. If an end of file is reached before any character is read, get-char returns the end-of-file object.

Scheme Procedure: lookahead-char input-port

The lookahead-char procedure is like get-char, but it does not update input-port to point past the character.

In the same way that it’s possible to "unget" a byte or bytes, it’s possible to "unget" the bytes corresponding to an encoded character.

Scheme Procedure: unget-char port char

Place character char in port so that it will be read by the next read operation. If called multiple times, the unread characters will be read again in last-in first-out order.

Scheme Procedure: unget-string port str

Place the string str in port so that its characters will be read from left-to-right as the next characters from port during subsequent read operations. If called multiple times, the unread characters will be read again in last-in first-out order.

Reading in a character at a time can be inefficient. If it’s possible to perform I/O over multiple characters at a time, via strings, that might be faster.

Scheme Procedure: get-string-n input-port count

The get-string-n procedure reads from input-port, blocking as necessary, until count characters are available, or until an end of file is reached. count must be an exact, non-negative integer, representing the number of characters to be read.

If count characters are available before end of file, get-string-n returns a string consisting of those count characters. If fewer characters are available before an end of file, but one or more characters can be read, get-string-n returns a string containing those characters. In either case, the input port is updated to point just past the characters read. If no characters can be read before an end of file, the end-of-file object is returned.

Scheme Procedure: get-string-n! input-port string start count

The get-string-n! procedure reads from input-port in the same manner as get-string-n. start and count must be exact, non-negative integer objects, with count representing the number of characters to be read. string must be a string with at least $start + count$ characters.

If count characters are available before an end of file, they are written into string starting at index start, and count is returned. If fewer characters are available before an end of file, but one or more can be read, those characters are written into string starting at index start and the number of characters actually read is returned as an exact integer object. If no characters can be read before an end of file, the end-of-file object is returned.

Scheme Procedure: get-string-all input-port

Reads from input-port until an end of file, decoding characters in the same manner as get-string-n and get-string-n!.

If characters are available before the end of file, a string containing all the characters decoded from that data are returned. If no character precedes the end of file, the end-of-file object is returned.

Scheme Procedure: get-line input-port

Reads from input-port up to and including the linefeed character or end of file, decoding characters in the same manner as get-string-n and get-string-n!.

If a linefeed character is read, a string containing all of the text up to (but not including) the linefeed character is returned, and the port is updated to point just past the linefeed character. If an end of file is encountered before any linefeed character is read, but some characters have been read and decoded as characters, a string containing those characters is returned. If an end of file is encountered before any characters are read, the end-of-file object is returned.

Finally, there are just two core procedures to write characters to a port.

Scheme Procedure: put-char port char

Writes char to the port. The put-char procedure returns an unspecified value.

Scheme Procedure: put-string port string

Scheme Procedure: put-string port string start

Scheme Procedure: put-string port string start count

Write the count characters of string starting at index start to the port.

start and count must be non-negative exact integer objects. string must have a length of at least start + count. start defaults to 0. count defaults to (string-length string) - start$.

Calling put-string is equivalent in all respects to calling put-char on the relevant sequence of characters, except that it will attempt to write multiple characters to the port at a time, even if the port is unbuffered.

The put-string procedure returns an unspecified value.

Textual ports have a textual position associated with them: a line and a column. Reading in characters or writing them out advances the line and the column appropriately.

Scheme Procedure: port-column port

Scheme Procedure: port-line port

C Function: scm_port_column (port)

C Function: scm_port_line (port)

Return the current column number or line number of port.

Port lines and positions are represented as 0-origin integers, which is to say that the the first character of the first line is line 0, column 0. However, when you display a line number, for example in an error message, we recommend you add 1 to get 1-origin integers. This is because lines numbers traditionally start with 1, and that is what non-programmers will find most natural.

Scheme Procedure: set-port-column! port column

Scheme Procedure: set-port-line! port line

C Function: scm_set_port_column_x (port, column)

C Function: scm_set_port_line_x (port, line)

Set the current column or line number of port.