uri.html

   1 <html>
   2
   3 <head>
   4 <title>URI support in Allegro CL</title>
   5 </head>
   6
   7 <body>
   8
   9 <h1>URI support in Allegro CL</h1>
  10
  11 <p>This document contains the following sections:</p>
  12 <p><a href="#uri-intro-1">1.0 Introduction</a><br>
  13 <a href="#uri-api-1">2.0 The URI API definition</a><br>
  14 <a href="#parsing-decoding-1">3.0 Parsing, escape decoding/encoding and the path</a><br>
  15 <a href="#interning-uris-1">4.0 Interning URIs</a><br>
  16 <a href="#acl-implementation-1">5.0 Allegro CL implementation notes</a><br>
  17 <a href="#examples-1">6.0 Examples</a><br>
  18 </p>
  19
  20 <p>This version of the Allegro CL URI support documentation is for distribution with the
  21 Open Source version of the URI code. Links to Allegro CL documentation other than
  22 URI-specific files have been supressed. To see Allegro CL documentation, see <a
  23 href="http://www.franz.com/support/documentation/">http://www.franz.com/support/documentation/</a>,
  24 which is the Allegro CL documentation page of the franz inc. website. Links to Allegro CL
  25 documentation can be found on that page. </p>
  26
  27 <hr>
  28
  29 <hr>
  30
  31 <h2><a name="uri-intro-1">1.0 Introduction</a></h2>
  32
  33 <p><em>URI</em> stands for <em>Universal Resource Identifier</em>. For a description of
  34 URIs, see RFC2396, which can be found in several places, including the IETF web site (<a
  35 href="http://www.ietf.org/rfc/rfc2396.txt">http://www.ietf.org/rfc/rfc2396.txt</a>) and
  36 the UCI/ICS web site (<a href="http://www.ics.uci.edu/pub/ietf/uri/rfc2396.txt">http://www.ics.uci.edu/pub/ietf/uri/rfc2396.txt</a>).
  37 We prefer the UCI/ICS one as it has more examples. </p>
  38
  39 <p>URIs are a superset in functionality and syntax to URLs (Universal Resource Locators)
  40 and URNs (Universal Resource Names). That is, RFC2396 updates and merges RFC1738 and
  41 RFC1808 into a single syntax, called the URI. It does exclude some portions of RFC1738
  42 that define specific syntax of individual URL schemes. </p>
  43
  44 <p>In URL slang, the <em>scheme</em> is usually called the `protocol', but it is called
  45 scheme in RFC1738. A URL `host' corresponds to the URI `authority.' The URL slang
  46 `bookmark' or `anchor' is `fragment' in URI lingo. </p>
  47
  48 <p>The URI facility was available as a patch to Allegro CL 5.0.1 and is included with
  49 release 6.0. the URI facility might not be in an Allegro CL image. Evaluate <code>(require
  50 :uri)</code> to ensure the facility is loaded (that form returns <code>nil</code> if the
  51 URI module is already loaded). </p>
  52
  53 <p>Broadly, the URI facility creates a Lisp object that represents a URI, and provides
  54 setters and accessors to fields in the URI object. The URI object can also be interned,
  55 much like symbols in CL are. This document describes the facility and the related
  56 operators. </p>
  57
  58 <p>Aside from the obvious slots which are called out in the RFC, URIs also have a property
  59 list. With interning, this is another similarity between URIs and CL symbols. </p>
  60
  61 <hr>
  62
  63 <hr>
  64
  65 <h2><a name="uri-api-1">2.0 The URI API definition</a></h2>
  66
  67 <p>Symbols naming objects (functions, variables, etc.) in the <em>uri</em> module are
  68 exported from the <code>net.uri</code> package. </p>
  69
  70 <p>URIs are represented by CLOS objects. Their slots are: </p>
  71
  72 <pre>
  73 scheme
  74 host
  75 port
  76 path
  77 query
  78 fragment
  79 plist
  80 </pre>
  81
  82 <p>The <code>host</code> and <code>port</code> slots together correspond to the <code>authority</code>
  83 (see RFC2396). There is an accessor-like function, <a href="operators/uri-authority.htm"><b>uri-authority</b></a>,
  84 that can be used to extract the authority from a URI. See the RFC2396 specifications
  85 pointed to at the beginning of the <a href="#uri-intro-1">1.0 Introduction</a> for details
  86 of all the slots except <code>plist</code>. The <code>plist</code> slot contains a
  87 standard Common Lisp property list. </p>
  88
  89 <p>All symbols are external in the <code>net.uri</code> package, unless otherwise noted.
  90 Brief descriptions are given in this document, with complete descriptions in the
  91 individual pages.
  92
  93 <ul>
  94   <li><a href="classes/uri.htm"><code>uri</code></a>: the class of URI objects. </li>
  95   <li><a href="classes/urn.htm"><code>urn</code></a>: the class of URN objects. </li>
  96   <li><a href="operators/uri-p.htm"><b>uri-p</b></a> <p><b>Arguments: </b><i>object</i></p>
  97     <p>Returns true if <i>object</i> is an instance of class <a href="classes/uri.htm"><code>uri</code></a>.
  98     </p>
  99   </li>
 100   <li><a href="operators/copy-uri.htm"><b>copy-uri</b></a> <p><b>Arguments: </b><i>uri </i>&amp;key
 101     <i>place scheme host port path query fragment plist </i></p>
 102     <p>Copies the specified URI object. See the description page for information on the
 103     keyword arguments. </p>
 104   </li>
 105   <li><a href="operators/uri-scheme.htm"><b>uri-scheme</b></a><br>
 106     <a href="operators/uri-host.htm"><b>uri-host</b></a><br>
 107     <a href="operators/uri-port.htm"><b>uri-port</b></a><br>
 108     <a href="operators/uri-path.htm"><b>uri-path</b></a><br>
 109     <a href="operators/uri-query.htm"><b>uri-query</b></a><br>
 110     <a href="operators/uri-fragment.htm"><b>uri-fragment</b></a><br>
 111     <a href="operators/uri-plist.htm"><b>uri-plist</b></a><br>
 112     <p><b>Arguments: </b><i>uri-object </i></p>
 113     <p>These accessors return the value of the associated slots of the <i>uri-object</i> </p>
 114   </li>
 115   <li><a href="operators/uri-authority.htm"><b>uri-authority</b></a> <p><b>Arguments: </b><i>uri-object
 116     </i></p>
 117     <p>Returns the authority of <i>uri-object</i>. The authority combines the host and port. </p>
 118   </li>
 119   <li><a href="operators/render-uri.htm"><b>render-uri</b></a> <p><b>Arguments: </b><i>uri
 120     stream </i></p>
 121     <p>Print to <i>stream</i> the printed representation of <i>uri</i>. </p>
 122   </li>
 123   <li><a href="operators/parse-uri.htm"><b>parse-uri</b></a> <p><b>Arguments: </b><i>string </i>&amp;key
 124     (<i>class</i> 'uri)<i> </i></p>
 125     <p>Parse <i>string</i> into a URI object. </p>
 126   </li>
 127   <li><a href="operators/merge-uris.htm"><b>merge-uris</b></a> <p><b>Arguments: </b><i>uri
 128     base-uri </i>&amp;optional <i>place </i></p>
 129     <p>Return an absolute URI, based on <i>uri</i>, which can be relative, and <i>base-uri</i>
 130     which must be absolute. </p>
 131   </li>
 132   <li><a href="operators/enough-uri.htm"><b>enough-uri</b></a> <p><b>Arguments: </b><i>uri
 133     base </i></p>
 134     <p>Converts <i>uri</i> into a relative URI using <i>base</i> as the base URI. </p>
 135   </li>
 136   <li><a href="operators/uri-parsed-path.htm"><b>uri-parsed-path</b></a> <p><b>Arguments: </b><i>uri
 137     </i></p>
 138     <p>Return the parsed representation of the path. </p>
 139   </li>
 140   <li><a href="operators/uri.htm"><b>uri</b></a> <p><b>Arguments: </b><i>object </i></p>
 141     <p>Defined methods: if argument is a uri object, return it; create a uri object if
 142     possible and return it, or error if not possible. </p>
 143   </li>
 144 </ul>
 145
 146 <hr>
 147
 148 <hr>
 149
 150 <h2><a name="parsing-decoding-1">3.0 Parsing, escape decoding/encoding and the path</a></h2>
 151
 152 <p>The method <a href="operators/uri-path.htm"><b>uri-path</b></a> returns the path
 153 portion of the URI, in string form. The method <a href="operators/uri-parsed-path.htm"><b>uri-parsed-path</b></a>
 154 returns the path portion of the URI, in list form. This list form is discussed below,
 155 after a discussion of decoding/encoding. </p>
 156
 157 <p>RFC2396 lays out a method for inserting into URIs <em>reserved characters</em>. You do
 158 this by escaping the character. An <em>escaped</em> character is defined like this: </p>
 159
 160 <pre>
 161 escaped = &quot;%&quot; hex hex
 162
 163 hex = digit | &quot;A&quot; | &quot;B&quot; | &quot;C&quot; | &quot;D&quot; | &quot;E&quot; | &quot;F&quot; | &quot;a&quot; | &quot;b&quot; | &quot;c&quot; | &quot;d&quot; | &quot;e&quot; | &quot;f&quot;
 164 </pre>
 165
 166 <p>In addition, the RFC defines excluded characters: </p>
 167
 168 <pre>
 169 &quot;&lt;&quot; | &quot;&gt;&quot; | &quot;#&quot; | &quot;%&quot; | &lt;&quot;&gt; | &quot;{&quot; | &quot;}&quot; | &quot;|&quot; | &quot;\&quot; | &quot;^&quot; | &quot;[&quot; | &quot;]&quot; | &quot;`&quot;
 170 </pre>
 171
 172 <p>The set of reserved characters are: </p>
 173
 174 <pre>
 175 &quot;;&quot; | &quot;/&quot; | &quot;?&quot; | &quot;:&quot; | &quot;@&quot; | &quot;&amp;&quot; | &quot;=&quot; | &quot;+&quot; | &quot;$&quot; | &quot;,&quot;
 176 </pre>
 177
 178 <p>with the following exceptions:
 179
 180 <ul>
 181   <li>within the authority component, the characters &quot;;&quot;, &quot;:&quot;,
 182     &quot;@&quot;, &quot;?&quot;, and &quot;/&quot; are reserved. </li>
 183   <li>within a path segment, the characters &quot;/&quot;, &quot;;&quot;, &quot;=&quot;, and
 184     &quot;?&quot; are reserved. </li>
 185   <li>within a query component, the characters &quot;;&quot;, &quot;/&quot;, &quot;?&quot;,
 186     &quot;:&quot;, &quot;@&quot;, &quot;&amp;&quot;, &quot;=&quot;, &quot;+&quot;,
 187     &quot;,&quot;, and &quot;$&quot; are reserved. </li>
 188 </ul>
 189
 190 <p>From the RFC, there are two important rules about escaping and unescaping (encoding and
 191 decoding):
 192
 193 <ul>
 194   <li>decoding should only happen when the URI is parsed into component parts;</li>
 195   <li>encoding can only occur when a URI is made from component parts (ie, rendered for
 196     printing). </li>
 197 </ul>
 198
 199 <p>The implication of this is that to decode the URI, it must be in a parsed state. That
 200 is, you can't convert <font face="Courier New">%2f</font> (the escaped form of
 201 &quot;/&quot;) until the path has been parsed into its component parts. Another important
 202 desire is for the application viewing the component parts to see the decoded values of the
 203 components. For example, consider: </p>
 204
 205 <pre>
 206 http://www.franz.com/calculator/3%2f2
 207 </pre>
 208
 209 <p>This might be the implementation of a calculator, and how someone would execute 3/2.
 210 Clearly, the application that implements this would want to see path components of
 211 &quot;calculator&quot; and &quot;3/2&quot;. &quot;3%2f2&quot; would not be useful to the
 212 calculator application. </p>
 213
 214 <p>For the reasons given above, a parsed version of the path is available and has the
 215 following form: </p>
 216
 217 <pre>
 218 ([:absolute | :relative] component1 [component2...])
 219 </pre>
 220
 221 <p>where components are: </p>
 222
 223 <pre>
 224 element | (element param1 [param2 ...])
 225 </pre>
 226
 227 <p>and <em>element</em> is a path element, and the param's are path element parameters.
 228 For example, the result of </p>
 229
 230 <pre>
 231 (uri-parsed-path (parse-uri &quot;foo;10/bar:x;y;z/baz.htm&quot;))
 232 </pre>
 233
 234 <p>is </p>
 235
 236 <pre>
 237 (:relative (&quot;foo&quot; &quot;10&quot;) (&quot;bar:x&quot; &quot;y&quot; &quot;z&quot;) &quot;baz.htm&quot;)
 238 </pre>
 239
 240 <p>There is a certain amount of canonicalization that occurs when parsing:
 241
 242 <ul>
 243   <li>A path of <code>(:absolute)</code> or <code>(:absolute &quot;&quot;)</code> is
 244     equivalent to a <code>nil</code> path. That is, <code>http://a/</code> is parsed with a <code>nil</code>
 245     path and printed as <code>http://a</code>. </li>
 246   <li>Escaped characters that are not reserved are not escaped upon printing. For example, <code>&quot;foob%61r&quot;</code>
 247     is parsed into <code>&quot;foobar&quot;</code> and appears as <code>&quot;foobar&quot;</code>
 248     when the URI is printed. </li>
 249 </ul>
 250
 251 <hr>
 252
 253 <hr>
 254
 255 <h2><a name="interning-uris-1">4.0 Interning URIs</a></h2>
 256
 257 <p>This section describes how to intern URIs. Interning is not mandatory. URIs can be used
 258 perfectly well without interning them. </p>
 259
 260 <p>Interned URIs in Allegro are like symbols. That is, a string representing a URI, when
 261 parsed and interned, will always yield an <strong>eq</strong> object. For example: </p>
 262
 263 <pre>
 264 (eq (intern-uri &quot;http://www.franz.com&quot;)
 265     (intern-uri &quot;http://www.franz.com&quot;))
 266 </pre>
 267
 268 <p>is always true. (Two strings with identical contents may or may not be <strong>eq</strong>
 269 in Common Lisp, note.) </p>
 270
 271 <p>The functions associated with interning are:
 272
 273 <ul>
 274   <li><a href="operators/make-uri-space.htm"><b>make-uri-space</b></a> <p><b>Arguments: </b>&amp;key
 275     <i>size </i></p>
 276     <p>Make a new hash-table object to contain interned URIs. </p>
 277   </li>
 278   <li><a href="operators/uri-space.htm"><b>uri-space</b></a> <p><b>Arguments: </b></p>
 279     <p>Return the object into which URIs are currently being interned. </p>
 280   </li>
 281   <li><a href="operators/uri_eq.htm"><b>uri=</b></a> <p><b>Arguments: </b><i>uri1 uri2 </i></p>
 282     <p>Returns true if <i>uri1</i> and <i>uri2</i> are equivalent. </p>
 283   </li>
 284   <li><a href="operators/intern-uri.htm"><b>intern-uri</b></a> <p><b>Arguments: </b><i>uri-name
 285     </i>&amp;optional <i>uri-space </i></p>
 286     <p>Intern the uri object specified in the uri-space specified. Methods exist for strings
 287     and uri objects. </p>
 288   </li>
 289   <li><a href="operators/unintern-uri.htm"><b>unintern-uri</b></a> <p><b>Arguments: </b><i>uri
 290     </i>&amp;optional <i>uri-space </i></p>
 291     <p>Unintern the uri object specified or all uri objects (in <i>uri-space</i> if specified)
 292     if <i>uri</i> is <code>t</code>. </p>
 293   </li>
 294   <li><a href="operators/do-all-uris.htm"><b>do-all-uris</b></a> <p><b>Arguments: </b><i>(var </i>&amp;optional
 295     <i>uri-space result) </i>&amp;body <i>body </i></p>
 296     <p>Bind <i>var</i> to all currently defined uris (in <i>uri-space</i> if specified) and
 297     evaluate <i>body</i>. </p>
 298   </li>
 299 </ul>
 300
 301 <hr>
 302
 303 <hr>
 304
 305 <h2><a name="acl-implementation-1">5.0 Allegro CL implementation notes</a></h2>
 306
 307 <ol>
 308   <li>The following are true: <br>
 309     <code>(uri= (parse-uri &quot;http://www.franz.com/&quot;)</code> <br>
 310     &nbsp; &nbsp; <code>(parse-uri &quot;http://www.franz.com&quot;))</code> <br>
 311     <code>(eq (intern-uri &quot;http://www.franz.com/&quot;)</code> <br>
 312     &nbsp;&nbsp; <code>(intern-uri &quot;http://www.franz.com&quot;))</code><br>
 313   </li>
 314   <li>The following is true: <br>
 315     <code>(eq (intern-uri &quot;http://www.franz.com:80/foo/bar.htm&quot;)</code> <br>
 316     &nbsp; &nbsp; <code>(intern-uri &quot;http://www.franz.com/foo/bar.htm&quot;))</code><br>
 317     (I.e. specifying the default port is the same as specifying no port at all. This is
 318     specific in RFC2396.) </li>
 319   <li>The <em>scheme</em> and <em>authority</em> are case-insensitive. In Allegro CL, the
 320     scheme is a keyword that appears in the normal case for the Lisp in which you are
 321     executing. </li>
 322   <li><code>#u&quot;...&quot;</code> is shorthand for <code>(parse-uri &quot;...&quot;)</code>
 323     but if an existing <code>#u</code> dispatch macro definition exists, it will not be
 324     overridden. </li>
 325   <li>The interaction between setting the scheme, host, port, path, query, and fragment slots
 326     of URI objects, in conjunction with interning URIs will have very bad and unpredictable
 327     results. </li>
 328   <li>The printable representation of URIs is cached, for efficiency. This caching is undone
 329     when the above slots are changed. That is, when you create a URI the printed
 330     representation is cached. When you change one of the above mentioned slots, the printed
 331     representation is cleared and calculated when the URI is next printed. For example: </li>
 332 </ol>
 333
 334 <pre>
 335 user(10): (setq u #u&quot;http://foo.bar.com/foo/bar&quot;)
 336 #&lt;uri http://foo.bar.com/foo/bar&gt;
 337 user(11): (setf (net.uri:uri-host u) &quot;foo.com&quot;)
 338 &quot;foo.com&quot;
 339 user(12): u
 340 #&lt;uri http://foo.com/foo/bar&gt;
 341 user(13):
 342 </pre>
 343
 344 <p>This allows URIs behavior to follow the principle of least surprise. </p>
 345
 346 <hr>
 347
 348 <hr>
 349
 350 <h2><a name="examples-1">6.0 Examples</a></h2>
 351
 352 <pre>
 353 uri(10): (use-package :net.uri)
 354 t
 355 uri(11): (parse-uri &quot;foo&quot;)
 356 #&lt;uri foo&gt;
 357 uri(12): #u&quot;foo&quot;
 358 #&lt;uri foo&gt;
 359 uri(13): (setq base (intern-uri &quot;http://www.franz.com/foo/bar/&quot;))
 360 #&lt;uri http://www.franz.com/foo/bar/&gt;
 361 uri(14): (merge-uris (parse-uri &quot;foo.htm&quot;) base)
 362 #&lt;uri http://www.franz.com/foo/bar/foo.htm&gt;
 363 uri(15): (merge-uris (parse-uri &quot;?foo&quot;) base)
 364 #&lt;uri http://www.franz.com/foo/bar/?foo&gt;
 365 uri(16): (setq base (intern-uri &quot;http://www.franz.com/foo/bar/baz.htm&quot;))
 366 #&lt;uri http://www.franz.com/foo/bar/baz.htm&gt;
 367 uri(17): (merge-uris (parse-uri &quot;foo.htm&quot;) base)
 368 #&lt;uri http://www.franz.com/foo/bar/foo.htm&gt;
 369 uri(18): (merge-uris #u&quot;?foo&quot; base)
 370 #&lt;uri http://www.franz.com/foo/bar/?foo&gt;
 371 uri(19): (describe #u&quot;http://www.franz.com&quot;)
 372 #&lt;uri http://www.franz.com&gt; is an instance of #&lt;standard-class net.uri:uri&gt;:
 373  The following slots have :instance allocation:
 374   scheme        :http
 375   host          &quot;www.franz.com&quot;
 376   port          nil
 377   path          nil
 378   query         nil
 379   fragment      nil
 380   plist         nil
 381   escaped       nil
 382   string        &quot;http://www.franz.com&quot;
 383   parsed-path   nil
 384   hashcode      nil
 385 uri(20): (describe #u&quot;http://www.franz.com/&quot;)
 386 #&lt;uri http://www.franz.com&gt; is an instance of #&lt;standard-class net.uri:uri&gt;:
 387  The following slots have :instance allocation:
 388   scheme        :http
 389   host          &quot;www.franz.com&quot;
 390   port          nil
 391   path          nil
 392   query         nil
 393   fragment      nil
 394   plist         nil
 395   escaped       nil
 396   string        &quot;http://www.franz.com&quot;
 397   parsed-path   nil
 398   hashcode      nil
 399 uri(21): #u&quot;foobar#baz%23xxx&quot;
 400 #&lt;uri foobar#baz#xxx&gt;
 401 </pre>
 402
 403 <p><small>Copyright (c) 1998-2001, Franz Inc. Berkeley, CA., USA. All rights reserved.
 404 Created 2001.8.16.</small></p>
 405 </body>
 406 </html>