@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(Enum.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()) :: t()

Аналогично new/0, но генерирует исключение 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 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 отсутствует порт, для поля :port используется значение, возвращаемое функцией URI.default_port/1 для схемы URI. Схема также нормализуется до нижнего регистра.

Примеры

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 parse(t() | binary()) :: t()

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

Функция может парсить как абсолютные, так и относительные URL. Можно проверить, является ли URI абсолютным или относительным, проверив поле scheme на значение null. Более того, функция ожидает, что как абсолютные, так и относительные URI будут правильно сформированы и не выполняет никакой валидации. Смотрите раздел "Примеры" ниже. Используйте new/1, если вам нужна более строгая валидация.

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

Если в качестве аргумента передан объект %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{
  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
}

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

iex> URI.parse("/invalid_greater_than_in_path/>")
%URI{
  authority: nil,
  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{
  authority: nil,
  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"