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 Reading Scheme Code. See Writing Scheme Values, 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.
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.
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.
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.
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.
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.
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.
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.
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.
Writes char to the port. The put-char procedure returns
an unspecified value.
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.
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 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.