Модуль uri

Модуль URI предоставляет функции для преобразования строк URI в их компоненты и обратно — из компонентов в строку URI, например:

 
local uri = require('uri')parsed_uri = uri.parse('https://www.tarantool.io/doc/latest/reference/reference_lua/http/#api-reference')--[[---- host: www.tarantool.io  fragment: api-reference  scheme: https  path: /doc/latest/reference/reference_lua/http/...--]]formatted_uri = uri.format({ scheme = 'https',                             host = 'www.tarantool.io',                             path = '/doc/latest/reference/reference_lua/http/',                             fragment = 'api-reference' })--[[---- https://www.tarantool.io/doc/latest/reference/reference_lua/http/#api-reference...--]]

Для экранирования и снятия экранирования специальных символов используются соответствующие функции:

 
formatted_uri3_e = uri.format({    login = uri.escape('replic@ator'),    password = uri.escape(':::'),    host = 'foo.bar',    params = {x = uri.escape('sec ret?', uri.FORM_URLENCODED)}    },    true)--[[---- replic%40ator:%3A%3A%3A@foo.bar?x=sec+ret%3F...]]--parsed_uri3_e = uri.parse(formatted_uri3_e)--[[---- password: '%3A%3A%3A'  login: replic%40ator  query: x=sec+ret%3F  params:    x:    - sec+ret%3F  host: foo.bar...]]--parsed_uri3 = {    login = uri.unescape(parsed_uri3_e.login),    password = uri.unescape(parsed_uri3_e.password),    host = parsed_uri3_e.host,    params = {x = {uri.unescape(parsed_uri3_e.params.x[1], uri.FORM_URLENCODED)}},}--[[---- password: ':::'  params:    x:    - sec ret?  host: foo.bar  login: replic@ator...]]--

Этот модуль также можно использовать для кодирования и декодирования произвольных строк с заданными параметрами кодирования.

Ниже приведен список функций, свойств и связанных объектов модуля uri.

Разбор строки URI на компоненты.

См. также: uri.format()

Параметры:

• uri-string (string) — строка URI

• uri-table (table) — таблица URI со строкой URI и необязательным переопределением параметров запроса URI. Ключ строки URI в таблице должен быть 'uri' или 1 (первый элемент массива). Переопределение параметров запроса URI должно быть задано в элементе 'params' таблицы.

Возвращает

таблица компонентов URI (см. uri_components)

Тип возвращаемого значения

table

Пример:

 
local uri = require('uri')parsed_uri = uri.parse('https://www.tarantool.io/doc/latest/reference/reference_lua/http/#api-reference')--[[---- host: www.tarantool.io  fragment: api-reference  scheme: https  path: /doc/latest/reference/reference_lua/http/...--]]parsed_uri11 = uri.parse({'foo.bar?x=1&x=2'})parsed_uri12 = uri.parse({uri = 'foo.bar?x=1&x=2'})--[[---- host: foo.bar  params:    x:    - '1'    - '2'  query: x=1&x=2...--]]parsed_uri21 = uri.parse({'foo.bar?x=1', params = {x = 2, y = 3}})parsed_uri22 = uri.parse({uri = 'foo.bar?x=1', params = {x = 2, y = 3}})--[[---- host: foo.bar  params:    y:    - '3'    x:    - '2'  query: x=1...--]]

Формирование URI из заданных компонентов.

См. также: uri.parse()

Параметры:

• uri_components (table) — набор пар name=value, по одной для каждого компонента (см. uri_components)
• include_password (boolean) — определяет, отображается ли компонент пароля в открытом виде; в противном случае он опускается

Возвращает

строка URI

Тип возвращаемого значения

string

Пример:

 
local uri = require('uri')formatted_uri = uri.format({ scheme = 'https',                             host = 'www.tarantool.io',                             path = '/doc/latest/reference/reference_lua/http/',                             fragment = 'api-reference' })--[[---- https://www.tarantool.io/doc/latest/reference/reference_lua/http/#api-reference...--]]parsed_uri12 = uri.parse({uri = 'foo.bar?x=1&x=2'})formatted_uri1 = uri.format(parsed_uri12)--[[---- foo.bar?x=1&x=2...--]]parsed_uri21 = uri.parse({'foo.bar?x=1', params = {x = 2, y = 3}})formatted_uri2 = uri.format(parsed_uri21)--[[---- foo.bar?y=3&x=2...--]]

Начиная с: 2.11.0

Кодирование строки с заданными параметрами кодирования.

По умолчанию uri.escape() использует параметры кодирования, определенные в таблице uri.RFC3986. При необходимости параметры кодирования можно настроить с помощью необязательного параметра uri_encoding_opts, например:

• Передать предопределенный набор параметров для кодирования определенной части URI (например, uri.PATH или uri.QUERY).
• Передать пользовательские параметры кодирования с помощью объекта uri_encoding_opts.

Параметры:

• string — строка для кодирования
• uri_encoding_opts (table) — параметры кодирования (необязательно, см. uri_encoding_opts)

Возвращает

закодированная строка

Тип возвращаемого значения

string

Пример 1:

В этом примере показано, как закодировать строку с параметрами кодирования по умолчанию.

 
local uri = require('uri')escaped_string = uri.escape('C++')--[[---- C%2B%2B...--]]

Пример 2:

В этом примере показано, как закодировать строку с параметрами кодирования uri.FORM_URLENCODED.

 
local uri = require('uri')escaped_string_url_enc = uri.escape('John Smith', uri.FORM_URLENCODED)--[[---- John+Smith...--]]

Пример 3:

В этом примере показано, как закодировать строку с пользовательскими параметрами кодирования.

 
local uri = require('uri')local escape_opts = {    plus = true,    unreserved = uri.unreserved("a-z")}escaped_string_custom = uri.escape('Hello World', escape_opts)--[[---- '%48ello+%57orld'...--]]

Начиная с: 2.11.0

Декодирование строки с заданными параметрами кодирования.

По умолчанию uri.unescape() использует параметры кодирования, определенные в таблице uri.RFC3986. При необходимости параметры кодирования можно настроить с помощью необязательного параметра uri_encoding_opts, например:

• Передать предопределенный набор параметров для кодирования определенной части URI (например, uri.PATH или uri.QUERY).
• Передать пользовательские параметры кодирования с помощью объекта uri_encoding_opts.

Параметры:

• string — строка для декодирования
• uri_encoding_opts (table) — параметры кодирования (необязательно, см. uri_encoding_opts)

Возвращает

декодированная строка

Тип возвращаемого значения

string

Пример 1:

В этом примере показано, как декодировать строку с параметрами кодирования по умолчанию.

 
local uri = require('uri')unescaped_string = uri.unescape('C%2B%2B')--[[---- C++...--]]

Пример 2:

В этом примере показано, как декодировать строку с параметрами кодирования uri.FORM_URLENCODED.

 
local uri = require('uri')unescaped_string_url_enc = uri.unescape('John+Smith', uri.FORM_URLENCODED)--[[---- John Smith...--]]

Пример 3:

В этом примере показано, как декодировать строку с пользовательскими параметрами кодирования.

 
local uri = require('uri')local escape_opts = {    plus = true,    unreserved = uri.unreserved("a-z")}unescaped_string_custom = uri.unescape('%48ello+%57orld', escape_opts)--[[---- Hello World...--]]

Параметры кодирования, использующие незарезервированные символы, определенные в RFC 3986. Это параметры по умолчанию, используемые для кодирования и декодирования с помощью функций uri.escape() и uri.unescape() соответственно.

См. также: uri_encoding_opts

Тип возвращаемого значения

table

Параметры, используемые для кодирования компонента URI path.

См. также: uri_encoding_opts

Тип возвращаемого значения

table

Параметры, используемые для кодирования отдельных частей path.

См. также: uri_encoding_opts

Тип возвращаемого значения

table

Параметры, используемые для кодирования компонента URI query.

См. также: uri_encoding_opts

Тип возвращаемого значения

table

Параметры, используемые для кодирования отдельных частей query.

См. также: uri_encoding_opts

Тип возвращаемого значения

table

Параметры, используемые для кодирования компонента URI fragment.

См. также: uri_encoding_opts

Тип возвращаемого значения

table

Параметры, используемые для кодирования параметров формы application/x-www-form-urlencoded.

См. также: uri_encoding_opts

Тип возвращаемого значения

table

Компоненты URI. Объект uri_components используется в следующих функциях:

• Функция uri.parse() возвращает объект uri_components.
• Функция uri.format() принимает объект uri_components в качестве аргумента.

Схема URI.

Примеры: https, http

Имя пользователя, являющееся частью подкомпонента userinfo.

Пароль, являющийся частью подкомпонента userinfo.

Подкомпонент host.

Пример: www.tarantool.io

Подкомпонент service. Это свойство может возвращать разные значения в зависимости от используемой схемы URI, например:

• Если используется схема https или http, service возвращает значение порта.
• Если используется Unix domain socket, service возвращает путь к сокету.

Примеры: 3301, /tmp/unix.sock

Компонент path.

Пример: /doc/latest/reference/reference_lua/http/

Компонент query.

Пример: key1=value1&key2=value2

Параметры компонента query. Переопределяет query. Элементами таблицы могут быть string или массивы string.

Пример: {key1 = 'value1', key2 = 'value2', key3 = {'1', '2'}}

Компонент fragment.

Пример: api-reference

IPv4-адрес.

Пример: 127.0.0.1

IPv6-адрес.

Пример: 2a00:1148:b0ba:2016:12bf:48ff:fe78:fd10

Unix domain socket.

Пример: /tmp/unix.sock

Начиная с: 2.11.0

Параметры кодирования URI. Эти параметры можно передавать в функции uri.escape() и uri.unescape().

Пример:

В приведенном ниже примере показано, как закодировать строку с пользовательскими параметрами кодирования.

 
local uri = require('uri')local escape_opts = {    plus = true,    unreserved = uri.unreserved("a-z")}escaped_string_custom = uri.escape('Hello World', escape_opts)--[[---- '%48ello+%57orld'...--]]

Включает кодирование + как символа пробела. По умолчанию для этого свойства задано значение false.

Тип возвращаемого значения

boolean

Задает Lua-шаблон, определяющий незарезервированные символы, которые не кодируются.

Тип возвращаемого значения

table

Пример: 'a-zA-Z0-9%-._~'