Fine tuning the manual...
This commit is contained in:
Diego Nehab
parent
0a4c1534f3
commit
ba2f0b8c6b
8 changed files with 129 additions and 83 deletions
|
|
@ -35,8 +35,15 @@
|
|||
|
||||
<h2 id=smtp>SMTP</h2>
|
||||
|
||||
<p> The <tt>smtp.lua</tt> module provides functionality to send e-mail
|
||||
messages. The implementation conforms to the Simple Mail Transfer Protocol,
|
||||
<p> The <tt>smtp</tt> namespace provides functionality to send e-mail
|
||||
messages. The high-level API consists of two functions: one to
|
||||
define an e-mail message, and another to actually send the message.
|
||||
Although almost all users will find that these functions provide more than
|
||||
enough functionality, the underlying implementation allows for even more
|
||||
control (if you bother to read the code).
|
||||
</p>
|
||||
|
||||
<p>The implementation conforms to the Simple Mail Transfer Protocol,
|
||||
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
|
||||
Another RFC of interest is <a
|
||||
href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>,
|
||||
|
|
@ -52,6 +59,15 @@ sources and sinks</a> and the <a href=mime.html>MIME</a> module is
|
|||
assumed. In fact, the SMTP module was the main reason for their
|
||||
creation. </p>
|
||||
|
||||
<p>
|
||||
To obtain the <tt>smtp</tt> namespace, run:
|
||||
</p>
|
||||
|
||||
<pre class=example>
|
||||
-- loads the SMTP module and everything it requires
|
||||
local smtp = require("smtp")
|
||||
</pre>
|
||||
|
||||
<p>
|
||||
MIME headers are represented as a Lua table in the form:
|
||||
</p>
|
||||
|
|
@ -62,12 +78,8 @@ MIME headers are represented as a Lua table in the form:
|
|||
headers = {<br>
|
||||
field-1-name = <i>field-1-value</i>,<br>
|
||||
field-2-name = <i>field-2-value</i>,<br>
|
||||
field-3-name = <i>field-3-value</i>,
|
||||
</tt></td></tr>
|
||||
<tr><td align=center><tt>
|
||||
...
|
||||
</tt></td></tr>
|
||||
<tr><td><tt>
|
||||
field-3-name = <i>field-3-value</i>,<br>
|
||||
...<br>
|
||||
field-n-name = <i>field-n-value</i><br>
|
||||
}
|
||||
</tt></td></tr>
|
||||
|
|
@ -105,12 +117,12 @@ smtp.<b>send{</b><br>
|
|||
from = <i>string</i>,<br>
|
||||
rcpt = <i>string</i> or <i>string-table</i>,<br>
|
||||
source = <i>LTN12 source</i>,<br>
|
||||
[user = <i>string</i>],<br>
|
||||
[password = <i>string</i>],<br>
|
||||
[server = <i>string</i>],<br>
|
||||
[port = <i>string</i>]<br>
|
||||
[domain = <i>string</i>],<br>
|
||||
[step = <i>LTN12 pump step</i>],<br>
|
||||
[user = <i>string</i>,]<br>
|
||||
[password = <i>string</i>,]<br>
|
||||
[server = <i>string</i>,]<br>
|
||||
[port = <i>string</i>,]<br>
|
||||
[domain = <i>string</i>,]<br>
|
||||
[step = <i>LTN12 pump step</i>,]<br>
|
||||
<b>}</b>
|
||||
</p>
|
||||
|
||||
|
|
@ -127,8 +139,9 @@ The sender is given by the e-mail address in the <tt>from</tt> field.
|
|||
<tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail
|
||||
address, or a string
|
||||
in case there is just one recipient.
|
||||
The contents of the message are given by a <em>simple</em> LTN12 <tt>source</tt>. Several
|
||||
arguments are optional:
|
||||
The contents of the message are given by a <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
<tt>source</tt>. Several arguments are optional:
|
||||
</p>
|
||||
<ul>
|
||||
<li> <tt>user</tt>, <tt>password</tt>: User and password for
|
||||
|
|
@ -138,7 +151,9 @@ methods if supported by the server (both are unsafe);
|
|||
<li> <tt>port</tt>: Port to connect to. Defaults to 25;
|
||||
<li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the
|
||||
local machine host name;
|
||||
<li> <tt>step</tt>: LTN12 pump step function used to pass data from the
|
||||
<li> <tt>step</tt>:
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
pump step function used to pass data from the
|
||||
source to the server. Defaults to the LTN12 <tt>pump.step</tt> function.
|
||||
</ul>
|
||||
|
||||
|
|
@ -166,7 +181,8 @@ exact opposite of what you expect.
|
|||
Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the
|
||||
message. Each recipient of an SMTP mail message receives a copy of the
|
||||
message body along with the headers, and nothing more. The headers
|
||||
<em>are</em> part of the message and should be produced by the LTN12
|
||||
<em>are</em> part of the message and should be produced by the
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
<tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em>
|
||||
part of the message and will not be sent to anyone.
|
||||
</p>
|
||||
|
|
@ -258,8 +274,8 @@ smtp.<b>message(</b>mesgt<b>)</b>
|
|||
</p>
|
||||
|
||||
<p class=description>
|
||||
Returns a LTN12 source that sends an SMTP message body, possibly multipart
|
||||
(arbitrarily deep).
|
||||
Returns a <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep).
|
||||
</p>
|
||||
|
||||
<p class=parameters>
|
||||
|
|
@ -277,12 +293,12 @@ mesgt = {<br>
|
|||
}<br>
|
||||
<br>
|
||||
multipart-mesgt = {<br>
|
||||
preamble = <i>string</i><br>
|
||||
[preamble = <i>string</i>,]<br>
|
||||
[1] = <i>mesgt</i>,<br>
|
||||
[2] = <i>mesgt</i>,<br>
|
||||
...<br>
|
||||
[<i>n</i>] = <i>mesgt</i>,<br>
|
||||
epilogue = <i>string</i>,<br>
|
||||
[epilogue = <i>string</i>,]<br>
|
||||
}<br>
|
||||
</tt></td></tr>
|
||||
</table>
|
||||
|
|
@ -291,14 +307,19 @@ multipart-mesgt = {<br>
|
|||
<p class=parameters>
|
||||
For a simple message, all that is needed is a set of <tt>headers</tt>
|
||||
and the <tt>body</tt>. The message <tt>body</tt> can be given as a string
|
||||
or as a LTN12 source. For multipart messages, the body is a table that
|
||||
recursively defines each part as an independent message, plus a preamble
|
||||
and an epilogue.
|
||||
or as a <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
source. For multipart messages, the body is a table that
|
||||
recursively defines each part as an independent message, plus an optional
|
||||
<tt>preamble</tt> and <tt>epilogue</tt>.
|
||||
</p>
|
||||
|
||||
<p class=return>
|
||||
The function returns a <em>simple</em> LTN12 source that produces the
|
||||
message contents as defined by <tt>mesgt</tt>. Hopefully, the following
|
||||
The function returns a <em>simple</em>
|
||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||
source that produces the
|
||||
message contents as defined by <tt>mesgt</tt>, chunk by chunk.
|
||||
Hopefully, the following
|
||||
example will make things clear. When in doubt, refer to the appropriate RFC
|
||||
as listed in the introduction. </p>
|
||||
|
||||
|
|
@ -320,7 +341,7 @@ source = smtp.message{
|
|||
body = {
|
||||
preamble = "If your client doesn't understand attachments, \r\n" ..
|
||||
"it will still display the preamble and the epilogue.\r\n" ..
|
||||
"Preamble might show up even in a MIME enabled client.",
|
||||
"Preamble will probably appear even in a MIME enabled client.",
|
||||
-- first part: no headers means plain text, us-ascii.
|
||||
-- The mime.eol low-level filter normalizes end-of-line markers.
|
||||
[1] = {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue