From c53dad98839f5139dcedc128d2545dd2542a7157 Mon Sep 17 00:00:00 2001 From: Diego Nehab Date: Tue, 25 May 2004 06:51:43 +0000 Subject: [PATCH] Starting the manual. Oh well. --- doc/callback.html | 348 --------------------------------------------- doc/code.html | 202 -------------------------- doc/dns.html | 2 +- doc/reference.html | 118 ++++++++------- doc/stream.html | 166 --------------------- 5 files changed, 71 insertions(+), 765 deletions(-) delete mode 100644 doc/callback.html delete mode 100644 doc/code.html delete mode 100644 doc/stream.html diff --git a/doc/callback.html b/doc/callback.html deleted file mode 100644 index 98b4476..0000000 --- a/doc/callback.html +++ /dev/null @@ -1,348 +0,0 @@ - - - - -LuaSocket: Network support for the Lua language - - - - - - - -
-
-
- - - -
-LuaSocket -
Network support for the Lua language -
-

-home · -download · -introduction · -reference -

-
-
-
- - - -

Callbacks

- -

-HTTP, FTP, and SMTP transfers sometimes involve large amounts of -information. Sometimes an application needs to generate outgoing data -in real time, or needs to process incoming information as it is being -received. To address these problems, LuaSocket allows HTTP and SMTP message -bodies and FTP file contents to be streamed through the -callback mechanism outlined below. -

- -

-Instead of returning the received contents -as a big to the Lua application, the library allows the user to -provide a receive callback that will be called with successive -chunks of data, as the data becomes available. Conversely, the send -callback mechanism can be used when the application wants to incrementally provide LuaSocket with the data to be sent. -

- - - -

-receive_cb(chunk, err) -

- -

-A receive callback will be repeatedly called by -LuaSocket whenever new data is available. Each time it is called, the -callback receives successive chunks of downloaded data. -

- -

-Chunk contains the latest downloaded chunk of data. -When the transmission is over, the function is called with an -empty string (i.e. "") in chunk. -If an error occurs, the function receives a nil -chunk and an error message in err. -

- -

-The callback can abort transmission by returning nil as its first -return value, and an optional error message as the -second return value. To continue receiving -data, the function should return non-nil as its first return -value. Optionally, in this case, it may return a -second return value, with a new callback function to take its place. -

- - - -

-send_cb() -

- -

-A send callback will be called whenever LuaSocket -needs more data to be sent. -

- -

-Each time the callback is called, it should return the next chunk of data. It -can optionally return, as it's second return value, a new callback to replace -itself. The callback can abort the process at any time by returning -nil followed by an optional error message. -

- - - -

Predefined Callbacks

- -

-The Callback module provides several predefined callbacks to -perform the most common input/output operations. Callbacks are provided -that send and receive contents of files and strings. Furthermore, -composition functions are provided to chain callbacks with filters, such as -the filters defined in the MIME module. -Together, these two modules provide a powerful interface to send and -receive information. -

- - - -

-socket.callback.done() -

- -

-This function creates and returns a callback that successfully terminates -the transmission. -

- - - -

-socket.callback.fail(message) -

- -

-This function creates and returns a callback that aborts the -transmission with a given error message. -

- - - -

-socket.callback.receive.concat(cat) -

- -

-This function creates a receive callback that stores whatever it receives -into a concat object. When done, the application can get the contents -received as a single string, directly from the concat object. -

- -

-Cat is the target concat object, or nil. -If cat is nil, the function creates its own -concat object. -

- -

-The function returns a receive callback for the file, and the concat object -that will be used to store the received contents. -

- - - -

-socket.callback.receive.file(file, io_err) -

- -

-This function creates a receive callback that stores whatever it receives -into a file. When done, the callback closes the file. -

- -

-File is a file handle opened for writing. If file is -nil, io_err can contain an error message. In this -case, the function returns a callback that just aborts -transmission with the error message. -

- -

-The function returns a receive callback for the file. -

- -

-Note: This function is designed so that it directly accepts the return -values of Lua's IO io.open library function. -

- - - -

-socket.callback.receive.chain(filter, receive_cb) -

- -

-This function creates a receive callback that passes all received data -through a filter, before handing it to a given receive callback. -

- -

-Cat is the target concat object, or nil. -If cat is nil, the function creates its own -concat object. -

- -

-The function returns a receive callback for the file, and the concat object -that will be used to store the received contents. -

- -

-Note: Several filters are defined in the MIME -module. Below is an example that creates a receive callback that -creates a string from the received contents, after decoding the -Quoted-Printable transfer content encoding. -

- -
-string_cb, concat = socket.callback.receive.concat()
-receive_cb = socket.callback.receive.chain(
-   socket.mime.decode("quoted-printable"),
-   string_cb
-)
-
- -

-The call to callback.chain creates a chained -receive callback that decodes data using the -mime.decode -Quoted-Printable MIME filter and -hands the decoded data to a concat receive callback. -The concatenated decoded data can be retrieved later -from the associated concat object. -

- - - -

-socket.callback.send.file(file, io_err) -

- -

-This function creates a send callback that returns the contents -of a file, chunk by chunk, until the file has been entirely sent. -When done, the callback closes the file. -

- -

-File is a file handle opened for reading. If file is -nil, io_err can contain an error message. In this -case, the function returns a callback that just aborts -transmission with the error message. -

- -

-The function returns a send callback for the file. -

- -

-Note: This function is designed so that it directly accepts the return -values of Lua's IO io.open library function. -

- - - -

-socket.callback.send.string(str, err) -

- -

-This function creates a send callback that will send -the contents of a string. -

- -

-Str is the string to be sent. -

- -

-It returns a send callback for the string, -or nil if str is nil. -

- - - -

-socket.callback.send.chain(send_cb, filter) -

- -

-This function creates a send callback that will filter -all the data it receives from another send callback, before -sending it through. -

- -

-Send_cb is the send callback to be chained to filter. -

- -

-Returns a callback chained with the filter. -

- -

-Note: Several filters are defined in the MIME -module. Below is an example that creates a send callback that sends -a file's contents encoded in the Base64 transfer content encoding. -

- -
-send_cb = socket.callback.send.chain(
-   socket.callback.send.file(io.open("input.bin"))
-   socket.mime.chain(
-       socket.mime.encode("base64"),
-       socket.mime.wrap("base64")
-   )
-)
-
- -

-The call to mime.chain -creates a chained filter that encodes it's input and then breaks it -into lines. The call to callback.chain creates a chained -send callback that reads the file from disk and passes it through the -filter before sending it. -

- - - -
-
-
-

-home · -download · -introduction · -reference -

-

- -Last modified by Diego Nehab on
-Sat Aug 9 01:00:41 PDT 2003 - -

-
-
- - - diff --git a/doc/code.html b/doc/code.html deleted file mode 100644 index 4668b7a..0000000 --- a/doc/code.html +++ /dev/null @@ -1,202 +0,0 @@ - - - - -LuaSocket: Network support for the Lua language - - - - - - - -
-
-
- - - -
-LuaSocket -
Network support for the Lua language -
-

-home · -download · -introduction · -reference -

-
-
-
- - - -

Code

- -

-The code.lua module offers routines to convert back and forth -some common types of content encoding, including Base 64 and URL -escaping. Base 64 is described in -RFC -2045, -URL escaping is described in -RFC -2396. -

- - - -

-socket.code.base64(content, single) -

- -

-Applies the Base 64 content coding to a string. -

- -

-Content is the string to be encoded. -If single is set to anything -but nil, the output is returned as a single -line, otherwise the function splits the content into 76 character long -lines after encoding. -

- -

-The function returns the encoded string. -

- -
-code = socket.code.base64("diego:password")
--- code = "ZGllZ286cGFzc3dvcmQ="
-
- - - -

-socket.code.unbase64(content) -

- -

-Removes the Base 64 content coding from a string. -

- -

-Content is the string to be decoded. -

- -

-The function returns the decoded string. -

- - - -

-socket.code.escape(content) -

- -

-Applies the URL escaping content coding to a string -Each byte is encoded as a percent character followed -by the two byte hexadecimal representation of its integer -value. -

- -

-Content is the string to be encoded. -

- -

-The function returns the encoded string. -

- -
-code = socket.code.escape("/#?;")
--- code = "%2f%23%3f%3b"
-
- - - -

-socket.code.unescape(content) -

- -

-Removes the URL escaping content coding from a string. -

- -

-Content is the string to be decoded. -

- -

-The function returns the decoded string. -

- - - -

-socket.code.hexa(content) -

- -

-Applies the hexadecimal content coding to a string. -Each byte is encoded as the byte hexadecimal -representation of its integer value.

-

- -

-Content is the string to be encoded. -

- -

-The function returns the encoded string. -

- -
-code = socket.code.hexa("\16\32\255")
--- code = "1020ff"
-
- - - -

-socket.code.unhexa(content) -

- -

-Removes the hexadecimal content coding from a string. -

- -

-Content is the string to be decoded. -

- -

-The function returns the decoded string. -

- - - -
-
-
-

-home · -download · -introduction · -reference -

-

- -Last modified by Diego Nehab on
-Sat Aug 9 01:00:41 PDT 2003 - -

-
-
- - - diff --git a/doc/dns.html b/doc/dns.html index 71a9719..8e63407 100644 --- a/doc/dns.html +++ b/doc/dns.html @@ -82,7 +82,7 @@ Converts from IP address to host name.

-The function a string with the canonic host name of the given +The function returns a string with the canonic host name of the given address, followed by a table with all information returned by the resolver. In case of error, the function returns nil followed by an error message. diff --git a/doc/reference.html b/doc/reference.html index 6e14891..6372e64 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -35,31 +35,6 @@

Reference

- - -
-Callbacks (socket.callback) -
-done, -fail. -
-
-send: -chain, -file, -string. -
-
-receive: -chain, -file, -concat. -
-
- - - -
DNS services (socket.dns)
@@ -75,34 +50,45 @@ FTP (socket.ftp)
get, -get_cb, put, -put_cb. +open.
-Globals (socket) +Globals
-bind, -callback, -concat, -connect, -debug, -dns, -ftp, -http, +LUASOCKET_LIBNAME, mime, -select, -sleep, -smtp, -time, -tcp. -udp, -url, -version. +ltn12, +socket. +
+
+ + +
+LuaSocket namespace (socket) +
+bind, +connect, +debug, +dns, +ftp, +http, +protect, +select, +sink, +source, +sleep, +smtp, +time, +tcp, +try, +udp, +url, +version.
@@ -115,15 +101,49 @@
get, post, -request, -request_cb. +request. +
+
+ + + +
+LTN012 (ltn12) +
+filter: +chain, +cycle. +
+
+pump: +all, +step. +
+
+sink: +chain, +error, +file, +null, +simplify, +table. +
+
+source: +cat, +chain, +empty, +file, +simplify, +rewind, +string.
-MIME (socket.mime) +MIME (mime)
high-level: normalize, @@ -149,7 +169,9 @@
SMTP (socket.smtp)
-mail +open, +message, +send.
diff --git a/doc/stream.html b/doc/stream.html deleted file mode 100644 index 585ad18..0000000 --- a/doc/stream.html +++ /dev/null @@ -1,166 +0,0 @@ - - - - -LuaSocket: Network support for the Lua language - - - - - - - -
-
-
- - - -
-LuaSocket -
Network support for the Lua language -
-

-home · -download · -introduction · -reference -

-
-
-
- - - -

Streaming with Callbacks

- -

-HTTP, FTP, and SMTP transfers sometimes involve large amounts of -information. Sometimes an application needs to generate outgoing data -in real time, or needs to process incoming information as it is being -received. To address these problems, LuaSocket allows HTTP and SMTP message -bodies and FTP file contents to be received or sent through the -callback mechanism outlined below. -

- -

-Instead of returning the entire contents of an entity -as strings to the Lua application, the library allows the user to -provide a receive callback that will be called with successive -chunks of data, as the data becomes available. Conversely, the send -callbacks can be used when the application wants to incrementally -provide LuaSocket with the data to be sent. -

- - - -

-receive_cb(chunk, err) -

- -

-The callback provided by the user will be repeatedly called by the -library whenever new data is available. Each time it is called, the -callback receives successive chunks of downloaded data. -

- -

-Chunk contains the current chunk of data. -When the transmission is over, the function is called with an -empty string (i.e. "") as the chunk. -If an error occurs, the function receives nil -as chunk and an error message in err. -

- -

-The callback can abort transmission by returning nil as its first -return value, and an optional error message as the -second return value. If the application wants to continue receiving -data, the function should return non-nil as it's first return -value. In this case, the function can optionally return a -new callback function, to replace itself, as the second return value. -

- -

-Note: The callback module provides several standard receive callbacks, including the following: -

- -
-function receive.concat(concat)
-    concat = concat or socket.concat.create()
-    local callback = function(chunk, err)
-        -- if not finished, add chunk
-        if chunk and chunk ~= "" then
-            concat:addstring(chunk)
-            return 1
-        end
-    end
-    return callback, concat
-end
-
- -

-This function creates a new receive callback that concatenates all -received chunks into a the same concat object, which can later be -queried for its contents. -

- - - -

-send_cb() -

- -

-The callback provided by the user will be repeatedly called whenever the -library needs more data to be sent. -

- -

-Each time the callback is called, it should return the next chunk of data. It -can optionally return, as it's second return value, a new callback to replace -itself. The callback can abort the process at any time by returning -nil followed by an optional error message. -

- -

-Note: Below is the implementation of the callback.send.file -function. Given an open file handle, it returns a send callback that will send the contents of that file, chunk by chunk. -

- -
-function send.file(file, io_err)
-    -- if successful, return the callback that reads from the file
-    if file then
-        return function()
-            -- send next block of data
-            return (file:read(BLOCKSIZE)) or ""
-        end
-    -- else, return a callback that just aborts the transfer
-    else return fail(io_err or "unable to open file") end
-end
-
- - - -
-
-
-

-home · -download · -introduction · -reference -

-

- -Last modified by Diego Nehab on
-Sat Aug 9 01:00:41 PDT 2003 - -

-
-
- - -