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 @@ - - - -
--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. -
- - - --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. -
- - - - - - - 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 @@ - - - - --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. -
- - - - - - - 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 @@
-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) +@@ -115,15 +101,49 @@+bind, +connect, +debug, +dns, +ftp, +http, +protect, +select, +sink, +source, +sleep, +smtp, +time, +tcp, +try, +udp, +url, +version.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)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 @@ - - - - --mail +open, +message, +send.LuaSocket: Network support for the Lua language - - - - - - - - - - - -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 -- - - - - - -