Module:PerksController

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

---
--- Serves the Perks searching template by capturing input and using it to control the display of data.
---
---@module PerksController
local PerksController = {}



--region Dependencies

local PerksData = require("Module:PerksData")

local ControllerUtilities = require("Module:ControllerUtilities")

--endregion



--region Private constants

local ARG_ID_LIST = "id"
local ARG_NAME_LIST = "name"
local ARG_DESCRIPTION_LIST = "description"
local ARG_SEARCH_ALL_LIST = "search"
local ARG_RARITY = "rarity"
local ARG_SOURCE = "source"
local ARGS_EXCLUDE_LIST = "exclude"
local ARG_CAPTION = "caption"
local ARG_SKIP_SOURCES = "skip_sources"
local ARG_SKIP_FLAG_VALUE = "skip"
local ARG_SHOW_ID = "show_id"
local ARG_SHOW_RARITY = "show_rarity"
local ARG_SHOW_DESCRIPTION = "show_description"
local ARG_SHOW_SOURCE_ALTAR = "show_source_altar"
local ARG_SHOW_SOURCE_CORNERSTONE = "show_source_cornerstone"
local ARG_SHOW_SOURCE_ORDER = "show_source_order"
local ARG_SHOW_SOURCE_RELIC = "show_source_relic"
local ARG_SHOW_SOURCE_TRADER = "show_source_trader"
local ARG_SHOW_PRICE = "show_price"
local ARG_SHOW_FLAG_VALUE = "show"
local ARG_DISPLAY_OVERRIDE = "display"
local ARG_DISPLAY_OVERRIDE_OPTION_LIST = "list"
local ARG_DISPLAY_OVERRIDE_OPTION_INLINE = "inline"
local ARG_LIST_TYPE = "list_type"

local TEMPLATE_PARAMETER_CAPTION = ARG_CAPTION
local TEMPLATE_PARAMETER_ID = ARG_ID_LIST
local TEMPLATE_PARAMETER_RARITY = ARG_RARITY
local TEMPLATE_PARAMETER_DESC = ARG_DESCRIPTION_LIST
local TEMPLATE_PARAMETER_SOURCE_ALTAR = "is_from_altar"
local TEMPLATE_PARAMETER_SOURCE_CORNERSTONE = "is_from_cornerstone"
local TEMPLATE_PARAMETER_SOURCE_ORDER = "is_from_order"
local TEMPLATE_PARAMETER_SOURCE_RELIC = "is_from_relic"
local TEMPLATE_PARAMETER_SOURCE_TRADER = "is_from_trader"
local TEMPLATE_PARAMETER_NUM_SOURCES = "num_sources_shown"
local TEMPLATE_PARAMETER_PRICE = "price"
local TEMPLATE_PARAMETER_SHOW_ID = ARG_SHOW_ID
local TEMPLATE_PARAMETER_LIST_TYPE = ARG_LIST_TYPE
local TEMPLATE_PARAMETER_ICON_SIZE = "icon_size"
local TEMPLATE_PARAMETER_ICON_SIZE_DEFAULT = "none"

local TEMPLATE_TABLE_BASE = "PerksCornerstonesTable"
local TEMPLATE_TABLE_SUFFIX_ROW = "/row"
local TEMPLATE_TABLE_SUFFIX_END = "/end"
local TEMPLATE_TABLE_SKIP_SOURCES_VARIANT = "/SkipSources"
local TEMPLATE_LIST_ITEM = "PerksCornerstonesList/item"
local TEMPLATE_INLINE_LINK = "pl"

local DISPLAY_YES = "true"

--endregion



--region Private member variables

local currentFrame = {}

local perkIDs = {}
local isIDAlreadyAdded = {}

--endregion



--region Private methods

--- Takes a list of possible IDs and only loads the valid ones of the specified rarity or source to the member variable perkIDs. Skips all ids present in the exclude list.
---
---@param newIDs table an array of possible IDs to check before adding
---@param rarityToCheck string a rarity to filter to, needs to be normalized
---@param sourceToCheck string a source to filter to, needs to be normalized
---@param excludeList table an array of IDs that should not be added
local function loadPerkIDs(newIDs, rarityToCheck, sourceToCheck, excludeList)

    for _, id in ipairs(newIDs) do

        if PerksData.isPerkIDValid(id) and not excludeList[id] and not isIDAlreadyAdded[id] then

            -- In this situation, nil values mean to skip the filter.
            local isRarityMatch = not rarityToCheck or "" == rarityToCheck or PerksData.isRarityMatchByID(id, rarityToCheck)
            local isSourceMatch = not sourceToCheck or "" == sourceToCheck or PerksData.isAnySource(id, sourceToCheck)

            if isRarityMatch and isSourceMatch then
                table.insert(perkIDs, id)
                isIDAlreadyAdded[id] = true
            end
        end
    end
end

--- Requests the desired lists of IDs from Perks data models, applies some post-processing, and stores them in the member variable perkIDs.
---
---@param selectList table array of ids of the cornerstone to include
---@param searchNameList table array of search criteria for names
---@param searchDescriptionsList table array of search criteria for descriptions
---@param rarity string the rarity of the cornerstones
---@param source string the source of cornerstones
---@param excludeList table list of ids
local function loadIDs(selectList, searchNameList, searchDescriptionsList, rarity, source, excludeList)

    perkIDs = {}
    isIDAlreadyAdded = {}
    local attemptedSearch = false

    -- Load the selected IDs
    if selectList then
        loadPerkIDs(selectList, rarity, source, excludeList)
        -- It should always be true, but it can be blank.
        if #selectList > 0 then
            attemptedSearch = true
        end
    end

    -- Add any name matches
    if searchNameList and #searchNameList > 0 then
        for _, searchName in ipairs(searchNameList) do
            local newIDs = PerksData.getAllPerkIDsWhereName(searchName)
            loadPerkIDs(newIDs, rarity, source, excludeList)
            attemptedSearch = true
        end
    end

    -- Add any description matches
    if searchDescriptionsList and #searchDescriptionsList > 0 then
        for _, searchDescription in ipairs(searchDescriptionsList) do
            local newIDs = PerksData.getAllPerkIDsWhereDescription(searchDescription)
            loadPerkIDs(newIDs, rarity, source, excludeList)
            attemptedSearch = true
        end
    end

    -- Or, if no searching was attempted (regardless of result), show all from the selected rarities and sources.
    if not attemptedSearch then
        local newIDs = PerksData.getAllPerkIDsFilteredByRarityAndSource(rarity, source)
        loadPerkIDs(newIDs, rarity, source, excludeList)
        attemptedSearch = true
    end

    -- Or, if no searching was even attempted (regardless of result), show them all.
    if not attemptedSearch then
        local newIDs = PerksData.getAllPerkIDs()
        loadStormforgedIDs(newIDs, excludeList)
    end

    if #perkIDs > 0 then
        -- Alphabetize by name.
        table.sort(perkIDs, PerksData.compareNames)
    end

    return perkIDs
end

--- Ensures that if a caption is not defined, there is a suitable fallback in case the author has specified an id, name, or search term to use, so readers know what they're looking at.
---
--- If no caption was specified and also none of those filtering parameters, then leave it up to the template by returning a blank caption.
---
---@param desiredCaption string the caption requested, if any
---@param selectList table array of ids of the cornerstone to include
---@param searchNameList table array of search criteria for names
---@param searchDescriptionList table array of search criteria for descriptions
---@param rarity string the rarity of the cornerstones
---@param source string the source of cornerstones
---@return string an appropriate caption, or blank if it should be default
local function resolveCaption(desiredCaption, selectList, searchNameList, searchDescriptionList, rarity, source, excludeList)

    -- No matter what, if the author provided a caption, use that.
    if desiredCaption and desiredCaption ~= "" then
        return desiredCaption
    end

    -- If no selection, delegate to template.
    local addedToText = false

    desiredCaption = "" .. #perkIDs

    if rarity and rarity ~= "" then
        desiredCaption = desiredCaption .. " " .. rarity .. " Perk"
        addedToText = true
    else
        desiredCaption = desiredCaption .. " Perk"
        -- did not addedToText, this is just default
    end

    if #perkIDs > 1 then
        desiredCaption = desiredCaption .. "s"
    end

    if source and source ~= "" then
        desiredCaption = desiredCaption .. " from " .. source .. "s"
        addedToText = true
    end

    if selectList and #selectList > 0 then
        if #selectList == 1 then
            desiredCaption = desiredCaption .. " with ID '" .. selectList[1] .. "'"
        else
            desiredCaption = desiredCaption .. " with selected IDs"
        end
        addedToText = true
    end

    if searchNameList and #searchNameList > 0 then
        if addedToText then
            desiredCaption = desiredCaption .. " and"
        end
        if #searchNameList == 1 and searchNameList[1] then
            desiredCaption = desiredCaption .. " named '" .. searchNameList[1] .. "'"
        else
            desiredCaption = desiredCaption .. " with specific names"
        end
        addedToText = true
    end

    if searchDescriptionList and #searchDescriptionList > 0 then
        if addedToText then
            desiredCaption = desiredCaption .. " and"
        end
        if #searchDescriptionList == 1 and searchDescriptionList[1] then
            desiredCaption = desiredCaption .. " mentioning '" .. searchDescriptionList[1] .. "'"
        else
            desiredCaption = desiredCaption .. " by searching descriptions"
        end
        addedToText = true
    end

    if excludeList and #excludeList > 0 then
        desiredCaption = desiredCaption .. " (with exclusions)"
        addedToText = true
    end

    if addedToText then
        return desiredCaption
    else
        -- Delegate to the template for the default
        return ""
    end
end

---resolveTableStartTemplate
---@param isSkippingSources boolean true if skipping variant should be used
---@return string the full title of the template, for expandTemplate
local function resolveTableStartTemplate(isSkippingSources)

    local suffixIfSkipping = (isSkippingSources and TEMPLATE_TABLE_SKIP_SOURCES_VARIANT) or ""

    return TEMPLATE_TABLE_BASE .. suffixIfSkipping
end

---resolveTableRowTemplate
---@param isSkippingSources boolean true if skipping variant should be used
---@return string the full title of the template, for expandTemplate
local function resolveTableRowTemplate(isSkippingSources)

    local suffixIfSkipping = (isSkippingSources and TEMPLATE_TABLE_SKIP_SOURCES_VARIANT) or ""

    return TEMPLATE_TABLE_BASE .. TEMPLATE_TABLE_SUFFIX_ROW .. suffixIfSkipping
end

---resolveEndTemplate
---@return string the template name to use
local function resolveTableEndTemplate()

    return TEMPLATE_TABLE_BASE .. TEMPLATE_TABLE_SUFFIX_END
end

--- Calls the view (other templates) to render the beginning of the table.
---
---@param desiredCaption string the caption for the table, if any
---@param isSkippingSources boolean true if skipping variant should be used
---@param argsForTableTemplate table a set of arguments ready to pass through to the called template
---@return string the wiki markup assembled by the view (other templates)
local function makeMarkupForTableStart(desiredCaption, isSkippingSources, argsForTableTemplate)

    argsForTableTemplate[TEMPLATE_PARAMETER_CAPTION] = desiredCaption

    -- Count how many source columns should be shown.
    local sources = {
        ARG_SHOW_SOURCE_ALTAR,
        ARG_SHOW_SOURCE_CORNERSTONE,
        ARG_SHOW_SOURCE_ORDER,
        ARG_SHOW_SOURCE_RELIC,
        ARG_SHOW_SOURCE_TRADER
    }
    local numSourcesShown = 0
    for _, index in ipairs(sources) do
        if ARG_SHOW_FLAG_VALUE == argsForTableTemplate[index] then
            numSourcesShown = numSourcesShown + 1
        end
    end
    argsForTableTemplate[TEMPLATE_PARAMETER_NUM_SOURCES] = numSourcesShown

    return currentFrame:expandTemplate{ title = resolveTableStartTemplate(isSkippingSources), args = argsForTableTemplate }

end

--- Calls the view (other templates) to render a single row of the table with data based on the provided identifier.
---
---@param id string the unique identifier of a Perk or Cornerstone to use to add data to a new table row
---@param isSkippingSources boolean true if skipping variant should be used
---@param argsForTableTemplate table a set of arguments ready to pass through to the called template
---@return string the wiki markup assembled by the view (other templates)
local function makeMarkupPerRow(id, isSkippingSources, argsForTableTemplate)

    argsForTableTemplate[TEMPLATE_PARAMETER_ID] = id
    argsForTableTemplate[TEMPLATE_PARAMETER_RARITY] = PerksData.getRarityByID(id)
    argsForTableTemplate[TEMPLATE_PARAMETER_DESC] = ControllerUtilities.findAndReplaceSpriteTagsWithFiles(PerksData.getDescriptionByID(id), currentFrame)
    argsForTableTemplate[TEMPLATE_PARAMETER_PRICE] = PerksData.getPriceByID(id)

    -- This is default, but adds a lot of extra template overhead if it's not needed, so only add it if necessary.
    if not isSkippingSources then
        argsForTableTemplate[TEMPLATE_PARAMETER_SOURCE_ALTAR] = PerksData.isFromAltarByID(id) and DISPLAY_YES
        argsForTableTemplate[TEMPLATE_PARAMETER_SOURCE_CORNERSTONE] = PerksData.isFromCornerstoneByID(id) and DISPLAY_YES
        argsForTableTemplate[TEMPLATE_PARAMETER_SOURCE_ORDER] = PerksData.isFromOrderByID(id) and DISPLAY_YES
        argsForTableTemplate[TEMPLATE_PARAMETER_SOURCE_RELIC] = PerksData.isFromEventByID(id) and DISPLAY_YES
        argsForTableTemplate[TEMPLATE_PARAMETER_SOURCE_TRADER] = PerksData.isFromTraderByID(id) and DISPLAY_YES
    end

    return currentFrame:expandTemplate{ title = resolveTableRowTemplate(isSkippingSources), args = argsForTableTemplate }
end

--- Handles assembling the rows for all of the IDs in the member variable list altarIDs.
---
---@param isSkippingSources boolean true if skipping sources columns
---@param argsForTableTemplate table a table of arguments to pass through to the view templates
---@return string the wiki markup assembled by the view (other templates)
local function makeMarkupForTableRows(isSkippingSources, argsForTableTemplate)

    local markup = ""
    for _, id in ipairs(perkIDs) do
        markup = markup .. makeMarkupPerRow(id, isSkippingSources, argsForTableTemplate)
    end

    return markup
end

--- Calls the view (other templates) to render the end of the table.
---
---@return string the wiki markup assembled by the view (other templates)
local function makeMarkupForTableEnd()

    return currentFrame:expandTemplate{ title = resolveTableEndTemplate(), args = {} }
end

---Calls the view (other templates) to render the content and appends it to the wiki markup string that will replace this controller's template.
-----
----- Calls several methods to build pieces of the table's markup based on the author's requests.
---
---@param desiredCaption string the caption for the table
---@param isSkippingSources boolean true if skipping sources columns
---@param argsForTableTemplate table a table of arguments to pass through to the view templates
---@return string the wiki markup assembled by the view (other templates)
local function renderTable(desiredCaption, isSkippingSources, argsForTableTemplate)

    local startMarkup = makeMarkupForTableStart(desiredCaption, isSkippingSources, argsForTableTemplate)
    local rowsMarkup = makeMarkupForTableRows(isSkippingSources, argsForTableTemplate)

    return startMarkup .. rowsMarkup .. makeMarkupForTableEnd()
end

---makeMarkupPerListItem
---@param id string the id of the cornerstone to display
---@param listType string the type of list to create
---@param isShowingID boolean true when needing to show the ID column
---@return string the wiki markup assembled by the view (other templates)
local function makeMarkupPerListItem(id, listType, isShowingID)

    local templateParameters = {
        [TEMPLATE_PARAMETER_ID] = id,
        [TEMPLATE_PARAMETER_LIST_TYPE] = listType,
        [TEMPLATE_PARAMETER_SHOW_ID] = isShowingID and ARG_SHOW_FLAG_VALUE
    }

    return currentFrame:expandTemplate{ title = TEMPLATE_LIST_ITEM, args = templateParameters }
end

---makeMarkupForListItems
---@param listType string the type of list to create
---@param isShowingID boolean true when needing to show the ID column
---@return string the wiki markup assembled by the view (other templates)
local function makeMarkupForListItems(listType, isShowingID)

    local markup = ""
    for _, id in ipairs(perkIDs) do
        markup = markup .. makeMarkupPerListItem(id, listType, isShowingID)
    end

    return markup
end

---renderList
---@param listType string the type of list to create
---@param isShowingID boolean true when needing to show the ID column
---@return string the wiki markup assembled by the view (other templates
local function renderList(listType, isShowingID)

    return makeMarkupForListItems(listType, isShowingID)
end

---makeMarkupPerLink
---@param id string the id of the cornerstone to display
---@param isShowingID boolean true when needing to show the ID column
---@return string the wiki markup assembled by the view (other templates)
local function makeMarkupPerLink(id, isShowingID)

    local templateParameters = {
        [TEMPLATE_PARAMETER_ID] = id,
        [TEMPLATE_PARAMETER_ICON_SIZE] = TEMPLATE_PARAMETER_ICON_SIZE_DEFAULT,
    }

    local link = currentFrame:expandTemplate{ title = TEMPLATE_INLINE_LINK, args = templateParameters }

    if isShowingID then
        return link .. " ('" .. id .. "')"
    else
        return link
    end
end

---makeMarkupForInlineLinks
---@param isShowingID boolean true when needing to show the ID column
---@return string the wiki markup assembled by the view (other templates)
local function makeMarkupForInlineLinks(isShowingID)

    local markup = ""
    for i, id in ipairs(perkIDs) do
        if i > 1 then
            markup = markup .. ", "
        end
        markup = markup .. makeMarkupPerLink(id, isShowingID)
    end

    return markup
end

---renderInline
---@param isShowingID boolean true when needing to show the ID column
---@return string the wiki markup assembled by the view (other templates)
local function renderInlineLinks(isShowingID)

    return makeMarkupForInlineLinks(isShowingID)
end

--endregion



--region Public methods

function PerksController.main(frame)

    -- Selection parameters
    local selectList = ControllerUtilities.expandCommaSeparatedStringsIntoTable(frame.args[ARG_ID_LIST], false)
    local excludeList = ControllerUtilities.expandCommaSeparatedStringsIntoTable(frame.args[ARGS_EXCLUDE_LIST], true)
    local searchNameList = ControllerUtilities.expandCommaSeparatedStringsIntoTable(frame.args[ARG_NAME_LIST], false)
    local searchDescriptionList = ControllerUtilities.expandCommaSeparatedStringsIntoTable(frame.args[ARG_DESCRIPTION_LIST], false)
    local searchAllList = ControllerUtilities.expandCommaSeparatedStringsIntoTable(frame.args[ARG_SEARCH_ALL_LIST], false)

    local rarityFilter = PerksData.normalizeRarityText(frame.args[ARG_RARITY])
    local sourceFilter = PerksData.normalizeSourceText(frame.args[ARG_SOURCE])

    -- Substitute the search all terms for name or description, if they weren't provided but search-all was.
    if searchAllList and #searchAllList > 0 then
        if #searchNameList < 1 then
            searchNameList = searchAllList
        end
        if #searchDescriptionList < 1 then
            searchDescriptionList = searchAllList
        end
    end

    -- Display parameters
    local desiredCaption = frame.args[ARG_CAPTION]
    local displayOverride = frame.args[ARG_DISPLAY_OVERRIDE]
    local listType = frame.args[ARG_LIST_TYPE]
    local isShowingID = ARG_SHOW_FLAG_VALUE == frame.args[ARG_SHOW_ID]
    local isSkippingSources = ARG_SKIP_FLAG_VALUE == frame.args[ARG_SKIP_SOURCES]

    -- For clarity, copy each value instead of reusing the whole args table.
    local argumentsToPassThroughToTable = {
        [ARG_SKIP_SOURCES] = frame.args[ARG_SKIP_SOURCES],
        [ARG_SHOW_ID] = frame.args[ARG_SHOW_ID],
        [ARG_SHOW_RARITY] = frame.args[ARG_SHOW_RARITY],
        [ARG_SHOW_DESCRIPTION] = frame.args[ARG_SHOW_DESCRIPTION],
        [ARG_SHOW_SOURCE_ALTAR] = frame.args[ARG_SHOW_SOURCE_ALTAR],
        [ARG_SHOW_SOURCE_CORNERSTONE] = frame.args[ARG_SHOW_SOURCE_CORNERSTONE],
        [ARG_SHOW_SOURCE_ORDER] = frame.args[ARG_SHOW_SOURCE_ORDER],
        [ARG_SHOW_SOURCE_RELIC] = frame.args[ARG_SHOW_SOURCE_RELIC],
        [ARG_SHOW_SOURCE_TRADER] = frame.args[ARG_SHOW_SOURCE_TRADER],
        [ARG_SHOW_PRICE] = frame.args[ARG_SHOW_PRICE]
    }

    currentFrame = frame

    loadIDs(selectList, searchNameList, searchDescriptionList, rarityFilter, sourceFilter, excludeList)
    if #perkIDs < 1 then
        return "No matching Perks found."
    end

    if displayOverride == ARG_DISPLAY_OVERRIDE_OPTION_LIST then
        return renderList(listType, isShowingID)
    end
    if displayOverride == ARG_DISPLAY_OVERRIDE_OPTION_INLINE then
        return renderInlineLinks(isShowingID)
    end

    -- Default display is table.
    desiredCaption = resolveCaption(desiredCaption, selectList, searchNameList, searchDescriptionList, rarityFilter, sourceFilter, excludeList)

    return renderTable(desiredCaption, isSkippingSources, argumentsToPassThroughToTable)
end

--endregion

return PerksController