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
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
<?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
(<url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>).
</p>
<p>A URI is an identifier consisting of a sequence of characters matching the syntax
rule named <em>URI</em> in <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>.
</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 cover the following use cases:</p>
<list type="bulleted">
<item>Parsing URIs into its components and returing a map<br></br>
<seealso marker="#parse/1"><c>parse/1</c></seealso>
</item>
<item>Recomposing a map of URI components into a URI string<br></br>
<seealso marker="#recompose/1"><c>recompose/1</c></seealso>
</item>
<item>Changing inbound binary and percent-encoding of URIs<br></br>
<seealso marker="#transcode/2"><c>transcode/2</c></seealso>
</item>
<item>Transforming URIs into a normalized form<br></br>
<seealso marker="#normalize/1"><c>normalize/1</c></seealso>
</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>Functions with <c>uri_string()</c> argument accept lists, binaries and
mixed lists (lists with binary elements) as input type. All of the functions but
<c>transcode/2</c> expects input as lists of unicode codepoints, UTF-8 encoded binaries
and UTF-8 percent-encoded URI parts ("%C3%B6" corresponds to the unicode character "ö").</p>
<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.</p>
<p>In case of lists there is only percent-encoding. In binaries, however, both binary encoding
and percent-encoding shall be considered. <c>transcode/2</c> provides the means to convert
between the supported encodings, it takes a <c>uri_string()</c> and a list of options
specifying inbound and outbound encodings.</p>
<p><url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url> does not mandate any specific
character encoding and it is usually defined by the protocol or surrounding text. This library
takes the same assumption, binary and percent-encoding are handled as one configuration unit,
they cannot be set to different values.</p>
</description>
<datatypes>
<datatype>
<name name="error"/>
<desc>
<p>Error tuple indicating the type of error. Possible values of the second component:</p>
<list type="bulleted">
<item><c>invalid_input</c></item>
<item><c>invalid_map</c></item>
<item><c>invalid_percent_encoding</c></item>
<item><c>invalid_scheme</c></item>
<item><c>invalid_uri</c></item>
<item><c>invalid_utf8</c></item>
</list>
<p>The third component is a term providing additional information about the
cause of the error.</p>
</desc>
</datatype>
<datatype>
<name name="uri_map"/>
<desc>
<p>Map holding the main components of a URI.</p>
</desc>
</datatype>
<datatype>
<name name="uri_string"/>
<desc>
<p>List of unicode codepoints, a UTF-8 encoded binary, or a mix of the two,
representing an <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>
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="normalize" arity="1"/>
<fsummary>Syntax-based normalization.</fsummary>
<desc>
<p>Transforms <c><anno>URIString</anno></c> into a normalized form
using Syntax-Based Normalization as defined by
<url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>.</p>
<p>This function implements case normalization, percent-encoding
normalization, path segment normalization and scheme based normalization
for HTTP(S) with basic support for FTP, SSH, SFTP and TFTP.</p>
<p><em>Example:</em></p>
<pre>
1> <input>uri_string:normalize("/a/b/c/./../../g").</input>
"/a/g"
2> <![CDATA[uri_string:normalize(<<"mid/content=5/../6">>).]]>
<![CDATA[<<"mid/6">>]]>
3> uri_string:normalize("http://localhost:80").
"https://localhost/"
</pre>
</desc>
</func>
<func>
<name name="parse" arity="1"/>
<fsummary>Parse URI into a map.</fsummary>
<desc>
<p>Parses an <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>
compliant <c>uri_string()</c> into a <c>uri_map()</c>, that holds the parsed
components of the <c>URI</c>.
If parsing fails, an error tuple is returned.</p>
<p>See also the opposite operation <seealso marker="#recompose/1">
<c>recompose/1</c></seealso>.</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"}
2> <![CDATA[uri_string:parse(<<"foo://[email protected]:8042/over/there?name=ferret">>).]]>
<![CDATA[#{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>Creates an <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url> compliant
<c><anno>URIString</anno></c> (percent-encoded), based on the components of
<c><anno>URIMap</anno></c>.
If the <c><anno>URIMap</anno></c> is invalid, an error tuple is returned.</p>
<p>See also the opposite operation <seealso marker="#parse/1">
<c>parse/1</c></seealso>.</p>
<p><em>Example:</em></p>
<pre>
1> <input>URIMap = #{fragment => "nose", host => "example.com", path => "/over/there",</input>
1> 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 <url href="https://www.ietf.org/rfc/rfc3986.txt">RFC 3986</url>
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. <c>in_encoding</c>
and <c>out_encoding</c> specifies both binary encoding and percent-encoding for the
input and output data. Mixed encoding, where binary encoding is not the same as
percent-encoding, is not supported.
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>
1> [{in_encoding, utf32},{out_encoding, utf8}]).
<![CDATA[<<"foo%C3%B6bar"/utf8>>]]>
2> uri_string:transcode("foo%F6bar", [{in_encoding, latin1},
2> {out_encoding, utf8}]).
"foo%C3%B6bar"
</pre>
</desc>
</func>
</funcs>
</erlref>
|
