diff options
author | Diego Nehab <diego@tecgraf.puc-rio.br> | 2003-08-31 01:00:15 +0000 |
---|---|---|
committer | Diego Nehab <diego@tecgraf.puc-rio.br> | 2003-08-31 01:00:15 +0000 |
commit | 982781f1464c9b7a8133130433f83dbf1f59a2c0 (patch) | |
tree | 8f96f9e9fa1e6bef8b8356037986ddc18673cade /doc/url.html | |
parent | 6789b83ff5c15296267f880d3b98cf8a1800c30a (diff) | |
download | luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.gz luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.bz2 luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.zip |
LuaSocket 2.0 User's Manual.
Diffstat (limited to 'doc/url.html')
-rw-r--r-- | doc/url.html | 265 |
1 files changed, 265 insertions, 0 deletions
diff --git a/doc/url.html b/doc/url.html new file mode 100644 index 0000000..e67ea13 --- /dev/null +++ b/doc/url.html | |||
@@ -0,0 +1,265 @@ | |||
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" | ||
2 | "http://www.w3.org/TR/html4/strict.dtd"> | ||
3 | <html> | ||
4 | |||
5 | <head> | ||
6 | <title>LuaSocket: Network support for the Lua language</title> | ||
7 | <link rel="stylesheet" href="reference.css" type="text/css"> | ||
8 | </head> | ||
9 | |||
10 | <body> | ||
11 | |||
12 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
13 | |||
14 | <div class=header> | ||
15 | <hr> | ||
16 | <center> | ||
17 | <table summary="LuaSocket logo"> | ||
18 | <tr><td align=center><a href="http://www.lua.org"> | ||
19 | <img border=0 alt="LuaSocket" src="luasocket.png"> | ||
20 | </a></td></tr> | ||
21 | <tr><td align=center valign=top>Network support for the Lua language | ||
22 | </td></tr> | ||
23 | </table> | ||
24 | <p class=bar> | ||
25 | <a href="home.html">home</a> · | ||
26 | <a href="home.html#download">download</a> · | ||
27 | <a href="introduction.html">introduction</a> · | ||
28 | <a href="reference.html">reference</a> | ||
29 | </p> | ||
30 | </center> | ||
31 | <hr> | ||
32 | </div> | ||
33 | |||
34 | <!-- url ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
35 | |||
36 | <h2 id=url>URL</h2> | ||
37 | |||
38 | <p> | ||
39 | The module <tt>url.lua</tt> provides functions to parse, protect, | ||
40 | and build URLs, as well as functions to compose absolute URLs | ||
41 | from base and relative URLs, according to | ||
42 | <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC | ||
43 | 2396</a>. | ||
44 | </p> | ||
45 | |||
46 | <p> | ||
47 | An URL is defined by the following grammar: | ||
48 | </p> | ||
49 | |||
50 | <blockquote> | ||
51 | <tt> | ||
52 | <url> ::= [<scheme>:][//<authority>][/<path>][;<params>][?<query>][#<fragment>]<br> | ||
53 | <authority> ::= [<userinfo>@]<host>[:<port>]<br> | ||
54 | <userinfo> ::= <user>[:<password>]<br> | ||
55 | <path> ::= {<segment>/}<segment><br> | ||
56 | </tt> | ||
57 | </blockquote> | ||
58 | |||
59 | <!-- absolute +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
60 | |||
61 | <p class=name id=absolute> | ||
62 | socket.url.<b>absolute(</b>base, relative<b>)</b> | ||
63 | </p> | ||
64 | |||
65 | <p class=description> | ||
66 | Builds an absolute URL from a base URL and a relative URL. | ||
67 | </p> | ||
68 | |||
69 | <p class=parameters> | ||
70 | <tt>Base</tt> is a string with the base URL and <tt>relative</tt> is a | ||
71 | string with the relative URL. | ||
72 | </p> | ||
73 | |||
74 | <p class=return> | ||
75 | The function returns a string with the absolute URL. | ||
76 | </p> | ||
77 | |||
78 | <p class=note> | ||
79 | Note: The rules that | ||
80 | govern the composition are fairly complex, and are described in detail in | ||
81 | <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC 2396</a>. | ||
82 | The example bellow should give an idea of what are the rules. | ||
83 | </p> | ||
84 | |||
85 | <pre class=example> | ||
86 | http://a/b/c/d;p?q | ||
87 | |||
88 | + | ||
89 | |||
90 | g:h = g:h | ||
91 | g = http://a/b/c/g | ||
92 | ./g = http://a/b/c/g | ||
93 | g/ = http://a/b/c/g/ | ||
94 | /g = http://a/g | ||
95 | //g = http://g | ||
96 | ?y = http://a/b/c/?y | ||
97 | g?y = http://a/b/c/g?y | ||
98 | #s = http://a/b/c/d;p?q#s | ||
99 | g#s = http://a/b/c/g#s | ||
100 | g?y#s = http://a/b/c/g?y#s | ||
101 | ;x = http://a/b/c/;x | ||
102 | g;x = http://a/b/c/g;x | ||
103 | g;x?y#s = http://a/b/c/g;x?y#s | ||
104 | . = http://a/b/c/ | ||
105 | ./ = http://a/b/c/ | ||
106 | .. = http://a/b/ | ||
107 | ../ = http://a/b/ | ||
108 | ../g = http://a/b/g | ||
109 | ../.. = http://a/ | ||
110 | ../../ = http://a/ | ||
111 | ../../g = http://a/g | ||
112 | </pre> | ||
113 | |||
114 | <!-- build ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
115 | |||
116 | <p class=name id=build> | ||
117 | socket.url.<b>build(</b>parsed_url<b>)</b> | ||
118 | </p> | ||
119 | |||
120 | <p class=description> | ||
121 | Rebuilds an URL from its parts. | ||
122 | </p> | ||
123 | |||
124 | <p class=parameters> | ||
125 | <tt>Parsed_url</tt> is a table with same components returned by | ||
126 | <a href="#parse"><tt>parse</tt></a>. | ||
127 | Lower level components, if specified, | ||
128 | take precedence over hight level components of the URL grammar. | ||
129 | </p> | ||
130 | |||
131 | <p class=return> | ||
132 | The function returns a string with the built URL. | ||
133 | </p> | ||
134 | |||
135 | <!-- build_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
136 | |||
137 | <p class=name id=build_path> | ||
138 | socket.url.<b>build_path(</b>segments, unsafe<b>)</b> | ||
139 | </p> | ||
140 | |||
141 | <p class=description> | ||
142 | Builds a <tt><path></tt> component from a list of | ||
143 | <tt><segment></tt> parts. | ||
144 | Before composition, any reserved characters found in a segment are escaped into | ||
145 | their protected form, so that the resulting path is a valid URL path | ||
146 | component. | ||
147 | </p> | ||
148 | |||
149 | <p class=parameters> | ||
150 | <tt>Segments</tt> is a list of strings with the <tt><segment></tt> | ||
151 | parts. If <tt>unsafe</tt> is anything but <tt>nil</tt>, reserved | ||
152 | characters are left untouched. | ||
153 | </p> | ||
154 | |||
155 | <p class=return> | ||
156 | The function returns a string with the | ||
157 | built <tt><path></tt> component. | ||
158 | </p> | ||
159 | |||
160 | <!-- parse ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
161 | |||
162 | <p class=name id=parse> | ||
163 | socket.url.<b>parse(</b>url, default<b>)</b> | ||
164 | </p> | ||
165 | |||
166 | <p class=description> | ||
167 | Parses an URL given as a string into a Lua table with its components. | ||
168 | </p> | ||
169 | |||
170 | <p class=parameters> | ||
171 | <tt>Url</tt> is the URL to be parsed. If the <tt>default</tt> table is | ||
172 | present, it is used to store the parsed fields. Only fields present in the | ||
173 | URL are overwritten. Therefore, this table can be used to pass default | ||
174 | values for each field. | ||
175 | </p> | ||
176 | |||
177 | <p class=return> | ||
178 | The function returns a table with all the URL components: | ||
179 | </p> | ||
180 | |||
181 | <blockquote><tt> | ||
182 | parsed_url = {<br> | ||
183 | url = <i>string</i>,<br> | ||
184 | scheme = <i>string</i>,<br> | ||
185 | authority = <i>string</i>,<br> | ||
186 | path = <i>string</i>,<br> | ||
187 | params = <i>string</i>,<br> | ||
188 | query = <i>string</i>,<br> | ||
189 | fragment = <i>string</i>,<br> | ||
190 | userinfo = <i>string</i>,<br> | ||
191 | host = <i>string</i>,<br> | ||
192 | port = <i>string</i>,<br> | ||
193 | user = <i>string</i>,<br> | ||
194 | password = <i>string</i><br> | ||
195 | } | ||
196 | </tt></blockquote> | ||
197 | |||
198 | <pre class=example> | ||
199 | parsed_url = socket.url.parse("http://www.puc-rio.br/~diego/index.lua?a=2#there") | ||
200 | -- parsed_url = { | ||
201 | -- scheme = "http", | ||
202 | -- authority = "www.puc-rio.br", | ||
203 | -- path = "/~diego/index.lua" | ||
204 | -- query = "a=2", | ||
205 | -- fragment = "there", | ||
206 | -- host = "www.puc-rio.br", | ||
207 | -- } | ||
208 | |||
209 | parsed_url = socket.url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i") | ||
210 | -- parsed_url = { | ||
211 | -- scheme = "ftp", | ||
212 | -- authority = "root:passwd@unsafe.org", | ||
213 | -- path = "/pub/virus.exe", | ||
214 | -- params = "type=i", | ||
215 | -- userinfo = "root:passwd", | ||
216 | -- host = "unsafe.org", | ||
217 | -- user = "root", | ||
218 | -- password = "passwd", | ||
219 | -- } | ||
220 | </pre> | ||
221 | |||
222 | <!-- parse_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
223 | |||
224 | <p class=name id=parse_path> | ||
225 | socket.url.<b>parse_path(</b>path<b>)</b> | ||
226 | </p> | ||
227 | |||
228 | <p class=description> | ||
229 | Breaks a <tt><path></tt> URL component into all its | ||
230 | <tt><segment></tt> parts. | ||
231 | </p> | ||
232 | |||
233 | <p class=description> | ||
234 | <tt>Path</tt> is a string with the path to be parsed. | ||
235 | </p> | ||
236 | |||
237 | <p class=return> | ||
238 | Since some characters are reserved in URLs, they must be escaped | ||
239 | whenever present in a <tt><path></tt> component. Therefore, before | ||
240 | returning a list with all the parsed segments, the function unescapes all | ||
241 | of them. | ||
242 | </p> | ||
243 | |||
244 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | ||
245 | |||
246 | <div class=footer> | ||
247 | <hr> | ||
248 | <center> | ||
249 | <p class=bar> | ||
250 | <a href="home.html">home</a> · | ||
251 | <a href="home.html#down">download</a> · | ||
252 | <a href="introduction.html">introduction</a> · | ||
253 | <a href="reference.html">reference</a> | ||
254 | </p> | ||
255 | <p> | ||
256 | <small> | ||
257 | Last modified by Diego Nehab on <br> | ||
258 | Sat Aug 9 01:00:41 PDT 2003 | ||
259 | </small> | ||
260 | </p> | ||
261 | </center> | ||
262 | </div> | ||
263 | |||
264 | </body> | ||
265 | </html> | ||