diff options
Diffstat (limited to 'doc/index.html')
-rw-r--r-- | doc/index.html | 101 |
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> |
39 | LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library | 39 | LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library |
40 | that is composed by two parts: a C layer that provides support for the TCP | 40 | that is composed by two parts: a C core that provides support for the TCP |
41 | and UDP transport layers, and a set of Lua modules that add support for | 41 | and UDP transport layers, and a set of Lua modules that add support for |
42 | the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and | 42 | functionality commonly needed by applications that deal with the Internet. |
43 | downloading files) protocols and other functionality commonly needed by | ||
44 | applications that deal with the Internet. | ||
45 | </p> | 43 | </p> |
46 | 44 | ||
47 | <p> | 45 | <p> |
48 | Network support has been implemented so that it is both efficient and | 46 | The core support has been implemented so that it is both efficient and |
49 | simple to use. LuaSocket can be used by any Lua application once it has | 47 | simple to use. The core can be used by any Lua application once it has |
50 | been properly initialized by the interpreter running the | 48 | been properly initialized by the interpreter running the |
51 | Lua application. The code has been tested and runs well on several Windows | 49 | Lua application. The code has been tested and runs well on several Windows |
52 | and Unix platforms. | 50 | and Unix platforms. |
53 | </p> | 51 | </p> |
54 | 52 | ||
55 | <p> | 53 | <p> |
54 | The most used modules implement the SMTP (sending e-mails), HTTP | ||
55 | (WWW access) and FTP (uploading and downloading files) client | ||
56 | protocols. These provide a very natural and generic interface to the e | ||
57 | functionality covered by the protocols. | ||
58 | In addition, you will find that the MIME (common encodings), URL (anything you | ||
59 | could possible want to do with one) and LTN12 (filters, sinks, sources | ||
60 | and pumps) modules can be very handy. | ||
61 | </p> | ||
62 | |||
63 | <p> | ||
56 | The library is available under the same | 64 | The library is available under the same |
57 | <a href="http://www.lua.org/copyright.html"> | 65 | <a href="http://www.lua.org/copyright.html"> |
58 | terms and conditions</a> as the Lua language, the MIT license. The idea is | 66 | terms 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> |
115 | Throughout LuaSocket's history, many people gave sugestions that helped | 123 | Throughout LuaSocket's history, many people gave suggestions that helped |
116 | improve it. For that, I thank the Lua comunity. | 124 | improve it. For that, I thank the Lua community. |
117 | Special thanks go to | 125 | Special thanks go to |
118 | David Burgess, who has pushed the library to a new level of quality and | 126 | David Burgess, who has helped push the library to a new level of quality and |
119 | from whom I have learned a lot of stuff that doesn't show up in RFCs. | 127 | from whom I have learned a lot of stuff that doesn't show up in RFCs. |
120 | Special thanks also to Carlos Cassino, who played a big part in the | 128 | Special thanks also to Carlos Cassino, who played a big part in the |
121 | extensible design seen in the C core of LuaSocket 2.0. | 129 | extensible 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> |
130 | Everything 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, |
131 | has been almost completely rewritten. The code has been ported to Lua 5.0 | 139 | which has been almost completely rewritten. The code has been ported to |
132 | and greatly improved. There have also been some API changes | 140 | Lua 5.0 and greatly improved. There have also been some API changes |
133 | that made the interface simpler and more consistent. Here are some of | 141 | that made the interface simpler and more consistent. Here are some of |
134 | the changes that made it into version 2.0: | 142 | the 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 | ||
211 | of 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 | |
197 | with 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 |
199 | that users will have no problems extending the functionality. | 222 | that users will have no problems extending the functionality to satisfy |
223 | personal 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, |
209 | specially code that relies on global functions. These are no longer | 236 | specially code that relies on global functions. These are no longer |
210 | available. Note that even the support modules (<tt>http</tt>, <tt>smtp</tt> | 237 | available. Note that even the support modules (<tt>http</tt>, <tt>smtp</tt> |
211 | etc) are independent now and should be "<tt>require</tt>ed"; | 238 | etc) 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 |
214 | agree the new stuff is better; | 241 | agree the new stuff is better; |