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) |3 |3 |0

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.