From b5bfc30d0b6d47f331c34f00aa9c4b5db7d1a74b Mon Sep 17 00:00:00 2001 From: Kazhnuz Date: Wed, 28 Jul 2021 13:42:23 +0200 Subject: [PATCH] chore: start improving doc --- sonic-radiance.love/birb/utils/datas.lua | 39 +++++++++++++++++++++++- sonic-radiance.love/birb/utils/math.lua | 2 +- sonic-radiance.love/birb/utils/table.lua | 30 +++++++++++++++++- 3 files changed, 68 insertions(+), 3 deletions(-) diff --git a/sonic-radiance.love/birb/utils/datas.lua b/sonic-radiance.love/birb/utils/datas.lua index 8bfdf2c..c2d410a 100644 --- a/sonic-radiance.love/birb/utils/datas.lua +++ b/sonic-radiance.love/birb/utils/datas.lua @@ -1,4 +1,4 @@ --- loveutils.datas : simple functions for data manipulation. +--- loveutils.datas : simple functions for data manipulation. --[[ Copyright © 2021 Kazhnuz @@ -26,11 +26,17 @@ local DataUtils = {} local DATADIR = "datas" local GAMEDATADIR = "gamedata" +--- Verify if a name correspond to a lua file +---@param name string the filename you want to test +---@return boolean isLua if the filename finish by .lua function DataUtils.isLuaFile(name) local extension = name:sub(#name - 3, #name) return (extension == ".lua") end +--- Transform a lua filename to a module name +---@param luaFile string the filename you want to transform +---@return boolean moduleName the module name function DataUtils.luaFileToModule(luaFile) if (DataUtils.isLuaFile(luaFile)) then return luaFile:sub(1, #luaFile - 4) @@ -39,6 +45,9 @@ function DataUtils.luaFileToModule(luaFile) end end +--- Transform a list of lua filename to a list of module name +---@param luaFileList table the filename list you want to transform +---@return table moduleList the module name list function DataUtils.luaFileListToModuleList(luaFileList) local moduleList = {} for i,luaFile in ipairs(luaFileList) do @@ -47,10 +56,18 @@ function DataUtils.luaFileListToModuleList(luaFileList) return moduleList end +--- Use "require" on a a composited filename +---@param parent string the parent filename +---@param filename string the filename of the file +---@return any data the content of the lua file function DataUtils.require(parent, filename) return require(DataUtils.concatFolder(parent, filename, true)) end +--- Require and copy the content of a lua file +--- It's mostly used for lua file containing data, for not having to copy their data +---@param filepath string the filepath of the file +---@return table data the copied content of the lua file function DataUtils.copy(filepath) local orig = require(filepath) local orig_type = type(orig) @@ -67,6 +84,11 @@ function DataUtils.copy(filepath) end +--- Require and copy the content of a lua file from it's parent folder +--- It's mostly used for lua file containing data, for not having to copy their data +---@param parent string the path of the parent +---@param filename string the filename of the file +---@return table data the copied content of the lua file function DataUtils.copyDataset(parent, filename) local orig = DataUtils.require(parent, filename) local orig_type = type(orig) @@ -82,18 +104,33 @@ function DataUtils.copyDataset(parent, filename) return copy end +--- Get a data directory path from the gamedata dir +---@param folder string the folder name +---@param lua boolean if we are dealing with lua modules +---@return string path the data directory path function DataUtils.concatDataFolder(folder, lua) return DataUtils.concatFolder(DataUtils.getGameDataDir(lua), folder, lua) end +--- Get the game data directory +---@param lua boolean if we are dealing with lua modules +---@return string path the gamedirectory path function DataUtils.getGameDataDir(lua) return DataUtils.concatFolder(DATADIR, GAMEDATADIR, lua) end +--- Concat a folder path +---@param parent string the path of the parent folder +---@param filename string the name of the element you want to concat to the path +---@param lua boolean if we are dealing with lua modules +---@return string path the path function DataUtils.concatFolder(parent, filename, lua) return parent .. DataUtils.sep(lua) .. filename end +--- Return the separater character for lua modules or filesystem pathname +---@param lua boolean if we are dealing with lua modules +---@return string sep the separator function DataUtils.sep(lua) if (lua) then return "." diff --git a/sonic-radiance.love/birb/utils/math.lua b/sonic-radiance.love/birb/utils/math.lua index 0cf8e15..47ded13 100644 --- a/sonic-radiance.love/birb/utils/math.lua +++ b/sonic-radiance.love/birb/utils/math.lua @@ -1,4 +1,4 @@ --- loveutils.math : easy to use functions for mathematics and geometry. +--- loveutils.math : easy to use functions for mathematics and geometry. --[[ Copyright © 2019 Kazhnuz diff --git a/sonic-radiance.love/birb/utils/table.lua b/sonic-radiance.love/birb/utils/table.lua index 2283617..4b1cfe3 100644 --- a/sonic-radiance.love/birb/utils/table.lua +++ b/sonic-radiance.love/birb/utils/table.lua @@ -23,6 +23,10 @@ local Table = {} +--- Get the sum of a liste of number +---@param table table the table which you want to find if it contain the content +---@param content any the content that you want to find in the table +---@return boolean contain if the table contain the content function Table.contain(table, content) for k, v in ipairs(table) do if (v == content) then @@ -32,6 +36,9 @@ function Table.contain(table, content) return false end +--- Get the table in form of a string +---@param table table the table which you want to transform into a string +---@return string string the string created from the table function Table.toString(table) local string = "{" for key, value in pairs(table) do @@ -52,6 +59,9 @@ function Table.toString(table) return string .. "}" end +--- Clone a table +---@param table1 table the table to clone +---@return table returnTable the cloned table function Table.clone(table1) local returnTable = {} for key, value in pairs(table1) do @@ -60,6 +70,10 @@ function Table.clone(table1) return returnTable end +--- Merge two list +---@param table1 table the first list to merge +---@param table2 table the list that you want to merge to the first +---@return table table1 the first list, merged with the second function Table.mergeList(table1, table2) for i, value in ipairs(table2) do table.insert(table1, value) @@ -67,6 +81,10 @@ function Table.mergeList(table1, table2) return table1 end +--- Merge two table +---@param table1 table the first table to merge +---@param table2 table the table that you want to merge to the first +---@return table table1 the first table, merged with the second function Table.merge(table1, table2) for key, value in pairs(table2) do table1[key] = value @@ -74,6 +92,10 @@ function Table.merge(table1, table2) return table1 end +--- Reduce a list with a function +---@param list table the list you want to reduce +---@param fn function a function to apply to the whole list. Args: the first reduced list & the current value +---@return any acc the result of the reducing function Table.reduce(list, fn) local acc for k, v in ipairs(list) do @@ -86,6 +108,9 @@ function Table.reduce(list, fn) return acc end +--- Get the sum of a liste of number +---@param table table the list to parse into an sum +---@return number sum the sum of the table function Table.sum(table) local sum = 0 for _, v in pairs(table) do @@ -95,11 +120,14 @@ function Table.sum(table) return sum end +--- Get the average of a liste of number +---@param table table the list to parse into an average +---@return number average the average of the table function Table.average(table) return Table.sum(table) / #table end ---Parse a basic list into a structured table. Return an error if the number of arguments is not the same +--- Parse a basic list into a structured table. Return an error if the number of arguments is not the same ---@param table table the list to parse into a table ---@param structure table the structure to create the table : each name correspond to an attribute of the parsed table ---@param nullableNbr integer the number of nullable argument (at the end of the functions) (can be null)