Module:Sequences

This is the main module for the following templates:

• Template:Sort Value

In addition, this module exports the following functions.

sortValue

sortValue(game, sequence, subject)

Returns

• Integer sort value of subject for the given sequence in game, or nil if none found.

Examples

#	Input	Output	Status
1	sortValue("ST", "Realms", "Snow Realm")	2
2	sortValue("ST", "Realms", "💩 Realm")	nil

---

local p = {}
local h = {}

local Franchise = require("Module:Franchise")
local Term = require("Module:Term")
local utilsArg = require("Module:UtilsArg")
local utilsCargo = require("Module:UtilsCargo")
local utilsString = require("Module:UtilsString")
local utilsTable = require("Module:UtilsTable")

local CARGO_TABLE = "Sequences"
local CATEGORY_INVALID_ARGS = require("Module:Constants/category/invalidArgs")

function p.SortValue(frame)
	local args, err = utilsArg.parse(frame:getParent().args, p.Templates["Sort Value"])
	local categories = err and err.categoryText or ""
	if err then
		return subject, err.categoryText
	end
	
	local game = args.game
	local sequence = args.sequence
	local subject = args.subject
	
	local term = Term.link(subject, game)
	local sortValue, sequences = p.sortValue(game, sequence, subject)
	
	if #sequences > 1 then
		local utilsError = require("Module:UtilsError")
		local utilsMarkup = require("Module:UtilsMarkup")
		local sequences = utilsTable.map(sequences, utilsMarkup.code)
		sequences = table.concat(sequences, ", ")
		local warnMsg = string.format("<code>%s</code> belongs to multiple sequences. Please specify which sequence to use by setting the <code>sequence</code> parameter to one of: <code>%s</code>", subject, sequences)
		utilsError.warn(warnMsg)
		categories = categories.."[[Category:"..CATEGORY_INVALID_ARGS.."]]"
	end
	if not sortValue then
		local utilsError = require("Module:UtilsError")
		local warnMsg
		if sequence then
			warnMsg = string.format("Sort value not found for <code>%s</code> in sequence <code>%s</code> of game <code>%s</code>.", subject, sequence, game) 
		else
			warnMsg = string.format("Sort value not found for <code>%s</code> in game <code>%s</code>.", subject, game)
		end
		warnMsg = warnMsg.."Defaulting to alphabetical sorting. See [[Module:Sequences/Supported Sequences|Supported Sequences]] for list of valid sort values."
		utilsError.warn(warnMsg)
		categories = categories.."[[Category:"..CATEGORY_INVALID_ARGS.."]]"
		return term, categories
	else
		local dataSortValue = string.format('data-sort-value="%s"|', sortValue)
		return dataSortValue..term, categories
	end
end

function p.sortValue(game, sequence, subject)
	local queryResults = utilsCargo.query(CARGO_TABLE, "ordinality, sequence", {
		where = utilsCargo.allOf({
			game = game,
			subject = subject,
			sequence = sequence,
		}),
		orderBy = "sequence",
	})
	local sortValue = queryResults[1] and tonumber(queryResults[1].ordinality)
	local sequences = utilsTable.map(queryResults, "sequence")
	return sortValue, sequences
end

p.Templates = {
	["Sort Value"] = {
		purpose = "Displays [[Template:Term|terms]] in [[Help:Tables#Sortable_Tables|sortable tables]] such that the table data can be sorted according to an in-game order that was pre-defined using [[Template:Term List]].",
		usesData = true,
		paramOrder = {1, 2, "sequence"},
		params = {
			[1] = {
				name = "game",
				type = "string",
				required = true,
				desc = "A game code.",
				enum = Franchise.enum(),
			},
			[2] = {
				name = "subject",
				type = "string",
				required = true,
				desc = "A wiki page name to be sorted according to an in-game sequence.",
			},
			sequence = {
				type = "string",
				canOmit = true,
				desc = "If the given subject belongs to more than one sequence in the given game, use this parameter to specify which sequence to use for sorting. See [[Module:Sequences/Supported Sequences]]."
			},
		},
	},
}

function p.Schemas()
	return {
		getSortValue = {
			game = {
				type = "string",
				required = true,
				desc = "A game code from [[Data:Franchise]].",
			},
			sequence = {
				name = "sequence",
				type = "string",
				required = true,
				desc = "A sequence name. See [[Template:Sort Value#Supported Sequences]].",
			},
			subject = {
				type = "string",
				required = true,
				desc = "A wiki page name to get sort value for.",
			}
		}
	}
end

function p.Documentation()
	return {
		sortValue = {
			params = {"game", "sequence", "subject"},
			returns = "Integer sort value of <code>subject</code> for the given <code>sequence</code> in <code>game</code>, or <code>nil</code> if none found.",
			cases = {
				outputOnly = true,
				{
					args = {"ST", "Realms", "Snow Realm"},
					expect = 2
				},
				{
					args = {"ST", "Realms", "💩 Realm"},
					expect = nil
				},
			}
		},
	}
end

return p