7 files changed, 319 insertions, 78 deletions

diff --git a/doc/callback.html b/doc/callback.html
index 94af8ff..98b4476 100644
--- a/doc/callback.html
+++ b/doc/callback.html
@@ -31,16 +31,16 @@
 <hr>
 </div>
 
-<!-- stream ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- stream ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
-<h2 id=stream>Streaming with Callbacks</h2> 
+<h2 id=stream>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
+bodies  and FTP file  contents to  be streamed through the
 callback mechanism outlined below.  
 </p>
 
@@ -52,7 +52,7 @@ chunks of data, as the data becomes available. Conversely, the <em>send
 callback</em> mechanism can be used when the application wants to incrementally provide LuaSocket with the data to be sent. 
 </p>
 
-<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=receive> 
 <b>receive_cb(</b>chunk, err<b>)</b>
@@ -60,7 +60,7 @@ callback</em> mechanism can be used when the application wants to incrementally
 
 <p class=description>
 A receive callback will  be repeatedly  called by
-LuaSocket wheneve  new data  is available.  Each time  it is  called, the
+LuaSocket whenever  new data  is available.  Each time  it is  called, the
 callback receives successive chunks of downloaded data. 
 </p>
 
@@ -113,10 +113,129 @@ Together, these two modules provide a powerful interface to send and
 receive information.
 </p>
 
+<!-- done +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=done> 
+socket.callback.<b>done()</b>
+</p>
+
+<p class=description>
+This function creates and returns a callback that successfully terminates 
+the transmission.
+</p>
+
+<!-- fail +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=fail> 
+socket.callback.<b>fail(</b>message<b>)</b>
+</p>
+
+<p class=description>
+This function creates and returns a callback that aborts the
+transmission with a given error <tt>message</tt>. 
+</p>
+
+<!-- receive.concat +++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=receive.concat> 
+socket.callback.<b>receive.concat(</b>cat<b>)</b>
+</p>
+
+<p class=description>
+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. 
+</p>
+
+<p class=parameters>
+<tt>Cat</tt> is the target concat object, or <b><tt>nil</tt></b>. 
+If <tt>cat</tt> is <b><tt>nil</tt></b>, the function creates its own
+concat object. 
+</p>
+
+<p class=return>
+The function returns a receive callback for the file, and the concat object
+that will be used to store the received contents. 
+</p>
+
+<!-- receive.file +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=receive.file> 
+socket.callback.<b>receive.file(</b>file, io_err<b>)</b>
+</p>
+
+<p class=description>
+This function creates a receive callback that stores whatever it receives
+into a file. When done, the callback closes the file. 
+</p>
+
+<p class=parameters>
+<tt>File</tt> is a file handle opened for writing. If <tt>file</tt> is 
+<b><tt>nil</tt></b>, <tt>io_err</tt> can contain an error message. In this
+case, the function returns a callback that just aborts 
+transmission with the error message.
+</p>
+
+<p class=return>
+The function returns a receive callback for the file. 
+</p>
+
+<p class=note>
+Note: This function is designed so that it directly accepts the return 
+values of Lua's IO <tt>io.open</tt> library function.
+</p>
+
+<!-- receive.chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=receive.chain> 
+socket.callback.<b>receive.chain(</b>filter, receive_cb<b>)</b>
+</p>
+
+<p class=description>
+This function creates a receive callback that passes all received data
+through a filter, before handing it to a given receive callback. 
+</p>
+
+<p class=parameters>
+<tt>Cat</tt> is the target concat object, or <b><tt>nil</tt></b>. 
+If <tt>cat</tt> is <b><tt>nil</tt></b>, the function creates its own
+concat object. 
+</p>
+
+<p class=return>
+The function returns a receive callback for the file, and the concat object
+that will be used to store the received contents. 
+</p>
+
+<p class=note>
+Note: Several filters are defined in the <a href=mime.html>MIME</a> 
+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.
+</p>
+
+<pre class=example>
+string_cb, concat = socket.callback.receive.concat()
+receive_cb = socket.callback.receive.chain(
+   socket.mime.decode("quoted-printable"),
+   string_cb
+)
+</pre>
+
+<p class=note>
+The call to <tt>callback.chain</tt> creates a chained
+receive callback that decodes data using the 
+<tt><a href=mime.html#decode>mime.decode</a></tt> 
+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.
+</p>
+
 <!-- send.file ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=send.file> 
-<b>send.file</b>(file, io_err<b>)</b>
+socket.callback.<b>send.file(</b>file, io_err<b>)</b>
 </p>
 
 <p class=description>
@@ -126,25 +245,25 @@ When done, the callback closes the file.
 </p>
 
 <p class=parameters>
-<tt>File</tt> is a file opened for reading. If <tt>file</tt> is 
+<tt>File</tt> is a file handle opened for reading. If <tt>file</tt> is 
 <b><tt>nil</tt></b>, <tt>io_err</tt> can contain an error message. In this
 case, the function returns a callback that just aborts 
 transmission with the error message.
 </p>
 
 <p class=return>
-Returns a send callback for the file. 
+The function returns a send callback for the file. 
 </p>
 
 <p class=note>
 Note: This function is designed so that it directly accepts the return 
-values of the <tt>io.open</tt> function.
+values of Lua's IO <tt>io.open</tt> library function.
 </p>
 
 <!-- send.string ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=send.string> 
-<b>send.string(</b>str, err<b>)</b>
+socket.callback.<b>send.string(</b>str, err<b>)</b>
 </p>
 
 <p class=description>
@@ -154,26 +273,17 @@ the contents of a string.
 
 <p class=parameters>
 <tt>Str</tt> is the string to be sent. 
-<!--
-If <tt>str</tt> is
-<b><tt>nil</tt></b>, <tt>err</tt> can optionally contain an error message.
--->
 </p>
 
 <p class=return>
-Returns a send callback for the string, or <b><tt>nil</tt></b> if the string is
-<b><tt>nil</tt></b>.
-</p>
-
-<p class=note>
-Note: A <tt>nil</tt></b> 
-send callback is equivalent to a callback that returns the empty string. 
+It returns a send callback for the string, 
+or <b><tt>nil</tt></b> if <tt>str</tt> is <b><tt>nil</tt></b>.
 </p>
 
 <!-- send.chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=send.chain> 
-<b>send.chain(</b>send_cb, filter<b>)</b>
+socket.callback.<b>send.chain(</b>send_cb, filter<b>)</b>
 </p>
 
 <p class=description>
@@ -207,9 +317,9 @@ send_cb = socket.callback.send.chain(
 </pre>
 
 <p class=note>
-The call to <a href=mime.html#chain><tt>socket.mime.chain</tt></a> 
+The call to <a href=mime.html#chain><tt>mime.chain</tt></a> 
 creates a chained filter that encodes it's input and then breaks it
-into lines. The call to <tt>socket.callback.chain</tt> creates a chained
+into lines.  The call to <tt>callback.chain</tt> creates a chained
 send callback that reads the file from disk and passes it through the
 filter before sending it.
 </p>
diff --git a/doc/dns.html b/doc/dns.html
index 17cee45..71a9719 100644
--- a/doc/dns.html
+++ b/doc/dns.html
@@ -36,8 +36,7 @@
 <h2 id=dns>DNS</h2> 
 
 <p>
-The following functions can be used to convert between host names and IP
-addresses. Both functions return <em>all</em> information returned by the
+Name resolution function return <em>all</em> information returned by the
 resolver in a table of the form:
 </p>
 
@@ -53,6 +52,21 @@ resolved = {<br>
 Note that the <tt>alias</tt> list can be empty.
 </p>
 
+<!-- gethostname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=gethostname> 
+socket.dns.<b>gethostname()</b>
+</p>
+
+<p class=description>
+Returns the standard host name for the machine. 
+</p>
+
+<p class=return>
+The function returns a string with the host name. 
+</p>
+
+
 <!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=tohostname> 
@@ -74,7 +88,6 @@ the  resolver.  In  case of error, the function returns <b><tt>nil</tt></b>
 followed by an error message.  
 </p>
 
-
 <!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=toip> 
diff --git a/doc/http.html b/doc/http.html
index f977ea9..f82f515 100644
--- a/doc/http.html
+++ b/doc/http.html
@@ -49,7 +49,7 @@ implementation    conforms     to    the    HTTP/1.1     standard,
 The module exports functions that provide HTTP functionality in different
 levels of abstraction, from a simple <a
 href="#get"><tt>get</tt></a>, to the generic, stream oriented
-<a href="#request_cb"> <tt>request_cb</tt></a>.
+<a href="#request_cb"><tt>request_cb</tt></a>.
 </p>
 
 <p>
diff --git a/doc/index.html b/doc/index.html
index 620f385..a2c2d59 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -40,7 +40,8 @@ LuaSocket  is a  <a href="http://www.lua.org">Lua</a>  extension library
 that is composed by two parts: a C layer that provides  support for the TCP
 and UDP transport layers, and a set of Lua modules that add support for
 the SMTP (sending  e-mails),  HTTP  (WWW access)  and  FTP  (uploading  and
-downloading files) protocols. 
+downloading files) protocols and other functionality commonly needed by
+applications that deal with the Internet. 
 </p>
 
 <p>
@@ -106,10 +107,25 @@ This  binary has been compiled  with the <tt>LUASOCKET_DEBUG</tt>
 option, and  should be able to run the automatic test procedures.
 </p>
 
+<!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<h2 id=thanks>Special thanks</h2>
+
+<p>
+Throughout LuaSocket its history, many people gave sugestions that helped
+improve it. For that, I thank the Lua comunity. 
+Special thanks go to
+David Burgess, who has pushed the library to a new level of quality and
+from whom I have learned a lot stuff that doesn't show up in RFCs.
+Special thanks also to Carlos Cassino, who played a big part in the 
+extensible design seen in the C core of LuaSocket 2.0. 
+</p>
+
 <!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <h2 id=new>What's New</h2>
 
+
 <p>
 Most of  the changes for  2.0 happened in the C layer, which
 has been almost completely rewritten. The code has been ported to Lua 5.0
diff --git a/doc/reference.html b/doc/reference.html
index 0bfd378..e6efb6e 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -40,6 +40,10 @@
 <blockquote>
 <a href="callback.html">Callbacks (socket.callback)</a>
 <blockquote>
+<a href="callback.html#done">done</a>,
+<a href="callback.html#fail">fail</a>.
+</blockquote>
+<blockquote>
 <a href="callback.html#send">send</a>:
 <a href="callback.html#send.chain">chain</a>,
 <a href="callback.html#send.file">file</a>,
@@ -121,7 +125,7 @@
 <blockquote>
 <a href="mime.html">MIME (socket.mime) </a>
 <blockquote>
-<a href="mime.html#filters">filters</a>:
+<a href="mime.html#high">high-level</a>:
 <a href="mime.html#decode">canonic</a>,
 <a href="mime.html#chain">chain</a>,
 <a href="mime.html#decode">decode</a>,
@@ -129,7 +133,7 @@
 <a href="mime.html#wrap">wrap</a>.
 </blockquote>
 <blockquote>
-<a href="mime.html#low-level">low-level</a>:
+<a href="mime.html#low">low-level</a>:
 <a href="mime.html#b64">b64</a>,
 <a href="mime.html#unb64">unb64</a>,
 <a href="mime.html#eol">eol</a>,
diff --git a/doc/tcp.html b/doc/tcp.html
index eb4cdfa..34d6c6e 100644
--- a/doc/tcp.html
+++ b/doc/tcp.html
@@ -44,10 +44,11 @@ socket.<b>tcp()</b>
 <p class=description> 
 Creates and returns a TCP master object. A master object can
 be transformed into a server object with the method 
-<a href=#bind><tt>bind</tt></a> or into a client object with the method 
-<a href=#connect><tt>connect</tt></a>. The only other method
-supported by a master object is the <a href=#close><tt>close</tt></a>
-method.</p>
+<a href=#listen><tt>listen</tt></a> (after a call to <a
+href=#bind><tt>bind</tt></a>) or into a client object with 
+the method <a href=#connect><tt>connect</tt></a>. The only other 
+method supported by a master object is the 
+<a href=#close><tt>close</tt></a> method.</p>
 
 <p class=return>
 In case of success, a new master object is returned. In case of error,
@@ -67,8 +68,9 @@ object and returns a client object representing that connection.
 
 <p class=return>
 If a connection is successfully initiated, a client object is returned.  
-If a  timeout condition  is  met,  the method  returns <b><tt>nil</tt></b> followed
-by the error string '<tt>timeout</tt>'. 
+If a  timeout condition  is  met,  the method  returns <b><tt>nil</tt></b>
+followed by the error string '<tt>timeout</tt>'. Other errors are 
+reported by <b><tt>nil</tt></b> followed by a message describing the error.
 </p>
 
 <p class=note>
@@ -77,25 +79,18 @@ with   a  server   object   in
 the <tt>receive</tt>  parameter  before  a   call  to  <tt>accept</tt> does
 <em>not</em> guarantee  <tt>accept</tt> will  return immediately.  Use the <a
 href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt>
-might block until <em>another</em> client shows up.
+might block until <em>another</em> client shows up. 
 </p>
 
 <!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <p class=name id=bind> 
-master:<b>bind(</b>address, port [, backlog]<b>)</b>
+master:<b>bind(</b>address, port<b>)</b>
 </p>
 
 <p class=description>
 Binds a master object to <tt>address</tt> and <tt>port</tt> on the
-local host, transforming it into a server object.  Server
-objects support the 
-<a href=#accept><tt>accept</tt></a>,  
-<a href=#getsockname><tt>getsockname</tt></a>, 
-<a href=#setoption><tt>setoption</tt></a>, 
-<a href=#settimeout><tt>settimeout</tt></a>, 
-and <a href=#close><tt>close</tt></a> methods.  
-</p>
+local host. 
 
 <p class=parameters>
 <tt>Address</tt> can be an IP address or a host name. 
@@ -103,10 +98,7 @@ and <a href=#close><tt>close</tt></a> methods.
 If <tt>address</tt>
 is '<tt>*</tt>', the system binds to all local interfaces
 using the <tt>INADDR_ANY</tt> constant. If <tt>port</tt> is 0, the system automatically
-chooses an ephemeral port.  The optional parameter <tt>backlog</tt>, which
-defaults to 1, specifies the  number  of  client connections that can
-be queued waiting for service. If the queue is full and another  client
-attempts connection,  the connection is  refused.
+chooses an ephemeral port.  
 </p>
 
 <p class=return>
@@ -115,8 +107,8 @@ method returns <b><tt>nil</tt></b> followed by an error message.
 </p>
 
 <p class=note>
-Note: The function <tt>socket.bind</tt> is available and is a short
-for <a href=#socket.tcp><tt>socket.tcp</tt></a> followed by the <tt>bind</tt> method.
+Note: The function <a href=#socket.bind><tt>socket.bind</tt></a> 
+is available and is a shortcut for the creation server sockets.
 </p>
 
 <!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
@@ -150,7 +142,8 @@ master:<b>connect(</b>address, port<b>)</b>
 
 <p class=description>
 Attempts to connect a master object to a remote host, transforming it into a
-client object. Client objects support methods 
+client object. 
+Client objects support methods 
 <a href=#send><tt>send</tt></a>,
 <a href=#receive><tt>receive</tt></a>, 
 <a href=#getsockname><tt>getsockname</tt></a>, 
@@ -170,8 +163,15 @@ describing the error. In case of success, the method returns 1.
 </p>
 
 <p class=note>
-Note: The function <tt>socket.connect</tt> is available and is a short
-for <a href=#socket.tcp><tt>socket.tcp</tt></a> followed by the <tt>connect</tt> method.
+Note: The function <a href=#socket.connect><tt>socket.connect</tt></a> 
+is available and is a shortcut for the creation of client sockets.
+</p>
+
+<p class=note>
+Note: Starting with LuaSocket 2.0, 
+the <a href=#settimeout><tt>settimeout</tt></a>
+function affects the behavior of connect, causing it to return in case of
+a timeout error.
 </p>
 
 <!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
@@ -210,12 +210,32 @@ The method returns a string with local IP address and a number with
 the port. In case of error, the method returns <b><tt>nil</tt></b>.
 </p>
 
-<p class=note>
-Note: Naturally, for a server object, the address and port returned are
-those passed to the <a href=#bind>bind</a> method. If the port value
-passed to bind was 0, the OS assigned ephemeral port is returned. For
-client objects, both the address and port are ephemeral and these are the
-values returned.  
+<!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=listen> 
+master:<b>listen(</b>backlog<b>)</b>
+</p>
+
+<p class=description>
+Specifies the socket is willing to receive connections, transforming the
+object into a server object.  Server objects support the 
+<a href=#accept><tt>accept</tt></a>,  
+<a href=#getsockname><tt>getsockname</tt></a>, 
+<a href=#setoption><tt>setoption</tt></a>, 
+<a href=#settimeout><tt>settimeout</tt></a>, 
+and <a href=#close><tt>close</tt></a> methods.  
+</p>
+
+<p class=parameters>
+The parameter <tt>backlog</tt> specifies the  number  of  client 
+connections that can
+be queued waiting for service. If the queue is full and another  client
+attempts connection,  the connection is  refused.
+</p>
+
+<p class=return>
+In case of  success, the  method returns  1. In case of error, the
+method returns <b><tt>nil</tt></b> followed by an error message.
 </p>
 
 <!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
@@ -242,8 +262,8 @@ closed. No end-of-line translation is performed;
 terminated by a  LF character (ASCII&nbsp;10), optionally  preceded by a
 CR character (ASCII&nbsp;13). The CR and LF characters are not included in
 the returned line. This is the default pattern;
-<li> <tt>number</tt>:  causes the  method to read  <tt>number</tt> raw
-bytes from the socket.
+<li> <tt>number</tt>:  causes the  method to read  a specified <tt>number</tt> 
+of bytes from the socket.
 </ul>
 
 <p class=return>
@@ -311,22 +331,30 @@ are sure you need it.
 depends on the option being set:
 
 <ul>
-<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> disables the
-Nagle's algorithm for the connection;
+
+<li> '<tt>keepalive</tt>':  Setting this option to <tt>true</tt> enables
+the periodic transmission of messages on a connected socket. Should the
+connected party fail to respond to these messages, the connection is
+considered broken and processes using the socket are notified; 
+
 <li> '<tt>linger</tt>': Controls the action taken when unsent data are
 queued on a socket and a close is performed.  The value is a table with a
 boolean entry '<tt>on</tt>' and a numeric entry for the time interval
-'<tt>timeout</tt>' in seconds.
- If the '<tt>on</tt>' field is set to <tt>true</tt>,
-the system will block the process on the close attempt until it is able to
-transmit the data or until '<tt>timeout</tt>' has passed. If '<tt>on</tt>'
-is <tt>false</tt> and a close is issued, the system will process the close
-in a manner that allows the process to continue as quickly as possible. I
-do not advise you to set this to anything other than zero. 
-<li> '<tt>keepalive</tt>':  Setting this option to <tt>true</tt> enables
-the periodic transmission of messages on a connected socket. Should the
-     connected party fail to respond to these messages, the connection is
-considered broken and processes using the socket are notified. 
+'<tt>timeout</tt>' in seconds. If the '<tt>on</tt>' field is set to
+<tt>true</tt>, the system will block the process on the close attempt until
+it is able to transmit the data or until '<tt>timeout</tt>' has passed. If
+'<tt>on</tt>' is <tt>false</tt> and a close is issued, the system will
+process the close in a manner that allows the process to continue as
+quickly as possible. I do not advise you to set this to anything other than
+zero; 
+
+<li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules
+used in validating addresses supplied in a call to 
+<a href=#bind><tt>bind</tt></a> should allow reuse of local addresses;
+
+<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> 
+disables the Nagle's algorithm for the connection.
+
 </ul>
 
 <p class=return>
@@ -382,7 +410,9 @@ indefinitely. Negative timeout values have the same effect.
 Note: although  timeout values  have millisecond  precision in LuaSocket,
 large  blocks can cause I/O functions not to  respect timeout values due
 to the time the library takes to  transfer blocks to and from the  OS
-and to and from the Lua interpreter. 
+and to and from the Lua interpreter. Also, function that accept host names
+and perform automatic name resolution might be blocked by the resolver for
+longer than the specified timeout value.
 </p>
 
 <p class=note>
@@ -391,6 +421,30 @@ changed for sake of uniformity, since all other method names already
 contained verbs making their imperative nature obvious.
 </p>
 
+<!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id=shutdown>
+client:<b>shutdown(</b>mode<b>)</b><br>
+</p>
+
+<p class=description>
+Shuts down part of a full duplex connection. 
+</p>
+
+<p class=parameters>
+Mode tells which way of the connection should be shut down and can
+take the value:
+<ul>
+<li>"<tt>both</tt>": disallow further sends and receives on the object.
+This is the default mode;
+<li>"<tt>send</tt>": disallow further sends on the object;
+<li>"<tt>receive</tt>": disallow further receives on the object.
+</ul>
+
+<p class=return>
+This function returns 1.
+</p>
+
 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <div class=footer>
diff --git a/doc/url.html b/doc/url.html
index 0eafafa..f3a7cb7 100644
--- a/doc/url.html
+++ b/doc/url.html
@@ -241,6 +241,50 @@ returning a list with all the parsed segments, the function unescapes all
 of them. 
 </p>
 
+<!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="escape">
+socket.url.<b>escape(</b>content<b>)</b>
+</p>
+
+<p class=description>
+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.
+</p>
+
+<p class=parameters>
+<tt>Content</tt> is the string to be encoded.
+</p>
+
+<p class=result>
+The function returns the encoded string.
+</p>
+
+<pre class=example>
+code = socket.url.escape("/#?;")
+-- code = "%2f%23%3f%3b"
+</pre>
+
+<!-- unescape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="unescape">
+socket.url.<b>unescape(</b>content<b>)</b>
+</p>
+
+<p class=description>
+Removes  the   URL   escaping    content   coding   from   a string.
+</p>
+
+<p class=parameters>
+<tt>Content</tt> is the string to be decoded.
+</p>
+
+<p class=return>
+The function returns the decoded string. 
+</p>
+
 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 
 <div class=footer>