Further improvements for ExpUtil

exp_util/module/include/inspect.lua

@@ -1,3 +1,5 @@
+--- @diagnostic disable
+
 local inspect = {
   _VERSION = "inspect.lua 3.1.0",
   _URL = "http://github.com/kikito/inspect.lua",

exp_util/module/include/package.lua

@@ -17,6 +17,7 @@ package.lifecycle_stage = {
 }
 
 --- Stores the current lifecycle stage we are in, compare values against package.lifecycle_stage
+--- See also: https://forums.factorio.com/viewtopic.php?f=28&t=115622
 package.lifecycle = package.lifecycle_stage.control
 
 return setmetatable({
@@ -25,6 +26,7 @@ return setmetatable({
     on_configuration_changed = function() package.lifecycle = package.lifecycle_stage.config_change end,
     events = {
         -- TODO find a reliable way to set to runtime because currently it will desync if accessed before player joined
+        -- TODO make clusterio optional dependency
         [defines.events.on_player_joined_game] = function() package.lifecycle = package.lifecycle_stage.runtime end,
         [Clustorio.events.on_server_startup] = function() package.lifecycle = package.lifecycle_stage.runtime end,
     },

exp_util/module/include/require.lua

@@ -1,4 +1,5 @@
 -- luacheck:ignore global require
+--- @diagnostic disable
 
 local package = require("modules/exp_util/include/package")
 local loaded = package.loaded

exp_util/module/include/table.lua

@@ -1,16 +1,19 @@
----@diagnostic disable: duplicate-set-field
+--- @diagnostic disable: duplicate-set-field
 -- luacheck:ignore global table
 
 local random = math.random
 local floor = math.floor
 local remove = table.remove
+local unpack = table.unpack
 local tonumber = tonumber
 local pairs = pairs
 local table_size = table_size
 
 --- Adds all keys of the source table to destination table as a shallow copy
--- @tparam table dst The table to insert into
--- @tparam table src The table to insert from
+--- @generic K, V
+--- @param dst table<K, V> Table to insert into
+--- @param src table<K, V> Table to insert from
+--- @return table<K, V> # Table that was passed as the first argument
 function table.merge(dst, src)
     local dst_len = #dst
     for k, v in pairs(src) do
@@ -21,75 +24,70 @@ function table.merge(dst, src)
             dst[k] = v
         end
     end
+
+    return dst
 end
 
---[[-- Much faster method for inserting items into an array
-@tparam table tbl the table that will have the values added to it
-@tparam[opt] number start_index the index at which values will be added, nil means end of the array
-@tparam table values the new values that will be added to the table
-@treturn table the table that was passed as the first argument
-@usage-- Adding 1000 values into the middle of the array
-local tbl = {}
-local values = {}
-for i = 1, 1000 do tbl[i] = i values[i] = i end
-table.insert_array(tbl, 500, values) -- around 0.4ms
-]]
-function table.insert_array(tbl, start_index, values)
-    if not values then
-        values = start_index
+--- Much faster method for inserting items into an array
+--- @generic V
+--- @param dst V[] Array that will have the values added to it
+--- @param start_index number|table|nil Index at which values will be added, nil means end of the array
+--- @param src V[]? Array of values that will be added
+--- @return V[] # Array that was passed as the first argument
+function table.insert_array(dst, start_index, src)
+    if not src then
+        assert(type(start_index) == "table")
+        src = start_index
         start_index = nil
     end
 
     if start_index then
-        local starting_length = #tbl
-        local adding_length = #values
+        local starting_length = #dst
+        local adding_length = #src
         local move_to = start_index + adding_length + 1
         for offset = starting_length - start_index, 0, -1 do
-            tbl[move_to + offset] = tbl[starting_length + offset]
+            dst[move_to + offset] = dst[starting_length + offset]
         end
 
         start_index = start_index - 1
     else
-        start_index = #tbl
+        start_index = #dst
     end
 
-    for offset, item in ipairs(values) do
-        tbl[start_index + offset] = item
+    for offset, item in ipairs(src) do
+        dst[start_index + offset] = item
     end
 
-    return tbl
+    return dst
 end
 
---[[-- Much faster method for inserting keys into a table
-@tparam table tbl the table that will have keys added to it
-@tparam[opt] number start_index the index at which values will be added, nil means end of the array, numbered indexs only
-@tparam table tbl2 the table that may contain both string and numbered keys
-@treturn table the table passed as the first argument
-@usage-- Merging two tables
-local tbl = {}
-local tbl2 = {}
-for i = 1, 100 do tbl[i] = i tbl['_'..i] = i tbl2[i] = i tbl2['__'..i] = i end
-table.insert_table(tbl, 50, tbl2)
-]]
-function table.insert_table(tbl, start_index, tbl2)
-    if not tbl2 then
-        tbl2 = start_index
+--- Much faster method for inserting keys into a table
+--- @generic K, V
+--- @param dst table<K, V> Table that will have keys added to it
+--- @param start_index number|table|nil Index at which values will be added, nil means end of the array, numbered indexes only
+--- @param src table<K, V> ? Table that may contain both string and numbered keys
+--- @return table<K, V>  # Table passed as the first argument
+function table.insert_table(dst, start_index, src)
+    if not src then
+        assert(type(start_index) == "table")
+        src = start_index
         start_index = nil
     end
 
-    table.insert_array(tbl, start_index, tbl2)
-    for key, value in pairs(tbl2) do
+    table.insert_array(dst, start_index, src)
+    for key, value in pairs(src) do
         if not tonumber(key) then
-            tbl[key] = value
+            dst[key] = value
         end
     end
 
-    return tbl
+    return dst
 end
 
---- Searches an array to remove a specific element without an index
--- @tparam table tbl The array to remove the element from
--- @param element The element to search for
+--- Searches a table to remove a specific element without an index
+--- @generic V
+--- @param tbl table<any, V> Table to remove the element from
+--- @param element V Element to remove
 function table.remove_element(tbl, element)
     for k, v in pairs(tbl) do
         if v == element then
@@ -100,22 +98,27 @@ function table.remove_element(tbl, element)
 end
 
 --- Removes an item from an array in O(1) time. Does not guarantee the order of elements.
--- @tparam table tbl The array to remove the element from
--- @tparam number index Must be >= 0. The case where index > #tbl is handled.
+--- @generic V
+--- @param tbl V[] Array to remove the element from
+--- @param index number Must be >= 0. The case where index > #tbl is handled.
+--- @return V? # Element which was removed or nil
 function table.remove_index(tbl, index)
     local count = #tbl
     if index > count then
         return
     end
 
+    local rtn = tbl[count]
     tbl[index] = tbl[count]
     tbl[count] = nil
+    return rtn
 end
 
 --- Return the key which holds this element element
--- @tparam table tbl The table to search
--- @param element The element to find
--- @return The key of the element or nil
+--- @generic K, V
+--- @param tbl table<K, V> Table to search
+--- @param element V Element to find
+--- @return K? # Key of the element or nil
 function table.get_key(tbl, element)
     for k, v in pairs(tbl) do
         if v == element then
@@ -127,9 +130,10 @@ function table.get_key(tbl, element)
 end
 
 --- Checks if the arrayed portion of a table contains an element
--- @tparam table tbl The table to search
--- @param element The element to find
--- @treturn ?number The index of the element or nil
+--- @generic V
+--- @param tbl V[] Table to search
+--- @param element V Element to find
+--- @return number? # Index of the element or nil
 function table.get_index(tbl, element)
     for i = 1, #tbl do
         if tbl[i] == element then
@@ -141,47 +145,48 @@ function table.get_index(tbl, element)
 end
 
 --- Checks if a table contains an element
--- @tparam table tbl The table to search
--- @param e The element to find
--- @treturn boolean True if the element was found
+--- @generic V
+--- @param tbl table<any, V> Table to search
+--- @param element V Element to find
+--- @return boolean # True if the element was found
 function table.contains(tbl, element)
     return table.get_key(tbl, element) and true or false
 end
 
 --- Checks if the arrayed portion of a table contains an element
--- @tparam table tbl The table to search
--- @param e The element to find
--- @treturn boolean True if the element was found
+--- @generic V
+--- @param tbl V[] Table to search
+--- @param element V Element to find
+--- @return boolean # True if the element was found
 function table.array_contains(tbl, element)
     return table.get_index(tbl, element) and true or false
 end
 
---[[-- Extracts certain keys from a table, similar to deconstruction in other languages
-@tparam table tbl table the which contains the keys
-@tparam string ... the names of the keys you want extracted
-@return the keys in the order given
-@usage -- Deconstruction of a required module
-local format_number, distance = table.deconstruct(require('util'), 'format_number', 'distance')
-]]
+--- Extracts certain keys from a table, similar to deconstruction in other languages
+--- @generic K, V
+--- @param tbl table<K, V> Table the which contains the keys
+--- @param ... K Keys to extracted
+--- @return V ... Values in the order given
 function table.deconstruct(tbl, ...)
     local values = {}
-    for _, key in pairs{ ... } do
-        table.insert(values, tbl[key])
+    for index, key in pairs{ ... } do
+        values[index] = tbl[key]
     end
 
-    return table.unpack(values)
+    return unpack(values)
 end
 
 --- Chooses a random entry from a table, can only be used during runtime
--- @tparam table tbl The table to select from
--- @tparam[opt=false] boolean key When true the key will be returned rather than the value
--- @return The selected element from the table
-function table.get_random(tbl, key)
+--- @generic K, V
+--- @param tbl table<K, V> Table to select from
+--- @param rtn_key boolean? True when the key will be returned rather than the value
+--- @return K | V # Selected element from the table
+function table.get_random(tbl, rtn_key)
     local target_index = random(1, table_size(tbl))
     local count = 1
     for k, v in pairs(tbl) do
         if target_index == count then
-            if key then
+            if rtn_key then
                 return k
             else
                 return v
@@ -189,16 +194,18 @@ function table.get_random(tbl, key)
         end
         count = count + 1
     end
+    error("Unreachable")
 end
 
 --- Chooses a random entry from a weighted table, can only be used during runtime
--- @tparam table weighted_table The table of items and their weights
--- @param[opt=1] item_key The index / key of items within each element
--- @param[opt=2] weight_key The index / key of the weights within each element
--- @return The selected element from the table
-function table.get_random_weighted(weighted_table, item_key, weight_index)
+--- @generic V, VK, WK
+--- @param weighted_table table<any, { [VK]: V, [WK]: number }> Table of items and their weights
+--- @param value_key VK? Index / key of value to within each element
+--- @param weight_index WK? Index / key of the weights within each element
+--- @return V # Selected element from the table
+function table.get_random_weighted(weighted_table, value_key, weight_index)
     local total_weight = 0
-    item_key = item_key or 1
+    value_key = value_key or 1
     weight_index = weight_index or 2
 
     for _, w in pairs(weighted_table) do
@@ -210,22 +217,23 @@ function table.get_random_weighted(weighted_table, item_key, weight_index)
     for _, w in pairs(weighted_table) do
         weight_sum = weight_sum + w[weight_index]
         if weight_sum >= index then
-            return w[item_key]
+            return w[value_key]
         end
     end
+    error("Unreachable")
 end
 
 --- Clears all existing entries in a table
--- @tparam table tbl The table to clear
--- @tparam[opt=false] boolean array When true only the array portion of the table is cleared
-function table.clear(t, array)
+--- @param tbl table Table to clear
+--- @param array boolean? True when only the array portion of the table is cleared
+function table.clear(tbl, array)
     if array then
-        for i = 1, #t do
-            t[i] = nil
+        for i = 1, #tbl do
+            tbl[i] = nil
         end
     else
-        for i in pairs(t) do
-            t[i] = nil
+        for i in pairs(tbl) do
+            tbl[i] = nil
         end
     end
 end
@@ -233,36 +241,31 @@ end
 --- Creates a fisher-yates shuffle of a sequential number-indexed table
 -- because this uses math.random, it cannot be used outside of events if no rng is supplied
 -- from: http://www.sdknews.com/cross-platform/corona/tutorial-how-to-shuffle-table-items
--- @tparam table tbl The table to shuffle
--- @tparam[opt=math.random] function rng The function to provide random numbers
-function table.shuffle(t, rng)
+--- @generic K
+--- @param tbl table<K, any> Table to shuffle
+--- @param rng fun(iter: number): K Function to provide random numbers
+function table.shuffle(tbl, rng)
     local rand = rng or math.random
-    local iterations = #t
-    if iterations == 0 then
-        error("Not a sequential table")
-        return
-    end
+    local iterations = assert(#tbl > 0, "Not a sequential table")
     local j
-
     for i = iterations, 2, -1 do
         j = rand(i)
-        t[i], t[j] = t[j], t[i]
+        tbl[i], tbl[j] = tbl[j], tbl[i]
     end
 end
 
 --- Default table comparator sort function.
--- @local
--- @param x one comparator operand
--- @param y the other comparator operand
--- @return true if x logically comes before y in a list, false otherwise
-local function sort_func(x, y) -- sorts tables with mixed index types.
-    local tx = type(x)
-    local ty = type(y)
+--- @param lhs any LHS comparator operand
+--- @param rhs any RHS comparator operand
+--- @return boolean True if lhs logically comes before rhs in a list, false otherwise
+local function sort_func(lhs, rhs) -- sorts tables with mixed index types.
+    local tx = type(lhs)
+    local ty = type(rhs)
     if tx == ty then
-        if type(x) == "string" then
-            return string.lower(x) < string.lower(y)
+        if type(lhs) == "string" then
+            return string.lower(lhs) < string.lower(rhs)
         else
-            return x < y
+            return lhs < rhs
         end
     elseif tx == "number" then
         return true -- only x is a number and goes first
@@ -272,108 +275,103 @@ local function sort_func(x, y) -- sorts tables with mixed index types.
 end
 
 --- Returns a copy of all of the values in the table.
--- @tparam table tbl the to copy the keys from, or an empty table if tbl is nil
--- @tparam[opt] boolean sorted whether to sort the keys (slower) or keep the random order from pairs()
--- @tparam[opt] boolean as_string whether to try and parse the values as strings, or leave them as their existing type
--- @treturn array an array with a copy of all the values in the table
+--- @generic V
+--- @param tbl table<any, V> Table to copy the values from, or an empty table if tbl is nil
+--- @param sorted boolean? True to sort the keys (slower) or keep the random order from pairs()
+--- @param as_string boolean? True to try and parse the values as strings, or leave them as their existing type
+--- @return V[] # Array with a copy of all the values in the table
 function table.get_values(tbl, sorted, as_string)
     if not tbl then return {} end
-    local valueset = {}
+    local value_set = {}
     local n = 0
-    if as_string then -- checking as_string /before/ looping is faster
+    if as_string then -- checking as_string before looping is faster
         for _, v in pairs(tbl) do
             n = n + 1
-            valueset[n] = tostring(v)
+            value_set[n] = tostring(v)
         end
     else
         for _, v in pairs(tbl) do
             n = n + 1
-            valueset[n] = v
+            value_set[n] = v
         end
     end
     if sorted then
-        table.sort(valueset, sort_func)
+        table.sort(value_set, sort_func)
     end
-    return valueset
+    return value_set
 end
 
 --- Returns a copy of all of the keys in the table.
--- @tparam table tbl the to copy the keys from, or an empty table if tbl is nil
--- @tparam[opt] boolean sorted whether to sort the keys (slower) or keep the random order from pairs()
--- @tparam[opt] boolean as_string whether to try and parse the keys as strings, or leave them as their existing type
--- @treturn array an array with a copy of all the keys in the table
+--- @generic K
+--- @param tbl table<K, any> Table to copy the keys from, or an empty table if tbl is nil
+--- @param sorted boolean? True to sort the keys (slower) or keep the random order from pairs()
+--- @param as_string boolean? True to try and parse the keys as strings, or leave them as their existing type
+--- @return K[] # Array with a copy of all the keys in the table
 function table.get_keys(tbl, sorted, as_string)
     if not tbl then return {} end
-    local keyset = {}
+    local key_set = {}
     local n = 0
     if as_string then -- checking as_string /before/ looping is faster
         for k, _ in pairs(tbl) do
             n = n + 1
-            keyset[n] = tostring(k)
+            key_set[n] = tostring(k)
         end
     else
         for k, _ in pairs(tbl) do
             n = n + 1
-            keyset[n] = k
+            key_set[n] = k
         end
     end
     if sorted then
-        table.sort(keyset, sort_func)
+        table.sort(key_set, sort_func)
     end
-    return keyset
+    return key_set
 end
 
 --- Returns the list is a sorted way that would be expected by people (this is by key)
--- @tparam table tbl the table to be sorted
--- @treturn table the sorted table
+--- @generic K, V
+--- @param tbl table<K, V> Table to be sorted
+--- @return table<K, V> # Sorted table
 function table.alphanum_sort(tbl)
     local o = table.get_keys(tbl)
     local function padnum(d)
         local dec, n = string.match(d, "(%.?)0*(.+)")
         return #dec > 0 and ("%.12f"):format(d) or ("%s%03d%s"):format(dec, #n, n)
     end
+
     table.sort(o, function(a, b)
         return tostring(a):gsub("%.?%d+", padnum) .. ("%3d"):format(#b)
             < tostring(b):gsub("%.?%d+", padnum) .. ("%3d"):format(#a)
     end)
+
     local _tbl = {}
     for _, k in pairs(o) do _tbl[k] = tbl[k] end
-
     return _tbl
 end
 
 --- Returns the list is a sorted way that would be expected by people (this is by key) (faster alternative than above)
--- @tparam table tbl the table to be sorted
--- @treturn table the sorted table
+--- @generic K, V
+--- @param tbl table<K, V> Table to be sorted
+--- @return table<K, V> # Sorted table
 function table.key_sort(tbl)
     local o = table.get_keys(tbl, true)
     local _tbl = {}
     for _, k in pairs(o) do _tbl[k] = tbl[k] end
-
     return _tbl
 end
 
---[[
-  Returns the index where t[index] == target.
-  If there is no such index, returns a negative value such that bit32.bnot(value) is
-  the index that the value should be inserted to keep the list ordered.
-  t must be a list in ascending order for the return value to be valid.
-
-  Usage example:
-  local t = {1, 3,5, 7,9}
-  local x = 5
-  local index = table.binary_search(t, x)
-  if index < 0 then
-    game.print("value not found, smallest index where t[index] > x is: " .. bit32.bnot(index))
-  else
-    game.print("value found at index: " .. index)
-  end
-]]
-function table.binary_search(t, target)
+--- Returns the index where t[index] == target.
+-- If there is no such index, returns a negative value such that bit32.bnot(value) is
+-- the index that the value should be inserted to keep the list ordered.
+-- It must be a list in ascending order for the return value to be valid.
+--- @generic V
+--- @param tbl V[] Array to search
+--- @param target V Target to find
+--- @return number # Index the value was at
+function table.binary_search(tbl, target)
     -- For some reason bit32.bnot doesn't return negative numbers so I'm using ~x = -1 - x instead.
-
     local lower = 1
-    local upper = #t
+    local upper = #tbl
 
     if upper == 0 then
         return -2 -- ~1
@@ -381,7 +379,7 @@ function table.binary_search(t, target)
 
     repeat
         local mid = floor((lower + upper) * 0.5)
-        local value = t[mid]
+        local value = tbl[mid]
         if value == target then
             return mid
         elseif value < target then
@@ -394,38 +392,25 @@ function table.binary_search(t, target)
     return -1 - lower -- ~lower
 end
 
--- add table-related functions that exist in base factorio/util to the 'table' table
+-- Add table-related functions that exist in base factorio/util to the 'table' table
 require "util"
 
 --- Similar to serpent.block, returns a string with a pretty representation of a table.
 -- Notice: This method is not appropriate for saving/restoring tables. It is meant to be used by the programmer mainly while debugging a program.
--- @tparam table root tTe table to serialize
--- @tparam table options Options are depth, newline, indent, process
--- depth sets the maximum depth that will be printed out. When the max depth is reached, inspect will stop parsing tables and just return {...}
--- process is a function which allow altering the passed object before transforming it into a string.
--- A typical way to use it would be to remove certain values so that they don't appear at all.
--- return <string> the prettied table
-table.inspect = require "modules.exp_util.include.inspect" --- @dep modules.exp_util.includes.inspect
+table.inspect = require("modules/exp_util/include/inspect").inspect
 
 --- Takes a table and returns the number of entries in the table. (Slower than #table, faster than iterating via pairs)
 table.size = table_size
 
 --- Creates a deepcopy of a table. Metatables and LuaObjects inside the table are shallow copies.
 -- Shallow copies meaning it copies the reference to the object instead of the object itself.
--- @tparam table object The object to copy
--- @treturn table The copied object
 table.deep_copy = table.deepcopy -- added by util
 
 --- Merges multiple tables. Tables later in the list will overwrite entries from tables earlier in the list.
 -- Ex. merge({{1, 2, 3}, {[2] = 0}, {[3] = 0}}) will return {1, 0, 0}
--- @tparam table tables A table of tables to merge
--- @treturn table The merged table
 table.deep_merge = util.merge
 
 --- Determines if two tables are structurally equal.
--- @tparam table tbl1 The first table
--- @tparam table tbl2 The second table
--- @treturn boolean True if the tables are equal
 table.equals = table.compare -- added by util
 
 return table