aboutsummaryrefslogtreecommitdiff
path: root/docs/url.html
diff options
context:
space:
mode:
authorCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
committerCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
commit5c4fc93d5f4137bf4c22ddf1a048c907a4a26727 (patch)
treea9a68e1f6a9c3bfe2b64fa1c3a4098865b7d3b5d /docs/url.html
parentccef3bc4e2aa6ee5b997a80aabb58f4ff0b0e98f (diff)
parent43a97b7f0053313b43906371dbdc226271e6c8ab (diff)
downloadluasocket-hjelmeland-patch-1.tar.gz
luasocket-hjelmeland-patch-1.tar.bz2
luasocket-hjelmeland-patch-1.zip
Merge branch 'master' into hjelmeland-patch-1hjelmeland-patch-1
Diffstat (limited to 'docs/url.html')
-rw-r--r--docs/url.html328
1 files changed, 328 insertions, 0 deletions
diff --git a/docs/url.html b/docs/url.html
new file mode 100644
index 0000000..6ff673d
--- /dev/null
+++ b/docs/url.html
@@ -0,0 +1,328 @@
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="index.html">home</a> &middot;
28<a href="index.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>
42The <tt>url</tt> namespace provides functions to parse, protect,
43and build URLs, as well as functions to compose absolute URLs
44from base and relative URLs, according to
45<a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>.
46</p>
47
48<p>
49To obtain the <tt>url</tt> namespace, run:
50</p>
51
52<pre class=example>
53-- loads the URL module
54local url = require("socket.url")
55</pre>
56
57<p>
58An URL is defined by the following grammar:
59</p>
60
61<blockquote>
62<tt>
63&lt;url&gt; ::= [&lt;scheme&gt;:][//&lt;authority&gt;][/&lt;path&gt;][;&lt;params&gt;][?&lt;query&gt;][#&lt;fragment&gt;]<br>
64&lt;authority&gt; ::= [&lt;userinfo&gt;@]&lt;host&gt;[:&lt;port&gt;]<br>
65&lt;userinfo&gt; ::= &lt;user&gt;[:&lt;password&gt;]<br>
66&lt;path&gt; ::= {&lt;segment&gt;/}&lt;segment&gt;<br>
67</tt>
68</blockquote>
69
70<!-- absolute +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
71
72<p class=name id="absolute">
73url.<b>absolute(</b>base, relative<b>)</b>
74</p>
75
76<p class=description>
77Builds an absolute URL from a base URL and a relative URL.
78</p>
79
80<p class=parameters>
81<tt>Base</tt> is a string with the base URL or
82a parsed URL table. <tt>Relative</tt> is a
83string with the relative URL.
84</p>
85
86<p class=return>
87The function returns a string with the absolute URL.
88</p>
89
90<p class=note>
91Note: The rules that
92govern the composition are fairly complex, and are described in detail in
93<a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>.
94The example bellow should give an idea of what the rules are.
95</p>
96
97<pre class=example>
98http://a/b/c/d;p?q
99
100+
101
102g:h = g:h
103g = http://a/b/c/g
104./g = http://a/b/c/g
105g/ = http://a/b/c/g/
106/g = http://a/g
107//g = http://g
108?y = http://a/b/c/?y
109g?y = http://a/b/c/g?y
110#s = http://a/b/c/d;p?q#s
111g#s = http://a/b/c/g#s
112g?y#s = http://a/b/c/g?y#s
113;x = http://a/b/c/;x
114g;x = http://a/b/c/g;x
115g;x?y#s = http://a/b/c/g;x?y#s
116. = http://a/b/c/
117./ = http://a/b/c/
118.. = http://a/b/
119../ = http://a/b/
120../g = http://a/b/g
121../.. = http://a/
122../../ = http://a/
123../../g = http://a/g
124</pre>
125
126<!-- build ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
127
128<p class=name id="build">
129url.<b>build(</b>parsed_url<b>)</b>
130</p>
131
132<p class=description>
133Rebuilds an URL from its parts.
134</p>
135
136<p class=parameters>
137<tt>Parsed_url</tt> is a table with same components returned by
138<a href="#parse"><tt>parse</tt></a>.
139Lower level components, if specified,
140take precedence over high level components of the URL grammar.
141</p>
142
143<p class=return>
144The function returns a string with the built URL.
145</p>
146
147<!-- build_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
148
149<p class=name id="build_path">
150url.<b>build_path(</b>segments, unsafe<b>)</b>
151</p>
152
153<p class=description>
154Builds a <tt>&lt;path&gt;</tt> component from a list of
155<tt>&lt;segment&gt;</tt> parts.
156Before composition, any reserved characters found in a segment are escaped into
157their protected form, so that the resulting path is a valid URL path
158component.
159</p>
160
161<p class=parameters>
162<tt>Segments</tt> is a list of strings with the <tt>&lt;segment&gt;</tt>
163parts. If <tt>unsafe</tt> is anything but <b><tt>nil</tt></b>, reserved
164characters are left untouched.
165</p>
166
167<p class=return>
168The function returns a string with the
169built <tt>&lt;path&gt;</tt> component.
170</p>
171
172<!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
173
174<p class=name id="escape">
175url.<b>escape(</b>content<b>)</b>
176</p>
177
178<p class=description>
179Applies the URL escaping content coding to a string
180Each byte is encoded as a percent character followed
181by the two byte hexadecimal representation of its integer
182value.
183</p>
184
185<p class=parameters>
186<tt>Content</tt> is the string to be encoded.
187</p>
188
189<p class=result>
190The function returns the encoded string.
191</p>
192
193<pre class=example>
194-- load url module
195url = require("socket.url")
196
197code = url.escape("/#?;")
198-- code = "%2f%23%3f%3b"
199</pre>
200
201<!-- parse ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
202
203<p class=name id="parse">
204url.<b>parse(</b>url, default<b>)</b>
205</p>
206
207<p class=description>
208Parses an URL given as a string into a Lua table with its components.
209</p>
210
211<p class=parameters>
212<tt>Url</tt> is the URL to be parsed. If the <tt>default</tt> table is
213present, it is used to store the parsed fields. Only fields present in the
214URL are overwritten. Therefore, this table can be used to pass default
215values for each field.
216</p>
217
218<p class=return>
219The function returns a table with all the URL components:
220</p>
221
222<blockquote><tt>
223parsed_url = {<br>
224&nbsp;&nbsp;url = <i>string</i>,<br>
225&nbsp;&nbsp;scheme = <i>string</i>,<br>
226&nbsp;&nbsp;authority = <i>string</i>,<br>
227&nbsp;&nbsp;path = <i>string</i>,<br>
228&nbsp;&nbsp;params = <i>string</i>,<br>
229&nbsp;&nbsp;query = <i>string</i>,<br>
230&nbsp;&nbsp;fragment = <i>string</i>,<br>
231&nbsp;&nbsp;userinfo = <i>string</i>,<br>
232&nbsp;&nbsp;host = <i>string</i>,<br>
233&nbsp;&nbsp;port = <i>string</i>,<br>
234&nbsp;&nbsp;user = <i>string</i>,<br>
235&nbsp;&nbsp;password = <i>string</i><br>
236}
237</tt></blockquote>
238
239<pre class=example>
240-- load url module
241url = require("socket.url")
242
243parsed_url = url.parse("http://www.example.com/cgilua/index.lua?a=2#there")
244-- parsed_url = {
245-- scheme = "http",
246-- authority = "www.example.com",
247-- path = "/cgilua/index.lua"
248-- query = "a=2",
249-- fragment = "there",
250-- host = "www.puc-rio.br",
251-- }
252
253parsed_url = url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i")
254-- parsed_url = {
255-- scheme = "ftp",
256-- authority = "root:passwd@unsafe.org",
257-- path = "/pub/virus.exe",
258-- params = "type=i",
259-- userinfo = "root:passwd",
260-- host = "unsafe.org",
261-- user = "root",
262-- password = "passwd",
263-- }
264</pre>
265
266<!-- parse_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
267
268<p class=name id="parse_path">
269url.<b>parse_path(</b>path<b>)</b>
270</p>
271
272<p class=description>
273Breaks a <tt>&lt;path&gt;</tt> URL component into all its
274<tt>&lt;segment&gt;</tt> parts.
275</p>
276
277<p class=description>
278<tt>Path</tt> is a string with the path to be parsed.
279</p>
280
281<p class=return>
282Since some characters are reserved in URLs, they must be escaped
283whenever present in a <tt>&lt;path&gt;</tt> component. Therefore, before
284returning a list with all the parsed segments, the function removes
285escaping from all of them.
286</p>
287
288<!-- unescape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
289
290<p class=name id="unescape">
291url.<b>unescape(</b>content<b>)</b>
292</p>
293
294<p class=description>
295Removes the URL escaping content coding from a string.
296</p>
297
298<p class=parameters>
299<tt>Content</tt> is the string to be decoded.
300</p>
301
302<p class=return>
303The function returns the decoded string.
304</p>
305
306<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
307
308<div class=footer>
309<hr>
310<center>
311<p class=bar>
312<a href="index.html">home</a> &middot;
313<a href="index.html#down">download</a> &middot;
314<a href="installation.html">installation</a> &middot;
315<a href="introduction.html">introduction</a> &middot;
316<a href="reference.html">reference</a>
317</p>
318<p>
319<small>
320Last modified by Diego Nehab on <br>
321Thu Apr 20 00:26:05 EDT 2006
322</small>
323</p>
324</center>
325</div>
326
327</body>
328</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-22 06:30:53 +0000