GNU Info

(guile.info)Reading

---

Next: Writing Prev: Ports Up: Input and Output

---

Enter node , (file) or (file)node

Reading
=======

[Generic procedures for reading from ports.]

 - primitive: eof-object? x
     Returns `#t' if X is an end-of-file object; otherwise returns `#f'.

 - primitive: char-ready? [port]
     Returns `#t' if a character is ready on input PORT and returns
     `#f' otherwise.  If `char-ready?' returns `#t' then the next
     `read-char' operation on PORT is guaranteed not to hang.  If PORT
     is a file port at end of file then `char-ready?' returns `#t'.  (1)

 - primitive: read-char [port]
     Returns the next character available from PORT, updating PORT to
     point to the following character.  If no more characters are
     available, an end-of-file object is returned.

 - primitive: peek-char [port]
     Returns the next character available from PORT, _without_ updating
     PORT to point to the following character.  If no more characters
     are available, an end-of-file object is returned.(2)

 - primitive: unread-char cobj port
     Place 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.  If PORT is not
     supplied, the current input port is used.

 - primitive: unread-string str port
     Place the string STR in PORT so that its characters will be read
     in subsequent read operations.  If called multiple times, the
     unread characters will be read again in last-in first-out order.
     If PORT is not supplied, the current-input-port is used.

 - primitive: drain-input port
     Drains PORT's read buffers (including any pushed-back characters)
     and returns the contents as a single string.

 - primitive: port-column port
 - primitive: port-line [input-port]
     Return the current column number or line number of INPUT-PORT,
     using the current input port if none is specified.  If the number
     is unknown, the result is #f.  Otherwise, the result is a 0-origin
     integer - i.e. the first character of the first line is line 0,
     column 0.  (However, when you display a file position, for example
     in an error message, we recommand you add 1 to get 1-origin
     integers.  This is because lines and column numbers traditionally
     start with 1, and that is what non-programmers will find most
     natural.)

 - primitive: set-port-column! port column
 - primitive: set-port-line! port line
     Set the current column or line number of PORT, using the current
     input port if none is specified.

---------- Footnotes ----------

(1) `char-ready?' exists to make it possible for a program to accept
characters from interactive ports without getting stuck waiting for
input.  Any input editors associated with such ports must make sure
that characters whose existence has been asserted by `char-ready?'
cannot be rubbed out.  If `char-ready?' were to return `#f' at end of
file, a port at end of file would be indistinguishable from an
interactive port that has no ready characters.

(2) The value returned by a call to `peek-char' is the same as the
value that would have been returned by a call to `read-char' on the
same port.  The only difference is that the very next call to
`read-char' or `peek-char' on that PORT will return the value returned
by the preceding call to `peek-char'.  In particular, a call to
`peek-char' on an interactive port will hang waiting for input whenever
a call to `read-char' would have hung.