source: project/wiki/formular @ 13347

Last change on this file since 13347 was 13347, checked in by Ivan Raikov, 11 years ago

Updated doc for version 1.10

File size: 5.1 KB
Line 
1[[tags: egg]]
2
3== Introduction
4
5[[http://www.scriptarchive.com/formmail.html|FormMail]] is an HTML
6form to email gateway that receives the results of an HTML form and
7sends them to the specified email recipients.
8
9The {{formular}} library contains a collection of routines for parsing
10emails generated by FormMail. The emails can be read either from an
11SRFI-40 stream, or from a text file in Unix mbox format.
12
13There are two programs included with the library, {{form2wiki}} and
14{{form2txt}}. These programs read messages generated by FormMail from
15a Unix mbox file, and generate a representation of the form data in
16wiki format or text format.
17
18This egg includes a copy of NMS FormMail Version 3.14c1 that has been
19modified to 1) include the submitted fields in the confirmation email;
202) use quotation marks to enclose field text that contains newline
21characters; 3) escape the submitted text in the notification email.
22
23== Requires
24
25; [[rfc822]]
26; [[stream-ext]]
27; [[stream-sections]]
28; [[rb-tree]]
29; [[ssax-core]]
30; [[fmt]]
31; [[uri]]
32; [[utf8]]
33; [[args]]
34
35
36== Library procedures
37
38=== {{read-form:: ENVELOPE * STRM -> FORM}}
39
40Given SRFI-40 streams that contain an RFC 822 envelope and message,
41this procedure parses the headers and fields that are found in the
42message stream, and returns an s-expression of the form:
43
44 (form (envelope <envelope-string>)
45       (headers <RFC 822 header alist>)
46       (fields <field alist>))
47
48=== {{mbox->form-stream:: FNAME -> FORM-STREAM}}
49
50Given the name of a Unix mbox file, this procedure reads the file and
51returns an SRFI-40 stream representation of its contents, where each
52element in the stream is a form s-expression in the format created by
53the {{read-form}} procedure.
54
55=== {{form-stream->tree:: STRM -> TREE}}
56
57Given an SRFI-40 stream created by the {{mbox->form-stream}}
58procedure, this procedure returns an ordered dictionary structure,
59where the key is the email address of the form sender, and the value
60is the list of all forms submitted by that sender. The API of the tree
61object follows that of the e.g. [[treap]] and [[rb-tree]] libraries.
62
63
64== Usage of form2wiki and form2txt
65
66
67 form2wiki [options...] 
68
69The following options are recognized:
70
71;  <nowiki>--exclude=FROM1:FROM2:...</nowiki>   : specify a colon-separated list of entries to exclude (default is none )
72;  <nowiki>--include=FROM1:FROM2:...</nowiki>   : specify a colon-separated list of entries to include (default is all )
73;  <nowiki>--skip=N</nowiki>                    : skip first N entries (ordered by submission time)
74;  <nowiki>--flimits=FIELD1:LIMIT1,...</nowiki> : specify a comma-separated list of fields and character limits (default is none )
75;  <nowiki>--fields=FIELD1:FIELD2:...</nowiki>  : specify a colon-separated list of fields to process (default is all fields )
76;  <nowiki>--mbox-path=PATH</nowiki>            : specify path to input mbox (default: mbox)
77;  <nowiki>--order=N</nowiki>                   : specify order of form id (default: 3)
78;  <nowiki>--prefix=STRING</nowiki>             : specify prefix for wiki page title (default: Form Submission)
79;  <nowiki>--read-alist=FILE</nowiki>           : read an alist representation from FILE (mbox-path is ignored)
80;  <nowiki>-h, --help</nowiki>                  : Print help
81
82 form2txt [options...] operands
83
84The following options are recognized:
85
86;  <nowiki>--exclude=FROM1:FROM2</nowiki>  : specify a colon-separated list of entries to exclude (default is none )
87;  <nowiki>--fields=FIELD1:FIELD</nowiki>  : specify a colon-separated list of fields to process (default is all fields )
88;  <nowiki>--mbox-path=PATH</nowiki>       : specify path to input mbox (default: mbox)
89;  <nowiki>--order=N</nowiki>              : specify order of form id (default: 3)
90;  <nowiki>--prefix=STRING</nowiki>        : specify prefix for text page title (default: Form Submission)
91;  <nowiki>--write-alist=FILE</nowiki>     : write an alist representation to FILE
92;  <nowiki>--read-alist=FILE</nowiki>      : read an alist representation from FILE (mbox-path is ignored)
93;  <nowiki>-h, --help</nowiki>             : Print help
94
95
96== Authors
97
98Ivan Raikov
99
100== Version
101
102; 1.10 : Added options skip and read-alist to form2wiki
103; 1.9 : Bug fix in form2wiki
104; 1.8 : Added handling of malformed fields
105; 1.7 : Bug fix in the setup script
106; 1.6 : Added support for reading from and writing to s-expression alists
107; 1.5 : Bug fixes due to changes in the results returned by rfc822-field->tokens
108; 1.4 : Added missing dependencies to meta file
109; 1.1 : Added the documentation file to the egg
110; 1.0 : Initial version
111
112== License
113
114Copyright 2008-2009 Ivan Raikov and the Okinawa Institute of Science
115and Technology.
116
117This program is free software: you can redistribute it and/or modify
118it under the terms of the GNU General Public License as published by
119the Free Software Foundation, either version 3 of the License, or (at
120your option) any later version.
121
122This program is distributed in the hope that it will be useful, but
123WITHOUT ANY WARRANTY; without even the implied warranty of
124MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
125General Public License for more details.
126
127A full copy of the GPL license can be found at
128<http://www.gnu.org/licenses/>.
Note: See TracBrowser for help on using the repository browser.