Port Library

_Port_ Library
==============

Time-stamp: <2008-03-18 10:45:45 noel>

Keywords: _port_, _read_, _io_, _i/o_


Introduction
============

This library provides some useful functions on ports, based
on those provided by Scsh.


Basic Types
===========

> reader : input-port -> any

A reader reads data from a port, returning any type of data,
with the restriction that it returns the eof-object when the
end of data has been reached (which is usually when the
underlying port returns the eof-object but may be before
hand).  All the standard read functions (read, read-line,
etc.) are valid readers.


Functions
=========

To use these definitions:

   (require (planet "port.ss" ("schematics" "port.plt" 1)))

> (port->list reader [input-port])

Applys reader to the port, accumulating results in a list.
If no input-port is given the value of current-input-port is
used.

> (port->bytes [input-port])

Returns a bytes string containing all bytes read from the
port.  Reading stops when the port returns the eof-object.
If no input-port is given the value of current-input-port is
used.

> (port->string [input-port])

Returns a string containing all characters read from the
port.  Reading stops when the port returns the eof-object.
Data is converted from bytes using the UTF-8 conversion.
I.e. this function is equivalent to

  (bytes->string/utf-8 (read-bytes port))

If no input-port is given the value of current-input-port is
used.

> (port->string-list [input-port])

Returns a list of all lines from the port (as returned by
read-line).  Reading stops when the port returns the
eof-object.  If no input-port is given the value of
current-input-port is used.

> (post->sexp-list [input-port])

Returns a list of all data read from the port (using the
read function).  Reading stops when the port returns the
eof-object.  If no input-port is given the value of
current-input-port is used.

> (port-fold port reader op . seeds)

To quote the Scsh manual: "This procedure can be used to
perform a variety of iterative operations over an input
stream. It repeatedly uses reader to read an object from
port. If the first read returns eof, then the entire
port-fold operation returns the seeds as multiple values. If
the first read operation returns some other value v, then op
is applied to v and the seeds: (op v . seeds). This should
return a new set of seed values, and the reduction then
loops, reading a new value from the port, and so forth. (If
multiple seed values are used, then op must return multiple
values.)"


Credits
=======

Jacob Matthews provided the fast implementation of
port->string that uses copy-port