Module:GoodsData: Difference between revisions

Revision as of 21:30, 18 November 2023

Overview

Module for compiling goods (or resources as some call them) information from wiki data sources. Restructures the flat data tables that are produced from CsvUtils to make them more conducive to Lua methods that need to display the information.

Usage

The standard way of using this module is a call like the following:

iconFilename = GoodsData.getGoodIcon(goodName)

This will return a string corresponding to the filename of the good, including the .png extension. It is preferable to call the getter methods with the name of the good rather than retrieving the entire record for the good, so that your code stays protected from any variations in this module. The getter methods are all called with the plain-language name of the good, as spelled in the game.

longDescription = GoodsData.getGoodDescription(goodName)
inventoryCategory = GoodsData.getGoodCategory(goodName)
isEatable = GoodsData.isGoodEatable(goodName)
isBurnable = GoodsData.isGoodBurnable(goodName)
burnSeconds = GoodsData.getGoodBurnTime(goodName)
amberSellValue, amberBuyValue = GoodsData.getGoodValue(goodName)
iconFilename = GoodsData.getGoodIcon(goodName)

As a last resort, or if you need to transform the data structure, you can call the method getAllDataForGood(displayName). This returns a whole record from the data table corresponding to the requested display name.

The data table for goods has the following structure:

goodsTable = {
	["good1_ID"] = {
		["id"] = "good1_ID",
		["displayName"] = "Plain Language Name",
		["description"] = "A long string with some HTML entities too.",
		["category"] = "Inventory category",
		["eatable"] = true or false if food
		["canBeBurned"] = true or false if fuel and sacrifice
		["burningTime"] = 99, number of seconds
		["tradingSellValue"] = 99.99, in amber
		["tradingBuyValue"] = 99.99, in amber
		["iconName"] = "Icon_Resource_filename.png" including PNG extension
	},
	["good2_ID"] = {
		...
	},
	["good3_ID"] = {
		...
	},
	...
}

---
--- Module for compiling goods (or resources as some call them) information
--- from wiki data sources. Restructures the flat data tables that are produced
--- from CsvUtils to make them more conducive to Lua methods that need to
--- display the information.
---
--- The standard way of using this module is a call like the following:
---
--- iconFilename = GoodsData.getGoodIcon(goodName)
---
--- This will return a string corresponding to the filename of the good. It is
--- preferable to call the getter methods with the name of the good rather than
--- retrieving the entire record for the good, so that your code stays
--- protected from any variations in this module. The getter methods are all
--- called with the plain-language name of the good, as spelled in the game.
---
--- * longDescription = GoodsData.getGoodDescription(goodName)
--- * inventoryCategory = GoodsData.getGoodCategory(goodName)
--- * isEatable = GoodsData.isGoodEatable(goodName)
--- * isBurnable = GoodsData.isGoodBurnable(goodName)
--- * burnSeconds = GoodsData.getGoodBurnTime(goodName)
--- * amberSellValue, amberBuyValue = GoodsData.getGoodValue(goodName)
--- * iconFilename = GoodsData.getGoodIcon(goodName)
---
--- As a last resort, or if you need to transform the data structure, you can
--- call the method getAllDataForGood(displayName). This returns a whole record
--- from the data table corresponding to the requested display name.
---
--- The data table for goods has the following structure:
---
--- goodsTable = {
---		["good1_ID"] = {
--- 		["id"] = "good1_ID",
--- 		["displayName"] = "Plain Language Name",
--- 		["description"] = "A long string with some HTML entities too.",
--- 		["category"] = "Inventory category",
--- 		["eatable"] = true or false if food
---			["canBeBurned"] = true or false if fuel and sacrifice
---			["burningTime"] = 99, number of seconds
--- 		["tradingSellValue"] = 99.99, in amber
--- 		["tradingBuyValue"] = 99.99, in amber
--- 		["iconName"] = "Icon_Resource_filename.png" including PNG extension
---		},
--- 	["good2_ID"] = {
---			...
--- 	},
--- 	["good3_ID"] = {
---			...
--- 	},
--- 	...
--- }
---
--- @module GoodsData
local GoodsData = {}



local CsvUtils = require("Module:CsvUtils")



--region Private member variables

--- Main data table, like this: table[ID] = table containing data for that ID.
--- This needs to be indexed by ID because IDs are guaranteed to be unique.
local goodsTable

--- Lookup map. Built once and reused on all subsequent calls within this
--- session, like this: table[displayName] = goodID
local mapNamesToIDs

--endregion



--region Private constants

local DATA_TEMPLATE_NAME = "Template:Goods_csv"

local HEADER_ROW = 1
local DATA_ROWS = 2

local INDEX_ID = "id"
local INDEX_NAME = "displayName"
local INDEX_DESCRIPTION = "description"
local INDEX_CATEGORY = "category"
local INDEX_EATABLE = "eatable"
local INDEX_BURNABLE = "canBeBurned"
local INDEX_BURNTIME = "burningTime"
local INDEX_SELL_VALUE = "tradingSellValue"
local INDEX_BUY_VALUE = "tradingBuyValue"
local INDEX_ICON_FILENAME = "iconName"

--endregion



--region Private methods

---
--- Since the goods information is already flat and well structured, all this has
--- to do is swap out the integer keys for the good IDs and only return the data
--- rows, without the header row.
---
--- @param originalGoodsTable table of CSV-based data, with header row, data rows
--- @return table with new structure with IDs as keys
local function restructureGoodsTable(originalGoodsTable)

	mapNamesToIDs = {}

	local newGoodsTable = {}
	for _, originalGood in ipairs(originalGoodsTable[DATA_ROWS]) do

		-- Copy over the content, mapping unhelpful indexes into headers keys.
		local newGood = {}
		for index, key in pairs(originalGoodsTable[HEADER_ROW]) do

			-- Convert string versions of true/false to actual booleans
			if key == INDEX_EATABLE or key == INDEX_BURNABLE then
				newGood[key] = originalGood[index] == "True"
			else
				-- Append the file extension to the icon filename.
				if key == INDEX_ICON_FILENAME then
					newGood[key] = originalGood[index] .. ".png"
				else
					-- Everything else can be directly copied over.
					newGood[key] = originalGood[index]
				end
			end
		end

		newGoodsTable[newGood[INDEX_ID]] = newGood

		-- Also populate the map for looking up IDs with display names
		mapNamesToIDs[newGood[INDEX_NAME]] = newGood[INDEX_ID]
	end

	return newGoodsTable
end



---
--- Data loader function that uses the utility module and restructures the data
--- to be easier to access for invoking methods and later method calls. This
--- method is automatically called by all public member functions if the main
--- data table has not yet been populated in the current session.
local function loadData()
	
	-- Utility module retrieves the data as basic, flat lua tables. We don't
	-- need to use the header lookup table that's returned with the data table.
	local originalGoodsTable, _ = CsvUtils.extractTables(DATA_TEMPLATE_NAME)
	
	-- Now restructure to be more conducive for data about goods.
	goodsTable = restructureGoodsTable(originalGoodsTable)
end



---
--- Uses the display name, which people are more familiar with, to find the
--- encoded ID of the good. Useful for retrieving good data that is indexed by
--- ID.
---
--- Returns nil if the good with the specified name is not found.
---
--- @param displayName string plain-language name of the good to find
--- @return string ID of the good found, or nil if not found
local function findGoodIDByName(displayName)

	-- At runtime, this should never be nil or empty, so throw an error.
	if not displayName or displayName == "" then
		error("Parameter is nil or empty for the good's name: " .. displayName .. ".")
	end

	if not goodsTable then
		loadData()
	end

	return mapNamesToIDs[displayName]
end

--endregion



--region Public methods

---
--- Retrieve the whole table of data for the specified good. Instead of this,
--- you should probably be calling the individual getter methods.
---
--- Throws an error if called with nil or empty string. Returns nil if the
--- specified good cannot be found.
---
--- @param goodID string the ID of the good
--- @return table containing the data for the specified good with key-value pairs, or nil if not found
function GoodsData.getAllDataForGoodByID(goodID)

	-- At runtime, this should never be nil or empty.
	if not goodID or goodID == "" then
		error("Parameter is nil or empty for the good's ID.")
	end

	if not goodsTable then
		loadData()
	end

	return goodsTable[goodID]
end



---
--- Retrieve the whole table of data for the specified good. Instead of this,
--- you should probably be calling the individual getter methods.
---
--- Throws an error if called with nil or empty string. Returns nil if the
--- specified good cannot be found.
---
--- @param displayName string plain language name of the good
--- @return table containing the data for the specified good with key-value pairs, or nil if not found
function GoodsData.getAllDataForGood(displayName)

	-- At runtime, this should never be nil or empty.
	if not displayName or displayName == "" then
		error("Parameter is nil or empty for the good's name.")
	end

	if not goodsTable then
		loadData()
	end

	local goodID = findGoodIDByName(displayName)
	if not goodID then
		return nil
	end

	return goodsTable[goodID]
end



---
--- Retrieves the ID for the good specified by its plain language display name.
---
--- Returns nil if the good named was not found.
---
---@param displayName string the plain language name of the good
---@return string the good's ID
function GoodsData.getGoodID(displayName)

	local good = GoodsData.getAllDataForGood(displayName)

	if not good then
		return nil
	end

	return good[INDEX_ID]
end



---
--- Retrieves the description for the good specified by its plain language
--- display name.
---
--- Returns nil if the good named was not found.
---
---@param displayName string the plain language name of the good
---@return string the in-game description of the specified good
function GoodsData.getGoodDescription(displayName)

	local good = GoodsData.getAllDataForGood(displayName)

	if not good then
		return nil
	end

	return good[INDEX_DESCRIPTION]
end



---
--- Retrieves the inventory category for the good specified by its plain
--- language display name.
---
--- Returns nil if the good named was not found.
---
---@param displayName string the plain language name of the good
---@return string the category
function GoodsData.getGoodCategory(displayName)

	local good = GoodsData.getAllDataForGood(displayName)

	if not good then
		return nil
	end

	return good[INDEX_CATEGORY]
end



---
--- Retrieves whether the good is eatable, specified by its plain language
--- display name.
---
--- Returns nil if the good named was not found.
---
---@param displayName string the plain language name of the good
---@return boolean true if the good counts as food
function GoodsData.isGoodEatable(displayName)

	local good = GoodsData.getAllDataForGood(displayName)

	if not good then
		return nil
	end

	return good[INDEX_EATABLE]
end



---
--- Retrieves whether the good is burnable, specified by its plain language
--- display name.
---
--- Returns nil if the good named was not found.
---
---@param displayName string the plain language name of the good
---@return boolean true if the good counts as fuel
function GoodsData.isGoodBurnable(displayName)

	local good = GoodsData.getAllDataForGood(displayName)

	if not good then
		return nil
	end

	return good[INDEX_BURNABLE]
end



---
--- Retrieves the burn time for the good specified by its plain language
--- display name.
---
--- Returns nil if the good named was not found.
---
---@param displayName string the plain language name of the good
---@return number of seconds the good burns as fuel
function GoodsData.getGoodBurnTime(displayName)

	local good = GoodsData.getAllDataForGood(displayName)

	if not good then
		return nil
	end

	return good[INDEX_BURNTIME]
end



---
--- Retrieves the trading value for the good specified by its plain language
--- display name.
---
--- Returns nil if the good named was not found.
---
---@param displayName string the plain language name of the good
---@return number of amber the good sells for
---@return number of amber required to buy the good
function GoodsData.getGoodValue(displayName)

	local good = GoodsData.getAllDataForGood(displayName)

	if not good then
		return nil
	end

	return good[INDEX_SELL_VALUE], good[INDEX_BUY_VALUE]
end



---
--- Retrieves the icon filename for the good specified by its plain language
--- display name.
---
--- Returns nil if the good named was not found.
---
---@param displayName string the the plain language name of the good
---@return string the filename of the icon for the specified good
function GoodsData.getGoodIcon(displayName)

	local good = GoodsData.getAllDataForGood(displayName)

	if not good then
		return nil
	end

	return good[INDEX_ICON_FILENAME]
end



---
--- Retrieves the plain-language display name for the good specified by its ID.
---
--- Returns nil if the good named was not found.
---
---@param goodID string the ID of the good
---@return string the plain language name of the good
function GoodsData.getGoodNameByID(goodID)

	local good = GoodsData.getAllDataForGoodByID(goodID)

	if not good then
		return nil
	end

	return good[INDEX_NAME]
end



---
--- Retrieves the icon filename for the good specified by its ID.
---
--- Returns nil if the good named was not found.
---
---@param goodID string the ID of the good
---@return string the filename of the icon for the specified good
function GoodsData.getGoodIconByID(goodID)

	local good = GoodsData.getAllDataForGoodByID(goodID)

	if not good then
		return nil
	end

	return good[INDEX_ICON_FILENAME]
end

--endregion

return GoodsData