From a0bc53af4f29f15bd3c51a1e943cd549fd270bbd Mon Sep 17 00:00:00 2001 From: Doloment Date: Fri, 7 Mar 2025 03:04:02 +0700 Subject: [PATCH] Fix naming, codestyle and few errors; Change Ensure; Use Ensure in Table --- .emmyrc.json | 3 +- mods/API/Ensure/init.lua | 29 +++++-- mods/API/Table/init.lua | 168 +++++++++++++++++++++------------------ 3 files changed, 116 insertions(+), 84 deletions(-) diff --git a/.emmyrc.json b/.emmyrc.json index 0a3599c..1cc8590 100644 --- a/.emmyrc.json +++ b/.emmyrc.json @@ -8,7 +8,8 @@ "diagnostics": { "globals": [ "core", - "table" + "table", + "Ensure" ] }, "runtime": { diff --git a/mods/API/Ensure/init.lua b/mods/API/Ensure/init.lua index 050db28..e6ad95e 100644 --- a/mods/API/Ensure/init.lua +++ b/mods/API/Ensure/init.lua @@ -1,9 +1,26 @@ +local tostring = tostring + +Ensure = {} + --- Validates a function argument's type and throws a descriptive error on mismatch. ---- @param variable any The argument value to type-check ---- @param expected_type string Expected Lua type name (e.g., "number", "table", "string") +--- @param arg any The argument value to type-check +--- @param expectedType string Expected Lua type name (e.g., "number", "table", "string") --- @param n number Argument position in function call (1-based index) ---- @param func string Name of the parent function for error reporting -function ensure_arg_type(variable, expected_type, n, func) - local actual_type = type(variable) - assert(actual_type == expected_type, 'bad argument #%s to \'%s\' (%s expected, got %s)', tostring(n), func, expected_type, actual_type) +--- @param function_name string Name of the parent function for error reporting +function Ensure.argType(arg, expectedType, n, function_name) + local actualType = type(arg) + assert(actualType == expectedType, 'bad argument #%s to \'%s\' (%s expected, got %s)', tostring(n), function_name, expectedType, actualType) end + +--- @param arg any The argument value to type-check +--- @param n number Argument position in function call (1-based index) +--- @param function_name string Name of the parent function for error reporting +function Ensure.argNotNil(arg, n, function_name) + assert(arg ~= nil, 'bad argument #%s to \'%s\' (key cannot be nil)', n, function_name) +end + + +function Ensure.zeroDivision(divider, function_name) + assert(divider ~= 0, 'Division by zero in \'%s\'', function_name) +end + diff --git a/mods/API/Table/init.lua b/mods/API/Table/init.lua index f96062a..fa086ba 100644 --- a/mods/API/Table/init.lua +++ b/mods/API/Table/init.lua @@ -1,12 +1,16 @@ -local table_copy, table_key_value_swap, table_keyof, pairs, ipairs, next, type, assert - = table.copy, table.key_value_swap, table.keyof, pairs, ipairs, next, type, assert +local tableCopy, tableKeyOf, pairs, ipairs, next, type, assert, ensureArgType, ensureArgNotNil + = table.copy, table.keyof, pairs, ipairs, next, type, assert, Ensure.argType, Ensure.argNotNil + +-- While extending Lua's table library, we maintain snake_case naming for standard library +-- functions and arguments to match standard library conventions. The code that is not exposed +-- to the outer scope continues to use our camelCase convention. --- Returns the number of key-value pairs in the table `t`. --- For array-like tables, prefer the # operator. --- @param t table Table to check --- @return number -function table.size(t) - assert(type(t) == 'table', 'bad argument #1 to \'table.size\' (table expected, got ' .. type(t)) +function table.get_size(t) + ensureArgType(t, 'table', 1, 'table.get_size') local size = 0 for _ in pairs(t) do @@ -20,7 +24,7 @@ end --- @param t table Table to check --- @return any[] function table.get_keys(t) - assert(type(t) == 'table', 'bad argument #1 to \'table.get_keys\' (table expected, got ' .. type(t)) + ensureArgType(t, 'table', 1, 'table.get_keys') local keys = {} for key in pairs(t) do @@ -35,7 +39,7 @@ end --- @param value string | number Value to compare against --- @return any[]? function table.get_keys_by_value(t, value) - assert(type(t) == 'table', 'bad argument #1 to \'table.get_keys_by_value\' (table expected, got ' .. type(t)) + ensureArgType(t, 'table', 1, 'table.get_keys_by_value') local found = {} for k, v in pairs(t) do @@ -52,11 +56,11 @@ end --- @param value any Value to compare against --- @return boolean function table.contains(t, value) - assert(type(t) == 'table', 'bad argument #1 to \'table.contains\' (table expected, got ' .. type(t)) - return table_keyof(t, value) ~= nil + ensureArgType(t, 'table', 1, 'table.contains') + return tableKeyOf(t, value) ~= nil end -local table_contains = table.contains +local tableContains = table.contains --- Checks if the table `t` contains the specified key. Returns `true` if the key is found at least once, `false` otherwise. --- Use when you need to check for key, avoiding metamethods intervention. @@ -64,8 +68,8 @@ local table_contains = table.contains --- @param key any Value to compare against --- @return boolean function table.has_key(t, key) - assert(type(t) == 'table','bad argument #1 to \'table.has_key\' (table expected, got ' .. type(t)) - assert(key ~= nil,'bad argument #2 to \'table.has_key\' (key cannot be nil)') + ensureArgType(t, 'table', 1, 'table.has_key') + ensureArgNotNil(key, 2, 'table.has_key') for k in pairs(t) do if k == key then @@ -81,8 +85,8 @@ end --- @param value any Value to compare against --- @return boolean function table.all_equal_to(t, value) - assert(type(t) == 'table', 'bad argument #1 to \'table.all_equal_to\' (table expected, got ' .. type(t)) - assert(value ~= nil,'bad argument #2 to \'table.all_equal_to\' (value cannot be nil)') + ensureArgType(t, 'table', 1, 'table.all_equal_to') + ensureArgNotNil(value, 2, 'table.all_equal_to') for _, v in pairs(t) do if v ~= value then @@ -94,12 +98,12 @@ function table.all_equal_to(t, value) end --- Returns a table with only specified key-value pairs of the table `t`. ---- @param t table | any[] ---- @param keys string[] | number[] +--- @param t table | any[] Original table +--- @param keys string[] | number[] Array of keys --- @return table | any[] function table.pick(t, keys) - assert(type(t) == 'table', 'bad argument #1 to \'table.pick\' (table expected, got ' .. type(t)) - assert(type(keys) == 'table', 'bad argument #2 to \'table.pick\' (table expected, got ' .. type(keys)) + ensureArgType(t, 'table', 1, 'table.pick') + ensureArgType(keys, 'table', 2, 'table.pick') local result = {} for _, k in ipairs(keys) do @@ -110,14 +114,14 @@ function table.pick(t, keys) end --- Returns a `t` table copy with specified key-value pairs omitted. ---- @param t table | any[] ---- @param keys string[] +--- @param t table | any[] Original table +--- @param keys string[] | number[] Array of keys --- @return table | any[] function table.omit(t, keys) - assert(type(t) == 'table', 'bad argument #1 to \'table.exclude\' (table expected, got ' .. type(t)) - assert(type(keys) == 'table', 'bad argument #2 to \'table.exclude\' (table expected, got ' .. type(keys)) + ensureArgType(t, 'table', 1, 'table.omit') + ensureArgType(keys, 'table', 2, 'table.omit') - local result = table_copy(t) + local result = tableCopy(t) for _, k in ipairs(keys) do result[k] = nil end @@ -131,19 +135,19 @@ end --- @param target table | any[] Target table to merge into --- @param source table | any[] Source table to merge from --- @param recursively? boolean Enable recursive merging (default: false) -local function merge_in_place(target, source, recursively) +local function mergeInPlace(target, source, recursively) for key, value in pairs(source) do - local target_val = target[key] - local value_type = type(value) + local targetValue = target[key] + local valueType = type(value) - if target_val == nil then + if targetValue == nil then -- Add new key with deep copy if needed - target[key] = (value_type == 'table') and table_copy(value) or value + target[key] = (valueType == 'table') and tableCopy(value) or value elseif recursively then - local target_val_type = type(target_val) - if target_val_type == 'table' and value_type == 'table' then + local targetValueType = type(targetValue) + if targetValueType == 'table' and valueType == 'table' then -- Recursively merge into existing table - merge_in_place(target_val, value, true) + mergeInPlace(targetValue, value, true) end end end @@ -155,11 +159,11 @@ end --- @param recursively? boolean Enable recursive merging (default: false) --- @return table | any[] function table.merge(t1, t2, recursively) - assert(type(t1) == 'table', 'bad argument #1 to \'table.join\' (table expected, got ' .. type(t1)) - assert(type(t2) == 'table', 'bad argument #2 to \'table.join\' (table expected, got ' .. type(t2)) + ensureArgType(t1, 'table', 1, 'table.merge') + ensureArgType(t2, 'table', 2, 'table.merge') - local result = table_copy(t1) - merge_in_place(result, t2, recursively == true) + local result = tableCopy(t1) + mergeInPlace(result, t2, recursively == true) return result end @@ -168,7 +172,7 @@ end --- @param t any[] Array to check --- @return any[] function table.unique_values(t) - assert(type(t) == 'table', 'bad argument #1 to \'table.unique_values\' (table expected, got ' .. type(t)) + ensureArgType(t, 'table', 1, 'table.unique_values') local seen = {} local result = {} @@ -183,13 +187,11 @@ function table.unique_values(t) return result end - - --- Checks if table contains no elements. Returns `true` if table is empty, `false` otherwise. --- @param t table Table to check --- @return boolean function table.is_empty(t) - assert(type(t) == 'table', 'bad argument #1 to \'table.is_empty\' (table expected, got ' .. type(t)) + ensureArgType(t, 'table', 1, 'table.is_empty') return next(t) == nil end @@ -199,11 +201,11 @@ end --- @param keys string[] Array of keys to look for --- @return boolean function table.has_any_key_from(t, keys) - assert(type(t) == 'table', 'bad argument #1 to \'table.has_any_key_from\' (table expected, got ' .. type(t)) - assert(type(keys) == 'table', 'bad argument #2 to \'table.has_any_key_from\' (table expected, got ' .. type(keys)) + ensureArgType(t, 'table', 1, 'table.has_any_key_from') + ensureArgType(keys, 'table', 2, 'table.has_any_key_from') for key in pairs(t) do - if table_contains(keys, key) then + if tableContains(keys, key) then return true end end @@ -211,14 +213,13 @@ function table.has_any_key_from(t, keys) return false end - --- Deep comparison of two tables. Returns `true` if tables are deeply equal, `false` otherwise. --- @param t1 table | any[] First table --- @param t2 table | any[] Second table --- @return boolean function table.deep_equal(t1, t2) - assert(type(t1) == 'table', 'bad argument #1 to \'table.deep_equal\' (table expected, got ' .. type(t1)) - assert(type(t2) == 'table', 'bad argument #2 to \'table.deep_equal\' (table expected, got ' .. type(t2)) + ensureArgType(t1, 'table', 1, 'table.deep_equal') + ensureArgType(t2, 'table', 2, 'table.deep_equal') -- Check t1's entries for k, v1 in pairs(t1) do @@ -244,28 +245,15 @@ function table.deep_equal(t1, t2) return true end ---- Applies multipliers to corresponding values in the table `t`. Returns a table with resulting values. ---- @param t table Input values ---- @param multiplier_table table Multipliers ---- @return table -function table.multiply_values_with(t, multiplier_table) - assert(type(t) == 'table', 'bad argument #1 to \'table.multiply_values_with\' (table expected, got ' .. type(t)) - assert(type(multiplier_table) == 'table', 'bad argument #2 to \'table.multiply_values_with\' (table expected, got ' .. type(multiplier_table)) - - return table.map(t, function(key, value) - return multiplier_table[key] and value * multiplier_table[key] or value - end) -end - --- Transforms each value in `t` using a callback. --- @param t table | any[] Input table --- @param callback fun(key:string | number, value:any):any Transformation callback --- @return table function table.map(t, callback) - assert(type(t) == 'table', 'bad argument #1 to \'table.map\' (table expected, got ' .. type(t)) - assert(type(callback) == 'function', 'bad argument #2 to \'table.map\' (function expected, got ' .. type(callback)) + ensureArgType(t, 'table', 1, 'table.map') + ensureArgType(callback, 'function', 2, 'table.map') - local result = table_copy(t) + local result = tableCopy(t) for key, value in pairs(t) do result[key] = callback(key, value) end @@ -273,12 +261,27 @@ function table.map(t, callback) return result end +local tableMap = table.map + +--- Applies multipliers to corresponding values in the table `t`. Returns a table with resulting values. +--- @param t table Input values +--- @param multiplier_table table Multipliers +--- @return table +function table.multiply_values_with(t, multiplier_table) + ensureArgType(t, 'table', 1, 'table.multiply_values_with') + ensureArgType(multiplier_table, 'table', 2, 'table.multiply_values_with') + + return tableMap(t, function(key, value) + return multiplier_table[key] and value * multiplier_table[key] or value + end) +end + --- Iterates over each key-value pair in `t`. For every entry calls `callback` with key and value as arguments. --- @param t table | any[] Table to iterate through. --- @param callback fun(key:string | number, value:any) Callback applied to each key-value pair. function table.for_each(t, callback) - assert(type(t) == 'table', 'bad argument #1 to \'table.walk\' (table expected, got ' .. type(t)) - assert(type(callback) == 'function', 'bad argument #2 to \'table.walk\' (function expected, got ' .. type(callback)) + ensureArgType(t, 'table', 1, 'table.for_each') + ensureArgType(callback, 'function', 2, 'table.for_each') for key, value in pairs(t) do callback(key, value) @@ -286,20 +289,19 @@ function table.for_each(t, callback) end - --- Internal helper function for performing arithmetic operations between two tables. Returns resulting table with resulting values. --- Works almost like `table.map`, but while modyfying a copy of `t1` (which is the same in `table.map`), --- iterates through `t2` and therefore uses its key-value pairs. ---- @param t1 table | number[] Base table to modify ---- @param t2 table | number[] Table with values to operate with ---- @param empty_value number Default value for missing keys in `t1` ---- @param op fun(a:number, b:number):number Operation function to apply ---- @return table | number[] -local function operate_values(t1, t2, empty_value, op) - local result = table_copy(t1) +--- @param t1 table | number[] Base table to modify +--- @param t2 table | number[] Table with values to operate with +--- @param emptyValue number Default value for missing keys in `t1` +--- @param operation fun(a:number, b:number):number Operation function to apply +--- @return table | number[] +local function operateValues(t1, t2, emptyValue, operation) + local result = tableCopy(t1) for key, value in pairs(t2) do - local a = t1[key] or empty_value - result[key] = op(a, value) + local a = t1[key] or emptyValue + result[key] = operation(a, value) end return result @@ -311,7 +313,10 @@ end --- @param empty_value? number Default value for missing keys in t1 (default: 0) --- @return table | number[] function table.add_values(t1, t2, empty_value) - return operate_values(t1, t2, empty_value or 0, function(a, b) return a + b end) + ensureArgType(t1, 'table', 1, 'table.add_values') + ensureArgType(t2, 'table', 2, 'table.add_values') + + return operateValues(t1, t2, empty_value or 0, function(a, b) return a + b end) end --- Subtracts t2 values from t1 values with identical keys. Uses `t2` keys. If `t1` lacks a key, uses `empty_value`. @@ -320,7 +325,10 @@ end --- @param empty_value? number Default value for missing keys in `t1` (default: 0) --- @return table | number[] function table.subtract_values(t1, t2, empty_value) - return operate_values(t1, t2, empty_value or 0, function(a, b) return a - b end) + ensureArgType(t1, 'table', 1, 'table.subtract_values') + ensureArgType(t2, 'table', 2, 'table.subtract_values') + + return operateValues(t1, t2, empty_value or 0, function(a, b) return a - b end) end --- Multiplies values with identical keys. Uses `t2` keys. If `t1` lacks a key, uses `empty_value`. @@ -329,7 +337,10 @@ end --- @param empty_value? number Default value for missing keys in `t1` (default: 1) --- @return table | number[] function table.multiply_values(t1, t2, empty_value) - return operate_values(t1, t2, empty_value or 0, function(a, b) return a * b end) + ensureArgType(t1, 'table', 1, 'table.multiply_values') + ensureArgType(t2, 'table', 2, 'table.multiply_values') + + return operateValues(t1, t2, empty_value or 1, function(a, b) return a * b end) end --- Divides `t1` values by `t2` values with identical keys. Uses `t2` keys. If `t1` lacks a key, uses `empty_value`. @@ -338,9 +349,12 @@ end --- @param empty_value? number Default value for missing keys in `t1` (default: 1) --- @return table | number[] function table.divide_values(t1, t2, empty_value) - local op = function(a, b) + ensureArgType(t1, 'table', 1, 'table.add_values') + ensureArgType(t2, 'table', 2, 'table.divide_values') + + local operation = function(a, b) assert(b ~= 0, 'Division by zero in table.div_values') return a / b end - return operate_values(t1, t2, empty_value or 0, op) + return operateValues(t1, t2, empty_value or 1, operation) end