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

Last change on this file since 13217 was 13217, checked in by sjamaan, 11 years ago

Update uri-common docs to match the newly added predicates that match uri-generic's

File size: 8.0 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-scheme uri-common) => symbol</procedure>
70* <procedure>(uri-path uri-common) => list</procedure>
71* <procedure>(uri-query uri-common) => alist</procedure>
72* <procedure>(uri-fragment uri-common) => string</procedure>
73* <procedure>(uri-host uri-common) => string</procedure>
74* <procedure>(uri-port uri-common) => integer</procedure>
75* <procedure>(uri-username uri-common) => string</procedure>
76* <procedure>(uri-password uri-common) => string</procedure>
77
78If a component is not defined in the given URI-common, then the
79corresponding accessor returns {{#f}}.
80
81* <procedure>(update-uri URI-common #!key scheme path query fragment host port username password) => URI-common</procedure>
82
83Update the specified keys in the URI-common object in a functional way
84(ie, it creates a new copy with the modifications).
85
86* <procedure>(uri? URI) => BOOL</procedure>
87
88Is the given object an URI-common object?
89
90* <procedure>(relative-ref? URI) => BOOL</procedure>
91
92Is the given object a relative reference?  Relative references are
93defined by RFC 3986 as URI references which are not URIs; they contain
94no URI scheme and can be resolved against an absolute URI to obtain
95a complete URI using {{uri-relative-to}}.
96
97* <procedure>(absolute-uri? URI) => BOOL</procedure>
98
99Is the given object an absolute URI?  Absolute URI is defined by
100RFC 3986 as a non-relative URI reference without a fragment.  Absolute
101URIs can be used as a base URI to resolve a relative-ref against, using
102{{uri-relative-to}}.
103
104==== Reference Resolution
105
106<procedure>(uri-relative-to URI URI) => URI</procedure>
107
108Resolve the first URI as a reference relative to the second URI,
109returning a new URI (RFC 3986, Section 5.2.2).
110
111<procedure>(uri-relative-from URI URI) => URI</procedure>
112
113Constructs a new, possibly relative, URI which represents the location
114of the first URI with respect to the second URI.
115
116<examples>
117<example>
118<init>(use uri-common)</init>
119<expr>(uri->string (uri-relative-to (uri-reference "../qux") (uri-reference "http://example.com/foo/bar/")))</expr>
120<result>"http://example.com/foo/qux"</result>
121</example>
122<example>
123<init>(use uri-common)</init>
124<expr>(uri->string (uri-relative-from (uri-reference "http://example.com/foo/qux") (uri-reference "http://example.com/foo/bar/")))</expr>
125<result>"../qux"</result>
126</example>
127</examples>
128
129==== Query encoding and decoding
130
131* <parameter>(form-urlencoded-separator [char-set/char/string])</parameter>
132* <procedure>(form-urlencode alist #!key (separator (form-urlencoded-separator))) => string</procedure>
133* <procedure>(form-urldecode string #!key (separator (form-urlencoded-separator))) => alist</procedure>
134
135Encode or decode an alist using the encoding corresponding to the
136[[http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1|form-urlencoded]]
137media type, using the given separator character(s).
138
139When encoding, if {{separator}} is a string, the first character will
140be used as the separator in the resulting querystring.  If it is a
141char-set, it will be converted to a string and its first character
142will be taken.  In either case, all of these characters are encoded if
143they occur inside the key/value pairs.
144
145When decoding, any character in the set (or string) will be seen as
146a separator.
147
148The separator defaults to the string {{";&"}}.  This means that
149either semicolons or ampersands are allowed as separators when decoding
150an URI string, but semicolons are used when generating strings.
151
152If you would like to use a different separator, you should parameterize
153''all'' calls to procedures that return an uri-common object.
154
155
156==== Normalization 
157
158<procedure>(uri-normalize-case URI) => URI</procedure>
159
160URI case normalization (RFC 3986 section 6.2.2.1)
161
162<procedure>(uri-normalize-path-segments URI) => URI</procedure>
163
164URI path segment normalization (RFC 3986 section 6.2.2.3)
165
166
167=== Requires
168
169* [[uri-generic]]
170* [[matchable]]
171* [[defstruct]]
172
173=== Version History
174
175* trunk Add predicates for absoluteness/relativeness, matching the ones in uri-generic.
176* 0.1 Initial Release
177
178=== License
179
180  Copyright 2008-2009 Peter Bex
181  All rights reserved.
182 
183  Redistribution and use in source and binary forms, with or without
184  modification, are permitted provided that the following conditions are
185  met:
186 
187  Redistributions of source code must retain the above copyright
188  notice, this list of conditions and the following disclaimer.
189 
190  Redistributions in binary form must reproduce the above copyright
191  notice, this list of conditions and the following disclaimer in the
192  documentation and/or other materials provided with the distribution.
193 
194  Neither the name of the author nor the names of its contributors may
195  be used to endorse or promote products derived from this software
196  without specific prior written permission.
197 
198  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
199  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
200  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
201  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
202  COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
203  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
204  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
205  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
206  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
207  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
208  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
209  OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.