On Unix systems, the standard distribution uses two base directories, one for system dependent files, and another for system -independent files. Let's call these directories <CDIR> -and <LDIR>, respectively. +independent files. Let's call these directories <CDIR> +and <LDIR>, respectively. For example, in my laptp, Lua 5.1 is configured to use '/usr/local/lib/lua/5.1' for <CDIR> and '/usr/local/share/lua/5.1' for @@ -57,9 +57,9 @@ use '/usr/local/lib/lua/5.1' for usually points to the directory where the Lua executable is found, and <LDIR> points to a lua/ directory inside <CDIR>. (These -settings can be overridden by environment variables +settings can be overridden by environment variables LUA_PATH and LUA_CPATH. See the Lua -documentation for details.) Here is the standard LuaSocket +documentation for details.) Here is the standard LuaSocket distribution directory structure:
@@ -76,7 +76,7 @@ distribution directory structure:
Naturally, on Unix systems, core.dll -would be replaced by core.so. +would be replaced by core.so.
One of the simplifications is the receive pattern capability. -Applications can read data from stream domains (such as TCP) +Applications can read data from stream domains (such as TCP) line by line, block by block, or until the connection is closed. All I/O reads are buffered and the performance differences between -different receive patterns are negligible. +different receive patterns are negligible.
Another advantage is the flexible timeout control mechanism. As in C, all I/O operations are blocking by default. For -example, the send, -receive and +example, the send, +receive and accept methods of the TCP domain will block the caller application until the operation is completed (if ever!). However, with a call to the @@ -87,7 +87,7 @@ the time it can be blocked by LuaSocket (the "total" timeout), on the time LuaSocket can internally be blocked by any OS call (the "block" timeout) or a combination of the two. Each LuaSocket call might perform several OS calls, so that the two timeout values are -not equivalent. +not equivalent.
@@ -95,10 +95,10 @@ Finally, the host name resolution is transparent, meaning that most functions and methods accept both IP addresses and host names. In case a host name is given, the library queries the system's resolver and tries the main IP address returned. Note that direct use of IP addresses -is more efficient, of course. The -toip -and tohostname -functions from the DNS module are provided to convert between host names and IP addresses. +is more efficient, of course. The +toip +and tohostname +functions from the DNS module are provided to convert between host names and IP addresses.
@@ -118,47 +118,47 @@ reassembled transparently on the other end. There are no boundaries in the data transfers. The library allows users to read data from the sockets in several different granularities: patterns are available for lines, arbitrary sized blocks or "read up to connection closed", all with -good performance. +good performance.
-The library distinguishes three types of TCP sockets: master, -client and server sockets. +The library distinguishes three types of TCP sockets: master, +client and server sockets.
Master sockets are newly created TCP sockets returned by the function -socket.tcp. A master socket is +socket.tcp. A master socket is transformed into a server socket after it is associated with a local address by a call to the -bind method followed by a call to the -listen. Conversely, a master socket -can be changed into a client socket with the method -connect, -which associates it with a remote address. +bind method followed by a call to the +listen. Conversely, a master socket +can be changed into a client socket with the method +connect, +which associates it with a remote address.
-On server sockets, applications can use the +On server sockets, applications can use the accept method to wait for a client connection. Once a connection is established, a client socket object is returned representing this connection. The other methods available for server socket objects are -getsockname, +getsockname, setoption, -settimeout, and -close. +settimeout, and +close.
Client sockets are used to exchange data between two applications over -the Internet. Applications can call the methods +the Internet. Applications can call the methods send and -receive +receive to send and receive data. The other methods -available for client socket objects are +available for client socket objects are getsockname, -getpeername, +getpeername, setoption, settimeout, shutdown, and @@ -175,7 +175,7 @@ port (one that is chosen by the operating system) on the local host and awaits client connections on that port. When a connection is established, the program reads a line from the remote end and sends it back, closing the connection immediately. You can test it using the telnet -program. +program.
@@ -217,68 +217,68 @@ error free. Data transfers are atomic, one datagram at a time. Reading only part of a datagram discards the rest, so that the following read operation will act on the next datagram. The advantages are in simplicity (no connection setup) and performance (no error checking or -error correction). +error correction).Note that although no guarantees are made, these days -networks are so good that, under normal circumstances, few errors +networks are so good that, under normal circumstances, few errors happen in practice.
-An UDP socket object is created by the +An UDP socket object is created by the socket.udp function. UDP sockets do not need to be connected before use. The method -sendto +sendto can be used immediately after creation to send a datagram to IP address and port. Host names are not allowed because performing name resolution for each packet would be forbiddingly -slow. Methods -receive and +slow. Methods +receive and receivefrom can be used to retrieve datagrams, the latter returning the IP and port of the sender as extra return values (thus being slightly less -efficient). +efficient).
When communication is performed repeatedly with a single peer, an -application should call the +application should call the setpeername method to specify a -permanent partner. Methods +permanent partner. Methods sendto and -receivefrom +receivefrom can no longer be used, but the method -send can be used to send data -directly to the peer, and the method -receive +send can be used to send data +directly to the peer, and the method +receive will only return datagrams originating from that peer. There is about 30% performance gain due to this practice.
-To associate an UDP socket with a local address, an application calls the -setsockname +To associate an UDP socket with a local address, an application calls the +setsockname method before sending any datagrams. Otherwise, the socket is automatically bound to an ephemeral address before the first data -transmission and once bound the local address cannot be changed. +transmission and once bound the local address cannot be changed. The other methods available for UDP sockets are -getpeername, -getsockname, +getpeername, +getsockname, settimeout, -setoption and -close. +setoption and +close.
-Example: +Example:
A simple daytime client, using LuaSocket. The program connects to a remote server and tries to retrieve the daytime, printing the answer it got or an -error message. +error message.
@@ -301,11 +301,11 @@ io.write(assert(udp:receive()))Support modules
-Although not covered in the introduction, LuaSocket offers +
Although not covered in the introduction, LuaSocket offers much more than TCP and UDP functionality. As the library evolved, support for HTTP, FTP, and SMTP were built on top of these. These modules -and many others are covered by the reference manual. +and many others are covered by the reference manual.
diff --git a/docs/url.html b/docs/url.html index 6ff673d..e03b094 100644 --- a/docs/url.html +++ b/docs/url.html @@ -1,10 +1,10 @@ - - +LuaSocket: URL support @@ -28,7 +28,7 @@ download · installation · introduction · -reference +reference
@@ -36,21 +36,21 @@ -URL
+URL
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 +from base and relative URLs, according to RFC 2396.
-+
To obtain the url namespace, run:
--- loads the URL module +-- loads the URL module local url = require("socket.url")@@ -74,7 +74,7 @@ url.absolute(base, relative)-Builds an absolute URL from a base URL and a relative URL. +Builds an absolute URL from a base URL and a relative URL.
@@ -130,14 +130,14 @@ url.build(parsed_url)
-Rebuilds an URL from its parts. +Rebuilds an URL from its parts.
Parsed_url is a table with same components returned by parse. Lower level components, if specified, -take precedence over high level components of the URL grammar. +take precedence over high level components of the URL grammar.
@@ -152,10 +152,10 @@ url.build_path(segments, unsafe)
Builds a <path> component from a list of -<segment> parts. +<segment> parts. Before composition, any reserved characters found in a segment are escaped into their protected form, so that the resulting path is a valid URL path -component. +component.
@@ -165,8 +165,8 @@ characters are left untouched.
-The function returns a string with the -built <path> component. +The function returns a string with the +built <path> component.
@@ -178,7 +178,7 @@ url.escape(content)Applies the URL escaping content coding to a string Each byte is encoded as a percent character followed -by the two byte hexadecimal representation of its integer +by the two byte hexadecimal representation of its integer value.
@@ -270,8 +270,8 @@ url.parse_path(path)-Breaks a <path> URL component into all its -<segment> parts. +Breaks a <path> URL component into all its +<segment> parts.
@@ -282,7 +282,7 @@ Breaks a <path> URL component into all its Since some characters are reserved in URLs, they must be escaped whenever present in a <path> component. Therefore, before returning a list with all the parsed segments, the function removes -escaping from all of them. +escaping from all of them.
@@ -300,7 +300,7 @@ Removes the URL escaping content coding from a string.-The function returns the decoded string. +The function returns the decoded string.