Introduction

FormMail is an HTML form to email gateway that receives the results of an HTML form and sends them to the specified email recipients.

The formular library contains a collection of routines for parsing emails generated by FormMail. The emails can be read either from an SRFI-40 stream, or from a text file in Unix mbox format.

There are two programs included with the library, form2wiki and form2txt. These programs read messages generated by FormMail from a Unix mbox file, and generate a representation of the form data in wiki format or text format.

This egg includes a copy of NMS FormMail Version 3.14c1 that has been modified to 1) include the submitted fields in the confirmation email; 2) use quotation marks to enclose field text that contains newline characters; 3) escape the submitted text in the notification email.

Requires

rfc822
stream-ext
stream-sections
rb-tree
ssax-core
fmt
uri
utf8
args

Library procedures

read-form:: ENVELOPE * STRM -> FORM

Given SRFI-40 streams that contain an RFC 822 envelope and message, this procedure parses the headers and fields that are found in the message stream, and returns an s-expression of the form:

(form (envelope <envelope-string>) 
      (headers <RFC 822 header alist>) 
      (fields <field alist>))

mbox->form-stream:: FNAME -> FORM-STREAM

Given the name of a Unix mbox file, this procedure reads the file and returns an SRFI-40 stream representation of its contents, where each element in the stream is a form s-expression in the format created by the read-form procedure.

form-stream->tree:: STRM -> TREE

Given an SRFI-40 stream created by the mbox->form-stream procedure, this procedure returns an ordered dictionary structure, where the key is the email address of the form sender, and the value is the list of all forms submitted by that sender. The API of the tree object follows that of the e.g. treap and rb-tree libraries.

Usage of form2wiki and form2txt

form2wiki [options...]  

The following options are recognized:

--exclude=FROM1
FROM2:... : specify a colon-separated list of entries to exclude (default is none )
--include=FROM1
FROM2:... : specify a colon-separated list of entries to include (default is all )
--after-date=N
omit entries with date before N (given in seconds)
--flimits=FIELD1
LIMIT1,... : specify a comma-separated list of fields and character limits (default is none )
--fields=FIELD1
FIELD2:... : specify a colon-separated list of fields to process (default is all fields )
--mbox-path=PATH
specify path to input mbox (default: mbox)
--order=N
specify order of form id (default: 3)
--prefix=STRING
specify prefix for wiki page title (default: Form Submission)
--read-alist=FILE
read an alist representation from FILE (mbox-path is ignored)
-h, --help
Print help
form2txt [options...] operands 

The following options are recognized:

--exclude=FROM1
FROM2 : specify a colon-separated list of entries to exclude (default is none )
--after-date=N
omit entries with date before N (given in seconds)
--fields=FIELD1
FIELD : specify a colon-separated list of fields to process (default is all fields )
--mbox-path=PATH
specify path to input mbox (default: mbox)
--order=N
specify order of form id (default: 3)
--prefix=STRING
specify prefix for text page title (default: Form Submission)
--write-alist=FILE
write an alist representation to FILE
--read-alist=FILE
read an alist representation from FILE (mbox-path is ignored)
-h, --help
Print help

Authors

Ivan Raikov

Version

1.12
Option after-date added to form2txt
1.11
Option skip in form2wiki replaced by after-date
1.10
Added options skip and read-alist to form2wiki
1.9
Bug fix in form2wiki
1.8
Added handling of malformed fields
1.7
Bug fix in the setup script
1.6
Added support for reading from and writing to s-expression alists
1.5
Bug fixes due to changes in the results returned by rfc822-field->tokens
1.4
Added missing dependencies to meta file
1.1
Added the documentation file to the egg
1.0
Initial version

License

Copyright 2008-2009 Ivan Raikov and the Okinawa Institute of Science and Technology.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A full copy of the GPL license can be found at <http://www.gnu.org/licenses/>.