Re: guile.info: Reading

[Alex Schroeder]

Gary Houston <address@hidden> writes:

>>  - primitive: drain-input port
>>      Drain PORT's read buffers (including any pushed-back characters)
>>      and return the content as a single string.
>
> You are not the first.  Would the following description be any
> clearer?
>
> 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. 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.

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

guile> (call-with-input-file ".emacs" drain-input)
""

Alex.
-- 
http://www.geocities.com/kensanata/
Coffee should be black as hell, strong as death and sweet as love.
        -- Turkish proverb