Working with in the manual.

7 files changed, 171 insertions, 62 deletions

diff --git a/TODO b/TODO
index ca5b445..2d846fe 100644
--- a/TODO
+++ b/TODO
@@ -19,38 +19,40 @@
 * Separar as classes em arquivos
 * Retorno de sendto em datagram sockets pode ser refused
 * select sets are now associative
-
-colocar pump.all, pump.step e pump.simplify.
-mudar ltn12.html e usar o exemplo source.cat que está muito melhor.
-
-break smtp.send into c = smtp.open, c:send() c:close()
+* colocar pump.all, pump.step
+* mudar ltn12.html e usar o exemplo source.cat que está muito melhor.
+* break smtp.send into c = smtp.open, c:send() c:close()
+* fazer com que a socket.source e socket.sink sejam "selectable".
+* change mime.eol to output marker on detection of first candidate, instead
+  of on the second. that way it works in one pass for strings that end with 
+  one candidate.
+* unify backbone of smtp and ftp
+* unify filter and send/receive callback. new sink/source/pump idea.
+* get rid of aux_optlstring
+* get rid of unpack in mime.lua
+* create socket.(sink|source).simplify 
+* break chain into a simpler binary chain and a complex (recursive) one. 
+* Create a passive mode option for the FTP (good for firewall).
+* Modules should return their namespace table in the end of the chunk.
+
+ajeitar o manual sobre select, mais liberal agora
+conjunto associativo
 
 falar sobre encodet/wrapt/decodet no manual sobre mime
 
 
 RECEIVE MUDOU!!! (partial stuff) COLOCAR NO MANUAL.
 HTTP.lua mudou bastante também.
-
-fazer com que a socket.source e socket.sink sejam "selectable".
-
-change mime.eol to output marker on detection of first candidate, instead
-of on the second. that way it works in one pass for strings that end with 
-one candidate.
+pump.step usado em todo mundo que recebe source ou sink
 
 colocar um userdata com gc metamethod pra chamar sock_close (WSAClose);
 sources ans sinks are always simple in http and ftp and smtp
-unify backbone of smtp and ftp
 expose encode/decode tables to provide extensibility for mime module
 use coroutines instead of fancy filters
-unify filter and send/receive callback. new sink/source/pump idea.
-get rid of aux_optlstring
-wrap sink and sources with a function that performs the replacement
-get rid of unpack in mime.lua
 
 check garbage collection in test*.lua
 pop3???
 
-break chain into a simpler binary chain and a complex (recursive) one. 
 
 add socket.TIMEOUT to be default timeout? 
 
@@ -123,9 +125,7 @@ to do with it.
 
 Make sure nobody can fuck up with the metatables...
 
-Create a passive mode option for the FTP (good for firewall).
 
-Modules should return their namespace table in the end of the chunk.
 
 Adjust dates in all files
 
diff --git a/doc/reference.html b/doc/reference.html
index 6372e64..ba519c0 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -55,10 +55,10 @@
 </blockquote>
 </blockquote>
 
-<!-- misc ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- global +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <blockquote>
-<a href="global.html">Globals</a>
+<a href="global.html">Global symbols</a>
 <blockquote>
 <a href="global.html#LUASOCKET_LIBNAME">LUASOCKET_LIBNAME</a>,
 <a href="global.html#mime">mime</a>,
@@ -68,32 +68,6 @@
 </blockquote>
 </table>
 
-<blockquote>
-<a href="socket.html">LuaSocket namespace (socket)</a>
-<blockquote>
-<a href="socket.html#bind">bind</a>,
-<a href="socket.html#connect">connect</a>,
-<a href="socket.html#debug">debug</a>,
-<a href="socket.html#dns">dns</a>,
-<a href="socket.html#ftp">ftp</a>,
-<a href="socket.html#http">http</a>,
-<a href="socket.html#protect">protect</a>,
-<a href="socket.html#select">select</a>,
-<a href="socket.html#sink">sink</a>,
-<a href="socket.html#source">source</a>,
-<a href="socket.html#sleep">sleep</a>,
-<a href="socket.html#smtp">smtp</a>,
-<a href="socket.html#time">time</a>,
-<a href="socket.html#tcp">tcp</a>,
-<a href="socket.html#try">try</a>,
-<a href="socket.html#udp">udp</a>,
-<a href="socket.html#url">url</a>,
-<a href="socket.html#version">version</a>.
-</blockquote>
-</blockquote>
-</table>
-
-
 <!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <blockquote>
@@ -175,6 +149,33 @@
 </blockquote>
 </blockquote>
 
+<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<blockquote>
+<a href="socket.html">The socket namespace (socket)</a>
+<blockquote>
+<a href="tcp.html#bind">bind</a>,
+<a href="tcp.html#connect">connect</a>,
+<a href="socket.html#debug">debug</a>,
+<a href="dns.html#dns">dns</a>,
+<a href="ftp.html#ftp">ftp</a>,
+<a href="http.html#http">http</a>,
+<a href="socket.html#protect">protect</a>,
+<a href="socket.html#select">select</a>,
+<a href="socket.html#sink">sink</a>,
+<a href="socket.html#source">source</a>,
+<a href="socket.html#sleep">sleep</a>,
+<a href="smtp.html#smtp">smtp</a>,
+<a href="socket.html#time">time</a>,
+<a href="tcp.html#tcp">tcp</a>,
+<a href="socket.html#try">try</a>,
+<a href="udp.html#udp">udp</a>,
+<a href="url.html#url">url</a>,
+<a href="socket.html#version">version</a>.
+</blockquote>
+</blockquote>
+</table>
+
 <!-- tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <blockquote>
diff --git a/doc/socket.html b/doc/socket.html
index 9372648..bde882b 100644
--- a/doc/socket.html
+++ b/doc/socket.html
@@ -33,7 +33,7 @@
 
 <!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<h2 id=socket>The LuaSocket namespace</h2> 
+<h2 id=socket>The socket namespace</h2> 
 
 <p>
 The <tt>socket</tt> namespace contains the namespace tables for all
@@ -74,7 +74,120 @@ The function an equivalent function that instead of throwing exceptoins,
 returns <tt><b>nil</b></tt> followed by an error message. 
 </p>
 
-<!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=select> 
+socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b>
+</p>
+
+<p class=description>
+Waits for a number of sockets to change status. 
+</p>
+
+<p class=parameters>
+<tt>Recvt</tt> is an array with the sockets to test for characters
+available for reading. Sockets in the <tt>sendt</tt> array are watched to
+see if it is OK to immediately write on them.  <tt>Timeout</tt> is the
+maximum amount of time (in seconds) to wait for a change in status.  A
+<tt><b>nil</b></tt>, negative or omitted <tt>timeout</tt> value allows the
+function to block indefinitely. <tt>Recvt</tt> and <tt>sendt</tt> can also
+be empty tables or <tt><b>nil</b></tt>. Non-socket values in the arrays
+will be silently ignored.
+</p>
+
+<p class=return> The function returns a table with the sockets ready for
+reading, a table with the sockets ready for writing and an error message.
+The error message is "<tt>timeout</tt>" if a timeout condition was met and
+<tt><b>nil</b></tt> otherwise.  The returned tables are associative, to
+simplify the test if a specific socket has changed status.  
+</p>
+
+<p class=note>
+<b>Important Note</b>: a known bug in WinSock causes <tt>select</tt> to fail 
+on non-blocking TCP sockets. The function may return a socket as
+writable even though the socket is <em>not</em> ready for sending.
+</p>
+
+<p class=note>
+<b>Important note</b>: calling select with a server socket in the receive
+parameter before a call to accept does <em>not</em> guarantee
+<a href=tcp.html#accept><tt>accept</tt></a> will return immediately. 
+Use the <a href=tcp.html#timeout><tt>timeout</tt></a> 
+method or <tt>accept</tt> might block forever.  
+</p>
+
+<p class=note>
+Interesting note: as mentioned in some manuals, calling select with both
+sets empty and a non-null timeout is a fairly portable way to sleep with
+sub-second precision.
+</p>
+
+
+<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=sink> 
+socket.<b>sink(</b>mode, socket<b>)</b>
+</p>
+
+<p class=description>
+Creates an 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN012</a>
+sink from a stream socket object. 
+</p>
+
+<p class=parameters>
+<tt>Mode</tt> defines the behaviour of the sink. The following
+options are available:
+</p>
+<ul>
+<li> <tt>"http-chunked"</tt>: sends data through socket after applying the
+<em>chunked transfer coding</em>, closing the socket when done;
+<li> <tt>"close-when-done"</tt>: sends all received data through the
+socket, closing the socket when done; 
+<li> <tt>"keep-open"</tt>: sends all received data through the
+socket, leaving it open when done. 
+</ul>
+<p>
+<tt>Socket</tt> is the stream socket object used to send the data. 
+</p>
+
+<p class=return>
+The function returns a sink with the appropriate behavior. 
+</p>
+
+<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=source> 
+socket.<b>source(</b>mode, socket [, length]<b>)</b>
+</p>
+
+<p class=description>
+Creates an 
+<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN012</a>
+source from a stream socket object. 
+</p>
+
+<p class=parameters>
+<tt>Mode</tt> defines the behaviour of the source. The following
+options are available:
+</p>
+<ul>
+<li> <tt>"http-chunked"</tt>: receives data from socket and removes the
+<em>chunked transfer coding</em> before returning the data;
+<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
+socket. This mode requires the extra argument <tt>length</tt>; 
+<li> <tt>"until-closed"</tt>: receives data from a socket until the other
+side closes the connection. 
+</ul>
+<p>
+<tt>Socket</tt> is the stream socket object used to receive the data. 
+</p>
+
+<p class=return>
+The function returns a source with the appropriate behavior. 
+</p>
+
+<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=try> 
 socket.<b>try(</b>ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub><b>)</b>
diff --git a/src/ftp.lua b/src/ftp.lua
index ee1f9aa..306b77f 100644
--- a/src/ftp.lua
+++ b/src/ftp.lua
@@ -114,7 +114,7 @@ function metat.__index:send(sendt)
         if err then data:close() end
         return ret, err
     end
-    local sink = socket.sink("close-when-empty", data)
+    local sink = socket.sink("close-when-done", data)
     socket.try(ltn12.pump.all(sendt.source, sink, checkstep))
     if string.find(code, "1..") then socket.try(self.tp:check("2..")) end
     return 1
diff --git a/src/smtp.lua b/src/smtp.lua
index 6ddeaae..8e672a0 100644
--- a/src/smtp.lua
+++ b/src/smtp.lua
@@ -51,10 +51,10 @@ function metat.__index:rcpt(to)
     return socket.try(self.tp:check("2.."))
 end
 
-function metat.__index:data(src)
+function metat.__index:data(src, step)
     socket.try(self.tp:command("DATA"))
     socket.try(self.tp:check("3.."))
-    socket.try(self.tp:source(src))
+    socket.try(self.tp:source(src, step))
     socket.try(self.tp:send("\r\n.\r\n"))
     return socket.try(self.tp:check("2.."))
 end
@@ -78,7 +78,7 @@ function metat.__index:send(mailt)
     else
         self:rcpt(mailt.rcpt)
     end
-    self:data(ltn12.source.chain(mailt.source, stuff()))
+    self:data(ltn12.source.chain(mailt.source, stuff()), mailt.step)
 end
 
 function open(server, port)
diff --git a/src/tp.lua b/src/tp.lua
index e9e38a1..4f2a615 100644
--- a/src/tp.lua
+++ b/src/tp.lua
@@ -87,13 +87,9 @@ function metat.__index:getcontrol()
     return self.control
 end
 
-function metat.__index:source(src, instr)
-    while true do
-        local chunk, err = src()
-        if not chunk then return not err, err end
-        local ret, err = self.control:send(chunk)
-        if not ret then return nil, err end
-    end
+function metat.__index:source(source, step)
+    local sink = socket.sink("keep-open", self.control)
+    return ltn12.pump.all(source, sink, step or ltn12.pump.step)
 end
 
 -- closes the underlying control
diff --git a/test/testmesg.lua b/test/testmesg.lua
index 796977e..8b33133 100644
--- a/test/testmesg.lua
+++ b/test/testmesg.lua
@@ -49,6 +49,5 @@ print(socket.smtp.send {
     rcpt = "<diego@cs.princeton.edu>",
     from = "<diego@cs.princeton.edu>",
     source = socket.smtp.message(mesgt),
-    server = "mail.iis.com.br",
-    port = 7
+    server = "mail.cs.princeton.edu"
 })