#lang scribble/doc

@(require scribble/manual
          (for-label scheme
                     "main.ss"
                     net/head))

@title{The "mboxrd-read" Tool}

This is a library of one function (with two front doors) that parse mboxrd
files into lazy lists of messages.

@defmodule[(planet clements/mboxrd-read)]

@defproc[(mboxrd-parse [path path?])
         (lazy-listof (list/c bytes? (promise/c bytes?)))]{

Given a path to an mbox file, return a lazy list of the messages in the 
file.  Each file is represented as a list containing a byte-string
representing the header and the promise of a byte-string representing 
the body.  These byte-strings can be appended to obtain the original
message except that every \n in the original is replaced by \r\n to
match the RFC 2822 format.}

@defproc[(mboxrd-parse/port [port port?])
         (lazy-listof (list/c bytes? (promise/c bytes?)))]{
                                                           
Similar to @scheme[mboxrd-read], but operates on a port rather than on a path.
Note that this procedure assumes that it's the only one reading the port. Bad 
stuff will happen if its not; it doesn't leave the "From " of the next 
message on the stream. This procedure closes the port when peek-char returns eof.
}

Additionally, you can use the utilities (e.g. @scheme[extract-field]) in
"net/head.ss" to process the header.

Let me know of any bugs.