Module:ServicesData: Difference between revisions

From Against the Storm Official Wiki
(Created to manage services data)
 
(adding method to get the service good ID for a service)
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
---
---@module ServicesData
--- Module for compiling services recipes information from wiki data sources.
local ServicesData = {}
--- 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:
---
--- goodID = ServicesRecipesData.getServiceGoodID(serviceName)
---
--- This will return the ID of the good that is used to satisfy the service
--- need. It is preferable to call getter methods with the ID of the service
--- rather than retrieving the entire record for the recipe, so that your code
--- stays protected from variations in this module.
---
--- * serviceID = ServicesRecipesData.getServiceRecipeID(serviceName)
--- * gradeStars = ServicesRecipesData.getServiceRecipeGrade(serviceName)
--- * goodID = ServicesRecipesData.getServiceGoodID(serviceName)
---
--- The most specific way of retrieving data that does not return a table is
--- the preferred way of retrieving the data, because it is the most protected
--- from changes in this module.
---
--- As a last resort, you may use methods that begin with "getAll..." that
--- return tables of data (that is, other than the ones that get lists of
--- recipeIDs), but as mentioned they are less preferable, because the internal
--- workings of this module may change, and these tables may suddenly change
--- their structure, ruining your code. When in doubt, take the extra time to
--- write code that uses one of the specific getter methods (that begin with
--- "getRecipe...").
---
--- The data table for these services recipes has the following structure:
---
--- recipesTable = {
--- ["recipe1_ID"] = {
--- ["id"] = "recipe1_ID",
--- ["gradeID"] = 1,
--- ["serviceNeed"] = "Education"
--- ["serviceGoods"] = {
--- [1] = {
--- ["goodID"] = "good1_ID",
--- ["stackSize"] = 1
--- },
--- [2] = { ... } or missing if fewer
--- }
--- },
--- ["recipe2_ID"] = {
--- ...
--- },
--- ["recipe3_ID"] = {
--- ...
--- },
--- ...
--- }
---
--- @module ServicesRecipesData
local ServicesRecipesData = {}
 




local CsvUtils = require("Module:CsvUtils")
--region Private member variables
--- Main data tables, like this:  table[recipeID] = table containing recipe
--- data
local recipesTable
--- Lookup map. Built once and reused on subsequent calls within this session,
--- like this:  table[serviceName] = { recipeID, recipeID, ... }
local mapNamesToIDs
--- Lookup map. Built once and reused on subsequent calls within this session,
--- like this:  table[goodID] = { serviceNeed1, serviceNeed2, ... }
local mapGoodIDsToRecipeIDs
--endregion
--region Private constants
local DATA_TEMPLATE_NAME = "Template:Institutions_Recipes_csv"
local INDEX_ID = "id"
local INDEX_GRADE = "gradeID"
local INDEX_SERVICE_NAME = "serviceNeed"
local INDEX_GOODS = "serviceGoods"
local INDEX_GOODS_GOOD_ID = "goodID"
local INDEX_GOODS_STACK_SIZE = "stackSize"
local PATTERN_SPLIT_STACK_AND_ID = "(%d+)%s([%[%]%s%a]+)"
local PATTERN_CAPTURE_END_NUMBER = "Grade(%d)"
--endregion
--region Private methods
---
--- Transforms the originalRecipesTable returned from CSV processing to be more
--- conducive to member functions looking up data. Converts text strings
--- into subtables. Converts header row into field keys on every record and
--- stores records by id rather than arbitrary integer.
---
--- @param originalRecipesTable table of CSV-based data, with header row, data rows
--- @param recipesHeaderLookup table lookup table of headers to get indexes
--- @return table better structured with IDs as keys
local function restructureRecipesTable(originalRecipesTable, recipesHeaderLookup)
-- A few constants we'll need only within this function.
local DATA_ROWS = 2
local INDEX_ORIGINAL_ID = 1
local INDEX_ORIGINAL_GRADE = 2
local INDEX_ORIGINAL_SERVED_NEED = 3
local MAX_SERVICES_GOODS = 6
local LOOKUP_SERVICE_GOODS_BASE_STRING = "Good"
mapNamesToIDs = {}
mapGoodIDsToRecipeIDs = {}
local newRecipeTable = {}
for _, originalRecipe in ipairs(originalRecipesTable[DATA_ROWS]) do
local newRecipe = {}
newRecipe[INDEX_ID] = originalRecipe[INDEX_ORIGINAL_ID]
newRecipe[INDEX_GRADE] = originalRecipe[INDEX_ORIGINAL_GRADE]:match(PATTERN_CAPTURE_END_NUMBER)
newRecipe[INDEX_SERVICE_NAME] = originalRecipe[INDEX_ORIGINAL_SERVED_NEED]
local serviceGoods = {}
for i = 1, MAX_SERVICES_GOODS do
local goodIndex = recipesHeaderLookup[LOOKUP_SERVICE_GOODS_BASE_STRING .. i]
local stackSize, goodID = originalRecipe[goodIndex]:match(PATTERN_SPLIT_STACK_AND_ID)
if not goodID then
break
end
local newGood = {
[INDEX_GOODS_GOOD_ID] = goodID,
[INDEX_GOODS_STACK_SIZE] = stackSize
}
table.insert(serviceGoods, newGood)
-- Populate the lookup map for goods.
if not mapGoodIDsToRecipeIDs[goodID] then
mapGoodIDsToRecipeIDs[goodID] = {}
end
table.insert(mapGoodIDsToRecipeIDs[goodID], newRecipe[INDEX_ID])
end
newRecipe[INDEX_GOODS] = serviceGoods
-- Populate the lookup map for services.
if not mapNamesToIDs[ newRecipe[INDEX_SERVICE_NAME] ] then
mapNamesToIDs[ newRecipe[INDEX_SERVICE_NAME] ] = {}
end
table.insert( mapNamesToIDs[ newRecipe[INDEX_SERVICE_NAME] ], newRecipe[INDEX_ID])
newRecipeTable[ newRecipe[INDEX_ID] ] = newRecipe
end
return newRecipeTable
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.
local originalRecipesTable, recipesHeaderLookup = CsvUtils.extractTables(DATA_TEMPLATE_NAME)
-- Now restructure to be more conducive.
recipesTable = restructureRecipesTable(originalRecipesTable, recipesHeaderLookup)
end


--region Dependencies
local InstitutionsData = require("Module:InstitutionsData")
--endregion
--endregion


Line 190: Line 12:
--region Public methods
--region Public methods


---@public
---Gets the icon filename associated with the specified service.
---
---
--- Returns the whole table of data for the specified recipe. Instead of this,
---@param name string service
--- you should probably be calling the individual getter methods.
---@return string icon filename
---
function ServicesData.getIcon(name)
--- Throws an error if called with a nil or empty string. Returns nil if the
    return "Icon_Need_" .. name .. ".png"
--- specified recipe cannot be found.
---
---@param recipeID string the ID of the recipe
---@return table containing the data for the specified recipe, or nil if not found
function ServicesRecipesData.getAllDataForRecipeByID(recipeID)
 
-- At runtime, this should never be nil or empty.
if not recipeID or recipeID == "" then
error("Parameter is nil or empty for recipe ID.")
end
 
if not recipesTable then
loadData()
end
 
return recipesTable[recipeID]
end
 
 
 
---
--- Retrieve all IDs for recipes for the specified service.
---
--- @param serviceName string the name of the service
--- @return table the recipes that result in the product
function ServicesRecipesData.getAllRecipeIDsForServiceName(serviceName)
 
-- At runtime, this should never be nil or empty.
if not serviceName or serviceName == "" then
error("Parameter is nil or empty for product ID.")
end
 
if not recipesTable then
loadData()
end
 
return mapNamesToIDs[serviceName]
end
end


 
---@public
 
---Gets the ID for the specified service
---
---
--- Retrieves all IDs for recipes for which the specified good is necessary.
---@param name string service
---
---@return string ID
--- @param goodID string the ID of the ingredient (good)
function ServicesData.getID(name)
--- @return table the recipes that could use that ingredient
    --Yep, IDs are just names right now.
function ServicesRecipesData.getAllRecipeIDsWithServiceGoodID(goodID)
    return name
 
-- At runtime, this should never be nil or empty.
if not goodID or goodID == "" then
error("Parameter is nil or empty for ingredient ID.")
end
 
if not recipesTable then
loadData()
end
 
return mapGoodIDsToRecipeIDs[goodID]
end
 
 
 
---
--- Retrieves the grade code for the recipe specified by its ID.
---
--- Returns nil if the recipe ID was not found.
---
---@param recipeID string the ID of the recipe
---@return string the code of the grade.
function ServicesRecipesData.getRecipeGradeByID(recipeID)
 
local recipe = ServicesRecipesData.getAllDataForRecipeByID(recipeID)
 
if not recipe then
return nil
end
 
return recipe[INDEX_GRADE]
end
end


function ServicesData.getServiceGoodID(name)


 
    local recipeList = InstitutionsData:getIDsAndRecipesWhereProductID(ServicesData.getID(name))
---
    if #recipeList > 0 then
--- Retrieves the service name for the recipe specified by its ID.
        --Just need one.
---
        local recipe = recipeList[1]
--- Returns nil if the recipe ID was not found.
        --Just the first slot, first option.
---
        return InstitutionsData:getRecipeIngredientOptionIDAt(recipe, 1, 1)
---@param recipeID string the ID of the recipe
    else
---@return string the ID of the good produced by the recipe
        return nil
function ServicesRecipesData.getRecipeServiceNameByID(recipeID)
    end
 
local recipe = ServicesRecipesData.getAllDataForRecipeByID(recipeID)
 
if not recipe then
return nil
end
 
return recipe[INDEX_SERVICE_NAME]
end
 
 
 
---
--- Retrieves the subtable of data for ingredients for the recipe specified by
--- its ID.
---
--- Returns nil if the recipe ID was not found.
---
---@param recipeID string the ID of the recipe
---@return table of good IDs and stack sizes
function ServicesRecipesData.getAllRecipeServiceGoodsByID(recipeID)
 
local recipe = ServicesRecipesData.getAllDataForRecipeByID(recipeID)
 
if not recipe then
return nil
end
 
return recipe[INDEX_GOODS]
end
 
 
 
---
--- Retrieves the specified service goods for the recipe specified by its ID.
---
--- Returns nil if the recipe ID was not found.
---
---@param recipeID string the ID of the recipe
---@param goodIndex number which ingredient to retrieve
---@return string the ID of the good that is the specified option, or nil if none
---@return number the stack size of that good, or nil if none
function ServicesRecipesData.getRecipeOptionByID(recipeID, goodIndex)
 
local recipe = ServicesRecipesData.getAllDataForRecipeByID(recipeID)
 
if not recipe then
return nil
end
 
local goods = ServicesRecipesData.getAllRecipeServiceGoodsByID(recipeID)
if not goods then
return nil
end
 
local good = goods[goodIndex]
 
return good[INDEX_GOODS_GOOD_ID], good[INDEX_GOODS_STACK_SIZE]
end
end


--endregion
--endregion


return ServicesRecipesData
return ServicesData

Latest revision as of 15:35, 11 November 2024

Documentation for this module may be created at Module:ServicesData/doc 

---@module ServicesData
local ServicesData = {}



--region Dependencies
local InstitutionsData = require("Module:InstitutionsData")
--endregion



--region Public methods

---@public
---Gets the icon filename associated with the specified service.
---
---@param name string service
---@return string icon filename
function ServicesData.getIcon(name)
    return "Icon_Need_" .. name .. ".png"
end

---@public
---Gets the ID for the specified service
---
---@param name string service
---@return string ID
function ServicesData.getID(name)
    --Yep, IDs are just names right now.
    return name
end

function ServicesData.getServiceGoodID(name)

    local recipeList = InstitutionsData:getIDsAndRecipesWhereProductID(ServicesData.getID(name))
    if #recipeList > 0 then
        --Just need one.
        local recipe = recipeList[1]
        --Just the first slot, first option.
        return InstitutionsData:getRecipeIngredientOptionIDAt(recipe, 1, 1)
    else
        return nil
    end
end

--endregion

return ServicesData
Retrieved from "https://hoodedhorse.com/wiki/Against_the_Storm/index.php?title=Module:ServicesData&oldid=9479"