2 files changed, 253 insertions, 1 deletions
diff --git a/doc/callback.html b/doc/callback.html
new file mode 100644
index 0000000..2c7ecd5
--- /dev/null
+++ b/doc/callback.html
@@ -0,0 +1,252 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
+    "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<title>LuaSocket: Network support for the Lua language</title>
+<link rel="stylesheet" href="reference.css" type="text/css">
+</head>
+<body>
+<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<div class=header>
+<hr>
+<center>
+<table summary="LuaSocket logo">
+<tr><td align=center><a href="http://www.lua.org">
+<img border=0 alt="LuaSocket" src="luasocket.png">
+</a></td></tr>
+<tr><td align=center valign=top>Network support for the Lua language
+</td></tr>
+</table>
+<p class=bar>
+<a href="home.html">home</a> &middot;
+<a href="home.html#download">download</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<a href="reference.html">reference</a> 
+</p>
+</center>
+<hr>
+</div>
+<!-- stream ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<h2 id=stream>Streaming with Callbacks</h2> 
+<p>
+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.  
+</p>
+<p>
+Instead of  returning the entire contents of an entity 
+as strings to the Lua  application, the library allows  the user to
+provide a  <em>receive callback</em> that  will be called  with successive
+chunks of data, as the data becomes available. Conversely, the <em>send
+callbacks</em> can be used when the application wants to incrementally 
+provide LuaSocket with the data to be sent. 
+</p>
+<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class=name id=receive_cb> 
+ret, err_or_f = <b>receive_cb(</b>chunk, err<b>)</b>
+</p>
+<p class=description>
+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. 
+</p>
+<p class=parameters>
+<tt>Chunk</tt> contains the current chunk of data.
+When the transmission  is over, the function  is called with an  
+empty string (i.e.&nbsp;<tt>""</tt>) as  the <tt>chunk</tt>. 
+If an  error occurs, the function  receives <tt>nil</tt> 
+as <tt>chunk</tt> and  an error  message in <tt>err</tt>. 
+</p>
+<p class=return>
+The callback  can abort transmission by returning <tt>nil</tt> 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-<tt>nil</tt> 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.  
+</p>
+<p class=note>
+Note: The <tt>callback</tt> module provides several standard receive callbacks, including the following:
+</p>
+<pre class=example>
+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
+</pre>
+<p class=note>
+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.
+</p>
+<!-- send_cb ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class=name>
+chunk, err_or_r = <b>send_cb()</b>
+</p>
+<p class=description>
+The callback provided by the user will be repeatedly called whenever the
+library needs more data to be sent. 
+</p>
+<p class=return> 
+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
+<tt>nil</tt> followed  by  an optional error message. 
+</p>
+<p class=note>
+Note: Below is the implementation of the <tt>callback.send.file</tt> 
+function. Given an open file handle, it returns a send callback that will send the contents of that file, chunk by chunk.
+</p>
+<pre class=example>
+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
+</pre>
+<!-- predefined +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<h2 id=predefined>Predefined Callbacks</h2> 
+<p>
+The module <tt>callback.lua</tt> 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 <tt>mime.lua</tt> module.
+</p>
+<!-- send.file ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class=name id=send.file> 
+<b>send.file</b>(file, io_err<b>)</b>
+</p>
+<p class=description>
+This function creates a send callback that will return the contents
+of a the file, until the file has been entirely sent. When done, the
+callback closes the file. 
+</p>
+<p class=parameters>
+<tt>File</tt> is a file open for reading. If <tt>file</tt> is 
+<tt>nil</tt>, <tt>io_err</tt> can contain an error message and the 
+returned callback just aborts transmission with the error message.
+</p>
+<p class=return>
+Returns a send callback for the file. 
+</p>
+<p class=note>
+Note: The function is designed so that it directly accepts the return 
+values of the <tt>io.open</tt> function.
+</p>
+<!-- send.string ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class=name id=send.string> 
+<b>send.string(</b>str<b>)</b>
+</p>
+<p class=description>
+This function creates a send callback that will send
+the contents of a string.  
+</p>
+<p class=parameters>
+<tt>Str</tt> is the string to be sent.
+</p>
+<p class=return>
+Returns a send callback for the string, or <tt>nil</tt> if the string is
+<tt>nil</tt>.
+</p>
+<p class=note>
+Note: If any function in the LuaSocket API receives a <tt>nil</tt> 
+send callback, it assumes there is nothing to be sent. 
+</p>
+<!-- send.chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class=name id=send.string> 
+<b>send.chain(</b>send_cb, filter<b>)</b>
+</p>
+<p class=description>
+This function creates a send callback that will send
+all data that it gets from another callback, 
+after passing the data through a filter. 
+</p>
+<p class=parameters>
+<tt>Send_cb</tt> is the send callback to be chained to <tt>filter</tt>.
+</p>
+<p class=return>
+Returns a callback chained with the filter. 
+</p>
+(write a note!)
+<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<div class=footer>
+<hr>
+<center>
+<p class=bar>
+<a href="home.html">home</a> &middot;
+<a href="home.html#down">download</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<a href="reference.html">reference</a>
+</p>
+<p>
+<small>
+Last modified by Diego Nehab on <br>
+Sat Aug 9 01:00:41 PDT 2003
+</small>
+</p>
+</center>
+</div>
+</body>
+</html>
diff --git a/doc/smtp.html b/doc/smtp.html
index 3a30a07..aa92149 100644
--- a/doc/smtp.html
+++ b/doc/smtp.html
@@ -36,7 +36,7 @@
 <h2 id=smtp>SMTP</h2> 
 <p>
-The  module  <tt>smtp.lua</tt>  provides functionality  to  send  e-mail
+The  <tt>smtp.lua</tt> module  provides functionality  to  send  e-mail
 messages. The implementation conforms to the Simple Mail Transfer Protocol,
 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
 The other RFC of interest in this implementation is

diff --git a/doc/callback.html b/doc/callback.html new file mode 100644 index 0000000..2c7ecd5 --- /dev/null +++ b/doc/callback.html
@@ -0,0 +1,252 @@
		1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
		2	"http://www.w3.org/TR/html4/strict.dtd">
		3	<html>
		4
		5	<head>
		6	<title>LuaSocket: Network support for the Lua language</title>
		7	<link rel="stylesheet" href="reference.css" type="text/css">
		8	</head>
		9
		10	<body>
		11
		12	<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
		13
		14	<div class=header>
		15	<hr>
		16	<center>
		17	<table summary="LuaSocket logo">
		18	<tr><td align=center><a href="http://www.lua.org">
		19	<img border=0 alt="LuaSocket" src="luasocket.png">
		20	</a></td></tr>
		21	<tr><td align=center valign=top>Network support for the Lua language
		22	</td></tr>
		23	</table>
		24	<p class=bar>
		25	<a href="home.html">home</a> ·
		26	<a href="home.html#download">download</a> ·
		27	<a href="introduction.html">introduction</a> ·
		28	<a href="reference.html">reference</a>
		29	</p>
		30	</center>
		31	<hr>
		32	</div>
		33
		34	<!-- stream ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
		35
		36	<h2 id=stream>Streaming with Callbacks</h2>
		37
		38	<p>
		39	HTTP, FTP, and SMTP transfers sometimes involve large amounts of
		40	information. Sometimes an application needs to generate outgoing data
		41	in real time, or needs to process incoming information as it is being
		42	received. To address these problems, LuaSocket allows HTTP and SMTP message
		43	bodies and FTP file contents to be received or sent through the
		44	callback mechanism outlined below.
		45	</p>
		46
		47	<p>
		48	Instead of returning the entire contents of an entity
		49	as strings to the Lua application, the library allows the user to
		50	provide a <em>receive callback</em> that will be called with successive
		51	chunks of data, as the data becomes available. Conversely, the <em>send
		52	callbacks</em> can be used when the application wants to incrementally
		53	provide LuaSocket with the data to be sent.
		54	</p>
		55
		56	<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
		57
		58	<p class=name id=receive_cb>
		59	ret, err_or_f = <b>receive_cb(</b>chunk, err<b>)</b>
		60	</p>
		61
		62	<p class=description>
		63	The callback provided by the user will be repeatedly called by the
		64	library whenever new data is available. Each time it is called, the
		65	callback receives successive chunks of downloaded data.
		66	</p>
		67
		68	<p class=parameters>
		69	<tt>Chunk</tt> contains the current chunk of data.
		70	When the transmission is over, the function is called with an
		71	empty string (i.e. <tt>""</tt>) as the <tt>chunk</tt>.
		72	If an error occurs, the function receives <tt>nil</tt>
		73	as <tt>chunk</tt> and an error message in <tt>err</tt>.
		74	</p>
		75
		76	<p class=return>
		77	The callback can abort transmission by returning <tt>nil</tt> as its first
		78	return value, and an optional error message as the
		79	second return value. If the application wants to continue receiving
		80	data, the function should return non-<tt>nil</tt> as it's first return
		81	value. In this case, the function can optionally return a
		82	new callback function, to replace itself, as the second return value.
		83	</p>
		84
		85	<p class=note>
		86	Note: The <tt>callback</tt> module provides several standard receive callbacks, including the following:
		87	</p>
		88
		89	<pre class=example>
		90	function receive.concat(concat)
		91	concat = concat or socket.concat.create()
		92	local callback = function(chunk, err)
		93	-- if not finished, add chunk
		94	if chunk and chunk ~= "" then
		95	concat:addstring(chunk)
		96	return 1
		97	end
		98	end
		99	return callback, concat
		100	end
		101	</pre>
		102
		103	<p class=note>
		104	This function creates a new receive callback that concatenates all
		105	received chunks into a the same concat object, which can later be
		106	queried for its contents.
		107	</p>
		108
		109	<!-- send_cb ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
		110
		111	<p class=name>
		112	chunk, err_or_r = <b>send_cb()</b>
		113	</p>
		114
		115	<p class=description>
		116	The callback provided by the user will be repeatedly called whenever the
		117	library needs more data to be sent.
		118	</p>
		119
		120	<p class=return>
		121	Each time the callback is called, it should return the next chunk of data. It
		122	can optionally return, as it's second return value, a new callback to replace
		123	itself. The callback can abort the process at any time by returning
		124	<tt>nil</tt> followed by an optional error message.
		125	</p>
		126
		127	<p class=note>
		128	Note: Below is the implementation of the <tt>callback.send.file</tt>
		129	function. Given an open file handle, it returns a send callback that will send the contents of that file, chunk by chunk.
		130	</p>
		131
		132	<pre class=example>
		133	function send.file(file, io_err)
		134	-- if successful, return the callback that reads from the file
		135	if file then
		136	return function()
		137	-- send next block of data
		138	return (file:read(BLOCKSIZE)) or ""
		139	end
		140	-- else, return a callback that just aborts the transfer
		141	else return fail(io_err or "unable to open file") end
		142	end
		143	</pre>
		144
		145	<!-- predefined +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
		146
		147	<h2 id=predefined>Predefined Callbacks</h2>
		148
		149	<p>
		150	The module <tt>callback.lua</tt> provides several predefined callbacks to
		151	perform the most common input/output operations. Callbacks are provided
		152	that send and receive contents of files and strings. Furthermore,
		153	composition functions are provided to chain callbacks with filters, such as
		154	the filters defined in the <tt>mime.lua</tt> module.
		155	</p>
		156
		157	<!-- send.file ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
		158
		159	<p class=name id=send.file>
		160	<b>send.file</b>(file, io_err<b>)</b>
		161	</p>
		162
		163	<p class=description>
		164	This function creates a send callback that will return the contents
		165	of a the file, until the file has been entirely sent. When done, the
		166	callback closes the file.
		167	</p>
		168
		169	<p class=parameters>
		170	<tt>File</tt> is a file open for reading. If <tt>file</tt> is
		171	<tt>nil</tt>, <tt>io_err</tt> can contain an error message and the
		172	returned callback just aborts transmission with the error message.
		173	</p>
		174
		175	<p class=return>
		176	Returns a send callback for the file.
		177	</p>
		178
		179	<p class=note>
		180	Note: The function is designed so that it directly accepts the return
		181	values of the <tt>io.open</tt> function.
		182	</p>
		183
		184	<!-- send.string ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
		185
		186	<p class=name id=send.string>
		187	<b>send.string(</b>str<b>)</b>
		188	</p>
		189
		190	<p class=description>
		191	This function creates a send callback that will send
		192	the contents of a string.
		193	</p>
		194
		195	<p class=parameters>
		196	<tt>Str</tt> is the string to be sent.
		197	</p>
		198
		199	<p class=return>
		200	Returns a send callback for the string, or <tt>nil</tt> if the string is
		201	<tt>nil</tt>.
		202	</p>
		203
		204	<p class=note>
		205	Note: If any function in the LuaSocket API receives a <tt>nil</tt>
		206	send callback, it assumes there is nothing to be sent.
		207	</p>
		208
		209	<!-- send.chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
		210
		211	<p class=name id=send.string>
		212	<b>send.chain(</b>send_cb, filter<b>)</b>
		213	</p>
		214
		215	<p class=description>
		216	This function creates a send callback that will send
		217	all data that it gets from another callback,
		218	after passing the data through a filter.
		219	</p>
		220
		221	<p class=parameters>
		222	<tt>Send_cb</tt> is the send callback to be chained to <tt>filter</tt>.
		223	</p>
		224
		225	<p class=return>
		226	Returns a callback chained with the filter.
		227	</p>
		228
		229	(write a note!)
		230
		231	<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
		232
		233	<div class=footer>
		234	<hr>
		235	<center>
		236	<p class=bar>
		237	<a href="home.html">home</a> ·
		238	<a href="home.html#down">download</a> ·
		239	<a href="introduction.html">introduction</a> ·
		240	<a href="reference.html">reference</a>
		241	</p>
		242	<p>
		243	<small>
		244	Last modified by Diego Nehab on <br>
		245	Sat Aug 9 01:00:41 PDT 2003
		246	</small>
		247	</p>
		248	</center>
		249	</div>
		250
		251	</body>
		252	</html>


diff --git a/doc/smtp.html b/doc/smtp.html index 3a30a07..aa92149 100644 --- a/doc/smtp.html +++ b/doc/smtp.html
@@ -36,7 +36,7 @@
36	<h2 id=smtp>SMTP</h2>	36	<h2 id=smtp>SMTP</h2>
37		37
38	<p>	38	<p>
39	The module <tt>smtp.lua</tt> provides functionality to send e-mail	39	The <tt>smtp.lua</tt> module provides functionality to send e-mail
40	messages. The implementation conforms to the Simple Mail Transfer Protocol,	40	messages. The implementation conforms to the Simple Mail Transfer Protocol,
41	<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.	41	<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
42	The other RFC of interest in this implementation is	42	The other RFC of interest in this implementation is