Embedded checks

Author: andreyaksenov

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_decimal_test.lua

@@ -0,0 +1,19 @@
+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)
+--]]
+
+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,22 @@
+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)
+--]]
+
+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,19 @@
+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)
+--]]
+
+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,18 @@
+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)
+--]]
+
+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,25 @@
+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)
+--]]
+
+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,18 @@
+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)
+--]]
+
+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_test.lua

@@ -0,0 +1,31 @@
+function configure_connection(options)
+    checks({
+        ip_address = 'string',
+        port = '?number'
+    })
+    local ip_address = options.ip_address or '127.0.0.1'
+    local port = options.port or 3301
+    if port ~= nil then
+        return ip_address..':'..port
+    else
+        return ip_address
+    end
+end
+--[[
+configure_connection({ip_address = '0.0.0.0', port = 3303})
+-- returns '0.0.0.0:3303'
+
+configure_connection({ip_address = '0.0.0.0', port = '3303'})
+-- raises an error: bad argument options.port to nil (?number expected, got string)
+
+configure_connection({login = 'testuser', ip_address = '0.0.0.0'})
+-- raises an error: unexpected argument options.login to nil
+--]]
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_checks = function()
+    luatest.assert_equals(configure_connection({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, {ip_address = '0.0.0.0', port = '3303'})
+    luatest.assert_error_msg_contains('unexpected argument options.login to nil', configure_connection, {login = 'testuser', ip_address = '0.0.0.0'})
+end

doc/code_snippets/test/checks/checks_type_combination_test.lua

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

doc/reference/reference_lua/checks.rst

@@ -0,0 +1,73 @@
+..  checks-module:
+
+Module checks
+=============
+
+**Since:** :doc:`2.11.0 </release/2.11.0>`
+
+
+
+
+
+
+.. _checks_api_reference:
+
+API Reference
+-------------
+
+..  container:: table
+
+    ..  rst-class:: left-align-column-1
+    ..  rst-class:: left-align-column-2
+
+    ..  list-table::
+        :widths: 35 65
+
+        *   -   **Functions**
+            -
+
+        *   -   :ref:`checks <checks-checks>`
+            -   Check argument types
+
+        *   -   **Objects**
+            -
+
+        *   -   :ref:`checkers <checks-checkers>`
+            -   Checkers for different types
+
+
+..  _checks-checks:
+
+checks()
+~~~~~~~~
+
+..  function:: checks(type_specifier, ...)
+
+    When called inside a function, checks that the function's arguments conforms to the specified types.
+
+    :param string/table type_specifier: a type specifier
+
+..  _checks-checkers:
+
+checkers
+~~~~~~~~
+
+..  class:: checkers
+
+    Checkers for different types.
+
+    .. _checks-checkers-datetime:
+
+    .. function:: datetime(object)
+
+        Check whether the specified object has the :doc:`datetime </reference/reference_lua/datetime>` type.
+
+        :param any object: an object to check the type for
+
+        **Example**
+
+        ..  literalinclude:: /code_snippets/test/checks/checkers_test.lua
+            :language: lua
+            :start-after: -- datetime/interval checkers
+            :end-before: -- is_datetime/is_interval = true
+            :dedent:

doc/reference/reference_lua/index.rst

@@ -22,6 +22,7 @@ This reference covers Tarantool's built-in Lua modules.
 
     box
     buffer
+    checks
     clock
     compat
     console