From ac4aac0909da26befaaeb6b415f66cf35b6980e0 Mon Sep 17 00:00:00 2001
From: Diego Nehab <diego@tecgraf.puc-rio.br>
Date: Fri, 18 Jun 2004 08:02:09 +0000
Subject: Implemented safe exceptions. This looks preeety good.

---
 doc/reference.html |  3 ++-
 doc/socket.html    | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 doc/tcp.html       | 28 ++++++++++++++---------
 3 files changed, 84 insertions(+), 13 deletions(-)

(limited to 'doc')

diff --git a/doc/reference.html b/doc/reference.html
index 607958b..f130d7b 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -143,8 +143,9 @@
 <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#skip">skip</a>,
 <a href="socket.html#sleep">sleep</a>,
+<a href="socket.html#source">source</a>,
 <a href="socket.html#time">time</a>,
 <a href="tcp.html#tcp">tcp</a>,
 <a href="socket.html#try">try</a>,
diff --git a/doc/socket.html b/doc/socket.html
index d7739f8..06296a3 100644
--- a/doc/socket.html
+++ b/doc/socket.html
@@ -169,6 +169,49 @@ socket, leaving it open when done.
 The function returns a sink with the appropriate behavior. 
 </p>
 
+<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=skip> 
+socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ...  ret<sub>N</sub>]<b>)</b>
+</p>
+
+<p class=description>
+Drops a number of arguments and returns the remaining.
+</p>
+
+<p class=parameters>
+<tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to
+<tt>ret<sub>N</sub></tt> are the arguments.
+</p>
+
+<p class=return> 
+The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
+</p>
+
+<p class=note>
+Note: This function is useful to avoid creation of dummy variables:
+</p>
+
+<pre class=example>
+-- get the status code and separator from SMTP server reply 
+local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
+</pre>
+
+<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=sleep> 
+socket.<b>sleep(</b>time<b>)</b>
+</p>
+
+<p class=description>
+Freezes the program execution during a given amount of time.
+</p>
+
+<p class=parameters> 
+<tt>Time</tt> is the number of seconds to sleep for. 
+The function truncates <tt>time</tt> to the nearest integer. 
+</p>
+
 <!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=source> 
@@ -201,6 +244,27 @@ side closes the connection.
 The function returns a source with the appropriate behavior. 
 </p>
 
+<!-- time ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=time> 
+socket.<b>time()</b>
+</p>
+
+<p class=description>
+Returns the time in seconds, relative to the origin of the 
+universe. Only time differences are meaninful. 
+</p>
+
+<p class=return> 
+The function returns the time as a number.
+</p>
+
+<pre class=example>
+t = socket.time()
+-- do stuff
+print(socket.time() - t .. " seconds elapsed")
+</pre>
+
 <!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=try> 
@@ -212,7 +276,7 @@ Throws an exception in case of error.
 </p>
 
 <p class=parameters>
-<tt>Ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> can be arbitrary
+<tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary
 arguments, but are usually the return values of a function call 
 nested with <tt>try</tt>. 
 </p>
diff --git a/doc/tcp.html b/doc/tcp.html
index 781ec6f..cd417a5 100644
--- a/doc/tcp.html
+++ b/doc/tcp.html
@@ -277,9 +277,10 @@ the transmission.
 <p class=note>
 <b>Important note</b>: This function was changed <em>severely</em>. It used
 to support multiple patterns (but I have never seen this feature used) and
-partial results used to be returned in the same way as successful results.
-This last feature violated the idea that all functions should return
-<tt><b>nil</b></tt> on error.  Thus the change.  
+now it doesn't anymore.  Partial results used to be returned in the same 
+way as successful results. This last feature violated the idea that all
+functions should return <tt><b>nil</b></tt> on error.  Thus it was changed
+too. 
 </p>
 
 <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
@@ -300,20 +301,25 @@ result to LuaSocket instead of passing several independent strings.
 </p>
 
 <p class=return>
-The method returns the number of bytes accepted by the transport layer,
-followed by an error code. The error code is <b><tt>nil</tt></b> if the operation
-completed with no errors, the string '<tt>closed</tt>' in case
+If successful, the method returns the number of bytes accepted by 
+the transport layer. In case of error, the method returns 
+<b><tt>nil</tt></b>, followed by an error message, followed by the
+partial number of bytes accepted by the transport layer.  
+The error message can be '<tt>closed</tt>' in case
 the connection was  closed before the transmission was  completed or the
 string  '<tt>timeout</tt>'  in  case  there was  a  timeout  during  the
 operation.
 </p>
 
 <p class=note>
-Note: The return values for the <tt>send</tt> method have been changed in
-LuaSocket 2.0! In previous versions, the method returned only the
-error message. Since returning <b><tt>nil</tt></b> in case of success goes 
-against all other LuaSocket methods and functions, the 
-<tt>send</tt> method been changed for the sake of uniformity. 
+<b>Important note</b>: 
+The return values for the <tt>send</tt> method have been changed in
+LuaSocket 2.0 alpha <b>and again</b> in the beta (sorry)! 
+In previous versions, the method returned only the
+error message. Since returning <b><tt>nil</tt></b> in case of success was
+nonsense, in alpha the first return value became the number of bytes sent.
+Alas, it wasn't returning <tt><b>nil</b></tt> in case of
+error. So it was changed again in beta. 
 </p>
 
 <!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
-- 
cgit v1.2.3-55-g6feb