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

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

Add a few descriptions about new procedures

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 #!key (query-separator (form-urlencoded-separator))) => uri-common</procedure>
33
34To convert between uri-generic and uri-common objects, use these
35procedures.  For information about the optional {{query-separator}} argument,
36see the [[#query-encoding-and-decoding|query encoding/decoding section]].
37
38<procedure>(uri-common->string uri-common userinfo) => string</procedure>
39
40Reconstructs the given URI into a string; uses a supplied function
41{{LAMBDA USERNAME PASSWORD -> STRING}} to map the userinfo part of the
42URI
43
44
45==== Predicates and Accessors
46
47* <procedure>(uri-common? uri-common) => bool</procedure>
48* <procedure>(uri-common-scheme uri-common) => symbol</procedure>
49* <procedure>(uri-common-path uri-common) => list</procedure>
50* <procedure>(uri-common-query uri-common) => alist</procedure>
51* <procedure>(uri-common-fragment uri-common) => string</procedure>
52* <procedure>(uri-common-host uri-common) => string</procedure>
53* <procedure>(uri-common-port uri-common) => integer</procedure>
54* <procedure>(uri-common-username uri-common) => string</procedure>
55* <procedure>(uri-common-password uri-common) => string</procedure>
56* <procedure>(uri-common-query-separator uri-common) => string</procedure>
57
58If a component is not defined in the given URI-common, then the
59corresponding accessor returns {{#f}}.
60
61* <procedure>(update-uri-common URI-common #!key scheme path query fragment host port username password) => URI-common</procedure>
62
63Update the specified keys in the URI-common object in a functional way
64(ie, it creates a new copy with the modifications).
65
66==== Reference Resolution
67
68<procedure>(uri-common-relative-to URI URI) => URI</procedure>
69
70Constructs an absolute URI given a relative URI and a base URI (RFC 3986, Section 5.2.2)
71
72<procedure>(uri-common-relative-from URI URI) => URI</procedure>
73
74Constructs a new, possibly relative, URI which represents the location
75of the first URI with respect to the second URI.
76
77==== Query encoding and decoding
78
79* <parameter>(form-urlencoded-separator [char-set/char/string])</parameter>
80* <procedure>(form-urlencode alist #!key (separator (form-urlencoded-separator))) => string</procedure>
81* <procedure>(form-urldecode string #!key (separator (form-urlencoded-separator))) => alist</procedure>
82
83Encode or decode an alist using the encoding corresponding to the
84[[http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1|form-urlencoded]]
85media type, using the given separator character(s).
86
87When encoding, if {{separator}} is a string, the first character will
88be used as the separator in the resulting querystring.  If it is a
89char-set, it will be converted to a string and its first character
90will be taken.  In either case, all of these characters are encoded if
91they occur inside the key/value pairs.
92
93When decoding, any character in the set (or string) will be seen as
94a separator.
95
96The separator defaults to the ampersand character.
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.