From 843a431ef98fd541d98fd3898463985d9bfcde28 Mon Sep 17 00:00:00 2001 From: Diego Nehab Date: Tue, 15 Jun 2004 23:00:56 +0000 Subject: [PATCH] Almost done with manual... --- doc/dns.html | 4 +- doc/http.html | 201 +++++++++++++++--------------------------- doc/index.html | 77 ++++++++++------ doc/introduction.html | 75 ++++++++-------- doc/mime.html | 2 +- 5 files changed, 165 insertions(+), 194 deletions(-) diff --git a/doc/dns.html b/doc/dns.html index 8e63407..226a604 100644 --- a/doc/dns.html +++ b/doc/dns.html @@ -70,7 +70,7 @@ The function returns a string with the host name.

-socket.dns.tohostname() +socket.dns.tohostname(address)

@@ -91,7 +91,7 @@ followed by an error message.

-socket.dns.toip() +socket.dns.toip(address)

diff --git a/doc/http.html b/doc/http.html index 16595f7..39eb2e4 100644 --- a/doc/http.html +++ b/doc/http.html @@ -98,36 +98,36 @@ Note: MIME headers are independent of order. Therefore, there is no problem in representing them in a Lua table.

+

+The following constants can be set to control the default behaviour of +the HTTP module: +

+ + +

-socket.http.get(url)
-socket.http.get{
-  url = string,
-  headers = header-table,
-  user = string,
-  password = string,
-  stay = bool,
-} +http.get(url)

-Performs the HTTP method GET. +Performs the HTTP method GET.

-The function can be -called either directly with a url or with a request table. -The use of a request table allows complete control over the components of -the request. Values passed explicitly as fields of the request table -override those given by the url. For a description of the fields, -see the request function. +Url identifies the entity to retrieve.

-The function returns the response message body, the mime headers, the -status code and an error message (if any). In case of failure, the -function returns all information it managed to gather. +If successful, the function returns the response message body, the mime +headers, and the status code. In case of failure, the +function returns nil followed by an error message.

@@ -136,35 +136,30 @@ Note: The function is trivially implemented with the use of the 

+-- load the http module
+http = require("http")
+
 -- connect to server "www.tecgraf.puc-rio.br" and retrieves this manual
 -- file from "/luasocket/http.html"
-b, h, c, e = socket.http.get("http://www.tecgraf.puc-rio.br/luasocket/http.html")
+b, h, c = http.get("http://www.tecgraf.puc-rio.br/luasocket/http.html")
 
 -- connect to server "www.tecgraf.puc-rio.br" and tries to retrieve
 -- "~diego/auth/index.html". Fails because authentication is needed.
-b, h, c, e = socket.http.get("http://www.tecgraf.puc-rio.br/~diego/auth/index.html")
+b, h, c = http.get("http://www.tecgraf.puc-rio.br/~diego/auth/index.html")
 -- b returns some useless page telling about the denied access, 
 -- h returns authentication information
 -- and c returns with value 401 (Authentication Required)
 
 -- tries to connect to server "wrong.host" to retrieve "/"
 -- and fails because the host does not exist.
-b, h, c, e = socket.http.get("http://wrong.host/")
--- b, h, c are nil, and e returns with value "host not found"
+r, e = http.get("http://wrong.host/")
+-- r is nil, and e returns with value "host not found"

-socket.http.post(url, body)
-socket.http.post{
-   url = string,
-   headers = header-table,
-   body = string,
-   user = string,
-   password = string,
-   stay = bool,
-} +http.post(url, body)

@@ -181,50 +176,64 @@ Note: This function is also trivially implemented with the use of the

-socket.http.request{
-  method = string,
+http.request{
  url = string,
-  headers = header-table,
-  body = string,
-  user = string,
-  password = string,
-  stay = string,
+  [sink = LTN12 sink],]
+  [method = string,]
+  [headers = header-table,]
+  [source = LTN12 source],
+  [step = LTN12 pump step,]
+  [proxy = string,]
+  [redirect = boolean]
}

-Performs the generic HTTP request using. +Performs the generic HTTP request, controled by a request table.

-The request uses method on url -sending the request headers and request body in the -request message. If authentication information is provided, the function +The most important parameters are the url and the LTN12 +sink that will receive the downloaded content. +Any part of the url can be overriden by including +the appropriate field in the request table. +If authentication information is provided, the function uses the Basic Authentication Scheme (see note) -to retrieve the document. User and password provided -explicitly override those given by the url. The stay -parameter, when set to anything but nil, prevents the function -from automatically following 301 or 302 server redirect messages. +to retrieve the document. If sink is nil, the +function discards the downloaded data. The optional parameters are the +following:

+

-The function returns a table with all components of the response message -it managed to retrieve. The response table has the following form: +In case of failure, the function returns nil followed by an +error message. If successful, the function returns a table +with all components of the response message. The response table has the following form:

-response = {
-  body = string,
+respt = {
  headers = header-table,
  status = string,
  code = number,
-  error = string
}

Even when there was failure (URL not found, for example), the -function may succeed retrieving a message body (a web page informing the +function usually succeeds retrieving a message body (a web page informing the URL was not found or some other useless page). To make sure the operation was successful, check the returned status code. For a list of the possible values and their meanings, refer to RFC 

+-- load the http module
+http = require("http")
+
 -- Requests information about a document, without downloading it.
 -- Useful, for example, if you want to display a download gauge and need
 -- to know the size of the document in advance
-response = socket.http.request {
+respt = http.request {
   method = "HEAD",
   url = "http://www.tecgraf.puc-rio.br/~diego"
 }
 -- Would return the following headers:
--- response.headers = {
+-- respt.headers = {
 --   date = "Tue, 18 Sep 2001 20:42:21 GMT",
 --   server = "Apache/1.3.12 (Unix)  (Red Hat/Linux)",
 --   ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT",
@@ -276,10 +288,14 @@ authentication is required.
 

 
 
+-- load required modules
+http = require("http")
+mime = require("mime")
+
 -- Connect to server "www.tecgraf.puc-rio.br" and tries to retrieve
 -- "~diego/auth/index.html", using the provided name and password to
 -- authenticate the request
-response = socket.http.request{
+respt = http.request{
   url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
   user = "diego",
   password = "password"
@@ -287,83 +303,12 @@ response = socket.http.request{
 
 -- Alternatively, one could fill the appropriate header and authenticate
 -- the request directly.
-headers = {
-  authentication = "Basic " .. socket.code.base64("diego:password")
-}
-response = socket.http.request {
+respt = http.request {
   url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
-  headers = headers
+  headers = { authentication = "Basic " .. (mime.b64("diego:password")) }
 }
 

 
-
-
-

-socket.http.request_cb(request, response)
-

-
-

-Performs the generic HTTP  request.
-

-
-

-The function receives two tables as parameters. The request table
-provides information about the request: 
-

-
-

-request = {

-  method = string,

-  url = string,

-  headers = header-table,

-  body_cb = send-callback,

-  user = string,

-  password = string,

-  stay = string,

-}
-

-
-

-The function uses the HTTP method specified in 
-request.method on the URL request.url,
-sending request.headers along with the request. The request
-message  body  is sent  via the send  callback request.body_cb.
-If authentication information is provided, the function    uses   the Basic
-Authentication    Scheme   (see    note)  to
-retrieve  the document.  Request.user and
-request.password  override  those  given  by the
-request.url.  The request.stay  parameter,  when set  to
-anything but nil, prevents the function  from automatically
-following 301 or 302 server redirect messages.  
-

-
-

-The response table specifies information about the desired
-response:
-

-
-

-response = {

-  body_cb = receive-callback

-}
-

-
-

-The function  returns the same  response table  as that returned  by the
-socket.http.request  function, except  the  response  message body  is
-returned    to    the    receive   callback   given    by    the
-response.body_cb field. 
-

-
-

-Note: For more information on callbacks, please refer to 
-Streaming with callbacks.
-

-
-

-Note: Method names are case sensitive
-

-
 
 
 

diff --git a/doc/index.html b/doc/index.html
index a2c2d59..c4c1e2f 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -47,7 +47,7 @@ applications that deal with the Internet.
 

 Network support has been  implemented so that it  is both efficient and
 simple to use.  LuaSocket can be used by any Lua application once it has
-been properly linked with and initialized by the interpreter running the
+been properly initialized by the interpreter running the
 Lua application.  The code has been tested and runs well on several Windows
 and Unix platforms. 
 

@@ -61,7 +61,7 @@ LuaSocket.
 

 
 

-Copyright © 1999-2003 Tecgraf/PUC-Rio. All rights reserved. 

+Copyright © 1999-2004 Tecgraf/PUC-Rio. All rights reserved. 

 Author: Diego Nehab
 

 
@@ -70,7 +70,7 @@ Author: Diego Nehab
 
Download

 
 

-LuaSocket version  2.0 alpha is now  available for download! It  is
+LuaSocket version  2.0 beta is now  available for download! It  is
 compatible with   Lua 5.0   and   has    been   tested   on
 Windows XP, Linux, and Mac OS X. 
 

@@ -81,8 +81,8 @@ The library can be downloaded in source code from the following links:
 
 

 

-luasocket-2.0-alpha.tar.gz 

-luasocket-2.0-alpha.zip
+luasocket-2.0-beta.tar.gz 

+luasocket-2.0-beta.zip
 

 

 
@@ -112,11 +112,11 @@ option, and  should be able to run the automatic test procedures.
 
Special thanks

 
 

-Throughout LuaSocket its history, many people gave sugestions that helped
+Throughout LuaSocket's 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.
+from whom I have learned a lot of 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. 
 

@@ -127,7 +127,7 @@ extensible design seen in the C core of LuaSocket 2.0.
 
 
 

-Most of  the changes for  2.0 happened in the C layer, which
+Everything is new! Many changes for  2.0 happened in the C layer, which
 has been almost completely rewritten. The code has been ported to Lua 5.0
 and greatly improved.  There have also been some API changes
 that made  the interface simpler and  more consistent. Here are  some of
@@ -140,58 +140,85 @@ the changes that made it into version 2.0:
      pipes (on Unix) and named pipes (on windows) as a bonus;
 
 
  •  Following the Lua 5.0 trend, all functions provided by the library are
-     in the namespace socket.  Functions such as
+     in namespaces. These should be obtained with calls to the
+    require function. Functions such as
      send/receive/timeout/close etc do not exist anymore as stand-alone
      functions. They are now only available as methods of the appropriate
      objects;
 
 
  •  All functions return a non-nil value as first return value if successful.
-     All functions return whatever could be retrieved followed by error message
-     in case of error. The best way to check for errors is to check for the
-     presence of an error message;  
+     All functions return nil followed by error message
+     in case of error; 
 
-
  •  UDP connected   sockets can break association with peer by calling
+
  •  Better error messages and parameter checking;
+
+
  •  Should be interrupt safe; 
+
+
  •  UDP connected sockets can break association with peer by calling
      setpeername with address '*';
 
 
  •  TCP has been changed to become more uniform.  First create an object,
      then connect or bind if needed, and finally use I/O functions. The
      socket.connect and socket.bind functions are still
      provided for simplicity, but they just call socket.tcp followed 
-     by the connect or bind methods;
+     by the connect or bind/listen methods;
 
-
  •  Better error messages and parameter checking;
+
  •  Greatly reduced the number of times select is called during data
+     transfers, by calling only on failure;
+
+
  •  TCP can set timeout value before connecting and also bind to local
+     address before connecting; 
+
+
  •  socket.select returns associative sets and checks if 
+     sockets had buffered data; 
 
 
  •  socket.sleep and socket.time are now part of the
      library and are supported. They used to be available only when
      LUASOCKET_DEBUG was defined, but it turns out they might be useful for
      applications;
 
-
  •  Socket options interface has been improved and TCP objects also 
-     support socket options.
+
  •  socket.try and socket.protect provide a simple
+     interface to exceptions that proved very in the implementation of
+     high-level modules; 
+
+
  •  Socket options interface has been improved. TCP objects also 
+     support socket options and many other options were added.
 
 
 
+
    
+Lots of changes in the Lua modules, too. The new MIME and LTN12 modules
+make all other modules much more powerful. The main new functionality is
+the support for multipart messages in the SMTP module.
+
    
+
+
      
+
+
    •  
+
+
    
+
+
 
 
 
    Incompatibilities with previous versions
    
 
 
      
+
 
    •  The introduction of namespaces affects all programs that use LuaSocket,
 specially code that relies on global functions. These are no longer
 available. Note that even the support modules (http, smtp
-etc) have been moved to the namespace (i.e.  socket.http,
-socket.smtp etc);
+etc) are independent now and should be "requireed"; 
 
-
    •  WARNING: The new send,
+
    •  FTP, SMTP and HTTP are completely new; I am sure you will
+agree the new stuff is better; 
+
+
    •  WARNING: The new send, receive,
 sendto, setpeername and setsockname, 
-ftp.put, ftp.put_cb return convention WILL break old code; 
+return convention WILL break old code; 
 
 
    •  Interface to options has changed;
 
-
    •  socket.select refuses tables that have anything that is not
-an object from the group select{able}. This includes even the
-'n' field. Silently ignoring objects was a source of bugs for Lua
-programs.
 
    
 
 
diff --git a/doc/introduction.html b/doc/introduction.html
index e6f0ea2..86c552b 100644
--- a/doc/introduction.html
+++ b/doc/introduction.html
@@ -37,12 +37,12 @@
 
 
    
 Communication in LuaSocket is performed via I/O objects. These can
-represent different network domains. Currently, support is
-provided for TCP and UDP, but there is work in progress to implement SSL,
-Local Domain, Pipes, File Descriptors etc. I/O objects provide a standard
+represent different network domains. Currently, support is provided for TCP
+and UDP, but nothing prevents other developers from implementing SSL, Local
+Domain, Pipes, File Descriptors etc. I/O objects provide a standard
 interface to I/O across different domains and operating systems.
 LuaSocket 2.0 has been rewritten from scratch to simplify the future
-addition of new domains.
+addition of new domains.  
 
    
 
 
    
@@ -93,7 +93,7 @@ Previous versions of LuaSocket provided global functions for operating on
 I/O objects. To give the library a Lua 5.0 feel, these have been eliminated
 from LuaSocket 2.0. I/O operations are only available as methods of the
 corresponding I/O objects.  Naturally, different I/O objects accept
-different operations. The core functionality for TCP and UDP objects is
+different operations. The TCP and UDP objects are
 introduced in the following sections, following a few words about
 initialization. 
 
    
@@ -103,18 +103,23 @@ initialization.
 
    Initializing the library
    
 
 
    
+The core LuaSocket functionality is implemented in C, and usually available as 
+a dynamic library which the interpreter can load when required. 
 Beginning with version 2.0 and following the Lua 5.0 trend, all LuaSocket
-functionality is defined inside a table (or rather a namespace) stored with
-the global name socket.  To  have this table created and its
-contents made available to a Lua script, the interpreter running the script
-must  be linked to the LuaSocket library, and  to whatever libraries  the
-host OS  requires  for network access (Windows requires ws2_32.lib, for
-instance). LuaSocket is initialized in  the
-Lua state given as the argument  to  the  function
-luaopen_socket, the  only  C function  exported  by  the  library.
-After initialization, scripts are free to use all of the LuaSocket API. 
+functionality is defined inside a tables (or rather a namespaces). No global
+variables are ever created.
+Namespaces are obtained with the require Lua function, which loads
+and initializes any required libraries and return the namespace. 
+For example, the core functionality or LuaSocket is usually available
+from the "socket" namespace. 
 
    
 
+
    +socket = require("socket")
+print(socket.VERSION)
+-- LuaSocket 2.0
+
    
+
 
 
 
    TCP
    
@@ -185,29 +190,25 @@ program.
 
    
 
 
    --- create a new TCP object
-server, err = socket.tcp()
-assert(server, err)
--- bind it to the local host, at any port
-ret, err = server:bind("*", 0)
-assert(ret, err)
+-- load namespace
+local socket = require("socket")
+-- create a TCP socket and bind it to the local host, at any port
+local server = socket.try(socket.bind("*", 0))
 -- find out which port the OS chose for us
-ip, port = server:getsockname()
+local ip, port = server:getsockname()
 -- print a message informing what's up
 print("Please telnet to localhost on port " .. port)
 print("After connecting, you have 10s to enter a line to be echoed")
 -- loop forever waiting for clients
 while 1 do
   -- wait for a conection from any client
-  client, err = server:accept()
+  local client = server:accept()
   -- make sure we don't block waiting for this client's line
   client:settimeout(10)
   -- receive the line
-  line, err = client:receive()
+  local line, err = client:receive()
   -- if there was no error, send it back to the client
-  if not err then 
-    client:send(line .. "\n") 
-  end
+  if not err then client:send(line .. "\n") end
   -- done with client, close the object
   client:close()
 end
@@ -286,21 +287,19 @@ error message.
 
    
 
 
    -host = "localhost" -- change here to the host you want to contact
-port = port or 13
+-- change here to the host an port you want to contact
+host = "localhost" 
+port = 13
+-- load namespace
+local socket = require("socket")
 -- convert host name to ip address
-ip, err = socket.dns.toip(host)
-assert(ip, err)
+local ip = socket.try(socket.dns.toip(host))
 -- create a new UDP object
-udp = socket.udp()
+local udp = socket.udp()
 -- contact daytime host
-nsent, err = udp:sendto("anything", ip, port)
-assert(not err, err)
--- retrieve the answer
-dgram, err = udp:receive()
-assert(dgram, err)
--- display to user
-print(dgram)
+socket.try(udp:sendto("anything", ip, port))
+-- retrieve the answer and print results
+io.write(socket.try((udp:receive())))
 
    
 
 
diff --git a/doc/mime.html b/doc/mime.html
index d2fcc3c..286e41c 100644
--- a/doc/mime.html
+++ b/doc/mime.html
@@ -44,7 +44,7 @@ MIME is described mainly in
 RFC 2045,
 2046,
 2047,
-2048 and
+2048, and
 2049.