To obtain the ftp namespace, run: +
+To obtain the ftp namespace, run:
@@ -99,7 +100,7 @@ ftp.get{
[command = string,]
[port = number,]
[type = string,]
- [step = LTN12 pump step],
+ [step = LTN12 pump step,]
}
@@ -115,7 +116,9 @@ If the argument of the get function is a table, the function
expects at least the fields host, sink, and one of
argument or path (argument takes
precedence). Host is the server to connect to. Sink is
-the simple LTN12 sink that will receive the downloaded data. Argument or
+the simple
+LTN12
+sink that will receive the downloaded data. Argument or
path give the target path to the resource in the server. The
optional arguments are the following:
@@ -127,7 +130,9 @@ authentication. Defaults to "ftp:anonymous@anonymous.org";
To obtain the ftp namespace, run: +
+To obtain the http namespace, run:
@@ -85,12 +87,8 @@ MIME headers are represented as a Lua table in the form:
headers = {
field-1-name = field-1-value,
field-2-name = field-2-value,
- field-3-name = field-3-value,
-
-
- ...
-
+ field-3-name = field-3-value,
+ ...
field-n-name = field-n-value
}
http.request{
url = string,
- [sink = LTN12 sink],]
+ [sink = LTN12 sink,]
[method = string,]
[headers = header-table,]
[source = LTN12 source],
@@ -203,7 +201,9 @@ Performs the generic HTTP request, controlled by a request table.
-The most important parameters are the url and the simple LTN12 sink that will receive the downloaded content.
+The most important parameters are the url and the simple
+LTN12
+sink that will receive the downloaded content.
Any part of the url can be overridden by including
the appropriate field in the request table.
If authentication information is provided, the function
@@ -215,11 +215,15 @@ following:
-The most used modules implement the SMTP (sending e-mails), HTTP -(WWW access) and FTP (uploading and downloading files) client +The most used modules implement the +SMTP +(sending e-mails), +HTTP +(WWW access) and +FTP +(uploading and downloading files) client protocols. These provide a very natural and generic interface to the e functionality covered by the protocols. -In addition, you will find that the MIME (common encodings), URL (anything you -could possible want to do with one) and LTN12 (filters, sinks, sources -and pumps) modules can be very handy. +In addition, you will find that the +MIME (common encodings), +URL +(anything you could possible want to do with one) and +LTN12 +(filters, sinks, sources and pumps) modules can be very handy.
diff --git a/doc/introduction.html b/doc/introduction.html index 59d1956..63a7d84 100644 --- a/doc/introduction.html +++ b/doc/introduction.html @@ -122,7 +122,7 @@ from the "socket" namespace.
socket = require("socket")
print(socket.VERSION)
--- LuaSocket 2.0
+--> LuaSocket 2.0
diff --git a/doc/ltn12.html b/doc/ltn12.html
index 7b379c2..9029b9c 100644
--- a/doc/ltn12.html
+++ b/doc/ltn12.html
@@ -42,7 +42,8 @@ functions. Please refer to the LTN for a deeper explanation of the
functionality provided by this module.
-To obtain the ltn12 namespace, run: +
+To obtain the ltn12 namespace, run:
diff --git a/doc/mime.html b/doc/mime.html index 791861e..e7211fa 100644 --- a/doc/mime.html +++ b/doc/mime.html @@ -55,7 +55,8 @@ follows the ideas presented in LTN012, Filters sources and sinks. -To obtain the mime namespace, run: +
+To obtain the mime namespace, run:
@@ -109,10 +110,6 @@ Returns a filter that decodes data from a given transfer content encoding. --The function returns the created filter. -
-@@ -131,10 +128,6 @@ textual or binary, by passing the mode strings "text" or "binary". Mode defaults to "text".
--The function returns the created filter. -
-Although both transfer content encodings specify a limit for the line length, the encoding filters do not break text into lines (for @@ -186,10 +179,6 @@ not to break lines in the middle of an escaped character. In that case, the line length is fixed at 76.
--The function returns the created filter. -
-For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following:
@@ -260,9 +249,7 @@ the context is returned after each new chunk. ASCII value of the last character of the previous chunk, if it was a candidate for line break, or 0 otherwise. B is the same as C, but for the current -chunk. If D is nil, A includes a -new end-of-line marker, depending on C. -Marker gives the new end-of-line marker and defaults to CRLF. +chunk. Marker gives the new end-of-line marker and defaults to CRLF.diff --git a/doc/smtp.html b/doc/smtp.html index 0fdc4a4..6b348e0 100644 --- a/doc/smtp.html +++ b/doc/smtp.html @@ -35,8 +35,15 @@SMTP
-The smtp.lua module provides functionality to send e-mail -messages. The implementation conforms to the Simple Mail Transfer Protocol, +
The smtp 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). +
+ +The implementation conforms to the Simple Mail Transfer Protocol, RFC 2821. Another RFC of interest is RFC 2822, @@ -52,6 +59,15 @@ sources and sinks and the MIME module is assumed. In fact, the SMTP module was the main reason for their creation.
++To obtain the smtp namespace, run: +
+ ++-- loads the SMTP module and everything it requires +local smtp = require("smtp") ++MIME headers are represented as a Lua table in the form:
@@ -62,12 +78,8 @@ MIME headers are represented as a Lua table in the form: headers = {
field-1-name = field-1-value,
field-2-name = field-2-value,
- field-3-name = field-3-value, - -- - ... - @@ -105,12 +117,12 @@ smtp.send{ + field-3-name = field-3-value,
+ ...
field-n-name = field-n-value
}
from = string,
rcpt = string or string-table,
source = LTN12 source,
- [user = string],
- [password = string],
- [server = string],
- [port = string]
- [domain = string],
- [step = LTN12 pump step],
+ [user = string,]
+ [password = string,]
+ [server = string,]
+ [port = string,]
+ [domain = string,]
+ [step = LTN12 pump step,]
} @@ -127,8 +139,9 @@ The sender is given by the e-mail address in the from field. Rcpt 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 simple LTN12 source. Several -arguments are optional: +The contents of the message are given by a simple +LTN12 +source. Several arguments are optional:
-Returns a LTN12 source that sends an SMTP message body, possibly multipart -(arbitrarily deep). +Returns a simple +LTN12 source that sends an SMTP message body, possibly multipart (arbitrarily deep).
@@ -277,12 +293,12 @@ mesgt = {
}
multipart-mesgt = {
- preamble = string
+ [preamble = string,]
[1] = mesgt,
[2] = mesgt,
...
[n] = mesgt,
- epilogue = string,
+ [epilogue = string,]
}
@@ -291,14 +307,19 @@ multipart-mesgt = {
For a simple message, all that is needed is a set of headers and the body. The message body 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 simple +LTN12 +source. For multipart messages, the body is a table that +recursively defines each part as an independent message, plus an optional +preamble and epilogue.
-The function returns a simple LTN12 source that produces the -message contents as defined by mesgt. Hopefully, the following +The function returns a simple +LTN12 +source that produces the +message contents as defined by mesgt, chunk by chunk. +Hopefully, the following example will make things clear. When in doubt, refer to the appropriate RFC as listed in the introduction.
@@ -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] = { diff --git a/doc/socket.html b/doc/socket.html index b3fbb6e..8b92a3f 100644 --- a/doc/socket.html +++ b/doc/socket.html @@ -39,6 +39,16 @@ The socket namespace contains the core functionality of LuaSocket. ++To obtain the socket namespace, run: +
+ +
+-- loads the socket module
+local socket = require("socket")
+
+
+
@@ -62,8 +72,9 @@ Converts a function that throws exceptions into a safe function.
-Funct is a function that calls -try to throw exceptions. +Func is a function that calls +try (or assert, or error) +to throw exceptions.
@@ -71,6 +82,13 @@ Returns an equivalent function that instead of throwing exceptions, returns nil followed by an error message.
++Note: Beware that if your function performs some illegal operation that +raises an error, the protected function will catch the error and return it +as a string. This is because the try function +uses errors as the mechanism to throw exceptions. +
+@@ -88,8 +106,8 @@ see if it is OK to immediately write on them. Timeout is the maximum amount of time (in seconds) to wait for a change in status. A nil, negative or omitted timeout value allows the function to block indefinitely. Recvt and sendt can also -be empty tables or nil. Non-socket values in the arrays -will be silently ignored. +be empty tables or nil. Non-socket values (or values with +non-numeric indices) in the arrays will be silently ignored.
The function returns a table with the sockets ready for @@ -186,7 +204,7 @@ The function returns a source with the appropriate behavior.
-socket.try(ret1, ret2 ... retN) +socket.try(ret1 [, ret2 ... retN])
@@ -194,16 +212,14 @@ Throws an exception in case of error.
-Ret1, ret2 ... retN can be arbitrary -arguments, but are usually the return values of a function call that -nested with the call to try. +Ret1 to retN can be arbitrary +arguments, but are usually the return values of a function call +nested with try.
-The function returns ret1, ret2 ... -retN if -ret1 is not nil. Otherwise, calls error -passing ret2. +The function returns ret1 to retN if +ret1 is not nil. Otherwise, it calls error passing ret2.
@@ -211,7 +227,7 @@ passing ret2.
c = socket.try(socket.connect("localhost", 80))
-
+
socket.VERSION