Справочник URI

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

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

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

Типы

t()

Функции

char_reserved?(символ): Проверяет, является ли символ «зарезервированным» символом в URI
char_unescaped?(символ): Проверяет, разрешен ли символ без экранирования в URI
char_unreserved?(символ): Проверяет, является ли символ «незарезервированным» символом в URI
decode(uri): Декодирует URI с процентами.
decode_query(запрос, карта \\ %{}): Декодирует строку запроса в карту.
decode_www_form(строка): Декодирует строку как «x-www-form-urlencoded».
default_port(схема): Возвращает стандартный порт для заданной схемы.
default_port(схема, порт): Регистрирует стандартный порт port для заданной scheme.
encode(строка, предикат \\ &char_unescaped?/1): Экранирует данную строку с процентами.
encode_query(перечислимый): Кодирует перечислимый объект в строку запроса.
encode_www_form(строка): Кодирует строку как «x-www-form-urlencoded».
merge(uri, rel): Объединяет два URI.
parse(uri): Разбирает правильное URI-ссылку на ее компоненты.
path_to_segments(путь)
query_decoder(запрос): Возвращает поток пар ключ-значение, представленных кортежами из двух элементов, в данном 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_reserved?(char) :: boolean

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

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

Примеры

iex> URI.char_reserved?(?+)
true

char_unescaped?(символ)

char_unescaped?(char) :: boolean

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

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

Примеры

iex> URI.char_unescaped?(?{)
false

char_unreserved?(символ)

char_unreserved?(char) :: boolean

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

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

Примеры

iex> URI.char_unreserved?(?_)
true

decode(uri)

decode(binary) :: binary

Декодирует URI с процентами.

Примеры

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

decode_query(запрос, карта \\ %{})

decode_query(binary, map) :: map

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

Учитывая строку запроса в формате 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(строка)

decode_www_form(binary) :: binary

Декодирует строку как «x-www-form-urlencoded».

Примеры

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

default_port(схема)

default_port(binary) :: nil | pos_integer

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

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

Примеры

iex> URI.default_port("ftp")
21

iex> URI.default_port("ponzi")
nil

default_port(схема, порт)

default_port(binary, pos_integer) :: :ok

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

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

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

encode(строка, предикат \\ &char_unescaped?/1)

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

Экранирует данную строку с процентами.

Эта функция принимает функцию predicate в качестве необязательного аргумента; если она передана, эта функция будет вызываться с каждым символом (байтом) в str в качестве её аргумента, и должна возвращать 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(перечислимый)

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(строка)

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("http://elixir-lang.org/")
%URI{scheme: "http", path: "/", query: nil, fragment: nil,
     authority: "elixir-lang.org", userinfo: nil,
     host: "elixir-lang.org", port: 80}

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}

path_to_segments(путь)

query_decoder(запрос)

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"