Re: guile.info: Reading

[Gary Houston]

> From: Alex Schroeder <address@hidden>
> Date: Tue, 25 Sep 2001 11:10:29 +0200

> Hm.  Maybe the problem is that I don't understand what an "input and
> push-back buffer".  Now that you've made the analogy to buffered
> output, it makes much more sense.  :)
> 
> Nevertheless, I suggest to add another sentence or two.
> 
> This procedure clears a port's input and push-back buffers, similar to
> the way that force-output clears the output buffer. The contents of
> the buffers are returned as a single string.  Note that the input
> buffer doesn't contain all the unread input -- it contains all the
> buffered input!  Draining the buffers may be useful, for example, for
> cleanly finishing buffered I/O so that the file descriptor can be used
> directly for further input.  Draining the input buffer of a file, for
> example, will not read until the end of the file.  It will only return
> whatever is buffered.
> 
> I am also a big fan of examples, but in this case I can only provide
> an example for the wrong use.  :)

Thanks, I've changed the docstring to:

 - primitive: drain-input port
     This procedure clears a port's internal 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.