source: project/url/url.html.v3.1 @ 4083

Last change on this file since 4083 was 4083, checked in by daishi, 14 years ago

moving url egg to uri egg

File size: 19.8 KB
Line 
1<html lang="en">
2<head>
3<title>Eggs Unlimited - url</title>
4<meta http-equiv="Content-Type" content="text/html">
5<meta http-equiv="Content-Style-Type" content="text/css">
6<style type="text/css"><!--
7  pre.display { font-family:inherit }
8  pre.format  { font-family:inherit }
9  pre.smalldisplay { font-family:inherit; font-size:smaller }
10  pre.smallformat  { font-family:inherit; font-size:smaller }
11  pre.smallexample { font-size:smaller }
12  pre.smalllisp    { font-size:smaller }
13  span.sc    { font-variant:small-caps }
14  span.roman { font-family:serif; font-weight:normal; }
15  span.sansserif { font-family:sans-serif; font-weight:normal; }
16--></style>
17</head>
18<body>
19
20<center><img src="egg.jpg"></center>
21<center><a href="index.html">back</a></center>
22
23<h2>url</h2>
24
25<h3>Description:</h3>
26Basic facilities for parsing RFC 1739 Uniform Resource Locators & RFC 3986 Uniform Resource Identifiers
27
28<h3>Author:</h3>
29<a href="mailto:felix@call-with-current-continuation.org">felix</a>
30
31<h3>Version:</h3>
32<ul>
33<li>3.1 [Alejandro Forero Cuervo]
34  <ul>
35    <li>Small bug fix for <code>url-encode</code>.</li>
36  </ul>
37</li>
38<li>3.0 [Kon Lovett]
39  <ul>
40  <li>Added support for string authority & query arguments to <code>make-uri</code>.</li>
41  <li>Added <code>uri-encode-split-path</code>, <code>uri-split-path-null?</code>,
42  <code>uri-path-null?</code>, <code>uri-decode-split-path</code>, and
43  <code>pathname-&gt;uri</code>.</li>
44  <li>Deprecated <code>uri-make-path</code>, <code>uri-split-fields</code>,
45  <code>uri-path-&gt;keys</code>, <code>path-&gt;uri</code>, <code>absolute-path?</code>,
46  <code>null-directory?</code>, <code>glob-pattern?</code>.</li>
47  <li>Added cached userinfo values.</li>
48  <li>Query string parsing now signals an error condition.</li>
49  <li>Changed query alist key type to string so the symbol table is not needlessly
50  expanded. This change is incompatible, thus the full version number release.</li>
51  </ul>
52</li>
53<li>2.1
54Bug fix for null path [Reported by John Janecek], also added reader & printer, bug fix for
55missing authority [Kon Lovett]</li>
56<li>2.0
57Combined uri egg & url egg [Daishi Kato & Kon Lovett]
58<li>1.1 Bug fix for <code>uri-&gt;url</code>, add userinfo accessors</li>
59<li>1.0 Initial Release</li>
60</ul>
61
62<h3>Usage:</h3>
63<pre>
64(require-extension url)
65</pre>
66
67<h3>Download:</h3>
68<a href="url.scm">url.scm</a>
69
70<h3>Requires:</h3>
71<a href="coerce.html">coerce</a>
72
73<h3>Documentation:</h3>
74
75<div class="defun">
76[procedure] (<b>exn-uri-query-parse-condition?</b> <var>X</var>)<br/>
77<blockquote>
78<p>Returns <code>#t</code> if <code>X</code> is a <code>exn-uri-query-parse-condition</code>
79object, or <code>#f</code> otherwise.
80<ul>
81<li>Condition kind of (exn uri query parse).</li>
82<li>Properties of 'location, 'message, 'arguments, and 'string, where string is the remaining
83query string at the point of failure.</li>
84</ul></p>
85</blockquote>
86</div>
87
88<div class="defun">
89[procedure] (<b>uri?</b> <var>X</var>)<br/>
90<blockquote>
91<p>Returns <code>#t</code> if <code>X</code> is an URI object, or <code>#f</code> otherwise.</p>
92</blockquote>
93</div>
94
95<div class="defun">
96[procedure] (<b>make-uri</b> <var>#!key scheme authority path query fragment</var>)<br/>
97<blockquote>
98<p>Returns a Uniform Resource Identifier object from <em>unencoded</em>
99component arguments.</p>
100<ul>
101<li>Scheme maybe a symbol or string, in which case it is converted to a symbol.</li>
102<li>Authority is a list of (userinfo host port) where userinfo is a string
103<code>"username:password"</code>, host is a string, and port is an integer. Any can be
104<code>#f</code>, indicating a missing item. Authority can also be a string, in which case it
105is parsed into a list form.</li>
106<li>Path maybe a list of ([directory ...] basename) where directory and basename
107are strings, or a string, in which case it is parsed into a path-list (also known as a "split
108path").</li>
109<li>Query is an association list where the key is a string and the value is any object. Query
110can also be a string, in which case it is parsed into an association list. An ill-formed query
111string, such as <code>"?foo?bar"</code>, will abort with a
112<code>exn-uri-query-parse-condition</code>.</li>
113<li>Fragment is a string.</li>
114</ul>
115</blockquote></div>
116
117<div class="defun">
118[procedure] (<b>uri-scheme</b> <var>URI</var>)<br/>
119[procedure] (<b>uri-scheme-specific</b> <var>URI</var>)<br/>
120[procedure] (<b>uri-authority</b> <var>URI</var>)<br/>
121[procedure] (<b>uri-userinfo</b> <var>URI</var>)<br/>
122[procedure] (<b>uri-username</b> <var>URI</var>)<br/>
123[procedure] (<b>uri-password</b> <var>URI</var>)<br/>
124[procedure] (<b>uri-host</b> <var>URI</var>)<br/>
125[procedure] (<b>uri-port</b> <var>URI</var>)<br/>
126[procedure] (<b>uri-path</b> <var>URI</var>)<br/>
127[procedure] (<b>uri-query</b> <var>URI</var>)<br/>
128[procedure] (<b>uri-fragment</b> <var>URI</var>)<br/>
129<blockquote>
130<p>Accessor procedures for <code>URI</code> objects.</p>
131<ul>
132<li>Scheme is a symbol.</li>
133<li>Scheme-Specific is scheme specific. Currently a list - ((uri-authority uri) (uri-path
134uri) (uri-query uri)).</li>
135<li>Authority is a list of (userinfo host port) where userinfo is a string
136<code>"username:password"</code>, host is a string,
137and port is an integer.</li>
138<li>Userinfo is a two value return of Username and Password.</li>
139<li>Username is a string.</li>
140<li>Password is a string.</li>
141<li>Host is a string.</li>
142<li>Port is an integer.</li>
143<li>Path is a list of ([directory ...] basename) where directory and basename are strings.</li>
144<li>Query is an association list where the key is a string and the value is any object.</li>
145<li>Fragment is a string.</li>
146</ul>
147<p>Any can be <code>#f</code>, indicating a missing item.</p>
148<p>A null string, <code>""</code>, indicates a root element.</p>
149<p>Example: An <var>authority</var> of <code>(#f "" #f)</code> means missing
150<var>userinfo</var>, missing <var>port</var>, and the "root" <var>host</var> or "localhost".
151In this case the actual host was missing from the source URI string, as in
152"file:///usr/local/share/chicken/doc/chicken.html#Index".</p>
153</blockquote>
154</div>
155
156<div class="defun">
157[procedure] (<b>uri</b> <var>STRING [DEFAULT-URI]</var>)<br/>
158<blockquote>
159<p>Parses the Uniform Resource Identifier (RFC 3986) <var>STRING</var> and returns a
160Uniform Resource Identifier object. Returns the <var>DEFAULT-URI</var>, if provided,
161when the parse fails, otherwise signals an error.</p>
162</blockquote>
163</div>
164
165<div class="defun">
166[procedure] (<b>uri-&gt;string</b> <var>URI</var>)<br/>
167<blockquote>
168<p>Returns the URI encoded string form of the <var>URI</var> object.</p>
169<p>Any query component values are converted to a string before the query component string form
170is built.</p>
171</blockquote>
172</div>
173
174<div class="defun">
175[procedure] (<b>uri-&gt;tree</b> <var>URI-STR [BASE-TREE]</var>)<br/>
176<blockquote>
177<p>Returns a list of 5 elements corresponding to the parts (<var>scheme</var>
178<var>authority</var> <var>path</var> <var>query</var> <var>fragment</var>) of string
179<var>URI-STR</var>. Elements corresponding to absent parts are <code>#f</code>.</p>
180
181<p>The <var>path</var> is a list of strings. If the first string is empty, then the path is
182absolute; otherwise relative. The optional <var>BASE-TREE</var> is a tree as returned by
183<code>uri-&gt;tree</code>; and is used as the base address for relative URIs.</p>
184
185<p>If the <var>authority</var> component is a <dfn>Server-based Naming Authority</dfn>, then
186it is a list of the <var>userinfo</var>, <var>host</var>, and <var>port</var> strings (or
187<code>#f</code>). For other types of <var>authority</var> components the <var>authority</var>
188will be a string.</p>
189
190<pre class="example">
191  (uri-&gt;tree "http://www.ics.uci.edu:80/pub/ietf/uri/#Related")
192  =&gt;
193  (http (#f "www.ics.uci.edu" 80) ("" "pub" "ietf" "uri" "") <code>#f</code> <code>#f</code> "Related")
194</pre>
195</blockquote></div>
196
197<div class="defun">
198[procedure] (<b>uri-split-path-null?</b> <var>PATH-LIST</var>)<br/>
199<blockquote>
200<p>Is the <var>PATH-LIST</var> "null"?</p>
201<ul>
202<li>Null here is defined as a <var>PATH-LIST</var> equal to either <code>#f</code>,
203<code>'()</code>, or <code>'("")</code>.</li>
204</ul>
205</blockquote>
206</div>
207
208<div class="defun">
209[procedure] (<b>uri-path-null?</b> <var>URI</var>)<br/>
210<blockquote>
211<p>Is the path component of the <varURI</var> "null"?</p>
212<ul>
213<li>Null here is defined as a <var>PATH-LIST</var> equal to either <code>#f</code>,
214<code>'()</code>, or <code>'("")</code>.</li>
215</ul>
216</blockquote>
217</div>
218
219<div class="defun">
220[procedure] (<b>uri-encode-split-path</b> <var>PATH-LIST</var>)<br/>
221<blockquote>
222<p>Returns a URI string combining the components of <var>PATH-LIST</var>.</p>
223</blockquote>
224</div>
225
226<div class="defun">
227[procedure] (<b>uri-decode-path</b> <var>PATH [BASE-PATH-LIST]</var>)<br/>
228<blockquote>
229<p>Returns a list path from the string <var>PATH</var>, with optional
230<var>BASE-PATH-LIST</var>.</p>
231<p>The optional <var>BASE-PATH-LIST</var> is a path-list as returned by
232<code>uri-&gt;tree</code>; and is used as the base address for relative paths.</p>
233</blockquote>
234</div>
235
236<div class="defun">
237[procedure] (<b>uri-decode-split-path</b> <var>PATH-LIST [BASE-PATH-LIST]</var>)<br/>
238<blockquote>
239<p>Returns a path-list from the encoded <var>PATH-LIST</var>, with optional
240<var>BASE-PATH-LIST</var>.</p>
241<p>The optional <var>BASE-PATH-LIST</var> is a path-list as returned by
242<code>uri-&gt;tree</code>; and is used as the base address for relative paths.</p>
243</blockquote>
244</div>
245
246<div class="defun">
247[procedure] (<b>uri-encode-query</b> <var>QUERY-ALIST</var>)<br/>
248<blockquote>
249<p>Converts a <var>QUERY-ALIST</var> to a <dfn>URI</dfn> encoded query-string.</p>
250</blockquote>
251</div>
252
253<div class="defun">
254[procedure] (<b>uri-decode-query</b> <var>QUERY-STRING</var>)<br/>
255<blockquote>
256<p>Converts a <dfn>URI</dfn> encoded <var>QUERY-STRING</var> to a query-alist.</p>
257<p>An ill-formed query string, such as <code>"?foo?bar"</code>, will abort with a
258<code>exn-uri-query-parse-condition</code>.</p>
259</blockquote>
260</div>
261
262<div class="defun">
263[procedure] (<b>uri-encode</b> <var>URI-COMPONENT</var>)<br/>
264<blockquote>
265<p>Returns a copy of the string <var>URI-COMPONENT</var> in which all <dfn>unsafe</dfn> octets
266(as defined in RFC 3986) have been `<samp><span class="samp">%</span></samp>' <dfn>escaped</dfn>.
267<code>uri-decode</code> decodes strings encoded by <code>uri-encode</code>.</p>
268</blockquote>
269</div>
270
271<div class="defun">
272[procedure] (<b>uri-decode</b> <var>URI-COMPONENT</var>)<br/>
273<blockquote>
274<p>Returns a copy of the string <var>URI-COMPONENT</var> in which each `<samp><span class="samp">%</span></samp>' escaped
275characters in <var>URI-component</var> is replaced with the character it encodes. This
276routine is useful for showing URI contents on error pages.</p>
277</blockquote>
278</div>
279
280<div class="defun">
281[procedure] (<b>absolute-uri?</b> <var>STRING</var>)<br/>
282<blockquote>
283<p>Returns <code>#t</code> if <var>STRING</var> is an absolute URI as indicated by a
284syntactically valid (per RFC 3986) <dfn>scheme</dfn>; otherwise returns
285<code>#f</code>.</p>
286</blockquote>
287</div>
288
289<div class="defun">
290[procedure] (<b>pathname-&gt;uri</b> <var>PATHNAME</var>)<br/>
291<blockquote>
292<p>Returns a URI-string for <var>PATHNAME</var> on the local host.</p>
293</blockquote>
294</div>
295
296<div class="defun">
297[procedure] (<b>uri-make-path</b> <var>PATH-LIST</var>)<br/>
298<blockquote>
299<p>Deprecated; will be removed. Use <code>uri-encode-split-path</code>.</p>
300<p>Returns a URI string combining the components of <var>PATH-LIST</var>.</p>
301</blockquote>
302</div>
303
304<div class="defun">
305[procedure] (<b>uri-split-fields</b> <var>STR CHR</var>)<br/>
306<blockquote>
307<p>Deprecated; will be removed. Use unit extras <code>string-split</code>.</p>
308<p>Returns a list of <var>STR</var> split at each occurrence of <var>CHR</var>. <var>CHR</var> does not
309appear in the returned list of strings.</p>
310</blockquote>
311</div>
312
313<div class="defun">
314[procedure] (<b>uri-path-&gt;keys</b> <var>PATH-LIST PTYPES</var>)<br/>
315<blockquote>
316<p>Deprecated; will be removed. Use <code>uri-decode-split-path</code> and coerce egg
317<code>coerce-all</code>.</p>
318<p><var>PATH-LIST</var> is a path-list as returned by <code>uri-split-fields</code>. <code>uri-path-&gt;keys</code>
319returns a list of items coerced to types <var>PTYPES</var>.</p>
320</blockquote>
321</div>
322
323<div class="defun">
324[procedure] (<b>path-&gt;uri</b> <var>PATH</var>)<br/>
325<blockquote>
326<p>Deprecated; will be removed. Use <code>pathname-&gt;uri</code>.</p>
327<p>Returns a URI-string for <var>PATH</var> on the local host.</p>
328</blockquote>
329</div>
330
331<div class="defun">
332[procedure] (<b>absolute-path?</b> <var>FILE-NAME</var>)<br/>
333<blockquote>
334<p>Deprecated; will be removed. Use utils unit <code>absolute-pathname?</code>.</p>
335<p>Returns <code>#t</code> if <var>FILE-NAME</var> is a fully specified pathname (does not
336depend on the current working directory); otherwise returns <code>#f</code>.</p>
337</blockquote>
338</div>
339
340<div class="defun">
341[procedure] (<b>null-directory?</b> <var>STRING</var>)<br/>
342<blockquote>
343<p>Deprecated; will be removed. Use utils unit <code>directory-null?</code>.</p>
344<p>Returns <code>#t</code> if changing directory to <var>STRING</var> would leave the current
345directory unchanged; otherwise returns <code>#f</code>.</p>
346</blockquote>
347</div>
348
349<div class="defun">
350[procedure] (<b>glob-pattern?</b> <var>STRING</var>)<br/>
351<blockquote>
352<p>Deprecated; will be removed. Use regex unit <code>glob?</code>.</p>
353<p>Returns <code>#t</code> if the string <var>STRING</var> contains characters used for
354specifying glob patterns, namely <code>#\*</code>, <code>#\?</code>, and <code>#\[</code>.</p>
355</blockquote>
356</div>
357
358<h4 class="subheading">URL Compatibility Procedures</h4>
359
360<div class="defun">
361[procedure] (<b>url?</b> <var>X</var>)<br/>
362<blockquote>
363<p>Returns <code>#t</code> if <code>X</code> is an URL object, or <code>#f</code> otherwise.</p>
364</blockquote>
365</div>
366
367<div class="defun">
368[procedure] (<b>url</b> <var>STRING</var>)<br/>
369<blockquote>
370<p>Parses the Uniform Resource Locator (RFC1738) <code>STRING</code> and returns an URL object.
371Encodings of the form <code>%NN</code> and occurrences of <code>+</code> are properly handled.</p>
372</blockquote>
373</div>
374
375<div class="defun">
376[procedure] (<b>make-url</b> <var>#!key scheme user password host port path typecode</var>)<br/>
377<blockquote>
378<p>Creates an URL object from its components. Any of the keyword parameters may be <code>#f</code>.</p>
379</blockquote>
380</div>
381
382<div class="defun">
383[procedure] (<b>url-scheme</b> <var>URL</var>)<br/>
384[procedure] (<b>url-user</b> <var>URL</var>)<br/>
385[procedure] (<b>url-password</b> <var>URL</var>)<br/>
386[procedure] (<b>url-host</b> <var>URL</var>)<br/>
387[procedure] (<b>url-port</b> <var>URL</var>)<br/>
388[procedure] (<b>url-path</b> <var>URL</var>)<br/>
389[procedure] (<b>url-typecode</b> <var>URL</var>)<br/>
390<blockquote>
391<p>Accessor procedures for <code>URL</code> objects that return the components of a parsed URL. All components are
392strings, with the exception of the port (an integer) and the typecode (a character).</p>
393</blockquote>
394</div>
395
396<div class="defun">
397[procedure] (<b>url->string</b> <var>URL</var>)<br/>
398<blockquote>
399<p>Returns a string-representation if the URL object <code>URL</code>.</p>
400</blockquote>
401</div>
402
403<div class="defun">
404[procedure] (<b>url-decode</b> <var>STRING</var>)<br/>
405<blockquote>
406<p>Replaces occurrences of <code>%XX</code> sequences in <code>STRING</code> with the respective characters.</p>
407</blockquote>
408</div>
409
410<div class="defun">
411[procedure] (<b>url-encode</b> <var>STRING [CHARLIST]</var>)<br/>
412<blockquote>
413<p>Replaces occurrences of characters which are non-alphanumeric and do not appear in the list of characters given in
414the optional argument <code>CHARLIST</code> by their character code in <code>%XX</code> format.</p>
415</blockquote>
416</div>
417
418<h4 class="subheading">FTP Procedures</h4>
419
420<pre>
421(require-extension ftp-parse)
422</pre>
423
424<p class="noindent">Before RFC 2396, the <dfn>File Transfer Protocol</dfn> (FTP) served a
425 purpose similar to a URL.
426
427<div class="defun">
428[procedure] (<b>parse-ftp-address</b> <var>URI</var>)<br/>
429<blockquote>
430<p>Returns a list of the decoded FTP <var>URI</var>; or <code>#f</code> if indecipherable. FTP
431<dfn>Uniform Resource Locator</dfn>, <dfn>ange-ftp</dfn>, and <dfn>getit</dfn>
432formats are handled. The returned list has four elements which are
433strings or <code>#f</code>:
434
435<ol type=1 start=0>
436<li>username
437<li>password
438<li>remote-site
439<li>remote-directory
440</ol></p>
441</blockquote>
442</div>
443
444
445<h3>License:</h3>
446<pre>
447Portions Copyright 2007 Kon Lovett
448All rights reserved.
449
450Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
451conditions are met:
452
453  Redistributions of source code must retain the above copyright notice, this list of conditions and the following
454    disclaimer.
455  Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
456    disclaimer in the documentation and/or other materials provided with the distribution.
457  Neither the name of the author nor the names of its contributors may be used to endorse or promote
458    products derived from this software without specific prior written permission.
459
460THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
461OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
462AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
463CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
464CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
465SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
466THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
467OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
468POSSIBILITY OF SUCH DAMAGE.
469</pre>
470<pre>
471Portions Copyright (c) 2003-2005, Felix L. Winkelmann
472All rights reserved.
473
474Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
475conditions are met:
476
477  Redistributions of source code must retain the above copyright notice, this list of conditions and the following
478    disclaimer.
479  Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
480    disclaimer in the documentation and/or other materials provided with the distribution.
481  Neither the name of the author nor the names of its contributors may be used to endorse or promote
482    products derived from this software without specific prior written permission.
483
484THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
485OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
486AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
487CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
488CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
489SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
490THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
491OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
492POSSIBILITY OF SUCH DAMAGE.
493</pre>
494<pre>
495Portions Copyright 1997, 1998, 2000, 2001 Aubrey Jaffer
496
497Permission to copy this software, to modify it, to redistribute it,
498to distribute modified versions, and to use it for any purpose is
499granted, subject to the following restrictions and understandings.
500
5011. Any copy made of this software must include this copyright notice
502in full.
503
5042. I have made no warranty or representation that the operation of
505this software will be error-free, and I am under no obligation to
506provide any services, by way of maintenance, update, or otherwise.
507
5083. In conjunction with products arising from the use of this
509material, there shall be no use of my name in any advertising,
510promotional, or sales literature without prior written consent in
511each case.
512</pre>
513
514<hr><a href="index.html">back</a>
515
516</body>
517</html>
Note: See TracBrowser for help on using the repository browser.