Module:GladeResourcesController

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

---@class GladeResourcesController
local GladeResourcesController = {}



--region Dependencies

local GladeResourcesData = require("Module:GladeResourcesData")
local GoodsData = require("Module:GoodsData")
local BiomesData = require("Module:BiomesData")
local BuildingDataProxy = require("Module:BuildingDataProxy")
local DataModelsWithGladeResourcesRecipes = {
    require("Module:MinesData"),
    require("Module:CampsData"),
    require("Module:FishingData"),
    require("Module:GatheringData"),
}

local VIEW_TEMPLATE_START = "Deposit/view"
local VIEW_TEMPLATE_ROW = "Deposit/view/row"
local VIEW_TEMPLATE_END = "Deposit/view/end"

local VIEW_BUILDING_LINK = "Building_link/view"
local VIEW_RESOURCE_LINK = "Resource_link/view"

--endregion



--region Private constants

local VIEW_ARG_HEAD = "heading"
local VIEW_ARG_DESC = "description"
local VIEW_ARG_CAPTION = "caption"
local VIEW_ARG_CHARGES = "charges"
local VIEW_ARG_NUM_DEPOSITS = "numdeposits"
local VIEW_ARG_MAX_BONUSES = "maxbonuses"

local VIEW_ARG_DEPOSIT = "deposit"
local VIEW_ARG_BUILDING = "building"

local VIEW_ARG_PRODUCT = "primary"
local VIEW_ARG_BONUS_1 = "bonus1"
local VIEW_ARG_BONUS_2 = "bonus2"
local VIEW_ARG_BONUS_3 = "bonus3"
local VIEW_ARG_BONUS_4 = "bonus4"

local VIEW_ARG_BIOME_1 = "biome1"
local VIEW_ARG_BIOME_2 = "biome2"
local VIEW_ARG_BIOME_3 = "biome3"
local VIEW_ARG_BIOME_4 = "biome4"
local VIEW_ARG_BIOME_5 = "biome5"
local VIEW_ARG_BIOME_6 = "biome6"
local VIEW_ARG_BIOME_7 = "biome7"
local VIEW_ARG_BIOME_8 = "biome8"

--endregion



--region Localization string constants

local ERROR_MESSAGE_PRODUCT_AND_BONUS_BUT_NOT_MATCH = "When searching for a good as both a main and bonus resource, the parameters must match."
local ERROR_MESSAGE_NO_PARAMETERS_GIVEN = "You must specify the name of a product, a bonus resource, or a building—and as it's spelled in the game."

--endregion



--region Private member variables

local frame

--endregion



--region Private methods


---@private
---Uses the specified building ID to go through applicable data models, assembling a list of possible deposits, filtered by the grade of the building.
---
---@param buildingID string a building's ID
---@return table array of deposit records retrieved from GladeResourcesData
local function assembleDepositsFromBuilding(buildingID)

    local depositsList = {}
    --This isn't as expensive as it looks, because typically only one data model will return something. However, we don't know which it will be in advance.
    for _, dataModel in ipairs(DataModelsWithGladeResourcesRecipes) do

        local recipeDataArray = dataModel:getIDsAndRecipesWhereBuildingID(buildingID)
        if #recipeDataArray > 0 then

            local products = {}
            for _, recipeData in ipairs(recipeDataArray) do
                local id = dataModel:getRecipeProductID(recipeData)
                products[id] = dataModel:getRecipeGrade(recipeData)
            end
            for id, grade in pairs(products) do
                local newList = GladeResourcesData.getAllDepositsWherePrimaryResourceAndGrade(id, grade)
                for _, deposit in ipairs(newList) do
                    table.insert(depositsList, deposit)
                end
            end
        end
    end

    return depositsList
end



---@private
---Looks up the building ID from the building data models for the one that can exploit the given deposit.
---
---@param deposit table record from GladeResourcesData
---@return string, string building display name, icon filename
local function getBuildingForDeposit(deposit)

    local productID = GladeResourcesData.getDepositPrimaryProduct(deposit)

    --This isn't as expensive as it looks, because typically only one data model will return something. However, we don't know which it will be in advance.
    for _, dataModel in ipairs(DataModelsWithGladeResourcesRecipes) do

        local recipeDataArray = dataModel:getIDsAndRecipesWhereProductID(productID)
        if #recipeDataArray > 0 then
            --Just return the first one.
            local id = dataModel:getRecipeBuildingID(recipeDataArray[1])
            local name = dataModel:getName(id)
            local icon = dataModel:getIcon(id)
            return name, icon
        end
    end
    return ""
end



---@private
---Checks whether the provided list of deposits can be harvested by a single building. If so, returns that building's name and icon (for use in a building link). Otherwise, returns nil.
---
---@param depositsList table array of deposit records retrieved from GladeResourcesData
---@return string, string building name and icon, if there is only one, nil if none or more than one
local function checkOnlyOneBuildingForAllDeposits(depositsList)

    local buildings = {}
    for _, deposit in ipairs(depositsList) do
        local name, icon = getBuildingForDeposit(deposit)
        buildings[name] = icon
    end

    local firstBuildingName, firstBuildingIcon = next(buildings)
    if firstBuildingName and not next(buildings, firstBuildingName) then
        return firstBuildingName, firstBuildingIcon
    else
        return nil
    end
end



---@private
---Goes through the provided list of deposits and finds the maximum number of bonuses, so that the view can be standardized.
---
---@param depositsList table array of deposit records retrieved from GladeResourcesData
---@return number maximum bonuses across all in the list
local function countMaxBonusesInList(depositsList)
    local maxFound = 0
    for _, deposit in ipairs(depositsList) do
        local numBonuses = GladeResourcesData.getDepositNumBonusResources(deposit)
        if numBonuses > maxFound then
            maxFound = numBonuses
        end
    end
    return maxFound
end



---@private
---Tallies up the categories and concatenates them. Also makes them plural if there are more than one of a particular category.
---
---@param depositsList table
---@return string the categories among the deposits
local function writeCaptionForDeposits(depositsList)

    local categories = {}
    for _, deposit in ipairs(depositsList) do
        local category = GladeResourcesData.getDepositCategory(deposit)
        if not categories[category] then
            categories[category] = 1
        else
            categories[category] = categories[category] + 1
        end
    end

    local caption = ""
    for category, categoryCount in pairs(categories) do
        if categoryCount > 1 then
            category = category .. "s"
        end
        if caption == "" then
            caption = category
        else
            caption = caption .. " & " .. category
        end
    end

    return caption
end



---@private
---Tallies up the descriptions. If there's exactly one, it returns that description, otherwise it returns blank since they can't be combined (and to save space).
---
---@param depositsList table
---@return string the one or shared description in the list, or "" if they are varied
local function writeDescriptionForDeposits(depositsList)

    --Heuristic: If there are more then 2, then there's no way all the descriptions match.
    if #depositsList > 2 then
        return ""
    end

    local descriptions = {}
    for _, deposit in ipairs(depositsList) do
        local desc = GladeResourcesData.getDepositDescription(deposit)
        descriptions[desc] = true
    end

    --Use exactly one description unless there are more, in which case return empty.
    local firstDescription = next(descriptions)
    if firstDescription and not next(descriptions, firstDescription) then
        return firstDescription
    else
        return ""
    end
end



---@private
---Sets up the view, based on the display override or lack thereof. Returns whatever else needs to be appended to do so.
---
---@param depositsList table list of deposits from GladeResourcesData
---@param maxBonuses number slots for bonus resources
---@param title string title for the whole panel
---@param buildingID string an ID for a building specified, if any
---@param displayOverride string override code, if any
---@return string wiki markup
local function renderViewStart(depositsList, maxBonuses, title, buildingID, displayOverride)

    displayOverride = displayOverride --TODO write the other view modes

    local skipBuildingColumn = ""
    if buildingID then
        skipBuildingColumn = "skip"
    else
        local buildingName = checkOnlyOneBuildingForAllDeposits(depositsList)
        if buildingName then
            skipBuildingColumn = "skip"
        end
    end


    local caption = writeCaptionForDeposits(depositsList)
    local numDeposits = #depositsList

    --Special case where we swap the title out for the name of the one deposit and show the description
    local description = ""
    if numDeposits == 1 then
        title = GladeResourcesData.getDepositName(depositsList[1])
        description = writeDescriptionForDeposits(depositsList)
    end

    local wikiMarkup = frame:expandTemplate{
        title = VIEW_TEMPLATE_START,
        args = {
            [VIEW_ARG_HEAD] = title,
            [VIEW_ARG_DESC] = description,
            [VIEW_ARG_CAPTION] = caption,
            [VIEW_ARG_NUM_DEPOSITS] = numDeposits,
            [VIEW_ARG_MAX_BONUSES] = maxBonuses,
            [VIEW_ARG_BUILDING] = skipBuildingColumn
        },
    }

    return wikiMarkup
end



---@private
-----Converts the data about the product in the specified deposit for the view.
---
---@param deposit table from GladeResourceData
---@param displayOverride string override code, if any
---@return string wiki markup
local function renderProduct(deposit, displayOverride)

    displayOverride = displayOverride --TODO write the other display modes

    local productID, amount = GladeResourcesData.getDepositPrimaryProduct(deposit)
    local iconFilename = GoodsData.getIcon(productID)
    local productName = GoodsData.getName(productID)

    local wikiMarkup = ""
    if amount > 1 then
        wikiMarkup = wikiMarkup .. "''" .. amount .. "'' "
    end

    wikiMarkup = wikiMarkup .. frame:expandTemplate{
        title = VIEW_RESOURCE_LINK,
        args = {
            ["iconsize"] = "medium",
            ["iconfilename"] = iconFilename,
            ["name"] = productName,
            ["display"] = "notext",
        }
    }

    return wikiMarkup
end



---@private
-----Converts the data about the specified bonus in the specified deposit for the view.
---
---@param deposit table from GladeResourceData
---@param index number which bonus from deposit to get
---@param displayOverride string override code, if any
---@return string wiki markup
local function renderBonus(deposit, index, displayOverride)

    displayOverride = displayOverride --TODO write the other display modes

    local productID, amount, chance = GladeResourcesData.getDepositBonusResourceAt(deposit, index)

    if not productID then
        return ""
    end

    local iconFilename = GoodsData.getIcon(productID)
    local productName = GoodsData.getName(productID)

    local wikiMarkup = ""
    if amount and amount > 1 then
        wikiMarkup = wikiMarkup .. "'''" .. amount .. "''' "
    end

    wikiMarkup = wikiMarkup .. frame:expandTemplate{
        title = VIEW_RESOURCE_LINK,
        args = {
            ["iconsize"] = "medium",
            ["iconfilename"] = iconFilename,
            ["name"] = productName,
            ["display"] = "notext",
        }
    }

    wikiMarkup = wikiMarkup .. "'''" .. chance*100 .. "%'''"

    return wikiMarkup
end


---@private
---Looks up the building that can get the specified deposit for the view.
---
---@param deposit table from GladeResourceData
---@param displayOverride string override code, if any
---@return string wiki markup
local function renderBuilding(deposit, displayOverride)

    displayOverride = displayOverride --TODO write the other display modes

    local buildingName, buildingIcon = getBuildingForDeposit(deposit)

    local wikiMarkup = frame:expandTemplate{
        title = VIEW_BUILDING_LINK,
        args = {
            ["name"] = buildingName,
            ["iconfilename"] = buildingIcon,
            ["display"] = "notext"
        }
    }

    return wikiMarkup
end


---@private
---Used when a building is specified or there's just one row.
---
---@param buildingID string
---@return string wiki markup
local function renderLargeBuildingLink(buildingID, buildingName, buildingIcon)

    if buildingID then
        buildingName = BuildingDataProxy.getName(buildingID)
        buildingIcon = BuildingDataProxy.getIcon(buildingID)
    end

    local wikiMarkup = frame:expandTemplate{
        title = VIEW_BUILDING_LINK,
        args = {
            ["name"] = buildingName,
            ["iconfilename"] = buildingIcon,
            ["iconsize"] = "large"
        }
    }

    return wikiMarkup
end



---@private
---Makes a row for one deposit. If the buildingID is given, skips showing it, because it means it's factored out of the rows.
---
---@param deposit table from GladeResourceData
---@param numDeposits number total number of deposits
---@param maxBonuses number slots for bonus resources
---@param buildingID string a specified buildingID, if any
---@param displayOverride string override code, if any
---@return string wiki markup
local function renderViewOneRow(deposit, numDeposits, maxBonuses, buildingID, displayOverride)

    displayOverride = displayOverride --TODO write the other display modes

    --Special case where we take out the name and building icon when there's just one deposit or it's all harvestable by one building.
    local depositName = ""
    if numDeposits > 1 then
        depositName = GladeResourcesData.getDepositName(deposit)
    end
    local buildingLink = ""
    if not buildingID then
        buildingLink = renderBuilding(deposit, displayOverride)
    end

    local viewArgs = {
        [VIEW_ARG_DEPOSIT] = depositName,
        [VIEW_ARG_BUILDING] = buildingLink,
        [VIEW_ARG_CHARGES] = GladeResourcesData.getDepositCharges(deposit),
        [VIEW_ARG_PRODUCT] = renderProduct(deposit, displayOverride),
        [VIEW_ARG_MAX_BONUSES] = maxBonuses,
        [VIEW_ARG_BONUS_1] = renderBonus(deposit, 1, displayOverride),
        [VIEW_ARG_BONUS_2] = renderBonus(deposit, 2, displayOverride),
        [VIEW_ARG_BONUS_3] = renderBonus(deposit, 3, displayOverride),
        [VIEW_ARG_BONUS_4] = renderBonus(deposit, 4, displayOverride),
    }

    return frame:expandTemplate{
        title = VIEW_TEMPLATE_ROW,
        args = viewArgs,
    }
end



---@private
---Goes through the list of deposits and makes rows for each.
---
---@param depositsList table list of deposits from GladeResourcesData
---@param maxBonuses number slots for bonus resources
---@param buildingID string an ID for a building specified, if any
---@param displayOverride string override code, if any
---@return string wiki markup
local function renderViewAllRows(depositsList, maxBonuses, buildingID, displayOverride)

    local numDeposits = #depositsList

    -- Factor out a single building from the rows.
    if not buildingID then
        local buildingName = checkOnlyOneBuildingForAllDeposits(depositsList)
        if buildingName then
            buildingID = BuildingDataProxy.getID(buildingName)
        end
    end

    local wikiMarkup = ""
    for _, deposit in ipairs(depositsList) do
        wikiMarkup = wikiMarkup .. "\n"
        wikiMarkup = wikiMarkup .. renderViewOneRow(deposit, numDeposits, maxBonuses, buildingID, displayOverride)
    end

    return wikiMarkup
end



---@private
---Closes out the view, based on the display override or lack thereof. Returns whatever else needs to be appended to do so.
---
---@param depositsList table list of deposits from GladeResourcesData
---@param buildingID string an ID for a building specified, if any
---@param displayOverride string override code, if any
---@return string wiki markup
local function renderViewEnd(depositsList, buildingID, displayOverride)

    displayOverride = displayOverride --TODO write the other display modes

    local buildingLink = ""
    if buildingID then
        buildingLink = renderLargeBuildingLink(buildingID)
    else
        local buildingName, buildingIcon = checkOnlyOneBuildingForAllDeposits(depositsList)
        if buildingName and buildingIcon then
            buildingLink = renderLargeBuildingLink(nil, buildingName, buildingIcon)
        end
    end

    local wikiMarkup = ""
    wikiMarkup = wikiMarkup .. frame:expandTemplate{
        title = VIEW_TEMPLATE_END,
        args = {
            ["building"] = buildingLink,
        },
    }
    return wikiMarkup
end

--endregion



--region Public methods

---Called from Template:Deposit. Returns markup text for display by using external view templates.
---
---@param mwFrame table the Mediawiki calling context for the template
---@return string wiki markup
function GladeResourcesController.main(mwFrame)

    frame = mwFrame
    local productName = frame.args.product --TODO these are currently IDs, they need to be names
    local bonusName = frame.args.bonus
    local buildingName = frame.args.building
    local displayOverride = frame.args.display

    --Unset blanks back to nil or get their names from their data model
    local productID
    if productName and productName ~= "" then
        productID = GoodsData.getGoodID(productName)
    end
    local bonusID
    if bonusName and bonusName ~= "" then
        bonusID = GoodsData.getGoodID(bonusName)
    end
    local buildingID = BuildingDataProxy.getID(buildingName)

    local depositsList = {}
    local title = ""
    if productID and bonusID then
        if productID ~= bonusID then
            return ERROR_MESSAGE_PRODUCT_AND_BONUS_BUT_NOT_MATCH
        else
            depositsList = GladeResourcesData.getAllDepositsWherePrimaryOrBonusResource(productID)
        end
        title = #depositsList .. " Deposits for " .. productName .. " or as a bonus."
    elseif productID then
        depositsList = GladeResourcesData.getAllDepositsWherePrimaryResource(productID)
        title = #depositsList .. " Deposits for " .. productName .. "."
    elseif bonusID then
        depositsList = GladeResourcesData.getAllDepositsWhereBonusResource(bonusID)
        title = #depositsList .. " Deposits where " .. bonusName .. " is a bonus."
    elseif buildingID then
        depositsList = assembleDepositsFromBuilding(buildingID)
        title = #depositsList .. " Deposits exploited by the " .. buildingName .. "."
    else
        return ERROR_MESSAGE_NO_PARAMETERS_GIVEN
    end

    local maxBonuses = countMaxBonusesInList(depositsList)

    local wikiMarkup = ""
    wikiMarkup = wikiMarkup .. renderViewStart(depositsList, maxBonuses, title, buildingID, displayOverride)
    wikiMarkup = wikiMarkup .. renderViewAllRows(depositsList, maxBonuses, buildingID, displayOverride)
    wikiMarkup = wikiMarkup .. renderViewEnd(depositsList, buildingID, displayOverride)

    return wikiMarkup
end

--endregion



return GladeResourcesController