From 534b0cedf714d4de0a6cf67570e11f232cdccf84 Mon Sep 17 00:00:00 2001 From: Diego Nehab Date: Sun, 28 Nov 2004 08:17:16 +0000 Subject: [PATCH] Added new instalation section to the manual. --- TODO | 6 +- doc/dns.html | 4 +- doc/ftp.html | 4 +- doc/http.html | 4 +- doc/index.html | 84 +++++++++++++----------- doc/installation.html | 149 ++++++++++++++++++++++++++++++++++++++++++ doc/introduction.html | 39 +++++------ doc/ltn12.html | 6 +- doc/mime.html | 4 +- doc/reference.html | 5 +- doc/smtp.html | 5 +- doc/socket.html | 4 +- doc/tcp.html | 4 +- doc/udp.html | 4 +- doc/url.html | 4 +- src/socket.lua | 25 ++++--- test/httptest.lua | 2 +- 17 files changed, 264 insertions(+), 89 deletions(-) create mode 100644 doc/installation.html diff --git a/TODO b/TODO index dfb9178..c366bf6 100644 --- a/TODO +++ b/TODO @@ -1,6 +1,3 @@ -use wim's filter.chain or something better -make sure standard libraries are "required" by modules before use. -eliminate globals from namespaces created by module(). ftp.send/recv return bytes transfered? new scheme to choose family/protocol of object to create change ltn13 to make sure drawbacks are obvious @@ -23,6 +20,9 @@ testar os options! - proteger ou atomizar o conjunto (timedout, receive), (timedout, send) - inet_ntoa também é uma merda. +*eliminate globals from namespaces created by module(). +*make sure standard libraries are "required" by modules before use. +*use wim's filter.chain or something better *close wasn't returning 1 *make sure errors not thrown by try() are not caught by protect() *move wsocket.c:sock_send kludge to buffer.c:sendraw? diff --git a/doc/dns.html b/doc/dns.html index 09a9bdb..2c4c51f 100644 --- a/doc/dns.html +++ b/doc/dns.html @@ -4,7 +4,7 @@ - + LuaSocket: DNS support @@ -26,6 +26,7 @@

home · download · +instalation · introduction · reference

@@ -114,6 +115,7 @@ message.

home · download · +instalation · introduction · reference

diff --git a/doc/ftp.html b/doc/ftp.html index 0b52007..a1a5162 100644 --- a/doc/ftp.html +++ b/doc/ftp.html @@ -4,7 +4,7 @@ - + LuaSocket: FTP support @@ -26,6 +26,7 @@

home · download · +instalation · introduction · reference

@@ -265,6 +266,7 @@ f, e = ftp.put{

home · download · +instalation · introduction · reference

diff --git a/doc/http.html b/doc/http.html index 13acd1c..deacaa5 100644 --- a/doc/http.html +++ b/doc/http.html @@ -4,7 +4,7 @@ - + LuaSocket: HTTP support @@ -27,6 +27,7 @@ home · download · introduction · +introduction · reference

@@ -299,6 +300,7 @@ r, c = http.request {

home · download · +instalation · introduction · reference

diff --git a/doc/index.html b/doc/index.html index c0a46ea..c3c391f 100644 --- a/doc/index.html +++ b/doc/index.html @@ -4,7 +4,7 @@ - + LuaSocket: Network support for the Lua language @@ -26,6 +26,7 @@

home · download · +instalation · introduction · reference

@@ -79,7 +80,7 @@ LuaSocket.

-Copyright © 1999-2004 Tecgraf/PUC-Rio. All rights reserved.
+Copyright © 2004 Diego Nehab. All rights reserved.
Author: Diego Nehab

@@ -88,7 +89,7 @@ Author: Diego Nehab

Download

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

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

-luasocket-2.0-beta2.tar.gz
-luasocket-2.0-beta2.zip +luasocket-2.0-beta3.tar.gz
+luasocket-2.0-beta3.zip

@@ -116,7 +117,7 @@ LuaSocket a quick try:

-luasocket-2.0-beta2-win32.zip +luasocket-2.0-beta3-win32.zip

@@ -124,11 +125,15 @@ LuaSocket a quick try: The quick and dirty way to use these binaries is to unpack everything into a directory, say c:\luasocket (include all Lua files from the LuaSocket distrbitution in the same directory too!). -Then set LUA_INIT to load the lua.lua helper file: +Then set LUA_INIT to load the compat-5.1.lua and set +LUA_PATH and LUA_CPATH to look for files in that +directory: 

-c:\luasocket\> set LUA_INIT=@lua.lua
+c:\luasocket\> set LUA_INIT=@compat-5.1.lua
+c:\luasocket\> set LUA_CPATH=?.dll
+c:\luasocket\> set LUA_PATH=?.lua

@@ -142,9 +147,13 @@ c:\luasocket\> lua Lua 5.0.2 Copyright (C) 1994-2004 Tecgraf, PUC-Rio > http = require"http" > print(http.request"http://www.tecgraf.puc-rio.br/luasocket/") ---> this file +--> this gets dumped to terminal +

Take a look at the installation section of +the manual to find out how to properly install the library after you are +done playing with it.

+

Special thanks

@@ -165,35 +174,31 @@ has been helping a lot too! Thanks to you all!

What's New

-Changes in the 2.0-beta2 were mostly bug-fixes. +The big change for the 2.0 (beta3) release was the adoption of the Lua 5.1 +package proposal. There were several bug fixes too (a beta is a +beta, is a beta).

@@ -201,10 +206,9 @@ higher resolution and no wrap around problems;

Incompatibilities with previous versions

@@ -225,6 +229,8 @@ those that have compatibility issues.

download · +download · +instalation · introduction · reference

diff --git a/doc/installation.html b/doc/installation.html new file mode 100644 index 0000000..d5e82d9 --- /dev/null +++ b/doc/installation.html @@ -0,0 +1,149 @@ + + + + + + +LuaSocket: Instalation + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +instalation · +introduction · +reference +

+
+
+
+ + + +

Instalation

+ +

LuaSocket 2.0 uses the new package proposal for Lua 5.1, throught the +compatibility module +Compat-5.1 released in conjunction with Roberto Ierusalimschy and The Kepler project. The proposal +was considered important enough by the community to justify early adoption. +All Lua library developers are encouraged to change their libraries in +preparation for the release of Lua 5.1.

+ +

As far as LuaSocket is concerned, this means that whoever is +deploying a solution that uses LuaSocket has a lot of freedom. Here we +describe only the standard distribution. If the standard doesn't meet your +needs, we refer you to the Lua discussion list, where any quesetion about +the package scheme will likely be answered promptly. +

+ +

Directory structure

+ +

The new package scheme has a root directory for the libraries installed +on a given system. Let's call this directory <ROOT>. +On my system, this is the /usr/local/share/lua/5.0 directory. +Here is the standard LuaSocket distribution directory structure:

+ +
+<ROOT>/compat-5.1.lua
+<ROOT>/socket.lua
+<ROOT>/lsocket.dll
+<ROOT>/mime.lua
+<ROOT>/lmime.dll
+<ROOT>/ltn12.lua
+<ROOT>/socket/http.lua
+<ROOT>/socket/tp.lua
+<ROOT>/socket/ftp.lua
+<ROOT>/socket/smtp.lua
+<ROOT>/socket/url.lua
+
+ +

Naturally, on Unix systems, lsocket.dll and lmime.dll +would be replaced by lsocket.so and lmime.so. In Mac OS +X, they would be replaced by lsocket.dylib and +lmime.dylib.

+ +

In order for the interpreter to find all LuaSocket components, three +environment variables need to be set. The first environment variable tells +the interpreter to load the compat-5.1.lua module.

+ +
+LUA_INIT=@<ROOT>/compat-5.1.lua
+
+ +The other two environment variables instruct the compatibility module to +look for dynamic libraries and modules in the appropriate directories and +with the appropriate filename extensions. + +
+LUA_PATH=<ROOT>/?.lua;?.lua
+LUA_CPATH=<ROOT>/?.dll;?.dll
+
+ +

Again, naturally, in Unix the shared library extension would be +.so instead of .dll and on Mac OS X they would be +.dylib

+ +

Using LuaSocket

+ +

With the above setup, and an interpreter with shared library support, +it should be easy to use LuaSocket. Just fire the interpreter and use the +require function to gain access to whatever module you need:

+ +
+Lua 5.0.2  Copyright (C) 1994-2004 Tecgraf, PUC-Rio
+> socket = require("socket")
+> print(socket.VERSION)
+--> LuaSocket 2.0 (beta3)
+
+ +

Each module loads their dependencies automatically, so you only need to +load the modues you are directly dependent upon.

+ +

+Lua 5.0.2  Copyright (C) 1994-2004 Tecgraf, PUC-Rio
+> http = require("socket.http")
+> print(http.get("http://www.tecgraf.puc-rio.br/luasocket"))
+--> homepage gets dumped to terminal
+
+ + + +
+
+
+

+home · +download · +instalation · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Thu Jun 17 02:47:21 EDT 2004 + +

+
+
+ + + diff --git a/doc/introduction.html b/doc/introduction.html index 20c4d36..a285b81 100644 --- a/doc/introduction.html +++ b/doc/introduction.html @@ -4,7 +4,8 @@ - + LuaSocket: Introduction to the core @@ -26,6 +27,7 @@

home · download · +instalation · introduction · reference

@@ -104,29 +106,6 @@ Together, these changes make network programming in LuaSocket much simpler than it is in C, as the following sections will show.

- - -

Initializing the library

- -

-The core LuaSocket is almost entirely implemented in C. It is -usually available as a dynamic library which the interpreter can load -with the help of a loader module written in Lua. -Beginning with version 2.0 and following the Lua 5.0 trend, all LuaSocket -functionality is defined inside tables (or rather namespaces). No global -variables are ever created. -Namespaces are obtained with the require Lua function, which loads -and initializes any required library and returns 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

@@ -318,6 +297,17 @@ io.write(socket.try((udp:receive()))) + + +

Much more

+ +

LuaSocket offers much more than TCP and UDP support. As the library +evolved, support for HTTP, FTP, +SMTP, MIME, URLs and much more was made available. These are +mostly implemented in Lua itself, with critical parts implemented in C for +efficiency

+
@@ -326,6 +316,7 @@ io.write(socket.try((udp:receive())))

home · download · +instalation · introduction · reference

diff --git a/doc/ltn12.html b/doc/ltn12.html index 40dcf96..4b8f188 100644 --- a/doc/ltn12.html +++ b/doc/ltn12.html @@ -4,8 +4,8 @@ - + LuaSocket: LTN12 module @@ -27,6 +27,7 @@ Pump, Support">

home · download · +instalation · introduction · reference

@@ -412,6 +413,7 @@ Creates and returns a source that produces the contents of a

home · download · +instalation · introduction · reference

diff --git a/doc/mime.html b/doc/mime.html index 6758a4b..594d749 100644 --- a/doc/mime.html +++ b/doc/mime.html @@ -4,7 +4,7 @@ - + LuaSocket: MIME module @@ -26,6 +26,7 @@

home · download · +instalation · introduction · reference

@@ -458,6 +459,7 @@ marker.

home · download · +instalation · introduction · reference

diff --git a/doc/reference.html b/doc/reference.html index 744da58..b15a2aa 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -4,7 +4,8 @@ - + LuaSocket: Index to reference manual @@ -26,6 +27,7 @@

home · download · +instalation · introduction · reference

@@ -220,6 +222,7 @@

home · download · +instalation · introduction · reference

diff --git a/doc/smtp.html b/doc/smtp.html index 4a9aaac..27223ae 100644 --- a/doc/smtp.html +++ b/doc/smtp.html @@ -4,7 +4,8 @@ - + LuaSocket: SMTP support @@ -26,6 +27,7 @@

home · download · +instalation · introduction · reference

@@ -394,6 +396,7 @@ r, e = smtp.send{

home · download · +instalation · introduction · reference

diff --git a/doc/socket.html b/doc/socket.html index c7525eb..809c256 100644 --- a/doc/socket.html +++ b/doc/socket.html @@ -4,7 +4,7 @@ - + LuaSocket: The socket namespace @@ -26,6 +26,7 @@

home · download · +instalation · introduction · reference

@@ -382,6 +383,7 @@ This constant has a string describing the current LuaSocket version.

home · download · +instalation · introduction · reference

diff --git a/doc/tcp.html b/doc/tcp.html index dfc2c29..57784ea 100644 --- a/doc/tcp.html +++ b/doc/tcp.html @@ -4,7 +4,7 @@ - + LuaSocket: TCP/IP support @@ -26,6 +26,7 @@

home · download · +instalation · introduction · reference

@@ -527,6 +528,7 @@ This function returns 1.

home · download · +instalation · introduction · reference

diff --git a/doc/udp.html b/doc/udp.html index b0c51f6..f712b2f 100644 --- a/doc/udp.html +++ b/doc/udp.html @@ -4,7 +4,7 @@ - + LuaSocket: UDP support @@ -26,6 +26,7 @@

home · download · +instalation · introduction · reference

@@ -398,6 +399,7 @@ imperative nature obvious.

home · download · +instalation · introduction · reference

diff --git a/doc/url.html b/doc/url.html index 92acf36..5c2be65 100644 --- a/doc/url.html +++ b/doc/url.html @@ -4,7 +4,7 @@ - + LuaSocket: URL support @@ -26,6 +26,7 @@

home · download · +instalation · introduction · reference

@@ -311,6 +312,7 @@ The function returns the decoded string.

home · download · +instalation · introduction · reference

diff --git a/src/socket.lua b/src/socket.lua index b3a4269..c3bbba9 100644 --- a/src/socket.lua +++ b/src/socket.lua @@ -7,8 +7,11 @@ ----------------------------------------------------------------------------- -- Declare module and import dependencies ----------------------------------------------------------------------------- -module("socket") +local base = require("base") +local string = require("string") +local math = require("math") local socket = require("lsocket") +module("socket") ----------------------------------------------------------------------------- -- Auxiliar functions @@ -40,11 +43,11 @@ socket.try = socket.newtry() function socket.choose(table) return function(name, opt1, opt2) - if type(name) ~= "string" then + if base.type(name) ~= "string" then name, opt1, opt2 = "default", name, opt1 end local f = table[name or "nil"] - if not f then error("unknown key (" .. tostring(name) .. ")", 3) + if not f then base.error("unknown key (".. base.tostring(name) ..")", 3) else return f(opt1, opt2) end end end @@ -59,7 +62,7 @@ socket.sinkt = {} socket.BLOCKSIZE = 2048 socket.sinkt["http-chunked"] = function(sock) - return setmetatable({ + return base.setmetatable({ getfd = function() return sock:getfd() end, dirty = function() return sock:dirty() end }, { @@ -72,7 +75,7 @@ socket.sinkt["http-chunked"] = function(sock) end socket.sinkt["close-when-done"] = function(sock) - return setmetatable({ + return base.setmetatable({ getfd = function() return sock:getfd() end, dirty = function() return sock:dirty() end }, { @@ -86,7 +89,7 @@ socket.sinkt["close-when-done"] = function(sock) end socket.sinkt["keep-open"] = function(sock) - return setmetatable({ + return base.setmetatable({ getfd = function() return sock:getfd() end, dirty = function() return sock:dirty() end }, { @@ -102,7 +105,7 @@ socket.sinkt["default"] = socket.sinkt["keep-open"] socket.sink = socket.choose(socket.sinkt) socket.sourcet["by-length"] = function(sock, length) - return setmetatable({ + return base.setmetatable({ getfd = function() return sock:getfd() end, dirty = function() return sock:dirty() end }, { @@ -119,7 +122,7 @@ end socket.sourcet["until-closed"] = function(sock) local done - return setmetatable({ + return base.setmetatable({ getfd = function() return sock:getfd() end, dirty = function() return sock:dirty() end }, { @@ -137,7 +140,7 @@ socket.sourcet["until-closed"] = function(sock) end socket.sourcet["http-chunked"] = function(sock) - return setmetatable({ + return base.setmetatable({ getfd = function() return sock:getfd() end, dirty = function() return sock:dirty() end }, { @@ -145,7 +148,7 @@ socket.sourcet["http-chunked"] = function(sock) -- get chunk size, skip extention local line, err = sock:receive() if err then return nil, err end - local size = tonumber(string.gsub(line, ";.*", ""), 16) + local size = base.tonumber(string.gsub(line, ";.*", ""), 16) if not size then return nil, "invalid chunk size" end -- was it the last chunk? if size <= 0 then @@ -168,3 +171,5 @@ end socket.sourcet["default"] = socket.sourcet["until-closed"] socket.source = socket.choose(socket.sourcet) + +base.setmetatable(socket, nil) diff --git a/test/httptest.lua b/test/httptest.lua index cade837..71021a4 100644 --- a/test/httptest.lua +++ b/test/httptest.lua @@ -23,7 +23,7 @@ http.TIMEOUT = 10 local t = socket.gettime() host = host or "diego.student.princeton.edu" -proxy = proxy or "http://dell-diego.cs.princeton.edu:3128" +proxy = proxy or "http://localhost:3128" prefix = prefix or "/luasocket-test" cgiprefix = cgiprefix or "/luasocket-test-cgi" index_file = "test/index.html"