From 27c8ae30aaef25d537669062d5f7f929eec18032 Mon Sep 17 00:00:00 2001 From: Diego Nehab Date: Wed, 16 Jun 2004 23:21:49 +0000 Subject: [PATCH] Updated the HTTP manual. Finaly done. --- doc/http.html | 148 ++++++++++++++++++--------------------------- doc/reference.html | 4 +- doc/url.html | 14 ++++- 3 files changed, 71 insertions(+), 95 deletions(-) diff --git a/doc/http.html b/doc/http.html index a621ec7..9125df7 100644 --- a/doc/http.html +++ b/doc/http.html @@ -48,11 +48,9 @@ implementation conforms to the HTTP/1.1 standard,

The module exports functions that provide HTTP functionality in different -levels of abstraction, from the simple -get function, through the generic -LTN12 based -request function, down to -even lower-level if you bother to look through the source code. +levels of abstraction. From the simple +string oriented requests, through generic +LTN12 based, down to even lower-level if you bother to look through the source code.

@@ -118,72 +116,10 @@ the HTTP module:

  • USERAGENT: default user agent reported to server. - - -

    -http.get(url)
    -

    - -

    -Performs the HTTP method GET. -

    - -

    -Url identifies the entity to retrieve. -

    - -

    -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. -

    - -

    -Note: The function is trivially implemented with the use of the -request function. -

    - -
    --- 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 = 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 = 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.
-r, e = http.get("http://wrong.host/")
--- r is nil, and e returns with value "host not found"
-
    - - - -

    -http.post(url, body)
    -

    - -

    -Same as get, except -that the POST method is used and the request -message body is sent along with the request. -

    - -

    -Note: This function is also trivially implemented with the use of the -request function. -

    -

    +http.request(url [, body])
    http.request{
      url = string,
      [sink = LTN12 sink,]
    @@ -197,11 +133,23 @@ http.request{

    -Performs the generic HTTP request, controlled by a request table. +The request function has two forms. The simple form downloads +a URL using the GET or POST method and is based +on strings. The generic form performs any HTTP method and is +LTN12 based.

    -The most important parameters are the url and the simple +If the first argument of the request function is a string, it +should be an url. In that case, if a body +is provided as a string, the function will perform a POST method +in the url. Otherwise, it performs a GET in the +url +

    + +

    +If the first argument is instead a table, the most important fields are +the url and the simple LTN12 sink that will receive the downloaded content. Any part of the url can be overridden by including @@ -232,20 +180,15 @@ function from automatically following 301 or 302 server redirect messages.

    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: +error message. If successful, the simple form returns the response +body as a string, followed by the response status code, the response +headers and the response status line. The complex function returns the same +information, except the first return value is just the number 1 (the body +goes to the sink).

    -
    -respt = {
    -  headers = header-table,
    -  status = string,
    -  code = number,
    -} -
    -

    -Even when the server fails to provide the contents of the requested URL (URL not found, for example), the +Even when the server fails to provide the contents of the requested URL (URL not found, for example), it usually returns 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 @@ -254,6 +197,35 @@ href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC 2616.

    +

    +Here are a few examples with the simple interface: +

    + +
    +-- 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 = http.request("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, c, h = http.request("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.
+r, e = http.request("http://wrong.host/")
+-- r is nil, and e returns with value "host not found"
+
    + +

    +And here is an example using the generic interface: +

    + 
     -- load the http module
 http = require("http")
@@ -261,12 +233,12 @@ 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
-respt = http.request {
+r, c, h = http.request {
   method = "HEAD",
   url = "http://www.tecgraf.puc-rio.br/~diego"
 }
--- Would return the following headers:
--- respt.headers = {
+-- r is 1, c is 200, and h would return the following headers:
+-- h = {
 --   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",
@@ -307,15 +279,11 @@ 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
-respt = http.request{
-  url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
-  user = "diego",
-  password = "password"
-}
+b, c, h = http.request("http://diego:password@www.tecgraf.puc-rio.br/~diego/auth/index.html")
 
 -- Alternatively, one could fill the appropriate header and authenticate
 -- the request directly.
-respt = http.request {
+r, c = http.request {
   url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
   headers = { authentication = "Basic " .. (mime.b64("diego:password")) }
 }
diff --git a/doc/reference.html b/doc/reference.html
index 43aeea5..9ff6004 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -50,7 +50,7 @@
 FTP
 
    
 get,
-put
+put.
 
    
 
 
@@ -59,8 +59,6 @@
 
    
 HTTP
 
    
-get,
-post,
 request.
 
    
 
    
diff --git a/doc/url.html b/doc/url.html
index cd699a2..1dbee52 100644
--- a/doc/url.html
+++ b/doc/url.html
@@ -36,13 +36,22 @@
 
    URL
     
 
 
    
-The  module  url.lua  provides  functions  to  parse,  protect,
+The  url  namespace provides  functions  to  parse,  protect,
 and build URLs, as well  as functions to compose  absolute URLs
 from base and relative URLs, according to 
 RFC
 2396.
 
    
 
+
     
+To obtain the url namespace, run:
+
    
+
+
    +-- loads the URL module 
+local url = require("url")
+
    
+
 
    
 An URL is defined by the following grammar:
 
    
@@ -67,7 +76,8 @@ Builds an absolute URL from a base URL and a relative URL.
 
    
 
 
    
-Base is a string with the base URL and relative is a
+Base is a string with the base URL or
+a parsed URL table.  Relative is a
 string with the relative URL.