Структура URI.

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

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

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

@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.

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

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

Эта функция также принимает predicate функцию в качестве необязательного аргумента. Если она передается, эта функция будет вызываться с каждым байтом в string в качестве аргумента и должна возвращать значение с истинным значением (любое значение, отличное от false или nil ), если заданный байт должен остаться неизменным, или возвращать ложное значение (false или nil ), если символ должен быть экранирован. По умолчанию URI.char_unescaped?/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) ключи и значения кодируются как в 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 для обеспечения обратной совместимости, но оно устарело.

Примеры

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"