Module checks

Since: 2.11.0

The checks module provides the ability to check the types of arguments passed to a Lua function. You need to call the checks(type_1, ...) function inside the target Lua function and pass one or more type qualifiers to check the corresponding argument types. There are two types of type qualifiers:

• A string type qualifier checks whether a function's argument conforms to the specified type. Example: 'string'.
• A table type qualifier checks whether the values of a table passed as an argument conform to the specified types. Example: { 'string', 'number' }.

In Tarantool 2.11.0 and later versions, the checks API is available in a script without loading the module.

For earlier versions, you need to install the checks module from the Tarantool rocks repository and load the module using the require() directive:

 
local checks = require('checks')

For each argument to check, you need to specify its own type qualifier in the checks(type_1, ...) function.

In the example below, the checks function accepts a string type qualifier to verify that only a string value can be passed to the greet function. Otherwise, an error is raised.

To check the types of several arguments, you need to pass the corresponding type qualifiers to the checks function. In the example below, both arguments should be string values.

To skip checking specific arguments, use the ? placeholder.

You can check the types of explicitly specified arguments for functions that accept a variable number of arguments.

This section describes how to check a specific argument type using a string type qualifier:

• The Supported types section describes all the types supported by the checks module.
• If required, you can make a union type to allow an argument to accept several types.
• You can make any of the supported types optional.
• To skip checking specific arguments, use the ? placeholder.

A string type qualifier can accept any of the Lua types, for example, string, number, table, or nil. In the example below, the checks function accepts string to validate that only a string value can be passed to the greet function.

You can use Tarantool-specific types in a string qualifier. The example below shows how to check that a function argument is a decimal value.

This table lists all the checks available for Tarantool types:

A string type qualifier can accept the name of a custom function that performs arbitrary validations. To achieve this, create a function returning true if the value is valid and add this function to the checkers table.

The example below shows how to use the positive function to check that an argument value is a positive number.

A string qualifier can accept a value stored in the __type field of the argument metatable.

To allow an argument to accept several types (a union type), concatenate type names with a pipe (|). In the example below, the argument can be both a number and string value.

To make any of the supported types optional, prefix its name with a question mark (?). In the example below, the name argument is optional. This means that the greet function can accept string and nil values.

As for a specific type, you can make a union type value optional: ?number|string.

You can skip checking of the specified arguments using the question mark (?) placeholder. In this case, the argument can be any type.

A table type qualifier checks whether the values of a table passed as an argument conform to the specified types. In this case, the following checks are made:

• The argument is checked to conform to the ?table type, and its content is validated.
• Table values are validated against the specified string type qualifiers.
• Table keys missing in checks are validated against the nil type.

The code below checks that the first and second table values have the string and number types.

In the next example, the same checks are made for the specified keys.

When called inside a function, checks that the function's arguments conform to the specified types.

Parameters:

• type_1 (string/table) — a string or table type qualifier used to check the argument type

• ... — optional type qualifiers used to check the types of other arguments

The checkers global variable provides access to checkers for different types. You can use this variable to add a custom checker that performs arbitrary validations.

checkers.uuid_str(value)

Check whether the specified value is uuid represented by a 36-byte hexadecimal string.

• value (any) — the value to check the type for

Returns

true if the specified value is uuid represented by a 36-byte hexadecimal string; otherwise, false

Return type

boolean

See also: uuid(value)