(guile.info.gz) Reading

 
 27.2 Reading
 ============
 
 [Generic procedures for reading from ports.]
 
  -- Scheme Procedure: eof-object? x
  -- C Function: scm_eof_object_p (x)
      Return `#t' if X is an end-of-file object; otherwise return `#f'.
 
  -- Scheme Procedure: char-ready? [port]
  -- C Function: scm_char_ready_p (port)
      Return `#t' if a character is ready on input PORT and return `#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)
 
  -- Scheme Procedure: read-char [port]
  -- C Function: scm_read_char (port)
      Return the next character available from PORT, updating PORT to
      point to the following character.  If no more characters are
      available, the end-of-file object is returned.
 
  -- Scheme Procedure: peek-char [port]
  -- C Function: scm_peek_char (port)
      Return the next character available from PORT, _without_ updating
      PORT to point to the following character.  If no more characters
      are available, the end-of-file object is returned.(2)
 
  -- Scheme Procedure: unread-char cobj [port]
  -- C Function: scm_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.
 
  -- Scheme Procedure: unread-string str port
  -- C Function: scm_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.
 
  -- Scheme Procedure: drain-input port
  -- C Function: scm_drain_input (port)
      This procedure clears a port's input buffers, similar to the way
      that force-output clears the output buffer.  The contents of the
      buffers are returned as a single string, e.g.,
 
           (define p (open-input-file ...))
           (drain-input p) => empty string, nothing buffered yet.
           (unread-char (read-char p) p)
           (drain-input p) => initial chars from p, up to the buffer size.
 
      Draining the buffers may be useful for cleanly finishing buffered
      I/O so that the file descriptor can be used directly for further
      input.
 
  -- Scheme Procedure: port-column port
  -- Scheme Procedure: port-line port
  -- C Function: scm_port_column (port)
  -- C Function: scm_port_line (port)
      Return the current column number or line number of 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 recommend 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.)
 
  -- Scheme Procedure: set-port-column! port column
  -- Scheme Procedure: set-port-line! port line
  -- C Function: scm_set_port_column_x (port, column)
  -- C Function: scm_set_port_line_x (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.
Info Catalog
(guile.info.gz) Ports
(guile.info.gz) Input and Output
(guile.info.gz) Writing
automatically generated byinfo2html