Mercurial > luasocket

comparison doc/url.html @ 0:4b915342e2a8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LuaSocket 2.0.2 + CMake build description.
author Eric Wing <ewing . public |-at-| gmail . com>
date Tue, 26 Aug 2008 18:40:01 -0700
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:4b915342e2a8
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 <meta name="description" content="LuaSocket: URL manipulation">
7 <meta name="keywords" content="Lua, LuaSocket, URL, Library, Link, Network, Support">
8 <title>LuaSocket: URL support</title>
9 <link rel="stylesheet" href="reference.css" type="text/css">
10 </head>
11
12 <body>
13
14 <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15
16 <div class=header>
17 <hr>
18 <center>
19 <table summary="LuaSocket logo">
20 <tr><td align=center><a href="http://www.lua.org">
21 <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
22 </a></td></tr>
23 <tr><td align=center valign=top>Network support for the Lua language
24 </td></tr>
25 </table>
26 <p class=bar>
27 <a href="home.html">home</a> &middot;
28 <a href="home.html#download">download</a> &middot;
29 <a href="installation.html">installation</a> &middot;
30 <a href="introduction.html">introduction</a> &middot;
31 <a href="reference.html">reference</a>
32 </p>
33 </center>
34 <hr>
35 </div>
36
37 <!-- url ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39 <h2 id=url>URL</h2>
40
41 <p>
42 The <tt>url</tt> namespace provides functions to parse, protect,
43 and build URLs, as well as functions to compose absolute URLs
44 from base and relative URLs, according to
45 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC
46 2396</a>.
47 </p>
48
49 <p>
50 To obtain the <tt>url</tt> namespace, run:
51 </p>
52
53 <pre class=example>
54 -- loads the URL module
55 local url = require("socket.url")
56 </pre>
57
58 <p>
59 An URL is defined by the following grammar:
60 </p>
61
62 <blockquote>
63 <tt>
64 &lt;url&gt; ::= [&lt;scheme&gt;:][//&lt;authority&gt;][/&lt;path&gt;][;&lt;params&gt;][?&lt;query&gt;][#&lt;fragment&gt;]<br>
65 &lt;authority&gt; ::= [&lt;userinfo&gt;@]&lt;host&gt;[:&lt;port&gt;]<br>
66 &lt;userinfo&gt; ::= &lt;user&gt;[:&lt;password&gt;]<br>
67 &lt;path&gt; ::= {&lt;segment&gt;/}&lt;segment&gt;<br>
68 </tt>
69 </blockquote>
70
71 <!-- absolute +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
72
73 <p class=name id=absolute>
74 url.<b>absolute(</b>base, relative<b>)</b>
75 </p>
76
77 <p class=description>
78 Builds an absolute URL from a base URL and a relative URL.
79 </p>
80
81 <p class=parameters>
82 <tt>Base</tt> is a string with the base URL or
83 a parsed URL table. <tt>Relative</tt> is a
84 string with the relative URL.
85 </p>
86
87 <p class=return>
88 The function returns a string with the absolute URL.
89 </p>
90
91 <p class=note>
92 Note: The rules that
93 govern the composition are fairly complex, and are described in detail in
94 <a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC 2396</a>.
95 The example bellow should give an idea of what the rules are.
96 </p>
97
98 <pre class=example>
99 http://a/b/c/d;p?q
100
101 +
102
103 g:h = g:h
104 g = http://a/b/c/g
105 ./g = http://a/b/c/g
106 g/ = http://a/b/c/g/
107 /g = http://a/g
108 //g = http://g
109 ?y = http://a/b/c/?y
110 g?y = http://a/b/c/g?y
111 #s = http://a/b/c/d;p?q#s
112 g#s = http://a/b/c/g#s
113 g?y#s = http://a/b/c/g?y#s
114 ;x = http://a/b/c/;x
115 g;x = http://a/b/c/g;x
116 g;x?y#s = http://a/b/c/g;x?y#s
117 . = http://a/b/c/
118 ./ = http://a/b/c/
119 .. = http://a/b/
120 ../ = http://a/b/
121 ../g = http://a/b/g
122 ../.. = http://a/
123 ../../ = http://a/
124 ../../g = http://a/g
125 </pre>
126
127 <!-- build ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
128
129 <p class=name id=build>
130 url.<b>build(</b>parsed_url<b>)</b>
131 </p>
132
133 <p class=description>
134 Rebuilds an URL from its parts.
135 </p>
136
137 <p class=parameters>
138 <tt>Parsed_url</tt> is a table with same components returned by
139 <a href="#parse"><tt>parse</tt></a>.
140 Lower level components, if specified,
141 take precedence over high level components of the URL grammar.
142 </p>
143
144 <p class=return>
145 The function returns a string with the built URL.
146 </p>
147
148 <!-- build_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
149
150 <p class=name id=build_path>
151 url.<b>build_path(</b>segments, unsafe<b>)</b>
152 </p>
153
154 <p class=description>
155 Builds a <tt>&lt;path&gt;</tt> component from a list of
156 <tt>&lt;segment&gt;</tt> parts.
157 Before composition, any reserved characters found in a segment are escaped into
158 their protected form, so that the resulting path is a valid URL path
159 component.
160 </p>
161
162 <p class=parameters>
163 <tt>Segments</tt> is a list of strings with the <tt>&lt;segment&gt;</tt>
164 parts. If <tt>unsafe</tt> is anything but <b><tt>nil</tt></b>, reserved
165 characters are left untouched.
166 </p>
167
168 <p class=return>
169 The function returns a string with the
170 built <tt>&lt;path&gt;</tt> component.
171 </p>
172
173 <!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
174
175 <p class=name id="escape">
176 url.<b>escape(</b>content<b>)</b>
177 </p>
178
179 <p class=description>
180 Applies the URL escaping content coding to a string
181 Each byte is encoded as a percent character followed
182 by the two byte hexadecimal representation of its integer
183 value.
184 </p>
185
186 <p class=parameters>
187 <tt>Content</tt> is the string to be encoded.
188 </p>
189
190 <p class=result>
191 The function returns the encoded string.
192 </p>
193
194 <pre class=example>
195 -- load url module
196 url = require("socket.url")
197
198 code = url.escape("/#?;")
199 -- code = "%2f%23%3f%3b"
200 </pre>
201
202 <!-- parse ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
203
204 <p class=name id=parse>
205 url.<b>parse(</b>url, default<b>)</b>
206 </p>
207
208 <p class=description>
209 Parses an URL given as a string into a Lua table with its components.
210 </p>
211
212 <p class=parameters>
213 <tt>Url</tt> is the URL to be parsed. If the <tt>default</tt> table is
214 present, it is used to store the parsed fields. Only fields present in the
215 URL are overwritten. Therefore, this table can be used to pass default
216 values for each field.
217 </p>
218
219 <p class=return>
220 The function returns a table with all the URL components:
221 </p>
222
223 <blockquote><tt>
224 parsed_url = {<br>
225 &nbsp;&nbsp;url = <i>string</i>,<br>
226 &nbsp;&nbsp;scheme = <i>string</i>,<br>
227 &nbsp;&nbsp;authority = <i>string</i>,<br>
228 &nbsp;&nbsp;path = <i>string</i>,<br>
229 &nbsp;&nbsp;params = <i>string</i>,<br>
230 &nbsp;&nbsp;query = <i>string</i>,<br>
231 &nbsp;&nbsp;fragment = <i>string</i>,<br>
232 &nbsp;&nbsp;userinfo = <i>string</i>,<br>
233 &nbsp;&nbsp;host = <i>string</i>,<br>
234 &nbsp;&nbsp;port = <i>string</i>,<br>
235 &nbsp;&nbsp;user = <i>string</i>,<br>
236 &nbsp;&nbsp;password = <i>string</i><br>
237 }
238 </tt></blockquote>
239
240 <pre class=example>
241 -- load url module
242 url = require("socket.url")
243
244 parsed_url = url.parse("http://www.example.com/cgilua/index.lua?a=2#there")
245 -- parsed_url = {
246 -- scheme = "http",
247 -- authority = "www.example.com",
248 -- path = "/cgilua/index.lua"
249 -- query = "a=2",
250 -- fragment = "there",
251 -- host = "www.puc-rio.br",
252 -- }
253
254 parsed_url = url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i")
255 -- parsed_url = {
256 -- scheme = "ftp",
257 -- authority = "root:passwd@unsafe.org",
258 -- path = "/pub/virus.exe",
259 -- params = "type=i",
260 -- userinfo = "root:passwd",
261 -- host = "unsafe.org",
262 -- user = "root",
263 -- password = "passwd",
264 -- }
265 </pre>
266
267 <!-- parse_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
268
269 <p class=name id=parse_path>
270 url.<b>parse_path(</b>path<b>)</b>
271 </p>
272
273 <p class=description>
274 Breaks a <tt>&lt;path&gt;</tt> URL component into all its
275 <tt>&lt;segment&gt;</tt> parts.
276 </p>
277
278 <p class=description>
279 <tt>Path</tt> is a string with the path to be parsed.
280 </p>
281
282 <p class=return>
283 Since some characters are reserved in URLs, they must be escaped
284 whenever present in a <tt>&lt;path&gt;</tt> component. Therefore, before
285 returning a list with all the parsed segments, the function removes
286 escaping from all of them.
287 </p>
288
289 <!-- unescape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
290
291 <p class=name id="unescape">
292 url.<b>unescape(</b>content<b>)</b>
293 </p>
294
295 <p class=description>
296 Removes the URL escaping content coding from a string.
297 </p>
298
299 <p class=parameters>
300 <tt>Content</tt> is the string to be decoded.
301 </p>
302
303 <p class=return>
304 The function returns the decoded string.
305 </p>
306
307 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
308
309 <div class=footer>
310 <hr>
311 <center>
312 <p class=bar>
313 <a href="home.html">home</a> &middot;
314 <a href="home.html#down">download</a> &middot;
315 <a href="installation.html">installation</a> &middot;
316 <a href="introduction.html">introduction</a> &middot;
317 <a href="reference.html">reference</a>
318 </p>
319 <p>
320 <small>
321 Last modified by Diego Nehab on <br>
322 Thu Apr 20 00:26:05 EDT 2006
323 </small>
324 </p>
325 </center>
326 </div>
327
328 </body>
329 </html>