Справочник URI

Утилиты для работы с URI.

Этот модуль предоставляет функции для работы с URI (например, для разбора URI или кодирования строк запроса). Функции в этом модуле реализованы в соответствии с RFC 3986.

Краткое описание

Типы

t()

Функции

char_reserved?(char)

Проверяет, является ли символ "зарезервированным" символом в URI.

char_unescaped?(char)

Проверяет, разрешен ли символ без экранирования в URI.

char_unreserved?(char)

Проверяет, является ли символ "незарезервированным" символом в URI.

decode(uri)

Декодирует URI, заменяя проценты на соответствующие символы.

decode_query(query, map \\ %{})

Декодирует строку запроса в карту.

decode_www_form(string)

Декодирует строку в формате "x-www-form-urlencoded".

default_port(scheme)

Возвращает стандартный порт для заданного схемы.

default_port(scheme, port)

Регистрирует стандартный port для заданного scheme.

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

Экранирует символы, требующие экранирования, в строке.

encode_query(enumerable)

Кодирует перечисляемый объект в строку запроса.

encode_www_form(string)

Кодирует строку в формате "x-www-form-urlencoded".

merge(uri, rel)

Объединяет два URI.

parse(uri)

Разбирает правильно сформированную ссылку URI на составляющие компоненты.

query_decoder(query)

Возвращает поток пар ключ-значение в заданном query.

to_string(uri)

Возвращает строковое представление заданной структуры URI.

Типы

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

Функции

char_reserved?(char)

char_reserved?(char()) :: boolean()

Проверяет, является ли символ "зарезервированным" символом в URI.

Зарезервированные символы определены в RFC 3986, раздел 2.2.

Примеры

iex> URI.char_reserved?(?+)
true

char_unescaped?(char)

char_unescaped?(char()) :: boolean()

Проверяет, разрешен ли символ без экранирования в URI.

Это значение по умолчанию используется в URI.encode/2, где как зарезервированные, так и незарезервированные символы сохраняются без экранирования.

Примеры

iex> URI.char_unescaped?(?{)
false

char_unreserved?(char)

char_unreserved?(char()) :: boolean()

Проверяет, является ли символ "незарезервированным" символом в URI.

Незарезервированные символы определены в RFC 3986, раздел 2.3.

Примеры

iex> URI.char_unreserved?(?_)
true

decode(uri)

decode(binary()) :: binary()

Декодирует URI, заменяя проценты на соответствующие символы.

Примеры

iex> URI.decode("https%3A%2F%2Felixir-lang.org")
"https://elixir-lang.org"

decode_query(query, map \\ %{})

decode_query(binary(), %{optional(binary()) => binary()}) :: %{
  optional(binary()) => binary()
}

Декодирует строку запроса в карту.

Учитывая строку запроса в формате key1=value1&key2=value2..., эта функция вставляет каждую пару ключ-значение в строку запроса в качестве одной записи в заданную map. Ключи и значения в полученной карте будут бинарными. Ключи и значения будут декодированы.

Используйте query_decoder/1, если вы хотите вручную перебирать каждое значение.

Примеры

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()

Декодирует строку в формате "x-www-form-urlencoded".

Примеры

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

default_port(scheme)

default_port(binary()) :: nil | non_neg_integer()

Возвращает стандартный порт для заданного схемы.

Если схема неизвестна модулю URI, эта функция возвращает nil. Стандартный порт для любой схемы можно настроить глобально через default_port/2.

Примеры

iex> URI.default_port("ftp")
21

iex> URI.default_port("ponzi")
nil

default_port(scheme, port)

default_port(binary(), non_neg_integer()) :: :ok

Регистрирует стандартный port для заданного scheme.

После вызова этой функции port будет возвращаться функцией default_port/1 для заданной схемы scheme. Обратите внимание, что эта функция изменяет стандартный порт для заданного scheme глобально, то есть для каждого приложения.

Рекомендуется вызывать эту функцию в обработчике запуска вашего приложения, если вы хотите зарегистрировать новые URI.

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

encode(binary(), (byte() -> boolean())) :: binary()

Экранирует символы, требующие экранирования, в строке.

Это означает, что зарезервированные символы, такие как : и /, и так называемые незарезервированные символы, которые имеют одинаковое значение как в экранированном, так и в неэкранированном виде, по умолчанию не будут экранированы.

См. encode_www_form, если вы хотите экранировать и зарезервированные символы.

Эта функция также принимает необязательную функцию predicate. Если она передана, эта функция будет вызываться с каждым байтом в string в качестве аргумента и должна возвращать true, если данный байт должен остаться без изменений.

Примеры

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()

Кодирует перечисляемый объект в строку запроса.

Принимает перечисляемый объект, который перечисляет как список пар из двух элементов (например, карту или список ключевых слов) и возвращает строку в формате key1=value1&key2=value2..., где ключи и значения закодированы в формате URL в соответствии с encode_www_form/1.

Ключи и значения могут быть любыми терминами, которые реализуют протокол String.Chars, за исключением списков, которые запрещены явно.

Примеры

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()

Кодирует строку в формате "x-www-form-urlencoded".

Пример

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

merge(uri, rel)

merge(t() | binary(), t() | binary()) :: t()

Объединяет два URI.

Эта функция объединяет два URI в соответствии с RFC 3986, раздел 5.2.

Примеры

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()

Разбирает правильно сформированную ссылку URI на составляющие компоненты.

Обратите внимание, что эта функция ожидает правильно сформированный URI и не выполняет никакой проверки. См. раздел "Примеры" ниже для примеров того, как URI.parse/1 может быть использован для разбора широкого спектра URI.

Эта функция использует регулярное выражение для разбора, определенное в RFC 3986, Приложение B.

Когда URI задан без порта, значение, возвращаемое URI.default_port/1 для схемы URI, используется для поля :port.

Если функция получает структуру %URI{}, она возвращает ее без изменений.

Примеры

iex> URI.parse("https://elixir-lang.org/")
%URI{
  authority: "elixir-lang.org",
  fragment: nil,
  host: "elixir-lang.org",
  path: "/",
  port: 443,
  query: nil,
  scheme: "https",
  userinfo: nil
}

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(query)

query_decoder(binary()) :: Enumerable.t()

Возвращает поток пар ключ-значение в заданном query.

Ключ и значение в каждой паре будут бинарными и будут декодированы.

Примеры

iex> URI.query_decoder("foo=1&bar=2") |> Enum.to_list()
[{"foo", "1"}, {"bar", "2"}]

to_string(uri)

to_string(t()) :: binary()

Возвращает строковое представление заданной структуры URI.

Примеры

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"

Обратите внимание, что при создании этого строкового представления используется authority если хост nil. В противном случае используются userinfo, host, и port.

iex> URI.to_string(%URI{authority: "foo@example.com:80"})
"//foo@example.com:80"

iex> URI.to_string(%URI{userinfo: "bar", host: "example.org", port: 81})
"//bar@example.org:81"

iex> URI.to_string(%URI{
...>   authority: "foo@example.com:80",
...>   userinfo: "bar",
...>   host: "example.org",
...>   port: 81
...> })
"//bar@example.org:81"