Elixir v1.1.0 URI
Utilities for working with and creating URIs.
Summary
Functions
Checks if the character is a “reserved” character in a URI
Checks if the character is allowed unescaped in a URI
Checks if the character is a “unreserved” character in a URI
Percent-unescapes a URI
Decodes a query string into a dictionary (by default uses a map)
Decodes a string as “x-www-urlencoded”
Returns the default port for a given scheme
Registers a scheme with a default port
Percent-escapes a URI.
Accepts predicate
function as an argument to specify if char can be left as is
Encodes an enumerable into a query string
Encodes a string as “x-www-urlencoded”
Parses a well-formed URI reference into its components
Returns an iterator function over the query string that decodes the query string in steps
Converts the URI to string
Types
t :: %URI{authority: term, fragment: term, host: term, path: term, port: term, query: term, scheme: term, userinfo: term}
Functions
Checks if the character is a “reserved” character in a URI.
Reserved characters are specified in RFC3986, section 2.2.
Checks if the character is allowed unescaped in a URI.
This is the default used by URI.encode/2
where both
reserved and unreserved characters are kept unescaped.
Checks if the character is a “unreserved” character in a URI.
Unreserved characters are specified in RFC3986, section 2.3.
Percent-unescapes a URI.
Examples
iex> URI.decode("http%3A%2F%2Felixir-lang.org")
"http://elixir-lang.org"
Decodes a query string into a dictionary (by default uses a map).
Given a query string of the form “key1=value1&key2=value2…”, produces a map with one entry for each key-value pair. Each key and value will be a binary. Keys and values will be percent-unescaped.
Use query_decoder/1
if you want to iterate over each value manually.
Examples
iex> URI.decode_query("foo=1&bar=2")
%{"bar" => "2", "foo" => "1"}
Decodes a string as “x-www-urlencoded”.
Examples
iex> URI.decode_www_form("%3Call+in%2F")
"<all in/"
Returns the default port for a given scheme.
If the scheme is unknown to URI, returns nil
.
Any scheme may be registered via default_port/2
.
Examples
iex> URI.default_port("ftp")
21
iex> URI.default_port("ponzi")
nil
Registers a scheme with a default port.
It is recommended for this function to be invoked in your application start callback in case you want to register new URIs.
Percent-escapes a URI.
Accepts predicate
function as an argument to specify if char can be left as is.
Example
iex> URI.encode("ftp://s-ite.tld/?value=put it+й")
"ftp://s-ite.tld/?value=put%20it+%D0%B9"
Encodes an enumerable into a query string.
Takes an enumerable (containing a sequence of two-item tuples)
and returns a string of the form “key1=value1&key2=value2…” where
keys and values are URL encoded as per encode/2
.
Keys and values can be any term that implements the String.Chars
protocol, except lists which are explicitly forbidden.
Examples
iex> hd = %{"foo" => 1, "bar" => 2}
iex> URI.encode_query(hd)
"bar=2&foo=1"
Encodes a string as “x-www-urlencoded”.
Example
iex> URI.encode_www_form("put: it+й")
"put%3A+it%2B%D0%B9"
Parses a well-formed URI reference into its components.
Note this function expects a well-formed URI and does not perform
any validation. See the examples section below of how URI.parse/1
can be used to parse a wide range of relative URIs.
This function uses the parsing regular expression as defined in the Appendix B of RFC3986.
When a URI is given without a port, the values registered via
URI.default_port/1
and URI.default_port/2
are used.
Examples
iex> URI.parse("http://elixir-lang.org/")
%URI{scheme: "http", path: "/", query: nil, fragment: nil,
authority: "elixir-lang.org", userinfo: nil,
host: "elixir-lang.org", port: 80}
iex> URI.parse("//elixir-lang.org/")
%URI{authority: "elixir-lang.org", fragment: nil, host: "elixir-lang.org",
path: "/", port: nil, query: nil, scheme: nil, userinfo: nil}
iex> URI.parse("/foo/bar")
%URI{authority: nil, fragment: nil, host: nil, path: "/foo/bar",
port: nil, query: nil, scheme: nil, userinfo: nil}
iex> URI.parse("foo/bar")
%URI{authority: nil, fragment: nil, host: nil, path: "foo/bar",
port: nil, query: nil, scheme: nil, userinfo: nil}
Returns an iterator function over the query string that decodes the query string in steps.
Examples
iex> URI.query_decoder("foo=1&bar=2") |> Enum.map(&(&1))
[{"foo", "1"}, {"bar", "2"}]