From da97890e0caa3554f5076fdab54babe4dbc18e23 Mon Sep 17 00:00:00 2001 From: Starbeamrainbowlabs Date: Tue, 17 Sep 2024 22:13:01 +0100 Subject: [PATCH] Make weac.table* appear in API docs --- .../utils/table/deepcopy.lua | 2 ++ worldeditadditions_core/utils/table/init.lua | 3 ++- .../utils/table/makeset.lua | 5 ++++ .../utils/table/shallowcopy.lua | 3 +++ .../utils/table/table_apply.lua | 7 +++-- .../utils/table/table_contains.lua | 2 ++ .../utils/table/table_filter.lua | 3 +++ .../utils/table/table_find.lua | 26 +++++++++++++++++++ .../utils/table/table_get_last.lua | 2 ++ .../utils/table/table_map.lua | 3 +++ .../utils/table/table_reduce.lua | 5 ++-- .../utils/table/table_tostring.lua | 3 +++ .../utils/table/table_unique.lua | 5 ++++ .../utils/table/table_unpack.lua | 9 +++++++ 14 files changed, 73 insertions(+), 5 deletions(-) create mode 100644 worldeditadditions_core/utils/table/table_find.lua diff --git a/worldeditadditions_core/utils/table/deepcopy.lua b/worldeditadditions_core/utils/table/deepcopy.lua index 0c7a89a..3353358 100644 --- a/worldeditadditions_core/utils/table/deepcopy.lua +++ b/worldeditadditions_core/utils/table/deepcopy.lua @@ -1,3 +1,5 @@ +--- +-- @module worldeditadditions_core.table -- 4. Supporting recursive structures. diff --git a/worldeditadditions_core/utils/table/init.lua b/worldeditadditions_core/utils/table/init.lua index f09829b..d55c519 100644 --- a/worldeditadditions_core/utils/table/init.lua +++ b/worldeditadditions_core/utils/table/init.lua @@ -4,9 +4,10 @@ -- ██ ██ ██ ██ ██ ██ ██ ██ -- ██ ██ ██ ██████ ███████ ███████ ███████ --- Functions that operate on tables. +--- Functions that operate on tables. -- Lua doesn't exactly come with batteries included, so this is quite an -- extensive collection of functions :P +-- @namespace worldeditadditions_core.table local wea_c = worldeditadditions_core diff --git a/worldeditadditions_core/utils/table/makeset.lua b/worldeditadditions_core/utils/table/makeset.lua index 9fb5910..7d46727 100644 --- a/worldeditadditions_core/utils/table/makeset.lua +++ b/worldeditadditions_core/utils/table/makeset.lua @@ -1,4 +1,9 @@ +--- +-- @module worldeditadditions_core.table + + --- Creates a table that stores data in keys. +-- See also `worldeditadditions_core.Set`. -- @source https://riptutorial.com/lua/example/13407/search-for-an-item-in-a-list -- @param list table The table of values to convert to keys. -- @return table The table of (key => true) pairs. diff --git a/worldeditadditions_core/utils/table/shallowcopy.lua b/worldeditadditions_core/utils/table/shallowcopy.lua index 4434749..d6e1e52 100644 --- a/worldeditadditions_core/utils/table/shallowcopy.lua +++ b/worldeditadditions_core/utils/table/shallowcopy.lua @@ -1,3 +1,6 @@ +--- +-- @module worldeditadditions_core.table + --- Shallow clones a table. -- @source http://lua-users.org/wiki/CopyTable diff --git a/worldeditadditions_core/utils/table/table_apply.lua b/worldeditadditions_core/utils/table/table_apply.lua index 779c1d2..472cea9 100644 --- a/worldeditadditions_core/utils/table/table_apply.lua +++ b/worldeditadditions_core/utils/table/table_apply.lua @@ -1,5 +1,8 @@ ---- SHALLOW ONLY - applies the values in source to overwrite the equivalent keys in target. --- Warning: This function mutates target! +--- +-- @module worldeditadditions_core.table + +--- SHALLOW ONLY - applies the values in source to overwrite the equivalent keys in `target`. +-- Warning: This function mutates `target`! -- @param source table The source to take values from -- @param target table The target to write values to local function table_apply(source, target) diff --git a/worldeditadditions_core/utils/table/table_contains.lua b/worldeditadditions_core/utils/table/table_contains.lua index e69e7cf..71ff075 100644 --- a/worldeditadditions_core/utils/table/table_contains.lua +++ b/worldeditadditions_core/utils/table/table_contains.lua @@ -1,3 +1,5 @@ +--- +-- @module worldeditadditions_core.table --- Looks to see whether a given table contains a given value. -- @param tbl table The table to look in. diff --git a/worldeditadditions_core/utils/table/table_filter.lua b/worldeditadditions_core/utils/table/table_filter.lua index a706904..00f746e 100644 --- a/worldeditadditions_core/utils/table/table_filter.lua +++ b/worldeditadditions_core/utils/table/table_filter.lua @@ -1,3 +1,6 @@ +--- +-- @module worldeditadditions_core.table + --- Filters the items in the given table using the given function. -- The function is executed for each item in the list. If it returns true, the -- item is kept. If it returns false, the item is discarded. diff --git a/worldeditadditions_core/utils/table/table_find.lua b/worldeditadditions_core/utils/table/table_find.lua new file mode 100644 index 0000000..2298303 --- /dev/null +++ b/worldeditadditions_core/utils/table/table_find.lua @@ -0,0 +1,26 @@ +--- +-- @module worldeditadditions_core.table + +--- Finds the first element in the given table that satisfies the given testing function. +-- A port of Javascript's `array.find` to Lua. +-- +-- Uses for .. in ipairs() under-the-hood. +-- +-- @param tbl table The table to search. +-- @param func function The testing function to call on each element. The function should return true/false as to whether the passed value passes the test function. The testing function will be provided with the following arguments: +-- 1. `value` (any): The value being inspected. +-- 2. `i` (number): The index in the table that the value can be found at +-- 3. `tbl` (table): The original table. +-- @return any|nil The first element in the table that satisfies the predicate, or nil if no such element is found. +function table_find(tbl, func) +end + +function table_find(tbl, func) + for i,value in ipairs(tbl) do + if func(value, i, tbl) then + return value + end + end +end + +return table_find \ No newline at end of file diff --git a/worldeditadditions_core/utils/table/table_get_last.lua b/worldeditadditions_core/utils/table/table_get_last.lua index f8caf69..d265897 100644 --- a/worldeditadditions_core/utils/table/table_get_last.lua +++ b/worldeditadditions_core/utils/table/table_get_last.lua @@ -2,6 +2,8 @@ local wea_c = worldeditadditions_core local table_unpack = dofile(wea_c.modpath.."/utils/table/table_unpack.lua") +--- +-- @module worldeditadditions_core.table --- Returns only the last count items in a given numerical table-based list. -- @param tbl table The table to fetch items from. diff --git a/worldeditadditions_core/utils/table/table_map.lua b/worldeditadditions_core/utils/table/table_map.lua index b0f1036..c49441b 100644 --- a/worldeditadditions_core/utils/table/table_map.lua +++ b/worldeditadditions_core/utils/table/table_map.lua @@ -1,3 +1,6 @@ +--- +-- @module worldeditadditions_core.table + --- Executes the given function on every item in the given table. -- Ignores return values that are nil and doesn't insert them into the table. -- @param tbl table The table to operate on. diff --git a/worldeditadditions_core/utils/table/table_reduce.lua b/worldeditadditions_core/utils/table/table_reduce.lua index 3bc0bed..6499e00 100644 --- a/worldeditadditions_core/utils/table/table_reduce.lua +++ b/worldeditadditions_core/utils/table/table_reduce.lua @@ -1,6 +1,7 @@ +--- +-- @module worldeditadditions_core.table - ---- Lua implementation of array.reduce() from Javascript. +--- Lua implementation of `array.reduce()` from Javascript. -- @param tbl The table to iterate over. -- @param func The function to call for every element in tbl. Will be passed the following arguments: accumulator, value, index, table. Of course, the provided function need not take this many arguments. -- @param initial_value The initial value of the accumulator. diff --git a/worldeditadditions_core/utils/table/table_tostring.lua b/worldeditadditions_core/utils/table/table_tostring.lua index da6778e..7ee0bf5 100644 --- a/worldeditadditions_core/utils/table/table_tostring.lua +++ b/worldeditadditions_core/utils/table/table_tostring.lua @@ -1,3 +1,6 @@ +--- +-- @module worldeditadditions_core.table + --- Returns the key value pairs in a table as a single string -- @param tbl table input table -- @param sep string key value seperator diff --git a/worldeditadditions_core/utils/table/table_unique.lua b/worldeditadditions_core/utils/table/table_unique.lua index 8dfc8ac..700f8c9 100644 --- a/worldeditadditions_core/utils/table/table_unique.lua +++ b/worldeditadditions_core/utils/table/table_unique.lua @@ -1,4 +1,9 @@ +--- +-- @module worldeditadditions_core.table + + --- Builds a new table with the elements of the given table appearing at most once. +-- See also `worldeditadditions_core.Set`. -- @param tbl table The table of values to make unique. -- @returns table A new table containing the values of the given table appearing at most once. local function table_unique(tbl) diff --git a/worldeditadditions_core/utils/table/table_unpack.lua b/worldeditadditions_core/utils/table/table_unpack.lua index cc4c643..3261b47 100644 --- a/worldeditadditions_core/utils/table/table_unpack.lua +++ b/worldeditadditions_core/utils/table/table_unpack.lua @@ -1,8 +1,17 @@ +--- +-- @module worldeditadditions_core.table + --- Polyfill for unpack / table.unpack. -- Calls unpack when available, and looks for table.unpack if unpack() isn't -- found. -- This is needed because in Lua 5.1 it's the global unpack(), but in Lua 5.4 -- it's moved to table.unpack(). +-- +-- Important: All unpack calls in WorldEditAdditions **MUST** use this function. +-- @param tbl table The table to unpack +-- @param [offset=0] number The offset at which to start unpacking. +-- @param [count=nil] number The number of items to unpack. Defaults to unpack all remaining items after `offset`. +-- @returns any... The selected items unpacked from the table. local function table_unpack(tbl, offset, count) ---@diagnostic disable-next-line: deprecated if type(unpack) == "function" then