4 <title>URI support in Allegro CL</title>
9 <h1>URI support in Allegro CL</h1>
11 <p>This document contains the following sections:</p>
12 <a href="#uri-intro-1">
14 <p>1.0 Introduction</a><br>
15 <a href="#uri-api-1">2.0 The URI API definition</a><br>
16 <a href="#parsing-decoding-1">3.0 Parsing, escape decoding/encoding and the path</a><br>
17 <a href="#interning-uris-1">4.0 Interning URIs</a><br>
18 <a href="#acl-implementation-1">5.0 Allegro CL implementation notes</a><br>
19 <a href="#examples-1">6.0 Examples</a><br>
22 <p>This version of the Allegro CL URI support documentation is for distribution with the
23 Open Source version of the URI code. Links to Allegro CL documentation other than
24 URI-specific files have been supressed. To see Allegro CL documentation, see <a
25 href="http://www.franz.com/support/documentation/">http://www.franz.com/support/documentation/</a>,
26 which is the Allegro CL documentation page of the franz inc. website. Links to Allegro CL
27 documentation can be found on that page. </p>
33 <h2><a name="uri-intro-1">1.0 Introduction</a></h2>
35 <p><em>URI</em> stands for <em>Universal Resource Identifier</em>. For a description of
36 URIs, see RFC2396, which can be found in several places, including the IETF web site (<a
37 href="http://www.ietf.org/rfc/rfc2396.txt">http://www.ietf.org/rfc/rfc2396.txt</a>) and
38 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>).
39 We prefer the UCI/ICS one as it has more examples. </p>
41 <p>URIs are a superset in functionality and syntax to URLs (Universal Resource Locators)
42 and URNs (Universal Resource Names). That is, RFC2396 updates and merges RFC1738 and
43 RFC1808 into a single syntax, called the URI. It does exclude some portions of RFC1738
44 that define specific syntax of individual URL schemes. </p>
46 <p>In URL slang, the <em>scheme</em> is usually called the `protocol', but it is called
47 scheme in RFC1738. A URL `host' corresponds to the URI `authority.' The URL slang
48 `bookmark' or `anchor' is `fragment' in URI lingo. </p>
50 <p>The URI facility was available as a patch to Allegro CL 5.0.1 and is included with
51 release 6.0. the URI facility might not be in an Allegro CL image. Evaluate <code>(require
52 :uri)</code> to ensure the facility is loaded (that form returns <code>nil</code> if the
53 URI module is already loaded). </p>
55 <p>Broadly, the URI facility creates a Lisp object that represents a URI, and provides
56 setters and accessors to fields in the URI object. The URI object can also be interned,
57 much like symbols in CL are. This document describes the facility and the related
60 <p>Aside from the obvious slots which are called out in the RFC, URIs also have a property
61 list. With interning, this is another similarity between URIs and CL symbols. </p>
67 <h2><a name="uri-api-1">2.0 The URI API definition</a></h2>
69 <p>Symbols naming objects (functions, variables, etc.) in the <em>uri</em> module are
70 exported from the <code>net.uri</code> package. </p>
72 <p>URIs are represented by CLOS objects. Their slots are: </p>
84 <p>The <code>host</code> and <code>port</code> slots together correspond to the <code>authority</code>
85 (see RFC2396). There is an accessor-like function, <a href="operators/uri-authority.htm"><b>uri-authority</b></a>,
86 that can be used to extract the authority from a URI. See the RFC2396 specifications
87 pointed to at the beginning of the <a href="#uri-intro-1">1.0 Introduction</a> for details
88 of all the slots except <code>plist</code>. The <code>plist</code> slot contains a
89 standard Common Lisp property list. </p>
91 <p>All symbols are external in the <code>net.uri</code> package, unless otherwise noted.
92 Brief descriptions are given in this document, with complete descriptions in the
96 <li><a href="classes/uri.htm"><code>uri</code></a>: the class of URI objects. </li>
97 <li><a href="classes/urn.htm"><code>urn</code></a>: the class of URN objects. </li>
98 <li><a href="operators/uri-p.htm"><b>uri-p</b></a> <p><b>Arguments: </b><i>object</i></p>
99 <p>Returns true if <i>object</i> is an instance of class <a href="classes/uri.htm"><code>uri</code></a>.
102 <li><a href="operators/copy-uri.htm"><b>copy-uri</b></a> <p><b>Arguments: </b><i>uri </i>&key
103 <i>place scheme host port path query fragment plist </i></p>
104 <p>Copies the specified URI object. See the description page for information on the
105 keyword arguments. </p>
107 <li><a href="operators/uri-scheme.htm"><b>uri-scheme</b></a><br>
108 <a href="operators/uri-host.htm"><b>uri-host</b></a><br>
109 <a href="operators/uri-port.htm"><b>uri-port</b></a><br>
110 <a href="operators/uri-path.htm"><b>uri-path</b></a><br>
111 <a href="operators/uri-query.htm"><b>uri-query</b></a><br>
112 <a href="operators/uri-fragment.htm"><b>uri-fragment</b></a><br>
113 <a href="operators/uri-plist.htm"><b>uri-plist</b></a><br>
114 <p><b>Arguments: </b><i>uri-object </i></p>
115 <p>These accessors return the value of the associated slots of the <i>uri-object</i> </p>
117 <li><a href="operators/uri-authority.htm"><b>uri-authority</b></a> <p><b>Arguments: </b><i>uri-object
119 <p>Returns the authority of <i>uri-object</i>. The authority combines the host and port. </p>
121 <li><a href="operators/render-uri.htm"><b>render-uri</b></a> <p><b>Arguments: </b><i>uri
123 <p>Print to <i>stream</i> the printed representation of <i>uri</i>. </p>
125 <li><a href="operators/parse-uri.htm"><b>parse-uri</b></a> <p><b>Arguments: </b><i>string </i>&key
126 (<i>class</i> 'uri)<i> </i></p>
127 <p>Parse <i>string</i> into a URI object. </p>
129 <li><a href="operators/merge-uris.htm"><b>merge-uris</b></a> <p><b>Arguments: </b><i>uri
130 base-uri </i>&optional <i>place </i></p>
131 <p>Return an absolute URI, based on <i>uri</i>, which can be relative, and <i>base-uri</i>
132 which must be absolute. </p>
134 <li><a href="operators/enough-uri.htm"><b>enough-uri</b></a> <p><b>Arguments: </b><i>uri
136 <p>Converts <i>uri</i> into a relative URI using <i>base</i> as the base URI. </p>
138 <li><a href="operators/uri-parsed-path.htm"><b>uri-parsed-path</b></a> <p><b>Arguments: </b><i>uri
140 <p>Return the parsed representation of the path. </p>
142 <li><a href="operators/uri.htm"><b>uri</b></a> <p><b>Arguments: </b><i>object </i></p>
143 <p>Defined methods: if argument is a uri object, return it; create a uri object if
144 possible and return it, or error if not possible. </p>
152 <h2><a name="parsing-decoding-1">3.0 Parsing, escape decoding/encoding and the path</a></h2>
154 <p>The method <a href="operators/uri-path.htm"><b>uri-path</b></a> returns the path
155 portion of the URI, in string form. The method <a href="operators/uri-parsed-path.htm"><b>uri-parsed-path</b></a>
156 returns the path portion of the URI, in list form. This list form is discussed below,
157 after a discussion of decoding/encoding. </p>
159 <p>RFC2396 lays out a method for inserting into URIs <em>reserved characters</em>. You do
160 this by escaping the character. An <em>escaped</em> character is defined like this: </p>
163 escaped = "%" hex hex
165 hex = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f"
168 <p>In addition, the RFC defines excluded characters: </p>
171 "<" | ">" | "#" | "%" | <"> | "{" | "}" | "|" | "\" | "^" | "[" | "]" | "`"
174 <p>The set of reserved characters are: </p>
177 ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" | "$" | ","
180 <p>with the following exceptions:
183 <li>within the authority component, the characters ";", ":",
184 "@", "?", and "/" are reserved. </li>
185 <li>within a path segment, the characters "/", ";", "=", and
186 "?" are reserved. </li>
187 <li>within a query component, the characters ";", "/", "?",
188 ":", "@", "&", "=", "+",
189 ",", and "$" are reserved. </li>
192 <p>From the RFC, there are two important rules about escaping and unescaping (encoding and
196 <li>decoding should only happen when the URI is parsed into component parts;</li>
197 <li>encoding can only occur when a URI is made from component parts (ie, rendered for
201 <p>The implication of this is that to decode the URI, it must be in a parsed state. That
202 is, you can't convert <font face="Courier New">%2f</font> (the escaped form of
203 "/") until the path has been parsed into its component parts. Another important
204 desire is for the application viewing the component parts to see the decoded values of the
205 components. For example, consider: </p>
208 http://www.franz.com/calculator/3%2f2
211 <p>This might be the implementation of a calculator, and how someone would execute 3/2.
212 Clearly, the application that implements this would want to see path components of
213 "calculator" and "3/2". "3%2f2" would not be useful to the
214 calculator application. </p>
216 <p>For the reasons given above, a parsed version of the path is available and has the
220 ([:absolute | :relative] component1 [component2...])
223 <p>where components are: </p>
226 element | (element param1 [param2 ...])
229 <p>and <em>element</em> is a path element, and the param's are path element parameters.
230 For example, the result of </p>
233 (uri-parsed-path (parse-uri "foo;10/bar:x;y;z/baz.htm"))
239 (:relative ("foo" "10") ("bar:x" "y" "z") "baz.htm")
242 <p>There is a certain amount of canonicalization that occurs when parsing:
245 <li>A path of <code>(:absolute)</code> or <code>(:absolute "")</code> is
246 equivalent to a <code>nil</code> path. That is, <code>http://a/</code> is parsed with a <code>nil</code>
247 path and printed as <code>http://a</code>. </li>
248 <li>Escaped characters that are not reserved are not escaped upon printing. For example, <code>"foob%61r"</code>
249 is parsed into <code>"foobar"</code> and appears as <code>"foobar"</code>
250 when the URI is printed. </li>
257 <h2><a name="interning-uris-1">4.0 Interning URIs</a></h2>
259 <p>This section describes how to intern URIs. Interning is not mandatory. URIs can be used
260 perfectly well without interning them. </p>
262 <p>Interned URIs in Allegro are like symbols. That is, a string representing a URI, when
263 parsed and interned, will always yield an <strong>eq</strong> object. For example: </p>
266 (eq (intern-uri "http://www.franz.com")
267 (intern-uri "http://www.franz.com"))
270 <p>is always true. (Two strings with identical contents may or may not be <strong>eq</strong>
271 in Common Lisp, note.) </p>
273 <p>The functions associated with interning are:
276 <li><a href="operators/make-uri-space.htm"><b>make-uri-space</b></a> <p><b>Arguments: </b>&key
278 <p>Make a new hash-table object to contain interned URIs. </p>
280 <li><a href="operators/uri-space.htm"><b>uri-space</b></a> <p><b>Arguments: </b></p>
281 <p>Return the object into which URIs are currently being interned. </p>
283 <li><a href="operators/uri_eq.htm"><b>uri=</b></a> <p><b>Arguments: </b><i>uri1 uri2 </i></p>
284 <p>Returns true if <i>uri1</i> and <i>uri2</i> are equivalent. </p>
286 <li><a href="operators/intern-uri.htm"><b>intern-uri</b></a> <p><b>Arguments: </b><i>uri-name
287 </i>&optional <i>uri-space </i></p>
288 <p>Intern the uri object specified in the uri-space specified. Methods exist for strings
289 and uri objects. </p>
291 <li><a href="operators/unintern-uri.htm"><b>unintern-uri</b></a> <p><b>Arguments: </b><i>uri
292 </i>&optional <i>uri-space </i></p>
293 <p>Unintern the uri object specified or all uri objects (in <i>uri-space</i> if specified)
294 if <i>uri</i> is <code>t</code>. </p>
296 <li><a href="operators/do-all-uris.htm"><b>do-all-uris</b></a> <p><b>Arguments: </b><i>(var </i>&optional
297 <i>uri-space result) </i>&body <i>body </i></p>
298 <p>Bind <i>var</i> to all currently defined uris (in <i>uri-space</i> if specified) and
299 evaluate <i>body</i>. </p>
307 <h2><a name="acl-implementation-1">5.0 Allegro CL implementation notes</a></h2>
310 <li>The following are true: <br>
311 <code>(uri= (parse-uri "http://www.franz.com/")</code> <br>
312 <code>(parse-uri "http://www.franz.com"))</code> <br>
313 <code>(eq (intern-uri "http://www.franz.com/")</code> <br>
314 <code>(intern-uri "http://www.franz.com"))</code><br>
316 <li>The following is true: <br>
317 <code>(eq (intern-uri "http://www.franz.com:80/foo/bar.htm")</code> <br>
318 <code>(intern-uri "http://www.franz.com/foo/bar.htm"))</code><br>
319 (I.e. specifying the default port is the same as specifying no port at all. This is
320 specific in RFC2396.) </li>
321 <li>The <em>scheme</em> and <em>authority</em> are case-insensitive. In Allegro CL, the
322 scheme is a keyword that appears in the normal case for the Lisp in which you are
324 <li><code>#u"..."</code> is shorthand for <code>(parse-uri "...")</code>
325 but if an existing <code>#u</code> dispatch macro definition exists, it will not be
327 <li>The interaction between setting the scheme, host, port, path, query, and fragment slots
328 of URI objects, in conjunction with interning URIs will have very bad and unpredictable
330 <li>The printable representation of URIs is cached, for efficiency. This caching is undone
331 when the above slots are changed. That is, when you create a URI the printed
332 representation is cached. When you change one of the above mentioned slots, the printed
333 representation is cleared and calculated when the URI is next printed. For example: </li>
337 user(10): (setq u #u"http://foo.bar.com/foo/bar")
338 #<uri http://foo.bar.com/foo/bar>
339 user(11): (setf (net.uri:uri-host u) "foo.com")
342 #<uri http://foo.com/foo/bar>
346 <p>This allows URIs behavior to follow the principle of least surprise. </p>
352 <h2><a name="examples-1">6.0 Examples</a></h2>
355 uri(10): (use-package :net.uri)
357 uri(11): (parse-uri "foo")
359 uri(12): #u"foo"
361 uri(13): (setq base (intern-uri "http://www.franz.com/foo/bar/"))
362 #<uri http://www.franz.com/foo/bar/>
363 uri(14): (merge-uris (parse-uri "foo.htm") base)
364 #<uri http://www.franz.com/foo/bar/foo.htm>
365 uri(15): (merge-uris (parse-uri "?foo") base)
366 #<uri http://www.franz.com/foo/bar/?foo>
367 uri(16): (setq base (intern-uri "http://www.franz.com/foo/bar/baz.htm"))
368 #<uri http://www.franz.com/foo/bar/baz.htm>
369 uri(17): (merge-uris (parse-uri "foo.htm") base)
370 #<uri http://www.franz.com/foo/bar/foo.htm>
371 uri(18): (merge-uris #u"?foo" base)
372 #<uri http://www.franz.com/foo/bar/?foo>
373 uri(19): (describe #u"http://www.franz.com")
374 #<uri http://www.franz.com> is an instance of #<standard-class net.uri:uri>:
375 The following slots have :instance allocation:
377 host "www.franz.com"
384 string "http://www.franz.com"
387 uri(20): (describe #u"http://www.franz.com/")
388 #<uri http://www.franz.com> is an instance of #<standard-class net.uri:uri>:
389 The following slots have :instance allocation:
391 host "www.franz.com"
398 string "http://www.franz.com"
401 uri(21): #u"foobar#baz%23xxx"
402 #<uri foobar#baz#xxx>
405 <p><small>Copyright (c) 1998-2001, Franz Inc. Berkeley, CA., USA. All rights reserved.
406 Created 2001.8.16.</small></p>