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

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

Add a note to get a simple rule when you should parameterize

File size: 5.7 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
98If you would like to use a different separator for output, you should
99parameterize ''all'' calls to procedures that return an uri-common
100object.
101
102
103==== Normalization 
104
105<procedure>(uri-common-normalize-case URI) => URI</procedure>
106
107URI case normalization (RFC 3986 section 6.2.2.1)
108
109<procedure>(uri-common-normalize-path-segments URI) => URI</procedure>
110
111URI path segment normalization (RFC 3986 section 6.2.2.3)
112
113
114=== Requires
115
116* [[uri-generic]]
117* [[matchable]]
118* [[defstruct]]
119
120=== Version History
121
122* 0.1 Initial Release
123
124=== License
125
126Copyright 2008-2009 Peter Bex.
127
128Redistribution and use in source and binary forms, with or without
129modification, are permitted provided that the following conditions are
130met:
131
132- Redistributions of source code must retain the above copyright
133  notice, this list of conditions and the following disclaimer.
134
135- Redistributions in binary form must reproduce the above copyright
136  notice, this list of conditions and the following disclaimer in the
137  documentation and/or other materials provided with the distribution.
138
139- Neither name of the copyright holders nor the names of its
140  contributors may be used to endorse or promote products derived from
141  this software without specific prior written permission.
142
143THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND THE
144CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
145BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
146FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
147COPYRIGHT HOLDERS OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
148INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
149(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
150SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
151HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
152STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
153IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
154POSSIBILITY OF SUCH DAMAGE.
155
Note: See TracBrowser for help on using the repository browser.