aboutsummaryrefslogtreecommitdiff
path: root/doc/index.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/index.html')
-rw-r--r--doc/index.html101
1 files changed, 64 insertions, 37 deletions
diff --git a/doc/index.html b/doc/index.html
index 7a3afa8..888bc92 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -37,22 +37,30 @@
37 37
38<p> 38<p>
39LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library 39LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library
40that is composed by two parts: a C layer that provides support for the TCP 40that is composed by two parts: a C core that provides support for the TCP
41and UDP transport layers, and a set of Lua modules that add support for 41and UDP transport layers, and a set of Lua modules that add support for
42the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and 42functionality commonly needed by applications that deal with the Internet.
43downloading files) protocols and other functionality commonly needed by
44applications that deal with the Internet.
45</p> 43</p>
46 44
47<p> 45<p>
48Network support has been implemented so that it is both efficient and 46The core support has been implemented so that it is both efficient and
49simple to use. LuaSocket can be used by any Lua application once it has 47simple to use. The core can be used by any Lua application once it has
50been properly initialized by the interpreter running the 48been properly initialized by the interpreter running the
51Lua application. The code has been tested and runs well on several Windows 49Lua application. The code has been tested and runs well on several Windows
52and Unix platforms. 50and Unix platforms.
53</p> 51</p>
54 52
55<p> 53<p>
54The most used modules implement the SMTP (sending e-mails), HTTP
55(WWW access) and FTP (uploading and downloading files) client
56protocols. These provide a very natural and generic interface to the e
57functionality covered by the protocols.
58In addition, you will find that the MIME (common encodings), URL (anything you
59could possible want to do with one) and LTN12 (filters, sinks, sources
60and pumps) modules can be very handy.
61</p>
62
63<p>
56The library is available under the same 64The library is available under the same
57<a href="http://www.lua.org/copyright.html"> 65<a href="http://www.lua.org/copyright.html">
58terms and conditions</a> as the Lua language, the MIT license. The idea is 66terms and conditions</a> as the Lua language, the MIT license. The idea is
@@ -112,10 +120,10 @@ option, and should be able to run the automatic test procedures.
112<h2 id=thanks>Special thanks</h2> 120<h2 id=thanks>Special thanks</h2>
113 121
114<p> 122<p>
115Throughout LuaSocket's history, many people gave sugestions that helped 123Throughout LuaSocket's history, many people gave suggestions that helped
116improve it. For that, I thank the Lua comunity. 124improve it. For that, I thank the Lua community.
117Special thanks go to 125Special thanks go to
118David Burgess, who has pushed the library to a new level of quality and 126David Burgess, who has helped push the library to a new level of quality and
119from whom I have learned a lot of stuff that doesn't show up in RFCs. 127from whom I have learned a lot of stuff that doesn't show up in RFCs.
120Special thanks also to Carlos Cassino, who played a big part in the 128Special thanks also to Carlos Cassino, who played a big part in the
121extensible design seen in the C core of LuaSocket 2.0. 129extensible design seen in the C core of LuaSocket 2.0.
@@ -127,28 +135,47 @@ extensible design seen in the C core of LuaSocket 2.0.
127 135
128 136
129<p> 137<p>
130Everything is new! Many changes for 2.0 happened in the C layer, which 138<em>Everything</em> is new! Many changes for 2.0 happened in the C layer,
131has been almost completely rewritten. The code has been ported to Lua 5.0 139which has been almost completely rewritten. The code has been ported to
132and greatly improved. There have also been some API changes 140Lua 5.0 and greatly improved. There have also been some API changes
133that made the interface simpler and more consistent. Here are some of 141that made the interface simpler and more consistent. Here are some of
134the changes that made it into version 2.0: 142the changes that made it into version 2.0:
135</p> 143</p>
136 144
137<ul> 145<ul>
138<li> Major C code rewrite. Code is modular and extensible. Hopefully, next 146<li> Major C code rewrite. Code is modular and extensible. Hopefully, other
139 versions will include code for local domain sockets, file descriptors, 147 developers will be motivated to provide code for SSL, local domain
140 pipes (on Unix) and named pipes (on windows) as a bonus; 148 sockets, file descriptors, pipes (on Unix) and named pipes etc;
141 149
142<li> Following the Lua 5.0 trend, all functions provided by the library are 150<li> Everything that is exported by the library is exported inside
143 in namespaces. These should be obtained with calls to the 151 namespaces. These should be obtained with calls to the
144 <tt>require</tt> function. Functions such as 152 <tt>require</tt> function;
153
154<li> Functions such as
145 send/receive/timeout/close etc do not exist anymore as stand-alone 155 send/receive/timeout/close etc do not exist anymore as stand-alone
146 functions. They are now only available as methods of the appropriate 156 functions. They are now only available as methods of the appropriate
147 objects; 157 objects;
148 158
149<li> All functions return a non-nil value as first return value if successful. 159<li> All functions return a non-nil value as first return value if successful.
150 All functions return <b><tt>nil</tt></b> followed by error message 160 All functions return <b><tt>nil</tt></b> followed by error message
151 in case of error; 161 in case of error. This made the library much easier to use;
162
163<li> Greatly reduced the number of times the C select is called
164 during data transfers, by calling only on failure. This might
165 improve a lot the maximum throughput;
166
167<li> TCP has been changed to become more uniform. It's possible to first
168 create a TCP object,
169 then connect or bind if needed, and finally use I/O functions.
170 <tt>socket.connect</tt> and <tt>socket.bind</tt> functions are still
171 provided for simplicity;
172
173<li> This allows for setting a timeout value before connecting;
174
175<li> And also allows binding to a local address before connecting;
176
177<li> New <tt>socket.dns.gethostname</tt> function and <tt>shutdown</tt>
178 method;
152 179
153<li> Better error messages and parameter checking; 180<li> Better error messages and parameter checking;
154 181
@@ -157,20 +184,9 @@ the changes that made it into version 2.0:
157<li> UDP connected sockets can break association with peer by calling 184<li> UDP connected sockets can break association with peer by calling
158 <tt>setpeername</tt> with address '<tt>*</tt>'; 185 <tt>setpeername</tt> with address '<tt>*</tt>';
159 186
160<li> TCP has been changed to become more uniform. First create an object, 187<li> Sets returned by <tt>socket.select</tt> are associative;
161 then connect or bind if needed, and finally use I/O functions. The
162 <tt>socket.connect</tt> and <tt>socket.bind</tt> functions are still
163 provided for simplicity, but they just call <tt>socket.tcp</tt> followed
164 by the <tt>connect</tt> or <tt>bind/listen</tt> methods;
165
166<li> Greatly reduced the number of times select is called during data
167 transfers, by calling only on failure;
168
169<li> TCP can set timeout value before connecting and also bind to local
170 address before connecting;
171 188
172<li> <tt>socket.select</tt> returns associative sets and checks if 189<li> Select checks if sockets have buffered data and returns immediately;
173 sockets had buffered data;
174 190
175<li> <tt>socket.sleep</tt> and <tt>socket.time</tt> are now part of the 191<li> <tt>socket.sleep</tt> and <tt>socket.time</tt> are now part of the
176 library and are supported. They used to be available only when 192 library and are supported. They used to be available only when
@@ -182,7 +198,7 @@ the changes that made it into version 2.0:
182 high-level modules; 198 high-level modules;
183 199
184<li> Socket options interface has been improved. TCP objects also 200<li> Socket options interface has been improved. TCP objects also
185 support socket options and many other options were added. 201 support socket options and many new options were added.
186 202
187</ul> 203</ul>
188 204
@@ -191,12 +207,23 @@ Lots of changes in the Lua modules, too!
191</p> 207</p>
192 208
193<ul> 209<ul>
210<li> Every module loads only the modules that it needs. There is no waste
211of memory. LuaSocket core takes only 20k of memory;
212
194<li> New MIME and LTN12 modules make all other modules much more powerful; 213<li> New MIME and LTN12 modules make all other modules much more powerful;
214
195<li> Support for multipart messages in the SMTP module; 215<li> Support for multipart messages in the SMTP module;
196<li> The old callback mechanism of FTP and HTTP has been replaced with LTN12 sources and sinks, 216
197with advantage; 217<li> The old callback mechanism of FTP and HTTP has been replaced with LTN12 sources and sinks, with advantage;
218
219<li> Common implementation for low-level FTP and SMTP;
220
198<li> FTP, HTTP, and SMTP are implemented in multiple levels in such a way 221<li> FTP, HTTP, and SMTP are implemented in multiple levels in such a way
199that users will have no problems extending the functionality. 222that users will have no problems extending the functionality to satisfy
223personal needs;
224
225<li> SMTP knows how to perform LOGIN and PLAIN authentication.
226
200</ul> 227</ul>
201 228
202<!-- incompatible +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 229<!-- incompatible +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
@@ -208,7 +235,7 @@ that users will have no problems extending the functionality.
208<li> The introduction of namespaces affects all programs that use LuaSocket, 235<li> The introduction of namespaces affects all programs that use LuaSocket,
209specially code that relies on global functions. These are no longer 236specially code that relies on global functions. These are no longer
210available. Note that even the support modules (<tt>http</tt>, <tt>smtp</tt> 237available. Note that even the support modules (<tt>http</tt>, <tt>smtp</tt>
211etc) are independent now and should be "<tt>require</tt>ed"; 238etc) are independent now and should be "<tt>require</tt>"d;
212 239
213<li> FTP, SMTP and HTTP are completely new; I am sure you will 240<li> FTP, SMTP and HTTP are completely new; I am sure you will
214agree the new stuff is better; 241agree the new stuff is better;