Next: , Previous: Random Access, Up: Input and Output

27.6 Line Oriented and Delimited Text

The delimited-I/O module can be accessed with: 

     (use-modules (ice-9 rdelim))

It can be used to read or write lines of text, or read text delimited by a specified set of characters. It's similar to the (scsh rdelim) module from guile-scsh, but does not use multiple values or character sets and has an extra procedure write-line.

— Scheme Procedure: read-line [port [handle-delim]]

Return a line of text from port if specified, otherwise from the value returned by (current-input-port). Under Unix, a line of text is terminated by the first end-of-line character or by end-of-file.

If handle-delim is specified, it should be one of the following symbols:

trim
Discard the terminating delimiter. This is the default, but it will be impossible to tell whether the read terminated with a delimiter or end-of-file.
concat
Append the terminating delimiter (if any) to the returned string.
peek
Push the terminating delimiter (if any) back on to the port.
split
Return a pair containing the string read from the port and the terminating delimiter or end-of-file object.

— Scheme Procedure: read-line! buf [port]

Read a line of text into the supplied string buf and return the number of characters added to buf. If buf is filled, then #f is returned. Read from port if specified, otherwise from the value returned by (current-input-port).

— Scheme Procedure: read-delimited delims [port [handle-delim]]
— Scheme Procedure: delims delims [port [handle-delim]]

Read text until one of the characters in the string delims is found or end-of-file is reached. Read from port if supplied, otherwise from the value returned by (current-input-port). handle-delim takes the same values as described for read-line.

— Scheme Procedure: read-delimited! delims buf [port [handle-delim [start [end]]]]

Read text into the supplied string buf and return the number of characters added to buf (subject to handle-delim, which takes the same values specified for read-line. If buf is filled, #f is returned for both the number of characters read and the delimiter. Also terminates if one of the characters in the string delims is found or end-of-file is reached. Read from port if supplied, otherwise from the value returned by (current-input-port).

— Scheme Procedure: write-line obj [port]
— C Function: scm_write_line (obj, port) |1 |1 |0

Display obj and a newline character to port. If port is not specified, (current-output-port) is used. This function is equivalent to: 

          (display obj [port])
          (newline [port])

Some of the abovementioned I/O functions rely on the following C primitives. These will mainly be of interest to people hacking Guile internals.

— Scheme Procedure: %read-delimited! delims buf gobble? port start end
— C Function: scm_read_delimited_x (delims, buf, gobble?, port, start, end)

Read characters from port into buf until one of the characters in the delims string is encountered. If gobble? is true, store the delimiter character in buf as well; otherwise, discard it. If port is not specified, use the value of (current-input-port). If start or end are specified, store data only into the substring of buf bounded by start and end (which default to the beginning and end of the buffer, respectively).

Return a pair consisting of the delimiter that terminated the string and the number of characters read. If reading stopped at the end of file, the delimiter returned is the eof-object; if the buffer was filled without encountering a delimiter, this value is #f.

— Scheme Procedure: %read-line [port]
— C Function: scm_read_line (port) |0 |1 |0

Read a newline-terminated line from port, allocating storage as necessary. The newline terminator (if any) is removed from the string, and a pair consisting of the line and its delimiter is returned. The delimiter may be either a newline or the eof-object; if %read-line is called at the end of file, it returns the pair (#<eof> . #<eof>).

27.7 Buffered Variant

You can use a buffered variant of read-line by evaluating: 

     (use-modules (ice-9 lineio))

This module provides a procedure to create a line-buffering input port, a related predicate, and two procedures to read a line from the port or push a line back onto the stream.

Note: The implementation of unread-string is kind of limited; it doesn't interact properly with unread-char, or any of the other port reading functions. Only read-string will get you back the things that unread-string accepts.

Normally a "line" is all characters up to and including a newline. If lines are put back using unread-string, they can be broken arbitrarily – that is, read-string returns strings passed to unread-string (or shared substrings of them).

— Scheme Procedure: lineio-port? port

Return #t iff port is a port capable of handling read-string and unread-string.

— Scheme Procedure: make-line-buffering-input-port underlying-port

Return a wrapper port for underlying-port.

The wrapper port buffers characters read from underlying-port internally, and parcels them out via calls to read-char, read-string and unread-string.

— Scheme Procedure: read-string line-buffering-input-port

Read a line from line-buffering-input-port. Return it as a string, ending with newline.

— Scheme Procedure: unread-string str line-buffering-input-port

Return string str to line-buffering-input-port. A subsequent call to read-string or read-char from this port will retrieve this string or its first character, respectively, before consulting the underlying port.