refactor(api): check.value.empty now accepts multi-checks; docs imp…

…roved.

Signed-off-by: Guennadi Maximov C <[email protected]>

lua/user_api/check/value.lua

@@ -4,7 +4,7 @@ require('user_api.types.user.check')
 ---@diagnostic disable-next-line:missing-fields
 local M = {}
 
--- NOTE: We define `is_nil` first as it's used by the other checkers.
+-- NOTE: We define `is_nil` first as it's used by the other checkers
 --- Checks whether a value is `nil`, i.e. non existant or explicitly set as nil
 --- ---
 --- ## Parameters
@@ -106,7 +106,7 @@ local function type_fun(t)
     end
 end
 
---- Checks whether a value is a string.
+--- Checks whether a value is a string
 --- ---
 --- ## Parameters
 ---
@@ -124,7 +124,7 @@ end
 --- ---
 M.is_str = type_fun('string')
 
---- Checks whether a value is a boolean.
+--- Checks whether a value is a boolean
 --- ---
 --- ## Parameters
 ---
@@ -140,9 +140,9 @@ M.is_str = type_fun('string')
 ---
 --- A boolean value indicating whether the data is a boolean or not.
 --- ---
-
 M.is_bool = type_fun('boolean')
---- Checks whether a value is a function.
+
+--- Checks whether a value is a function
 --- ---
 --- ## Parameters
 ---
@@ -160,7 +160,7 @@ M.is_bool = type_fun('boolean')
 --- ---
 M.is_fun = type_fun('function')
 
---- Checks whether a value is a number.
+--- Checks whether a value is a number
 --- ---
 --- ## Parameters
 ---
@@ -178,7 +178,7 @@ M.is_fun = type_fun('function')
 --- ---
 M.is_num = type_fun('number')
 
---- Checks whether a value is a table.
+--- Checks whether a value is a table
 --- ---
 --- ## Parameters
 ---
@@ -243,22 +243,39 @@ function M.is_int(var, multiple)
     return true
 end
 
---- Returns whether a given string/number/table is "empty", including these scenarios:
---- * Is an empty string (`x == ''`)
---- * Is an integer equal to zero (`x == 0`)
---- * Is an empty table
+--- Returns whether one or more given string/number/table are **empty**
+--- ---
+--- - Scenarios included if `multiple` is `false`:
+---     - Is an empty string (`x == ''`)
+---     - Is an integer equal to zero (`x == 0`)
+---     - Is an empty table (`{}`)
 ---
+--- If `multiple` is `true` apply the above to a table of allowed values
+--- NOTE: **THE FUNCTION IS NOT RECURSIVE**
+--- ---
 --- ## Parameters
---- * `v`: Must be either a string, number or a table.
----        Otherwise you'll get complaints and the function will return `true`
 ---
+--- - `v`: Must be either a string, number or a table.
+--- Otherwise you'll get complaints and the function will return `true`
+---
+--- - `multiple`: Tell the integer you're checking for multiple values. (Default: `false`).
+--- If set to `true`, every element of the table will be checked.
+--- If **any** element is not _empty_, the function automatically returns `false`.
+--- ---
 --- ## Returns
+---
 --- A boolean indicatin whether input data is empty or not.
 --- ---
-function M.empty(v)
+---@param v string|table|number|(string|table|number)[]
+---@param multiple? boolean
+---@return boolean
+function M.empty(v, multiple)
     local is_str = M.is_str
     local is_tbl = M.is_tbl
     local is_num = M.is_num
+    local is_bool = M.is_bool
+
+    multiple = is_bool(multiple) and multiple or false
 
     if is_str(v) then
         return v == ''
@@ -268,10 +285,28 @@ function M.empty(v)
         return v == 0
     end
 
-    if is_tbl(v) then
+    if is_tbl(v) and not multiple then
         return vim.tbl_isempty(v)
     end
 
+    if is_tbl(v) and multiple then
+        if vim.tbl_isempty(v) then
+            vim.notify(
+                '(user_api.check.value.empty): No values to check despite `multiple` being `true`',
+                vim.log.levels.WARN
+            )
+            return true
+        end
+
+        for _, val in next, v do
+            if M.empty(val) then
+                return true
+            end
+        end
+
+        return false
+    end
+
     vim.notify(
         '(user_api.check.value.empty): Value is neither a table, string nor a number',
         vim.log.levels.WARN

lua/user_api/types/user/check.lua

@@ -14,123 +14,148 @@
 
 ---@class User.Check.Value
 --- Checks whether a value is `nil`, i.e. non existant or explicitly set as nil
+--- ---
 --- ## Parameters
 ---
---- * `var`: Any data type to be checked if it's nil.
----          **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
----          Otherwise it will be flagged as non-existant and the function will return `true`
----
---- * `multiple`: Tell the function you're checking for multiple values. (Default: `false`).
----               If set to `true`, every element of the table will be checked.
----               If **any** element doesn't exist or is `nil`, the function automatically returns false
+--- - `var`: Any data type to be checked if it's nil.
+--- **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
+--- Otherwise it will be flagged as non-existant and the function will return `true`
 ---
+--- - `multiple`: Tell the function you're checking for multiple values. (Default: `false`).
+--- If set to `true`, every element of the table will be checked.
+--- If **any** element doesn't exist or is `nil`, the function automatically returns false
+--- ---
 --- ## Return
+---
 --- A boolean value indicating whether the data is `nil` or doesn't exist
 --- ---
 ---@field is_nil ValueFunc
 --- Checks whether a value is a string
+--- ---
 --- ## Parameters
 ---
---- * `var`: Any data type to be checked if it's a string.
----          **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
----          Otherwise it will be flagged as a non-string and the function will return `false`
----
---- * `multiple`: Tell the function you're checking for multiple values. (Default: `false`).
----               If set to `true`, every element of the table will be checked.
----               If **any** element is not a string, the function automatically returns false
+--- - `var`: Any data type to be checked if it's a string.
+--- **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
+--- Otherwise it will be flagged as a non-string and the function will return `false`.
 ---
+--- - `multiple`: Tell the function you're checking for multiple values. (Default: `false`).
+--- If set to `true`, every element of the table will be checked.
+--- If **any** element is not a string, the function automatically returns false.
+--- ---
 --- ## Return
---- A boolean value indicating whether the data is a string or not
+---
+--- A boolean value indicating whether the data is a string or not.
 --- ---
 ---@field is_str ValueFunc
 --- Checks whether a value is a table
+--- ---
 --- ## Parameters
 ---
---- * `var`: Any data type to be checked if it's a table.
----          **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
----          Otherwise it will be flagged as a non-table and the function will return `false`
----
---- * `multiple`: Tell the function you're checking for multiple values. (Default: `false`).
----               If set to `true`, every element of the table will be checked.
----               If **any** element is not a table, the function automatically returns false
+--- - `var`: Any data type to be checked if it's a table.
+--- **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
+--- Otherwise it will be flagged as a non-table and the function will return `false`.
 ---
+--- - `multiple`: Tell the function you're checking for multiple values. (Default: `false`).
+--- If set to `true`, every element of the table will be checked.
+--- If **any** element is not a table, the function automatically returns false.
+--- ---
 --- ## Return
---- A boolean value indicating whether the data is a table or not
+---
+--- A boolean value indicating whether the data is a table or not.
 --- ---
 ---@field is_tbl ValueFunc
 --- Checks whether a value is a number
+--- ---
 --- ## Parameters
 ---
---- * `var`: Any data type to be checked if it's a number.
----          **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
----          Otherwise it will be flagged as a non-number and the function will return `false`
----
---- * `multiple`: Tell the function you're checking for multiple values. (Default: `false`).
----               If set to `true`, every element of the table will be checked.
----               If **any** element is not a number, the function automatically returns false
+--- - `var`: Any data type to be checked if it's a number.
+--- **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
+--- Otherwise it will be flagged as a non-number and the function will return `false`.
 ---
+--- - `multiple`: Tell the function you're checking for multiple values. (Default: `false`).
+--- If set to `true`, every element of the table will be checked.
+--- If **any** element is not a number, the function automatically returns false.
+--- ---
 --- ## Return
---- A boolean value indicating whether the data is a number or not
+---
+--- A boolean value indicating whether the data is a number or not.
 --- ---
 ---@field is_num ValueFunc
 --- Checks whether a value is a function
+--- ---
 --- ## Parameters
 ---
---- * `var`: Any data type to be checked if it's a function.
----          **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
----          Otherwise it will be flagged as a non-function and the function will return `false`
----
---- * `multiple`: Tell the function you're checking for multiple values. (Default: `false`).
----               If set to `true`, every element of the table will be checked.
----               If **any** element is not a function, the function automatically returns false
+--- - `var`: Any data type to be checked if it's a function.
+--- **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
+--- Otherwise it will be flagged as a non-function and the function will return `false`.
 ---
+--- - `multiple`: Tell the function you're checking for multiple values. (Default: `false`).
+--- If set to `true`, every element of the table will be checked.
+--- If **any** element is not a function, the function automatically returns false.
+--- ---
 --- ## Return
---- A boolean value indicating whether the data is a function or not
+---
+--- A boolean value indicating whether the data is a function or not.
 --- ---
 ---@field is_fun ValueFunc
 --- Checks whether a value is a boolean
+--- ---
 --- ## Parameters
 ---
---- * `var`: Any data type to be checked if it's a boolean.
----          **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
----          Otherwise it will be flagged as a non-boolean and the function will return `false`
----
---- * `multiple`: Tell the function you're checking for multiple values. (Default: `false`).
----               If set to `true`, every element of the table will be checked.
----               If **any** element is not a boolean, the function automatically returns false
+--- - `var`: Any data type to be checked if it's a boolean.
+--- **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
+--- Otherwise it will be flagged as a non-boolean and the function will return `false`.
 ---
+--- - `multiple`: Tell the function you're checking for multiple values. (Default: `false`).
+--- If set to `true`, every element of the table will be checked.
+--- If **any** element is not a boolean, the function automatically returns false.
+--- ---
 --- ## Return
---- A boolean value indicating whether the data is a boolean or not
+---
+--- A boolean value indicating whether the data is a boolean or not.
 --- ---
 ---@field is_bool ValueFunc
---- Checks whether a value is an integer i.e. _greater than or equal to `0` and a **whole number**_
+--- Checks whether a value is an integer i.e. _greater than or equal to `0` and a **whole number**_.
+--- ---
 --- ## Parameters
 ---
 --- * `var`: Any data type to be checked if it's an integer.
----          **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
----          Otherwise it will be flagged as a non-integer and the function will return `false`
----
---- * `multiple`: Tell the integer you're checking for multiple values. (Default: `false`).
----               If set to `true`, every element of the table will be checked.
----               If **any** element is not an integer, the function automatically returns false
+--- **Keep in mind that if `multiple` is set to `true`, this _MUST_ be a _non-empty_ table**.
+--- Otherwise it will be flagged as a non-integer and the function will return `false`.
 ---
+--- - `multiple`: Tell the integer you're checking for multiple values. (Default: `false`).
+--- If set to `true`, every element of the table will be checked.
+--- If **any** element is not an integer, the function automatically returns false.
+--- ---
 --- ## Return
---- A boolean value indicating whether the data is an integer or not
+---
+--- A boolean value indicating whether the data is an integer or not.
 --- ---
 ---@field is_int fun(var: any, multiple: boolean?): boolean
---- Returns whether a given string/number/table is "empty", including these scenarios:
---- * Is an empty string (`x == ''`)
---- * Is an integer equal to zero (`x == 0`)
---- * Is an empty table
+--- Returns whether one or more given string/number/table are **empty**
+--- ---
+--- - Scenarios included if `multiple` is `false`:
+---     - Is an empty string (`x == ''`)
+---     - Is an integer equal to zero (`x == 0`)
+---     - Is an empty table (`{}`)
 ---
+--- If `multiple` is `true` apply the above to a table of allowed values
+--- NOTE: **THE FUNCTION IS NOT RECURSIVE**
+--- ---
 --- ## Parameters
---- * `v`: Must be either a string, number or a table.
----        Otherwise you'll get complaints and the function will return `true`
 ---
+--- - `v`: Must be either a string, number or a table.
+--- Otherwise you'll get complaints and the function will return `true`
+---
+--- - `multiple`: Tell the integer you're checking for multiple values. (Default: `false`).
+--- If set to `true`, every element of the table will be checked.
+--- If **any** element is not _empty_, the function automatically returns `false`.
+--- ---
 --- ## Returns
---- A boolean indicatin whether input data is empty or not
+---
+--- A boolean indicatin whether input data is empty or not.
 --- ---
----@field empty fun(v: string|table|number): boolean
+---@field empty fun(v: string|table|number|(string|table|number)[], multiple: boolean?): boolean
 ---@field fields fun(fields: string|integer|(string|integer)[], T: table<string|integer, any>): boolean
 ---@field tbl_values fun(values: any[], T: table, return_keys: boolean?): boolean|string|integer|(string|integer)[]
 ---@field single_type_tbl fun(type_str: Types, T: table): boolean