GNU Info

(guile.info)Line/Delimited

---

Next: Port Environment Prev: Random Access Up: Input and Output

---

Enter node , (file) or (file)node

Handling Line Oriented and Delimited Text
=========================================

[Line-oriented and delimited IO.  Or should this be merged into the
previous two sections?]

Extended I/O procedures are available which read or write lines of text
or read text delimited by a specified set of characters.

Interfaces to `read'/`fread' and `write'/`fwrite' are also available,
as `uniform-array-read!' and `uniform-array-write!', Note: Uniform
Arrays.

 - 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.

          NOTE: if the scsh module is loaded then multiple values are
          returned instead of a pair.

 - 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)'.

 - procedure: read-delimited 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'.

     NOTE: if the scsh module is loaded then DELIMS must be an scsh
     char-set, not a string.

 - 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)'.

     NOTE: if the scsh module is loaded then DELIMS must be an scsh
     char-set, not a string.

 - primitive: write-line obj [port]
     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.

 - primitive: %read-delimited! 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.

 - primitive: %read-line [port]
     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>)'.