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

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

Fix license sections to produce proper wiki output

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