1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>2017</year><year>2017</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>uri_string</title>
<prepared>Péter Dimitrov</prepared>
<docno>1</docno>
<date>2017-10-24</date>
<rev>A</rev>
</header>
<module>uri_string</module>
<modulesummary>URI processing functions.</modulesummary>
<description>
<p>This module contains functions for parsing and handling URIs (RFC 3986) and
form-urlencoded query strings (RFC 1866).</p>
<p>A URI is an identifier consisting of a sequence of characters matching the syntax
rule named <em>URI</em> in <em>RFC 3986</em>.</p>
<p> The generic URI syntax consists of a hierarchical sequence of components referred
to as the scheme, authority, path, query, and fragment:</p>
<pre>
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-empty
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
authority = [ userinfo "@" ] host [ ":" port ]
userinfo = *( unreserved / pct-encoded / sub-delims / ":" )
reserved = gen-delims / sub-delims
gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@"
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
</pre><br></br>
<p>The interpretation of a URI depends only on the characters used and not on how those
characters are represented in a network protocol.</p>
<p>The functions implemented by this module covers the following use cases:</p>
<list type="bulleted">
<item>Parsing URIs<br></br>
<c>parse/1</c></item>
<item>Recomposing URIs<br></br>
<c>recompose/2</c></item>
<item>Transcoding URIs<br></br>
<c>transcode/2</c></item>
<item>Working with form-urlencoded query strings<br></br>
<c>compose_query/[1,2], dissect_query/1</c></item>
</list>
<p>There are four different encodings present during the handling of URIs:</p>
<list type="bulleted">
<item>Inbound binary encoding in binaries</item>
<item>Inbound percent-encoding in lists and binaries</item>
<item>Outbound binary encoding in binaries</item>
<item>Outbound percent-encoding in lists and binaries</item>
</list>
<p>Unless otherwise specified the return value type and encoding are the same as the input
type and encoding. That is, binary input returns binary output, list input returns a list
output but mixed input returns list output. Input and output encodings are the same except
for <c>transcode/2</c>.</p>
<p>All of the functions but <c>transcode/2</c> expects input as unicode codepoints in
lists, UTF-8 encoding in binaries and UTF-8 encoding in percent-encoded URI parts.
<c>transcode/2</c> provides the means to convert between the supported URI encodings.</p>
</description>
<datatypes>
<datatype>
<name name="uri_map"/>
<desc>
<p>URI map holding the main components of a URI.</p>
</desc>
</datatype>
<datatype>
<name name="uri_string"/>
<desc>
<p>List of unicode codepoints, UTF-8 encoded binary, or a mix of the two,
representing an RFC 3986 compliant URI (<em>percent-encoded form</em>).
A URI is a sequence of characters from a very limited set: the letters of
the basic Latin alphabet, digits, and a few special characters.</p>
</desc>
</datatype>
</datatypes>
<funcs>
<func>
<name name="compose_query" arity="1"/>
<fsummary>Compose urlencoded query string.</fsummary>
<desc>
<p>Composes a form-urlencoded <c><anno>QueryString</anno></c> based on a
<c><anno>QueryList</anno></c>, a list of unescaped key-value pairs.
Media type <c>application/x-www-form-urlencoded</c> is defined in section
8.2.1 of <c>RFC 1866</c> (HTML 2.0). Reserved and unsafe characters, as
defined by RFC 1738 (Uniform Resource Locators), are percent-encoded.
</p>
<p><em>Example:</em></p>
<pre>
1> <input>uri_string:compose_query([{"foo bar","1"},{"city","örebro"}]).</input>
<![CDATA["foo+bar=1&city=%C3%B6rebro"]]>
</pre>
</desc>
</func>
<func>
<name name="compose_query" arity="2"/>
<fsummary>Compose urlencoded query string.</fsummary>
<desc>
<p>Same as <c>compose_query/1</c> but with an additional
<c><anno>Options</anno></c> parameter, that controls the type of separator used
between key-value pairs. There are three supported separator types: <c>amp</c> (<![CDATA[&]]>), <c>escaped_amp</c> (<![CDATA[&]]>) and <c>semicolon</c> (;). If the parameter <c><anno>Options</anno></c> is empty, separator takes the default value (<c>escaped_amp</c>).</p>
<p><em>Example:</em></p>
<pre>
1> <input>uri_string:compose_query([{"foo bar","1"},{"city","örebro"}],</input>
2> [{separator, semicolon}]).
"foo+bar=1;city=%C3%B6rebro"
</pre>
</desc>
</func>
<func>
<name name="dissect_query" arity="1"/>
<fsummary>Dissect query string.</fsummary>
<desc>
<p>Dissects an urlencoded <c><anno>QueryString</anno></c> and returns a
<c><anno>QueryList</anno></c>, a list of unescaped key-value pairs.
Media type <c>application/x-www-form-urlencoded</c> is defined in section
8.2.1 of <c>RFC 1866</c> (HTML 2.0). Percent-encoded segments are decoded
as defined by RFC 1738 (Uniform Resource Locators).
</p>
<p><em>Example:</em></p>
<pre>
1> <input>uri_string:dissect_query("foo+bar=1;city=%C3%B6rebro").</input>
[{"foo bar","1"},{"city","örebro"}]
</pre>
</desc>
</func>
<func>
<name name="parse" arity="1"/>
<fsummary>Parse URI into a map.</fsummary>
<desc>
<p>Returns a <c>URIMap</c>, that is a <em>uri_map()</em> with the parsed components
of the <c><anno>URIString</anno></c>.</p>
<p>If parsing fails, an error tuple is returned.</p>
<p><em>Example:</em></p>
<pre>
1> <input>uri_string:parse("foo://[email protected]:8042/over/there?name=ferret#nose").</input>
#{fragment => "nose",host => "example.com",
path => "/over/there",port => 8042,query => "name=ferret",
scheme => foo,userinfo => "user"}
</pre>
</desc>
</func>
<func>
<name name="recompose" arity="1"/>
<fsummary>Recompose URI.</fsummary>
<desc>
<p>Returns an RFC 3986 compliant <c><anno>URIString</anno></c> (percent-encoded).</p>
<p>If the <c><anno>URIMap</anno></c> is invalid, an error tuple is returned.</p>
<p><em>Example:</em></p>
<pre>
1> <input>URIMap = #{fragment => "nose", host => "example.com", path => "/over/there",</input>
port => 8042, query => "name=ferret", scheme => "foo", userinfo => "user"}.
#{fragment => "top",host => "example.com",
path => "/over/there",port => 8042,query => "?name=ferret",
scheme => foo,userinfo => "user"}
2> <input>uri_string:recompose(URIMap).</input>
"foo://example.com:8042/over/there?name=ferret#nose"</pre>
</desc>
</func>
<func>
<name name="transcode" arity="2"/>
<fsummary>Transcode URI.</fsummary>
<desc>
<p>Transcodes an RFC 3986 compliant <c><anno>URIString</anno></c>,
where <c><anno>Options</anno></c> is a list of tagged tuples, specifying the inbound
(<c>in_encoding</c>) and outbound (<c>out_encoding</c>) encodings.</p>
<p>If an argument is invalid, an error tuple is returned.</p>
<p><em>Example:</em></p>
<pre>
1> <input><![CDATA[uri_string:transcode(<<"foo%00%00%00%F6bar"/utf32>>,]]></input>
2> [{in_encoding, utf32},{out_encoding, utf8}]).
<![CDATA[<<"foo%C3%B6bar"/utf8>>]]>
</pre>
</desc>
</func>
</funcs>
</erlref>
|
