Модуль checks

Начиная с: 2.11.0

Модуль checks предоставляет возможность проверки типов аргументов, передаваемых в Lua-функцию. Необходимо вызвать функцию checks(type_1, ...) внутри целевой Lua-функции и передать один или несколько квалификаторов типа для проверки соответствующих типов аргументов. Существует два вида квалификаторов типа:

• Строковый квалификатор типа проверяет, соответствует ли аргумент функции указанному типу. Пример: 'string'.

• Табличный квалификатор типа проверяет, соответствуют ли значения таблицы, переданной в качестве аргумента, указанным типам. Пример: { 'string', 'number' }.

В Tarantool 2.11.0 и более поздних версиях API checks доступно в скрипте без загрузки модуля.

Для более ранних версий необходимо установить модуль checks из Tarantool rocks repository и загрузить его с помощью директивы require():

 
local checks = require('checks')

Для каждого проверяемого аргумента необходимо указать соответствующий квалификатор типа в функции checks(type_1, ...).

В примере ниже функция checks принимает строковый квалификатор типа string, чтобы убедиться, что в функцию greet можно передать только строковое значение. В противном случае возникает ошибка.

 
function greet(name)    checks('string')    return 'Hello, ' .. nameend--[[greet('John')-- returns 'Hello, John'greet(123)-- raises an error: bad argument #1 to nil (string expected, got number)--]]

Для проверки типов нескольких аргументов необходимо передать соответствующие квалификаторы типа в функцию checks. В примере ниже оба аргумента должны быть строковыми значениями.

 
function greet_fullname(firstname, lastname)    checks('string', 'string')    return 'Hello, ' .. firstname .. ' ' .. lastnameend--[[greet_fullname('John', 'Smith')-- returns 'Hello, John Smith'greet_fullname('John', 1)-- raises an error: bad argument #2 to nil (string expected, got number)--]]

Чтобы пропустить проверку определённых аргументов, используйте заполнитель ?.

Можно проверять типы явно указанных аргументов для функций, принимающих переменное количество аргументов.

 
function extra_arguments_num(a, b, ...)    checks('string', 'number')    return select('#', ...)end--[[extra_arguments_num('a', 2, 'c')-- returns 1extra_arguments_num('a', 'b', 'c')-- raises an error: bad argument #1 to nil (string expected, got number)--]]

В этом разделе описано, как проверить определённый тип аргумента с помощью строкового квалификатора типа:

• В разделе Поддерживаемые типы описаны все типы, поддерживаемые модулем checks.
• При необходимости можно создать объединённый тип, чтобы разрешить аргументу принимать несколько типов.
• Любой из поддерживаемых типов можно сделать необязательным.
• Чтобы пропустить проверку определённых аргументов, используйте заполнитель ?.

Строковый квалификатор типа может принимать любой из типов Lua, например, string, number, table или nil. В примере ниже функция checks принимает string для проверки того, что в функцию greet можно передать только строковое значение.

 
function greet(name)    checks('string')    return 'Hello, ' .. nameend--[[greet('John')-- returns 'Hello, John'greet(123)-- raises an error: bad argument #1 to nil (string expected, got number)--]]

В строковом квалификаторе можно использовать типы, специфичные для Tarantool. В примере ниже показано, как проверить, что аргумент функции является десятичным значением.

 
local decimal = require('decimal')function sqrt(value)    checks('decimal')    return decimal.sqrt(value)end--[[sqrt(decimal.new(16))-- returns 4sqrt(16)-- raises an error: bad argument #1 to nil (decimal expected, got number)--]]

В таблице ниже перечислены все проверки, доступные для типов Tarantool:

Строковый квалификатор типа может принимать имя пользовательской функции, выполняющей произвольные проверки. Для этого создайте функцию, возвращающую true, если значение допустимо, и добавьте эту функцию в таблицу checkers.

В примере ниже показано, как использовать функцию positive для проверки того, что значение аргумента является положительным числом.

 
function checkers.positive(value)    return (type(value) == 'number') and (value > 0)endfunction get_doubled_number(value)    checks('positive')    return value * 2end--[[get_doubled_number(10)-- returns 20get_doubled_number(-5)-- raises an error: bad argument #1 to nil (positive expected, got number)--]]

Строковый квалификатор может принимать значение, хранящееся в поле __type метатаблицы аргумента.

 
local blue = setmetatable({ 0, 0, 255 }, { __type = 'color' })function get_blue_value(color)    checks('color')    return color[3]end--[[get_blue_value(blue)-- returns 255get_blue_value({0, 0, 255})-- raises an error: bad argument #1 to nil (color expected, got table)--]]

Чтобы разрешить аргументу принимать несколько типов (объединённый тип), объедините имена типов с помощью символа вертикальной черты (|). В примере ниже аргумент может быть как значением типа number, так и string.

 
function get_argument_type(value)    checks('number|string')    return type(value)end--[[get_argument_type(1)-- returns 'number'get_argument_type('key1')-- returns 'string'get_argument_type(true)-- raises an error: bad argument #1 to nil (number|string expected, got boolean)--]]

Чтобы сделать любой из поддерживаемых типов необязательным, добавьте перед его именем вопросительный знак (?). В примере ниже аргумент name является необязательным. Это означает, что функция greet может принимать значения string и nil.

 
function greet(name)    checks('?string')    if name ~= nil then        return 'Hello, ' .. name    else        return 'Hello from Tarantool'    endend--[[greet('John')-- returns 'Hello, John'greet()-- returns 'Hello from Tarantool'greet(123)-- raises an error: bad argument #1 to nil (string expected, got number)--]]

Как и для конкретного типа, можно сделать значение объединённого типа необязательным: ?number|string.

Можно пропустить проверку указанных аргументов с помощью заполнителя — вопросительного знака (?). В этом случае аргумент может иметь любой тип.

 
function greet_fullname_any(firstname, lastname)    checks('string', '?')    return 'Hello, ' .. firstname .. ' ' .. tostring(lastname)end--[[greet_fullname_any('John', 'Doe')-- returns 'Hello, John Doe'greet_fullname_any('John', 1)-- returns 'Hello, John 1'--]]

Табличный квалификатор типа проверяет, соответствуют ли значения таблицы, переданной в качестве аргумента, указанным типам. В этом случае выполняются следующие проверки:

• Аргумент проверяется на соответствие типу ?table, а его содержимое проходит валидацию.
• Значения таблицы проверяются на соответствие указанным строковым квалификаторам типа.
• Ключи таблицы, отсутствующие в checks, проверяются на соответствие типу nil. В коде ниже проверяется, что первое и второе значения таблицы имеют типы string и number соответственно.

 
function configure_connection(options)    checks({ 'string', 'number' })    local ip_address = options[1] or '127.0.0.1'    local port = options[2] or 3301    return ip_address .. ':' .. portend--[[configure_connection({'0.0.0.0', 3303})-- returns '0.0.0.0:3303'configure_connection({'0.0.0.0', '3303'})-- raises an error: bad argument options[2] to nil (number expected, got string)--]]

В следующем примере выполняются те же проверки для указанных ключей.

 
function configure_connection_opts(options)    checks({ ip_address = 'string', port = 'number' })    local ip_address = options.ip_address or '127.0.0.1'    local port = options.port or 3301    return ip_address .. ':' .. portend--[[configure_connection_opts({ip_address = '0.0.0.0', port = 3303})-- returns '0.0.0.0:3303'configure_connection_opts({ip_address = '0.0.0.0', port = '3303'})-- raises an error: bad argument options.port to nil (number expected, got string)configure_connection_opts({login = 'testuser', ip_address = '0.0.0.0', port = 3303})-- raises an error: unexpected argument options.login to nil--]]

Ниже приведен перечень элементов модуля checks.

При вызове внутри функции проверяет, что аргументы функции соответствуют указанным типам.

Параметры:

• type_1 (string|table) — строковый или табличный квалификатор типа, используемый для проверки типа аргумента
• ... — необязательные квалификаторы типа для проверки типов других аргументов

Глобальная переменная checkers предоставляет доступ к функциям проверки для различных типов. Эту переменную можно использовать для добавления пользовательской функции проверки, выполняющей произвольные проверки.

Переменная checkers также предоставляет доступ к функциям проверки для типов, специфичных для Tarantool. Эти функции можно использовать в пользовательской функции проверки.

Проверка, является ли указанное значение datetime_object.

Параметры:

• value (any) — значение, тип которого требуется проверить

Возвращает

true, если указанное значение является datetime_object; иначе false

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

boolean

Пример:

Проверка, имеет ли указанное значение тип decimal.

Параметры:

• value (any) — значение, тип которого требуется проверить

Возвращает

true, если указанное значение имеет тип decimal; иначе false

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

boolean

Пример:

Проверка, является ли указанное значение error_object.

Параметры:

• value (any) — значение, тип которого требуется проверить

Возвращает

true, если указанное значение является error_object; иначе false

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

boolean

Пример:

Проверка, является ли указанное значение одним из следующих значений int64:

• число Lua в диапазоне от -2^53+1 до 2^53-1 (включительно)
• cdata Lua ctype<uint64_t> в диапазоне от 0 до LLONG_MAX
• cdata Lua ctype<int64_t>

Параметры:

• value (any) — значение, тип которого требуется проверить

Возвращает

true, если указанное значение является значением int64; иначе false

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

boolean

Пример:

Проверка, является ли указанное значение interval_object.

Параметры:

• value (any) — значение, тип которого требуется проверить

Возвращает

true, если указанное значение является interval_object; иначе false

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

boolean

Пример:

Проверка, является ли указанное значение кортежем.

Параметры:

• value (any) — значение, тип которого требуется проверить

Возвращает

true, если указанное значение является кортежем; иначе false

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

boolean

Пример:

Проверка, является ли указанное значение одним из следующих значений uint64:

• число Lua в диапазоне от 0 до 2^53-1 (включительно)
• cdata Lua ctype<uint64_t>
• cdata Lua ctype<int64_t> в диапазоне от 0 до LLONG_MAX

Параметры:

• value (any) — значение, тип которого требуется проверить

Возвращает

true, если указанное значение является значением uint64; иначе false

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

boolean

Пример:

Проверка, является ли указанное значение uuid_object.

Параметры:

• value (any) — значение, тип которого требуется проверить

Возвращает

true, если указанное значение является uuid_object; иначе false

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

boolean

Пример:

 
local uuid = require('uuid')local is_uuid = checkers.uuid(uuid())local is_uuid_bin = checkers.uuid_bin(uuid.bin())local is_uuid_str = checkers.uuid_str(uuid.str())

Проверка, является ли указанное значение uuid, представленным 16-байтной бинарной строкой.

Параметры:

• value (any) — значение, тип которого требуется проверить

Возвращает

true, если указанное значение является uuid, представленным 16-байтной бинарной строкой; иначе false

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

boolean

См. также: uuid(value)

Проверка, является ли указанное значение uuid, представленным 36-байтной шестнадцатеричной строкой.

Параметры:

• value (any) — значение, тип которого требуется проверить

Возвращает

true, если указанное значение является uuid, представленным 36-байтной шестнадцатеричной строкой; иначе false

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

boolean

См. также: uuid(value)