source/texk/web2c/luatexdir/luasocket/doc/url.html

   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>
  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.ietf.org/rfc/rfc2396.txt">RFC 2396</a>.
  46 </p>
  47
  48 <p>
  49 To obtain the <tt>url</tt> namespace, run:
  50 </p>
  51
  52 <pre class=example>
  53 -- loads the URL module
  54 local url = require("socket.url")
  55 </pre>
  56
  57 <p>
  58 An 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">
  73 url.<b>absolute(</b>base, relative<b>)</b>
  74 </p>
  75
  76 <p class=description>
  77 Builds 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
  82 a parsed URL table.  <tt>Relative</tt> is a
  83 string with the relative URL.
  84 </p>
  85
  86 <p class=return>
  87 The function returns a string with the absolute URL.
  88 </p>
  89
  90 <p class=note>
  91 Note: The rules that
  92 govern the composition are fairly complex, and are described in detail in
  93 <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>.
  94 The example bellow should give an idea of what the rules are.
  95 </p>
  96
  97 <pre class=example>
  98 http://a/b/c/d;p?q
  99
 100 +
 101
 102 g:h      =  g:h
 103 g        =  http://a/b/c/g
 104 ./g      =  http://a/b/c/g
 105 g/       =  http://a/b/c/g/
 106 /g       =  http://a/g
 107 //g      =  http://g
 108 ?y       =  http://a/b/c/?y
 109 g?y      =  http://a/b/c/g?y
 110 #s       =  http://a/b/c/d;p?q#s
 111 g#s      =  http://a/b/c/g#s
 112 g?y#s    =  http://a/b/c/g?y#s
 113 ;x       =  http://a/b/c/;x
 114 g;x      =  http://a/b/c/g;x
 115 g;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">
 129 url.<b>build(</b>parsed_url<b>)</b>
 130 </p>
 131
 132 <p class=description>
 133 Rebuilds 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>.
 139 Lower level components, if specified,
 140 take  precedence over  high level  components of  the URL grammar.
 141 </p>
 142
 143 <p class=return>
 144 The function returns a string with the built URL.
 145 </p>
 146
 147 <!-- build_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 148
 149 <p class=name id="build_path">
 150 url.<b>build_path(</b>segments, unsafe<b>)</b>
 151 </p>
 152
 153 <p class=description>
 154 Builds a <tt>&lt;path&gt;</tt> component from  a list of
 155 <tt>&lt;segment&gt;</tt> parts.
 156 Before composition, any reserved characters found in a segment are escaped into
 157 their protected  form, so that  the resulting path  is a valid  URL path
 158 component.
 159 </p>
 160
 161 <p class=parameters>
 162 <tt>Segments</tt> is a list of strings with the <tt>&lt;segment&gt;</tt>
 163 parts. If <tt>unsafe</tt>  is anything  but <b><tt>nil</tt></b>,  reserved
 164 characters are left untouched.
 165 </p>
 166
 167 <p class=return>
 168 The  function  returns   a string with the
 169 built <tt>&lt;path&gt;</tt> component.
 170 </p>
 171
 172 <!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 173
 174 <p class=name id="escape">
 175 url.<b>escape(</b>content<b>)</b>
 176 </p>
 177
 178 <p class=description>
 179 Applies the URL escaping content coding to a string
 180 Each byte is encoded as a percent character followed
 181 by the two byte hexadecimal representation of its integer
 182 value.
 183 </p>
 184
 185 <p class=parameters>
 186 <tt>Content</tt> is the string to be encoded.
 187 </p>
 188
 189 <p class=result>
 190 The function returns the encoded string.
 191 </p>
 192
 193 <pre class=example>
 194 -- load url module
 195 url = require("socket.url")
 196
 197 code = url.escape("/#?;")
 198 -- code = "%2f%23%3f%3b"
 199 </pre>
 200
 201 <!-- parse ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 202
 203 <p class=name id="parse">
 204 url.<b>parse(</b>url, default<b>)</b>
 205 </p>
 206
 207 <p class=description>
 208 Parses 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
 213 present, it is used to store the parsed fields. Only fields present in the
 214 URL are overwritten. Therefore, this table can be used to pass default
 215 values for each field.
 216 </p>
 217
 218 <p class=return>
 219 The function returns a table with all the URL components:
 220 </p>
 221
 222 <blockquote><tt>
 223 parsed_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
 241 url = require("socket.url")
 242
 243 parsed_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
 253 parsed_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">
 269 url.<b>parse_path(</b>path<b>)</b>
 270 </p>
 271
 272 <p class=description>
 273 Breaks 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>
 282 Since  some characters   are   reserved   in   URLs,  they must be escaped
 283 whenever present in a <tt>&lt;path&gt;</tt> component. Therefore, before
 284 returning a list with all the parsed segments, the function removes
 285 escaping from all of them.
 286 </p>
 287
 288 <!-- unescape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 289
 290 <p class=name id="unescape">
 291 url.<b>unescape(</b>content<b>)</b>
 292 </p>
 293
 294 <p class=description>
 295 Removes  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>
 303 The 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>
 320 Last modified by Diego Nehab on <br>
 321 Thu Apr 20 00:26:05 EDT 2006
 322 </small>
 323 </p>
 324 </center>
 325 </div>
 326
 327 </body>
 328 </html>