Lua library containing various useful functions and methods

utils.lua

--[[
Lua library containing various useful functions and methods
Copyright (C) 2025 ÐarkbloøM

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
--]]

local file = {}

--- Checks if a file exists.
--- Taken from: https://stackoverflow.com/a/11204889
---@param name string The name of the file.
---@return boolean
function file.exists(name)
  local f = io.open(name, "rb")
  if f then f:close() end
  return f ~= nil
end

--- Reads data from a file and returns a table containing every line.
--- Returns `nil` if the file specified by `name` does not exist.
--- Taken from: https://stackoverflow.com/a/11204889
---@param name string The name of the file.
---@return table|nil
function file.read(name)
  if not file.exists(name) then return nil end
  local lines = {}
  for line in io.lines(name) do table.insert(lines, line) end
  return line
end

_G.file = file

--- Removes trailing whitespaces from start and end of string.
---@param str string The string to trim.
---@return string
function string.trim(str)
  local out, _ = str:gsub("^%s+", ""):gsub("%s+$", "")
  return out
end

--- Splits string into table over specified character.
--- Taken from: https://stackoverflow.com/a/7615129
---@param str string The string to split.
---@param sep string The separator to split the string over.
---@return table
function string.split(str, sep)
  if sep == nil then sep = "%s" end
  local t = {}
  for s in str:gmatch("([^"..sep.."]+)") do table.insert(t, s) end
  return t
end

--- Waits for x seconds.
--- Taken from: http://lua-users.org/wiki/SleepFunction
---@param x number The number of seconds to wait.
_G.sleep = function (x)
  local t0 = os.clock()
  while os.clock() - t0 <= x do end
end

--- Runs `fn` for each element inside of `tbl`.
--- Uses `pairs` for itterating.
---@param tbl any
---@param fn function
table.foreach = function (tbl, fn)
  for k,v in pairs(tbl) do fn(v) end
end

--- Same as `table.foreach` but uses `ipairs` for itterating.
---@param tbl any
---@param fn function
table.foreachi = function (tbl, fn)
  for k,v in ipairs(tbl) do fn(v) end
end

How to use

1. Download the raw file into your project
2. Import it at the top of your program's main file:

require "utils"