aboutsummaryrefslogtreecommitdiff
path: root/doc/url.html
diff options
context:
space:
mode:
authorDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
committerDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
commit982781f1464c9b7a8133130433f83dbf1f59a2c0 (patch)
tree8f96f9e9fa1e6bef8b8356037986ddc18673cade /doc/url.html
parent6789b83ff5c15296267f880d3b98cf8a1800c30a (diff)
downloadluasocket-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.html265
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> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
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>
39The module <tt>url.lua</tt> provides functions to parse, protect,
40and build URLs, as well as functions to compose absolute URLs
41from base and relative URLs, according to
42<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC
432396</a>.
44</p>
45
46<p>
47An URL is defined by the following grammar:
48</p>
49
50<blockquote>
51<tt>
52&lt;url&gt; ::= [&lt;scheme&gt;:][//&lt;authority&gt;][/&lt;path&gt;][;&lt;params&gt;][?&lt;query&gt;][#&lt;fragment&gt;]<br>
53&lt;authority&gt; ::= [&lt;userinfo&gt;@]&lt;host&gt;[:&lt;port&gt;]<br>
54&lt;userinfo&gt; ::= &lt;user&gt;[:&lt;password&gt;]<br>
55&lt;path&gt; ::= {&lt;segment&gt;/}&lt;segment&gt;<br>
56</tt>
57</blockquote>
58
59<!-- absolute +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
60
61<p class=name id=absolute>
62socket.url.<b>absolute(</b>base, relative<b>)</b>
63</p>
64
65<p class=description>
66Builds 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
71string with the relative URL.
72</p>
73
74<p class=return>
75The function returns a string with the absolute URL.
76</p>
77
78<p class=note>
79Note: The rules that
80govern 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>.
82The example bellow should give an idea of what are the rules.
83</p>
84
85<pre class=example>
86http://a/b/c/d;p?q
87
88+
89
90g:h = g:h
91g = http://a/b/c/g
92./g = http://a/b/c/g
93g/ = http://a/b/c/g/
94/g = http://a/g
95//g = http://g
96?y = http://a/b/c/?y
97g?y = http://a/b/c/g?y
98#s = http://a/b/c/d;p?q#s
99g#s = http://a/b/c/g#s
100g?y#s = http://a/b/c/g?y#s
101;x = http://a/b/c/;x
102g;x = http://a/b/c/g;x
103g;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>
117socket.url.<b>build(</b>parsed_url<b>)</b>
118</p>
119
120<p class=description>
121Rebuilds 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>.
127Lower level components, if specified,
128take precedence over hight level components of the URL grammar.
129</p>
130
131<p class=return>
132The function returns a string with the built URL.
133</p>
134
135<!-- build_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
136
137<p class=name id=build_path>
138socket.url.<b>build_path(</b>segments, unsafe<b>)</b>
139</p>
140
141<p class=description>
142Builds a <tt>&lt;path&gt;</tt> component from a list of
143<tt>&lt;segment&gt;</tt> parts.
144Before composition, any reserved characters found in a segment are escaped into
145their protected form, so that the resulting path is a valid URL path
146component.
147</p>
148
149<p class=parameters>
150<tt>Segments</tt> is a list of strings with the <tt>&lt;segment&gt;</tt>
151parts. If <tt>unsafe</tt> is anything but <tt>nil</tt>, reserved
152characters are left untouched.
153</p>
154
155<p class=return>
156The function returns a string with the
157built <tt>&lt;path&gt;</tt> component.
158</p>
159
160<!-- parse ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
161
162<p class=name id=parse>
163socket.url.<b>parse(</b>url, default<b>)</b>
164</p>
165
166<p class=description>
167Parses 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
172present, it is used to store the parsed fields. Only fields present in the
173URL are overwritten. Therefore, this table can be used to pass default
174values for each field.
175</p>
176
177<p class=return>
178The function returns a table with all the URL components:
179</p>
180
181<blockquote><tt>
182parsed_url = {<br>
183&nbsp;&nbsp;url = <i>string</i>,<br>
184&nbsp;&nbsp;scheme = <i>string</i>,<br>
185&nbsp;&nbsp;authority = <i>string</i>,<br>
186&nbsp;&nbsp;path = <i>string</i>,<br>
187&nbsp;&nbsp;params = <i>string</i>,<br>
188&nbsp;&nbsp;query = <i>string</i>,<br>
189&nbsp;&nbsp;fragment = <i>string</i>,<br>
190&nbsp;&nbsp;userinfo = <i>string</i>,<br>
191&nbsp;&nbsp;host = <i>string</i>,<br>
192&nbsp;&nbsp;port = <i>string</i>,<br>
193&nbsp;&nbsp;user = <i>string</i>,<br>
194&nbsp;&nbsp;password = <i>string</i><br>
195}
196</tt></blockquote>
197
198<pre class=example>
199parsed_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
209parsed_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>
225socket.url.<b>parse_path(</b>path<b>)</b>
226</p>
227
228<p class=description>
229Breaks a <tt>&lt;path&gt;</tt> URL component into all its
230<tt>&lt;segment&gt;</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>
238Since some characters are reserved in URLs, they must be escaped
239whenever present in a <tt>&lt;path&gt;</tt> component. Therefore, before
240returning a list with all the parsed segments, the function unescapes all
241of 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> &middot;
251<a href="home.html#down">download</a> &middot;
252<a href="introduction.html">introduction</a> &middot;
253<a href="reference.html">reference</a>
254</p>
255<p>
256<small>
257Last modified by Diego Nehab on <br>
258Sat Aug 9 01:00:41 PDT 2003
259</small>
260</p>
261</center>
262</div>
263
264</body>
265</html>