URI
URI
Utilities for working with URIs.
This module provides functions for working with URIs (for example, parsing URIs or encoding query strings). For reference, most of the functions in this module refer to RFC 3986.
Summary
Types
Functions
- char_reserved?(char)
-
Checks if the character is a “reserved” character in a URI
- char_unescaped?(char)
-
Checks if the character is allowed unescaped in a URI
- char_unreserved?(char)
-
Checks if the character is a “unreserved” character in a URI
- decode(uri)
-
Percent-unescapes a URI
- decode_query(query, map \\ %{})
-
Decodes a query string into a map
- decode_www_form(string)
-
Decodes a string as “x-www-form-urlencoded”
- default_port(scheme)
-
Returns the default port for a given scheme
- default_port(scheme, port)
-
Registers the default port
port
for the givenscheme
- encode(string, predicate \\ &char_unescaped?/1)
-
Percent-escapes the given string
- encode_query(enumerable)
-
Encodes an enumerable into a query string
- encode_www_form(string)
-
Encodes a string as “x-www-form-urlencoded”
- merge(uri, rel)
-
Merges two URIs
- parse(uri)
-
Parses a well-formed URI reference into its components
- path_to_segments(path)
- query_decoder(query)
-
Returns a stream of two-element tuples representing key-value pairs in the given
query
- to_string(uri)
-
Returns the string representation of the given
URI
struct
Types
t()
t() :: %URI{authority: nil | binary, fragment: nil | binary, host: nil | binary, path: nil | binary, port: nil | :inet.port_number, query: nil | binary, scheme: nil | binary, userinfo: nil | binary}
Functions
char_reserved?(char)
char_reserved?(char) :: boolean
Checks if the character is a “reserved” character in a URI.
Reserved characters are specified in RFC 3986, section 2.2.
Examples
iex> URI.char_reserved?(?+)
true
char_unescaped?(char)
char_unescaped?(char) :: boolean
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.
Examples
iex> URI.char_unescaped?(?{)
false
char_unreserved?(char)
char_unreserved?(char) :: boolean
Checks if the character is a “unreserved” character in a URI.
Unreserved characters are specified in RFC 3986, section 2.3.
Examples
iex> URI.char_unreserved?(?_)
true
decode(uri)
decode(binary) :: binary
Percent-unescapes a URI.
Examples
iex> URI.decode("http%3A%2F%2Felixir-lang.org")
"http://elixir-lang.org"
decode_query(query, map \\ %{})
decode_query(binary, map) :: map
Decodes a query string into a map.
Given a query string of the form of key1=value1&key2=value2...
, this function inserts each key-value pair in the query string as one entry in the given map
. Keys and values in the resulting map will be binaries. 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"}
iex> URI.decode_query("percent=oh+yes%21", %{"starting" => "map"})
%{"percent" => "oh yes!", "starting" => "map"}
decode_www_form(string)
decode_www_form(binary) :: binary
Decodes a string as “x-www-form-urlencoded”.
Examples
iex> URI.decode_www_form("%3Call+in%2F")
"<all in/"
default_port(scheme)
default_port(binary) :: nil | non_neg_integer
Returns the default port for a given scheme.
If the scheme is unknown to the URI
module, this function returns nil
. The default port for any scheme can be configured globally via default_port/2
.
Examples
iex> URI.default_port("ftp")
21
iex> URI.default_port("ponzi")
nil
default_port(scheme, port)
default_port(binary, non_neg_integer) :: :ok
Registers the default port port
for the given scheme
.
After this function is called, port
will be returned by default_port/1
for the given scheme scheme
. Note that this function changes the default port for the given scheme
globally, meaning for every application.
It is recommended for this function to be invoked in your application’s start callback in case you want to register new URIs.
encode(string, predicate \\ &char_unescaped?/1)
encode(binary, (byte -> boolean)) :: binary
Percent-escapes the given string.
This function accepts a predicate
function as an optional argument; if passed, this function will be called with each character (byte) in string
as its argument and should return true
if that character should not be escaped and left as is.
Examples
iex> URI.encode("ftp://s-ite.tld/?value=put it+й")
"ftp://s-ite.tld/?value=put%20it+%D0%B9"
iex> URI.encode("a string", &(&1 != ?i))
"a str%69ng"
encode_query(enumerable)
encode_query(term) :: binary
Encodes an enumerable into a query string.
Takes an enumerable that enumerates as a list of two-element tuples (e.g., a map or a keyword list) and returns a string in the form of key1=value1&key2=value2...
where keys and values are URL encoded as per encode_www_form/1
.
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"
iex> query = %{"key" => "value with spaces"}
iex> URI.encode_query(query)
"key=value+with+spaces"
iex> URI.encode_query %{key: [:a, :list]}
** (ArgumentError) encode_query/1 values cannot be lists, got: [:a, :list]
encode_www_form(string)
encode_www_form(binary) :: binary
Encodes a string as “x-www-form-urlencoded”.
Example
iex> URI.encode_www_form("put: it+й")
"put%3A+it%2B%D0%B9"
merge(uri, rel)
merge(t | binary, t | binary) :: t
Merges two URIs.
This function merges two URIs as per RFC 3986, section 5.2.
Examples
iex> URI.merge(URI.parse("http://google.com"), "/query") |> to_string
"http://google.com/query"
iex> URI.merge("http://example.com", "http://google.com") |> to_string
"http://google.com"
parse(uri)
parse(t | binary) :: t
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 for examples of how URI.parse/1
can be used to parse a wide range of URIs.
This function uses the parsing regular expression as defined in RFC 3986, Appendix B.
When a URI is given without a port, the value returned by URI.default_port/1
for the URI’s scheme is used for the :port
field.
If a %URI{}
struct is given to this function, this function returns it unmodified.
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}
path_to_segments(path)
query_decoder(query)
query_decoder(binary) :: Enumerable.t
Returns a stream of two-element tuples representing key-value pairs in the given query
.
Key and value in each tuple will be binaries and will be percent-unescaped.
Examples
iex> URI.query_decoder("foo=1&bar=2") |> Enum.to_list()
[{"foo", "1"}, {"bar", "2"}]
to_string(uri)
to_string(t) :: binary
Returns the string representation of the given URI
struct.
iex> URI.to_string(URI.parse("http://google.com"))
"http://google.com"
iex> URI.to_string(%URI{scheme: "foo", host: "bar.baz"})
"foo://bar.baz"
© 2012–2017 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.4.5/URI.html