#lang scribble/doc
@(require "base.ss")

@title{@bold{Port}: useful functions for operating on ports}

by  Noel Welsh  (@tt{noelwelsh at GMail})

The Port library contains useful functions for operating on
ports, based on those provided by Scsh.



@section{API}

@defmodule[(planet schematics/port:1)]{

@defproc[(port->list [reader (-> input-port? any)]
                     [port input-port? (current-input-port)])
         (listof any)]{

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

@defproc[(port->bytes [port input-port? (current-input-port)]) bytes?]{

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 @scheme[current-input-port] is
used.}

@defproc[(port->string [port input-port? (current-input-port)]) string?]{

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

@schemeblock[(bytes->string/utf-8 (read-bytes port))]

If no input-port is given the value of @scheme[current-input-port] is
used.
}

@defproc[(port->string-list [port input-port? (current-input-port)]) (listof string?)]{

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

@defproc[(post->sexp-list [port input-port? (current-input-port)]) (listof any)]{

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

@defproc[(port-fold [port input-port?]
                    [reader (->* (input-port?) ('a 'b ...))]
                    [op (->* ('a 'b ...) (b' ...))]
                    [seed 'b] ...)
         (values 'b ...)]{

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.)"}

}