From 80feeb36f92a923f57f740c7c28c12bb8b69ec16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= This module contains functions for parsing and handling RFC 3986 compliant URIs. A URI is an identifier consisting of a sequence of characters matching the syntax
+ rule named URI in RFC 3986. The generic URI syntax consists of a hierarchical sequence of components referred
+ to as the scheme, authority, path, query, and fragment:
+ 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 / "-" / "." / "_" / "~"
+
+
The interpretation of a URI depends only on the characters used and not on how those + characters are represented in a network protocol.
+The functions implemented by this module covers the following use cases:
+
+
+
+
+
+
+
+
+
+
There are four different encodings present during the handling of URIs:
+
+
+
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
All of the functions but
Maybe improper list of bytes (0..255).
+URI map holding the main components of a URI.
+List of unicode codepoints, UTF-8 encoded binary, or a mix of the two, + representing an RFC 3986 compliant URI (percent-encoded form). + 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.
+Composes an urlencoded
If an argument is invalid, a
Example:
++1> uri_string:compose_query(...). ++
Creates an RFC 3986 compliant
If an argument is invalid, a
Example:
++1> uri_string:create_uri_reference(...,...). ++
Dissects an urlencoded
If an argument is invalid, a
Example:
++1> uri_string:dissect_query(...). ++
Normalizes an RFC 3986 compliant
If an argument is invalid, a
Example:
++1> uri_string:normalize("http://example.org/one/two/../../one"). +"http://example.org/one" ++
Returns a
If parsing fails, a
Example:
++1> uri_string:parse("foo://user@example.com:8042/over/there?name=ferret#nose"). +#{fragment => "nose",host => "example.com", + path => "/over/there",port => 8042,query => "name=ferret", + scheme => foo,userinfo => "user"} +2>+
Returns an RFC 3986 compliant
If the
Example:
++1> URIMap = #{fragment => "nose", host => "example.com", path => "/over/there", +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> uri_string:recompose(URIMap, []). +"foo://example.com:8042/over/there?name=ferret#nose"+
Resolves an RFC 3986 compliant
If an argument is invalid, a
Example:
++1> uri_string:resolve_uri_reference(...,...). ++
Transcodes an RFC 3986 compliant
If an argument is invalid, a
Example:
++1> uri_string:transcode(<<"foo://f%20oo">>, [{in_encoding, utf8}, +{out_encoding, utf16}]). +<<0,102,0,111,0,111,0,58,0,47,0,47,0,102,0,37,0,48,0,48,0,37,0,50,0,48,0, + 111,0,111>> ++