Структура URI.

Поля определены в соответствии со следующим представлением URI (с именами полей в скобках):

[scheme]://[userinfo]@[host]:[port][path]?[query]#[fragment]

Обратите внимание, что поле authority устарело. parse/1 по-прежнему будет его заполнять для обратной совместимости, но в целом следует избегать его установки или получения.

@spec append_path(t(), String.t()) :: t()

Добавляет path к данному uri.

Путь должен начинаться с / и не может содержать дополнительные компоненты URL, такие как фрагменты или строки запроса. Эта функция также предполагает, что путь является допустимым и не содержит строки запроса или фрагментов.

Примеры

iex> URI.append_path(URI.parse("http://example.com/foo/?x=1"), "/my-path") |> URI.to_string()
"http://example.com/foo/my-path?x=1"

iex> URI.append_path(URI.parse("http://example.com"), "my-path")
** (ArgumentError) path must start with "/", got: "my-path"

@spec append_query(t(), binary()) :: t()

Добавляет query к данному uri.

Указанная query не кодируется автоматически, используйте encode/2 или encode_www_form/1.

Примеры

iex> URI.append_query(URI.parse("http://example.com/"), "x=1") |> URI.to_string()
"http://example.com/?x=1"

iex> URI.append_query(URI.parse("http://example.com/?x=1"), "y=2") |> URI.to_string()
"http://example.com/?x=1&y=2"

iex> URI.append_query(URI.parse("http://example.com/?x=1"), "x=2") |> URI.to_string()
"http://example.com/?x=1&x=2"

@spec char_reserved?(byte()) :: boolean()

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

Как указано в RFC 3986, раздел 2.2, следующие символы зарезервированы: :, /, ?, #, [, ], @, !, $, &, ', (, ), *, +, ,, ;, =

Примеры

iex> URI.char_reserved?(?+)
true

@spec char_unescaped?(byte()) :: boolean()

Проверяет, может ли character быть неэкранированным в URI.

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

Примеры

iex> URI.char_unescaped?(?{)
false

@spec char_unreserved?(byte()) :: boolean()

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

Как указано в RFC 3986, раздел 2.3, следующие символы незарезервированы:

• Символы алфавитно-цифрового формата: A-Z, a-z, 0-9
• ~, _, -, .

Примеры

iex> URI.char_unreserved?(?_)
true

@spec decode(binary()) :: binary()

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

Примеры

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

@spec decode_query(binary(), %{optional(binary()) => binary()}, :rfc3986 | :www_form) ::
  %{
    optional(binary()) => binary()
  }

Декодирует query в словарь.

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

Вы можете указать один из следующих encoding вариантов:

• :www_form - (по умолчанию, начиная с v1.12.0) ключи и значения декодируются в соответствии с decode_www_form/1. Это формат, обычно используемый браузерами для строк запросов и данных форм. Он декодирует "+" как " ".

• :rfc3986 - (начиная с v1.12.0) ключи и значения декодируются в соответствии с decode/1. Результат такой же, как и у :www_form, за исключением того, что "+" остается неизменным в соответствии с RFC 3986.

Кодировка по умолчанию :www_form для обратной совместимости.

Используйте 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"}

iex> URI.decode_query("percent=oh+yes%21", %{}, :rfc3986)
%{"percent" => "oh+yes!"}

@spec decode_www_form(binary()) :: binary()

Декодирует string как "x-www-form-urlencoded".

Обратите внимание, что "x-www-form-urlencoded" не указан в RFC 3986. Однако это распространенный формат кодирования строк запросов и данных форм браузерами.

Примеры

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

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

Возвращает порт по умолчанию для данного scheme.

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

Примеры

iex> URI.default_port("ftp")
21

iex> URI.default_port("ponzi")
nil

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

Регистрирует порт по умолчанию для заданной port.

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

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

@spec encode(binary(), (byte() -> as_boolean(term()))) :: binary()

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

По умолчанию, эта функция предназначена для экранирования всего URI и, следовательно, будет экранировать только символы, не допустимые во всех частях URI. Зарезервированные символы (например, : и /) или незарезервированные (например, буквы и цифры) не экранируются.

Поскольку разные компоненты URI требуют разных правил экранирования, эта функция также принимает функцию predicate в качестве необязательного аргумента. Если она передана, эта функция будет вызываться с каждым байтом в string в качестве аргумента и должна возвращать истинное значение (любое, кроме false или nil) если заданный байт должен остаться неизменным, или ложное значение (false или nil) если символ должен быть экранирован. По умолчанию используется URI.char_unescaped?/1.

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

Примеры

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"

@spec encode_query(Enumerable.t(), :rfc3986 | :www_form) :: binary()

Кодирует enumerable в строку запроса с использованием encoding.

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

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

Вы можете указать одну из следующих encoding стратегий:

• :www_form - (по умолчанию, начиная с v1.12.0) ключи и значения кодируются в соответствии со стандартом URL-кодирования из encode_www_form/1. Этот формат обычно используется браузерами для строк запроса и данных форм. Он кодирует " " как "+".

• :rfc3986 - (начиная с v1.12.0) аналогично :www_form, за исключением того, что он кодирует " " как "%20" согласно RFC 3986. Это лучший вариант, если вы кодируете не в браузере, так как кодирование пробелов как "+" может быть неоднозначным для парсеров URI. Это может непреднамеренно привести к тому, что пробелы будут интерпретироваться как буквальные знаки плюс.

Кодирование по умолчанию :www_form для совместимости со старыми версиями.

Примеры

iex> query = %{"foo" => 1, "bar" => 2}
iex> URI.encode_query(query)
"bar=2&foo=1"

iex> query = %{"key" => "value with spaces"}
iex> URI.encode_query(query)
"key=value+with+spaces"

iex> query = %{"key" => "value with spaces"}
iex> URI.encode_query(query, :rfc3986)
"key=value%20with%20spaces"

iex> URI.encode_query(%{key: [:a, :list]})
** (ArgumentError) encode_query/2 values cannot be lists, got: [:a, :list]

@spec encode_www_form(binary()) :: binary()

Кодирует string как "x-www-form-urlencoded".

Обратите внимание, что "x-www-form-urlencoded" не определен как часть RFC 3986. Однако это распространенный формат кодирования строк запроса и данных форм в браузерах.

Пример

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

@spec 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"

@spec new(t() | String.t()) :: {:ok, t()} | {:error, String.t()}

Создаёт новую структуру URI из URI или строки.

Если задана структура %URI{}, она возвращает {:ok, uri}. Если задана строка, она будет обработана и проверена. Если строка корректна, возвращается {:ok, uri}, иначе возвращается {:error, part} с некорректной частью URI. Для парсинга URI без дальнейшей проверки см. parse/1.

Эта функция может парсить как абсолютные, так и относительные URL. Вы можете проверить, является ли URI абсолютным или относительным, проверив, является ли поле scheme nil или нет.

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

Примеры

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

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

iex> URI.new("/foo/bar")
{:ok, %URI{
  fragment: nil,
  host: nil,
  path: "/foo/bar",
  port: nil,
  query: nil,
  scheme: nil,
  userinfo: nil
}}

iex> URI.new("foo/bar")
{:ok, %URI{
  fragment: nil,
  host: nil,
  path: "foo/bar",
  port: nil,
  query: nil,
  scheme: nil,
  userinfo: nil
}}

iex> URI.new("//[fe80::]/")
{:ok, %URI{
  fragment: nil,
  host: "fe80::",
  path: "/",
  port: nil,
  query: nil,
  scheme: nil,
  userinfo: nil
}}

iex> URI.new("https:?query")
{:ok, %URI{
  fragment: nil,
  host: nil,
  path: nil,
  port: 443,
  query: "query",
  scheme: "https",
  userinfo: nil
}}

iex> URI.new("/invalid_greater_than_in_path/>")
{:error, ">"}

Передача существующего URI просто возвращает его, заключённый в кортеж:

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

@spec new!(t() | String.t()) :: t()

Аналогично new/1, но вызывает URI.Error, если задана некорректная строка.

Примеры

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

iex> URI.new!("/invalid_greater_than_in_path/>")
** (URI.Error) cannot parse due to reason invalid_uri: ">"

Передача существующего URI просто возвращает его:

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

@spec parse(t() | binary()) :: t()

Парсит URI в его компоненты без дальнейшей проверки.

Эта функция может парсить как абсолютные, так и относительные URL-адреса. Вы можете проверить, является ли URI абсолютным или относительным, проверив, является ли поле scheme нулевым или нет. Кроме того, эта функция ожидает, что и абсолютные, и относительные URI будут правильно сформированы и не выполняет никакой проверки. См. раздел "Примеры" ниже. Используйте new/1, если вы хотите проверить поля URI после парсинга.

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

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

:authority поле

Эта функция устанавливает поле :authority по соображениям обратной совместимости, но оно устарело.

Примеры

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{
  fragment: nil,
  host: nil,
  path: "/foo/bar",
  port: nil,
  query: nil,
  scheme: nil,
  userinfo: nil
}

iex> URI.parse("foo/bar")
%URI{
  fragment: nil,
  host: nil,
  path: "foo/bar",
  port: nil,
  query: nil,
  scheme: nil,
  userinfo: nil
}

В отличие от URI.new/1, эта функция будет парсить плохо сформированные URI, например:

iex> URI.parse("/invalid_greater_than_in_path/>")
%URI{
  fragment: nil,
  host: nil,
  path: "/invalid_greater_than_in_path/>",
  port: nil,
  query: nil,
  scheme: nil,
  userinfo: nil
}

Ещё один пример — URI с скобками в строках запроса. Он принимается parse/1, обычно принимается браузерами, но будет отвергнут new/1:

iex> URI.parse("/?foo[bar]=baz")
%URI{
  fragment: nil,
  host: nil,
  path: "/",
  port: nil,
  query: "foo[bar]=baz",
  scheme: nil,
  userinfo: nil
}

@spec query_decoder(binary(), :rfc3986 | :www_form) :: Enumerable.t()

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

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

Вы можете указать следующие параметры encoding:

• :www_form - (по умолчанию, начиная с v1.12.0) ключи и значения декодируются согласно decode_www_form/1. Этот формат обычно используется браузерами для строк запроса и данных форм. Он декодирует "+" как " ".

• :rfc3986 - (начиная с v1.12.0) ключи и значения декодируются согласно decode/1. Результат такой же, как у :www_form, за исключением того, что "+" остаётся неизменным, в соответствии с RFC 3986.

Кодирование по умолчанию :www_form для совместимости со старыми версиями.

Примеры

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

iex> URI.query_decoder("food=bread%26butter&drinks=tap%20water+please") |> Enum.to_list()
[{"food", "bread&butter"}, {"drinks", "tap water please"}]

iex> URI.query_decoder("food=bread%26butter&drinks=tap%20water+please", :rfc3986) |> Enum.to_list()
[{"food", "bread&butter"}, {"drinks", "tap water+please"}]

@spec to_string(t()) :: binary()

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

Примеры

iex> uri = URI.parse("http://google.com")
iex> URI.to_string(uri)
"http://google.com"

iex> uri = URI.parse("foo://bar.baz")
iex> URI.to_string(uri)
"foo://bar.baz"