Elixir v1.0.5 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-unescape a URI

Decodes a query string into a dictionary (by default uses a map)

Decode a string as “x-www-urlencoded”

Returns the default port for a given scheme

Registers a scheme with a default port

Percent-escape a URI. Accepts predicate function as an argument to specify if char can be left as is

Encodes an enumerable into a query string

Encode a string as “x-www-urlencoded”

Normalizes the scheme according to the spec by downcasing it

Parses a well-formed URI reference into its components

Returns an iterator function over the query string that decodes the query string in steps

Types

t :: %URI{authority: term, fragment: term, host: term, path: term, port: term, query: term, scheme: term, userinfo: term}

Functions

char_reserved?(c)

Checks if the character is a “reserved” character in a URI.

Reserved characters are specified in RFC3986, section 2.2.

char_unescaped?(c)

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.

char_unreserved?(c)

Checks if the character is a “unreserved” character in a URI.

Unreserved characters are specified in RFC3986, section 2.3.

decode(uri)

Percent-unescape a URI.

Examples

iex> URI.decode("http%3A%2F%2Felixir-lang.org")
"http://elixir-lang.org"
decode_query(q, dict \\ %{})

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"}
decode_www_form(str)

Decode a string as “x-www-urlencoded”.

Examples

iex> URI.decode_www_form("%3Call+in%2F")
"<all in/"
default_port(scheme)

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
default_port(scheme, port)

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.

encode(str, predicate \\ &(char_unescaped? / 1))

Percent-escape 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"
encode_query(l)

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"
encode_www_form(str)

Encode a string as “x-www-urlencoded”.

Example

iex> URI.encode_www_form("put: it+й")
"put%3A+it%2B%D0%B9"
normalize_scheme(scheme)

Normalizes the scheme according to the spec by downcasing it.

parse(uri)

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}
query_decoder(q)

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"}]