source: project/wiki/eggref/4/uri-common @ 13000

Last change on this file since 13000 was 13000, checked in by sjamaan, 12 years ago

Update uri-common docs. Do not refer to uri-generic docs but copy the text from those docs, making uri-common readable as a stand-alone document

File size: 6.9 KB
Line 
1[[tags: eggs]]
2[[toc:]]
3
4== uri-common
5
6=== Description
7
8The {{uri-common}} library provides simple and easy-to-use parsing
9and manipulation procedures for URIs using common schemes.
10
11These "common schemes" all have the following rules:
12
13* An empty path after the hostname is considered to be identical to the root path.
14* All components are to be fully URI-decoded (so no percent-encoded characters in it).
15* The query argument will be in
16   [[http://www.w3.org/TR/xforms/#structure-model-submission|application/x-www-form-urlencoded]] form.
17* The port is automatically determined if it is omitted and the URI scheme is known.
18
19=== Library Procedures
20
21This library replaces most of the procedures in [[uri-generic]]. If
22you need to work with URIs on the uri-generic level or need to work
23with both uri-generic and uri-common URI objects, you will have to
24import and prefix or rename procedures.
25
26==== Constructors
27
28These constructors fully decode their arguments, so afterwards it is
29impossible to distinguish between encoded delimiters and unencoded
30delimiters.  This makes uri-common objects decoding endpoints; no
31further decoding on the URI level is possible (of course, applications
32are free to decode further information inside the URI).  If for some
33reason, the original URI is still needed, it can be converted to a
34uri-generic.  However, updating a URI component causes this
35component's original encoding to be lost, so be careful!
36
37<procedure>(uri-reference string) => uri-common</procedure>
38
39A URI reference is either a URI or a relative reference (RFC 3986,
40Section 4.1).  If the given string's prefix does not match the syntax
41of a scheme followed by a colon separator, then the given string is
42parsed as a relative reference.
43
44<procedure>(absolute-uri string) => uri-common</procedure>
45
46Parses the given string as an absolute URI, in which no fragments are
47allowed (RFC 3986, Section 4.2)
48
49==== uri-generic and string representation
50
51<procedure>(uri->uri-generic uri-common) => uri-generic</procedure>
52<procedure>(uri-generic->uri uri-common) => uri-common</procedure>
53
54To convert between uri-generic and uri-common objects, use these
55procedures.  As stated above, this will allow you to retrieve the
56original encoding of the URI components, but once you update a
57component from the uri-common side, the original encoding is no longer
58available (the updated value replaces the original value).
59
60<procedure>(uri->string uri-common userinfo) => string</procedure>
61
62Reconstructs the given URI into a string; uses a supplied function
63{{LAMBDA USERNAME PASSWORD -> STRING}} to map the userinfo part of the
64URI.
65
66
67==== Predicates and Accessors
68
69* <procedure>(uri? uri-common) => bool</procedure>
70* <procedure>(uri-scheme uri-common) => symbol</procedure>
71* <procedure>(uri-path uri-common) => list</procedure>
72* <procedure>(uri-query uri-common) => alist</procedure>
73* <procedure>(uri-fragment uri-common) => string</procedure>
74* <procedure>(uri-host uri-common) => string</procedure>
75* <procedure>(uri-port uri-common) => integer</procedure>
76* <procedure>(uri-username uri-common) => string</procedure>
77* <procedure>(uri-password uri-common) => string</procedure>
78
79If a component is not defined in the given URI-common, then the
80corresponding accessor returns {{#f}}.
81
82* <procedure>(update-uri URI-common #!key scheme path query fragment host port username password) => URI-common</procedure>
83
84Update the specified keys in the URI-common object in a functional way
85(ie, it creates a new copy with the modifications).
86
87==== Reference Resolution
88
89<procedure>(uri-relative-to URI URI) => URI</procedure>
90
91Constructs an absolute URI given a relative URI and a base URI (RFC 3986, Section 5.2.2)
92
93<procedure>(uri-relative-from URI URI) => URI</procedure>
94
95Constructs a new, possibly relative, URI which represents the location
96of the first URI with respect to the second URI.
97
98==== Query encoding and decoding
99
100* <parameter>(form-urlencoded-separator [char-set/char/string])</parameter>
101* <procedure>(form-urlencode alist #!key (separator (form-urlencoded-separator))) => string</procedure>
102* <procedure>(form-urldecode string #!key (separator (form-urlencoded-separator))) => alist</procedure>
103
104Encode or decode an alist using the encoding corresponding to the
105[[http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1|form-urlencoded]]
106media type, using the given separator character(s).
107
108When encoding, if {{separator}} is a string, the first character will
109be used as the separator in the resulting querystring.  If it is a
110char-set, it will be converted to a string and its first character
111will be taken.  In either case, all of these characters are encoded if
112they occur inside the key/value pairs.
113
114When decoding, any character in the set (or string) will be seen as
115a separator.
116
117The separator defaults to the string {{";&"}}.  This means that
118either semicolons or ampersands are allowed as separators when decoding
119an URI string, but semicolons are used when generating strings.
120
121If you would like to use a different separator, you should parameterize
122''all'' calls to procedures that return an uri-common object.
123
124
125==== Normalization 
126
127<procedure>(uri-normalize-case URI) => URI</procedure>
128
129URI case normalization (RFC 3986 section 6.2.2.1)
130
131<procedure>(uri-normalize-path-segments URI) => URI</procedure>
132
133URI path segment normalization (RFC 3986 section 6.2.2.3)
134
135
136=== Requires
137
138* [[uri-generic]]
139* [[matchable]]
140* [[defstruct]]
141
142=== Version History
143
144* 0.1 Initial Release
145
146=== License
147
148  Copyright 2008-2009 Peter Bex
149  All rights reserved.
150 
151  Redistribution and use in source and binary forms, with or without
152  modification, are permitted provided that the following conditions are
153  met:
154 
155  Redistributions of source code must retain the above copyright
156  notice, this list of conditions and the following disclaimer.
157 
158  Redistributions in binary form must reproduce the above copyright
159  notice, this list of conditions and the following disclaimer in the
160  documentation and/or other materials provided with the distribution.
161 
162  Neither the name of the author nor the names of its contributors may
163  be used to endorse or promote products derived from this software
164  without specific prior written permission.
165 
166  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
167  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
168  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
169  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
170  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
171  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
172  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
173  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
174  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
175  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
176  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
177  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.