Merge pull request pioneerspacesim#5773 from Web-eWorks/lua-utils

Misc cleanup, fixes, and Lua function library improvements

data/lang/core/en.json

@@ -1835,6 +1835,10 @@
     "description": "Duration unit: one 7-day week",
     "message": "w"
   },
+  "UNIT_CUBIC_METERS": {
+	"description": "Volume unit: cubic meter",
+	"message": "m³"
+  },
   "UNKNOWN": {
     "description": "",
     "message": "<unknown>"

data/libs/SpaceStation.lua

@@ -2,6 +2,7 @@
 -- Licensed under the terms of the GPL v3. See licenses/GPL-3.txt
 
 ---@class SpaceStation : ModelBody
+---@field techLevel integer
 local SpaceStation = package.core['SpaceStation']
 
 local Economy     = require 'Economy'

data/libs/autoload.lua

@@ -56,9 +56,10 @@ string.interp = function (s, t)
 	end))
 end
 
--- allow using string.interp via "s" % { t }
 ---@class string
 ---@operator mod(table): string
+
+-- allow using string.interp via "s" % { t }
 getmetatable("").__mod = string.interp
 
 -- make a simple shallow copy of the passed-in table
@@ -74,5 +75,39 @@ table.copy = function(t)
 	return ret
 end
 
+-- Copy values from table b into a
+--
+-- Does not copy metatable nor recurse into the table.
+-- Pass an optional predicate to transform the keys and values before assignment.
+---@generic K, V
+---@param a table
+---@param b table<K, V>
+---@param predicate nil|fun(k: K, v: V): any, any
+---@return table
+table.merge = function(a, b, predicate)
+	for k, v in pairs(b) do
+		if predicate then k, v = predicate(k, v) end
+		a[k] = v
+	end
+	return a
+end
+
+-- Append array b to array a
+--
+-- Does not copy metatable nor recurse into the table.
+-- Pass an optional predicate to transform the keys and values before assignment.
+---@generic T
+---@param a table
+---@param b T[]
+---@param predicate nil|fun(v: T): any
+---@return table
+table.append = function(a, b, predicate)
+	for _, v in ipairs(b) do
+		if predicate then v = predicate(v) end
+		table.insert(a, v)
+	end
+	return a
+end
+
 -- make import break. you should never import this file
 return nil

data/libs/utils.lua

@@ -171,6 +171,7 @@ function utils.filter_table(table, predicate)
 	end
 	return t
 end
+
 --
 -- Function: filter_array
 --
@@ -185,12 +186,28 @@ end
 ---@param predicate fun(v: T): boolean
 function utils.filter_array(array, predicate)
 	local t = {}
-	for i, v in ipairs(array) do
+	for _, v in ipairs(array) do
 		if predicate(v) then table.insert(t, v) end
 	end
 	return t
 end
 
+-- Function: to_array
+--
+-- Filters the values of the given table and converts them to an array.
+-- Key iteration order is undefined (uses pairs() internally).
+---@generic K, V
+---@param t table<K, V>
+---@param predicate fun(v: V): boolean
+---@return V[]
+utils.to_array = function(t, predicate)
+	local out = {}
+	for _, v in pairs(t) do
+		if predicate(v) then table.insert(out, v) end
+	end
+	return out
+end
+
 --
 -- Function: stable_sort
 --
@@ -354,8 +371,8 @@ utils.inherits = function (baseClass, name)
 	new_class.meta = { __index = new_class, class=name }
 
 	-- generic constructor
-	function new_class.New(args)
-		local newinst = base_class.New(args)
+	function new_class.New(...)
+		local newinst = base_class.New(...)
 		setmetatable( newinst, new_class.meta )
 		return newinst
 	end
@@ -387,22 +404,74 @@ end
 -- Wrapper for utils.inherits that manages creating new class instances and
 -- calling the constructor.
 --
-utils.class = function (name, baseClass)
-	local new_class = utils.inherits(baseClass, name)
+utils.class = function (name, base_class)
+	base_class = base_class or object
+	local new_class = utils.inherits(base_class, name)
 
 	new_class.New = function(...)
 		local instance = setmetatable( {}, new_class.meta )
 
-		if new_class.Constructor then
-			new_class.Constructor(instance, ...)
-		end
+		new_class.Constructor(instance, ...)
 
 		return instance
 	end
 
+	new_class.Constructor = function(self, ...)
+		if base_class.Constructor then
+			base_class.Constructor(self, ...)
+		end
+	end
+
 	return new_class
 end
 
+local _proto = {}
+
+_proto.__clone = function(self) end
+
+function _proto:clone(mixin)
+	local new = { __index = self }
+	setmetatable(new, new)
+
+	new:__clone()
+
+	if mixin then
+		table.merge(new, mixin)
+	end
+
+	return new
+end
+
+-- Simple Self/iolang style prototype chains
+-- Can be used with lua serialization as long as no functions are set anywhere
+-- but on the base prototype returned from utils.proto
+utils.proto = function(classname)
+	local newProto = _proto:clone()
+
+	newProto.class = classname
+
+	function newProto:Serialize()
+		local out = table.copy(self)
+
+		-- Cannot serialize functions, so references to the base prototype are
+		-- not serialized
+		if out.__index == newProto then
+			out.__index = nil
+		end
+
+		return out
+	end
+
+	-- If a prototype doesn't have a serialized __index field, it referred to
+	-- this base prototype originally
+	function newProto:Unserialize()
+		self.__index = self.__index or newProto
+		return setmetatable(self, self)
+	end
+
+	return newProto
+end
+
 --
 -- Function: print_r
 --
@@ -425,17 +494,20 @@ utils.print_r = function(t)
 			if type(t) == "table" then
 				for key, val in pairs(t) do
 					local string_key = tostring(key)
+					local string_val = tostring(val)
 
-					if type(val) == "table" then
-						write(indent, '[%s] => %s {', string_key, tostring(t))
+					if type(val) == "table" and not print_r_cache[string_val] then
+						write(indent, '[%s] => %s {', string_key, string_val)
 
 						sub_print_r(val, indent + string.len(string_key) + 8)
 
 						write(indent + string.len(string_key) + 6, "}")
+					elseif type(val) == "table" then
+						write(indent, "[%s] => *%s", string_key, string_val)
 					elseif (type(val)=="string") then
-						write(indent, "[%s] => '%s'", string_key, val)
+						write(indent, "[%s] => '%s'", string_key, string_val)
 					else
-						write(indent, "[%s] => %s", string_key, tostring(val))
+						write(indent, "[%s] => %s", string_key, string_val)
 					end
 				end
 			else

data/meta/Color.lua

@@ -0,0 +1,51 @@
+-- Copyright © 2008-2023 Pioneer Developers. See AUTHORS.txt for details
+-- Licensed under the terms of the GPL v3. See licenses/GPL-3.txt
+
+-- This file implements type information about C++ classes for Lua static analysis
+
+---@meta
+
+---@class Color
+---@field r integer
+---@field g integer
+---@field b integer
+---@field a integer
+---
+---@operator add: Color
+---@operator add(number): Color
+---@operator mul: Color
+---@operator mul(number): Color
+---@operator call: Color
+
+---@class Color
+local Color = {}
+
+---@param r number
+---@param g number
+---@param b number
+---@param a number?
+---@return Color
+---@overload fun(hex: string): Color
+function _G.Color(r, g, b, a) end
+
+-- Return a copy of this color darkened by the given amount (in 0.0..1.0)
+-- Use negative values to lighten.
+--
+-- Rturns a new Color object
+---@param s number
+---@return Color
+function Color:shade(s) end
+
+-- Increase the perceptual saturation of this color by some factor (in 0.0..1.0)
+--
+-- Returns a new Color object
+---@param t number
+---@return Color
+function Color:tint(t) end
+
+-- Set the opacity of this color to the passed value (in 0.0..1.0 or 1..255)
+--
+-- Returns a new Color object
+---@param o number
+---@return Color
+function Color:opacity(o) end

data/meta/Rand.lua

@@ -14,16 +14,16 @@ function Rand.New(seed) end
 ---@param min number inclusive minimum value, defaults to 0
 ---@param max number exclusive maximum value, defaults to 1
 ---@return number
----@overload fun(): number
----@overload fun(max: number): number
+---@overload fun(self: self): number
+---@overload fun(self: self, max: number): number
 function Rand:Number(min, max) end
 
 -- Returns a random integer in the range [min, max), exclusive.
 ---@param min integer inclusive minimum value, defaults to 0
 ---@param max integer exclusive maximum value, defaults to 1
 ---@return integer
----@overload fun(): integer
----@overload fun(max: integer): integer
+---@overload fun(self: self): integer
+---@overload fun(self: self, max: integer): integer
 function Rand:Integer(min, max) end
 
 -- Generates a random integer drawn from a Poisson distribution.

data/pigui/baseui.lua

@@ -4,7 +4,9 @@
 local Engine = require 'Engine'
 local pigui = Engine.pigui
 
+---@class ui
 local ui = require 'pigui.libs.forwarded'
+
 ui.rescaleUI = require 'pigui.libs.rescale-ui'
 
 ---@type EventQueue

data/pigui/init.lua

@@ -6,6 +6,7 @@
 -- aren't available later...
 local Player = require 'Player'
 
+---@class ui
 local ui = require 'pigui.baseui'
 
 require 'pigui.libs.text'

data/pigui/libs/buttons.lua

@@ -1,10 +1,12 @@
 -- Copyright © 2008-2024 Pioneer Developers. See AUTHORS.txt for details
 -- Licensed under the terms of the GPL v3. See licenses/GPL-3.txt
 local Engine = require 'Engine'
-local ui = require 'pigui.baseui'
 local pigui = Engine.pigui
 local Vector2 = _G.Vector2
 
+---@class ui
+local ui = require 'pigui.baseui'
+
 --
 -- Function: ui.withButtonColors
 --