URI

Структура 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. Ключи и значения в результирующей карте будут двоичными. Ключи и значения будут декодированы с процентами.

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

• :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

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

После вызова этой функции 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) ключи и значения кодируются в 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 значение nil или нет. Кроме того, эта функция ожидает, что как абсолютные, так и относительные 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"