Document the 'checks' module

doc/code_snippets/test/checks/checkers_test.lua

@@ -0,0 +1,46 @@
+-- datetime/interval checkers
+local datetime = require('datetime')
+local is_datetime = checkers.datetime(datetime.new { day = 1, month = 6, year = 2023 })
+local is_interval = checkers.interval(datetime.interval.new { day = 1 })
+-- is_datetime/is_interval = true
+
+-- decimal checker
+local decimal = require('decimal')
+local is_decimal = checkers.decimal(decimal.new(16))
+-- is_decimal = true
+
+-- error checker
+local server_error = box.error.new({ code = 500, reason = 'Server error' })
+local is_error = checkers.error(server_error)
+-- is_error = true
+
+-- int64/uint64 checkers
+local is_int64 = checkers.int64(-1024)
+local is_uint64 = checkers.uint64(2048)
+-- is_int64/is_uint64 = true
+
+-- tuple checker
+local is_tuple = checkers.tuple(box.tuple.new(1, 'The Beatles', 1960))
+-- is_tuple = true
+
+-- uuid checkers
+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())
+-- is_uuid/is_uuid_bin/is_uuid_str = true
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(is_datetime, true)
+    luatest.assert_equals(is_interval, true)
+    luatest.assert_equals(is_decimal, true)
+    luatest.assert_equals(is_error, true)
+    luatest.assert_equals(is_int64, true)
+    luatest.assert_equals(is_uint64, true)
+    luatest.assert_equals(is_tuple, true)
+    luatest.assert_equals(is_uuid, true)
+    luatest.assert_equals(is_uuid_bin, true)
+    luatest.assert_equals(is_uuid_str, true)
+end

doc/code_snippets/test/checks/checks_any_optional_test.lua

@@ -0,0 +1,19 @@
+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'
+--]]
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(greet_fullname_any('John', 'Doe'), 'Hello, John Doe')
+    luatest.assert_equals(greet_fullname_any('John', 1), 'Hello, John 1')
+end

doc/code_snippets/test/checks/checks_decimal_test.lua

@@ -0,0 +1,20 @@
+local decimal = require('decimal')
+function sqrt(value)
+    checks('decimal')
+    return decimal.sqrt(value)
+end
+--[[
+sqrt(decimal.new(16))
+-- returns 4
+
+sqrt(16)
+-- raises an error: bad argument #1 to nil (decimal expected, got number)
+--]]
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(sqrt(decimal.new(16)), 4)
+    luatest.assert_error_msg_contains('bad argument #1 to nil (decimal expected, got number)', sqrt, 16)
+end

doc/code_snippets/test/checks/checks_function_test.lua

@@ -0,0 +1,23 @@
+function checkers.positive(value)
+    return (type(value) == 'number') and (value > 0)
+end
+
+function get_doubled_number(value)
+    checks('positive')
+    return value * 2
+end
+--[[
+get_doubled_number(10)
+-- returns 20
+
+get_doubled_number(-5)
+-- raises an error: bad argument #1 to nil (positive expected, got number)
+--]]
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(get_doubled_number(10), 20)
+    luatest.assert_error_msg_contains('bad argument #1 to nil (positive expected, got number)', get_doubled_number, -5)
+end

doc/code_snippets/test/checks/checks_metatable_type_test.lua

@@ -0,0 +1,20 @@
+local blue = setmetatable({ 0, 0, 255 }, { __type = 'color' })
+function get_blue_value(color)
+    checks('color')
+    return color[3]
+end
+--[[
+get_blue_value(blue)
+-- returns 255
+
+get_blue_value({0, 0, 255})
+-- raises an error: bad argument #1 to nil (color expected, got table)
+--]]
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(get_blue_value(blue), 255)
+    luatest.assert_error_msg_contains('bad argument #1 to nil (color expected, got table)', get_blue_value, { 0, 0, 255 })
+end

doc/code_snippets/test/checks/checks_string_multiple_test.lua

@@ -0,0 +1,19 @@
+function greet_fullname(firstname, lastname)
+    checks('string', 'string')
+    return 'Hello, ' .. firstname .. ' ' .. lastname
+end
+--[[
+greet_fullname('John', 'Smith')
+-- returns 'Hello, John Smith'
+
+greet_fullname('John', 1)
+-- raises an error: bad argument #2 to nil (string expected, got number)
+--]]
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(greet_fullname('John', 'Smith'), 'Hello, John Smith')
+    luatest.assert_error_msg_contains('bad argument #2 to nil (string expected, got number)', greet_fullname, 'John', 1)
+end

doc/code_snippets/test/checks/checks_string_optional_test.lua

@@ -0,0 +1,26 @@
+function greet(name)
+    checks('?string')
+    if name ~= nil then
+        return 'Hello, ' .. name
+    else
+        return 'Hello from Tarantool'
+    end
+end
+--[[
+greet('John')
+-- returns 'Hello, John'
+
+greet()
+-- returns 'Hello from Tarantool'
+
+greet(123)
+-- raises an error: bad argument #1 to nil (string expected, got number)
+--]]
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(greet('John'), 'Hello, John')
+    luatest.assert_error_msg_contains('bad argument #1 to nil (string expected, got number)', greet, 123)
+end

doc/code_snippets/test/checks/checks_string_test.lua

@@ -0,0 +1,19 @@
+function greet(name)
+    checks('string')
+    return 'Hello, ' .. name
+end
+--[[
+greet('John')
+-- returns 'Hello, John'
+
+greet(123)
+-- raises an error: bad argument #1 to nil (string expected, got number)
+--]]
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(greet('John'), 'Hello, John')
+    luatest.assert_error_msg_contains('bad argument #1 to nil (string expected, got number)', greet, 123)
+end

doc/code_snippets/test/checks/checks_table_indexes_test.lua

@@ -0,0 +1,21 @@
+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 .. ':' .. port
+end
+--[[
+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)
+--]]
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(configure_connection({ '0.0.0.0', 3303 }), '0.0.0.0:3303')
+    luatest.assert_error_msg_contains('bad argument options[2] to nil (number expected, got string)', configure_connection, { '0.0.0.0', '3303' })
+end

doc/code_snippets/test/checks/checks_table_keys_test.lua

@@ -0,0 +1,25 @@
+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 .. ':' .. port
+end
+--[[
+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
+--]]
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(configure_connection_opts({ ip_address = '0.0.0.0', port = 3303 }), '0.0.0.0:3303')
+    luatest.assert_error_msg_contains('bad argument options.port to nil (number expected, got string)', configure_connection_opts, { ip_address = '0.0.0.0', port = '3303' })
+    luatest.assert_error_msg_contains('unexpected argument options.login to nil', configure_connection_opts, { login = 'testuser', ip_address = '0.0.0.0', port = 3303 })
+end

doc/code_snippets/test/checks/checks_type_combination_test.lua

@@ -0,0 +1,23 @@
+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)
+--]]
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(get_argument_type(1), 'number')
+    luatest.assert_equals(get_argument_type('key1'), 'string')
+    luatest.assert_error_msg_contains('bad argument #1 to nil (number|string expected, got boolean)', get_argument_type, true)
+end

doc/code_snippets/test/checks/checks_vararg_test.lua

@@ -0,0 +1,19 @@
+function extra_arguments_num(a, b, ...)
+    checks('string', 'number')
+    return select('#', ...)
+end
+--[[
+extra_arguments_num('a', 2, 'c')
+-- returns 1
+
+extra_arguments_num('a', 'b', 'c')
+-- raises an error: bad argument #1 to nil (string expected, got number)
+--]]
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(extra_arguments_num('a', 2, 'c'), 1)
+    luatest.assert_error_msg_contains('bad argument #2 to nil (number expected, got string)', extra_arguments_num, 'a', 'b', 'c')
+end