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

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

remove all reference to query-separator except in the form-urlencode/form-urldecode case

File size: 5.6 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
21==== Constructors
22
23<procedure>(uri-common-reference string) => uri-common</procedure>
24<procedure>(absolute-uri-common string) => uri-common</procedure>
25
26Construct a new uri-common object, analogous to uri-reference and
27absolute-uri from [[uri-generic]].
28
29==== uri-generic and string representation
30
31<procedure>(uri-common->uri-generic uri-common) => uri-generic</procedure>
32<procedure>(uri-generic->uri-common uri-common) => uri-common</procedure>
33
34To convert between uri-generic and uri-common objects, use these
35procedures.
36
37<procedure>(uri-common->string uri-common userinfo) => string</procedure>
38
39Reconstructs the given URI into a string; uses a supplied function
40{{LAMBDA USERNAME PASSWORD -> STRING}} to map the userinfo part of the
41URI
42
43
44==== Predicates and Accessors
45
46* <procedure>(uri-common? uri-common) => bool</procedure>
47* <procedure>(uri-common-scheme uri-common) => symbol</procedure>
48* <procedure>(uri-common-path uri-common) => list</procedure>
49* <procedure>(uri-common-query uri-common) => alist</procedure>
50* <procedure>(uri-common-fragment uri-common) => string</procedure>
51* <procedure>(uri-common-host uri-common) => string</procedure>
52* <procedure>(uri-common-port uri-common) => integer</procedure>
53* <procedure>(uri-common-username uri-common) => string</procedure>
54* <procedure>(uri-common-password uri-common) => string</procedure>
55
56If a component is not defined in the given URI-common, then the
57corresponding accessor returns {{#f}}.
58
59* <procedure>(update-uri-common URI-common #!key scheme path query fragment host port username password) => URI-common</procedure>
60
61Update the specified keys in the URI-common object in a functional way
62(ie, it creates a new copy with the modifications).
63
64==== Reference Resolution
65
66<procedure>(uri-common-relative-to URI URI) => URI</procedure>
67
68Constructs an absolute URI given a relative URI and a base URI (RFC 3986, Section 5.2.2)
69
70<procedure>(uri-common-relative-from URI URI) => URI</procedure>
71
72Constructs a new, possibly relative, URI which represents the location
73of the first URI with respect to the second URI.
74
75==== Query encoding and decoding
76
77* <parameter>(form-urlencoded-separator [char-set/char/string])</parameter>
78* <procedure>(form-urlencode alist #!key (separator (form-urlencoded-separator))) => string</procedure>
79* <procedure>(form-urldecode string #!key (separator (form-urlencoded-separator))) => alist</procedure>
80
81Encode or decode an alist using the encoding corresponding to the
82[[http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1|form-urlencoded]]
83media type, using the given separator character(s).
84
85When encoding, if {{separator}} is a string, the first character will
86be used as the separator in the resulting querystring.  If it is a
87char-set, it will be converted to a string and its first character
88will be taken.  In either case, all of these characters are encoded if
89they occur inside the key/value pairs.
90
91When decoding, any character in the set (or string) will be seen as
92a separator.
93
94The separator defaults to the string {{";&"}}.  This means that
95ampersands are allowed as separators, but semicolons are preferred,
96and generated URI string always contain semicolons as separators.
97
98==== Normalization 
99
100<procedure>(uri-common-normalize-case URI) => URI</procedure>
101
102URI case normalization (RFC 3986 section 6.2.2.1)
103
104<procedure>(uri-common-normalize-path-segments URI) => URI</procedure>
105
106URI path segment normalization (RFC 3986 section 6.2.2.3)
107
108
109=== Requires
110
111* [[uri-generic]]
112* [[matchable]]
113* [[defstruct]]
114
115=== Version History
116
117* 0.1 Initial Release
118
119=== License
120
121Copyright 2008-2009 Peter Bex.
122
123Redistribution and use in source and binary forms, with or without
124modification, are permitted provided that the following conditions are
125met:
126
127- Redistributions of source code must retain the above copyright
128  notice, this list of conditions and the following disclaimer.
129
130- Redistributions in binary form must reproduce the above copyright
131  notice, this list of conditions and the following disclaimer in the
132  documentation and/or other materials provided with the distribution.
133
134- Neither name of the copyright holders nor the names of its
135  contributors may be used to endorse or promote products derived from
136  this software without specific prior written permission.
137
138THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND THE
139CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
140BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
141FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
142COPYRIGHT HOLDERS OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
143INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
144(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
145SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
146HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
147STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
148IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
149POSSIBILITY OF SUCH DAMAGE.
150
Note: See TracBrowser for help on using the repository browser.