Node:Line/Delimited, 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.

read-line [port] [handle-delim] Scheme Procedure
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.

read-line! buf [port] Scheme Procedure
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).

read-delimited delims [port] [handle-delim] Scheme Procedure
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.

read-delimited! delims buf [port] [handle-delim] [start] [end] Scheme Procedure
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).

write-line obj [port] Scheme Procedure
scm_write_line (obj, port) C Function
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.

%read-delimited! delims str gobble [port [start [end]]] Scheme Procedure
scm_read_delimited_x (delims, str, gobble, port, start, end) C Function
Read characters from port into str until one of the characters in the delims string is encountered. If gobble is true, discard the delimiter character; otherwise, leave it in the input stream for the next read. 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 str bounded by start and end (which default to the beginning and end of the string, 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 string was filled without encountering a delimiter, this value is #f.

%read-line [port] Scheme Procedure
scm_read_line (port) C Function
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>).