Module:Transclusion Arguments

This module is the Lua interface for Special:CargoTables/TransclusionArguments, which stores information about which arguments are used with which templates/modules on what pages. It is not to be confused with Wikipedia's Module:Arguments nor Zelda Wiki's equivalent Module:UtilsArg, which parse and validate template arguments.

---

local p = {}

local utilsArg = require("Module:UtilsArg")
local utilsCargo = require("Module:UtilsCargo")

local TABLE = "TransclusionArguments"
local TABLE_LINK = "[[Special:CargoTables/"..TABLE.."]]"

function p.Main(frame)
	local utilsLayout = require("Module:UtilsLayout")
	local utilsMarkup = require("Module:UtilsMarkup")
	local utilsTable = require("Module:UtilsTable")

	local args = utilsArg.parse(frame:getParent().args, p.Templates.Arguments)
	if args.isValid then
		args.isValid = args.isValid == "yes"
	end
	local limit = args.limit and tonumber(args.limit)
	args.limit = nil

	local arguments = p.query(args)
	arguments = utilsTable.uniqueBy(arguments, "_pageName")
	arguments = utilsTable.groupBy(arguments, "argument")
	arguments = utilsTable.mapValues(arguments, utilsTable._map("_pageName"))
	
	local rows = {}
	local totalPages = 0
	for argument, pages in pairs(arguments) do
		argument = "<code>"..argument.."</code>"
		local pageLinks = utilsTable.map(pages, utilsMarkup.link)
		local pageList = table.concat(pageLinks, " • ")
		table.insert(rows, {argument, #pages, pageList})
		totalPages = totalPages + #pages
	end
	-- sort descending by # of pages then ascending by argument value
	table.sort(rows, function(a, b)
		if a[2] == b[2] then
			return a[1] < b[1]
		else
			return a[2] > b[2]
		end
	end)
	
	if limit then
		rows = utilsTable.take(rows, limit)
	end

	local wikitable = utilsLayout.table({
		caption = string.format('<div style="text-align:left">Total pages: %d</span>', totalPages),
		headers = {args.header or args.parameter, "Page Count", "Pages"},
		rows = rows,
		sortable = true,
	})
	return wikitable
end

function p.query(args)
	local isValid = args.isValid
	if isValid ~= nil then
		isValid = isValid and "1" or "0"
	end
	local rows = utilsCargo.query(TABLE, "_pageName, template, module, pageInstance, parameter, argument, isValid", {
		where = utilsCargo.allOf({
			template = args.template,
			module = args.module,
			pageInstance = args.pageInstance,
			parameter = args.parameter,
			argument = args.argument,
			isValid = isValid
		}),
		limit = args.limit,
	})
	return rows
end

function p.store(transclusion)
	return utilsArg.store(transclusion)
end

p.Templates = {
	["Arguments"] = {
		format = "block",
		purpose = string.format("Uses %s to construct a table that identifies which pages use a certain template with certain arguments.", TABLE_LINK),
		usesData = true,
		paramOrder = {"template", "parameter", "header", "argument", "isValid", "limit"},
		params = {
			template = {
				required = true,
				desc = "A template name.",
				type = "wiki-template-name",
				trim = true,
			},
			parameter = {
				required = true,
				desc = "A parameter name for the given template.",
				type = "string",
				trim = true,
			},
			header = {
				required = true,
				desc = "A header value for the resulting table.",
				trim = true,
			},
			argument = {
				desc = "A specific argument value to query for, if desired.",
				type = "string",
			},
			isValid = {
				desc = "If empty, the query will be for all arguments. If <code>yes</code>, only valid arguments are included. If <code>no</code>, only invalid arguments are included.",
				enum = {"yes", "no"},
				trim = true,
				nilIfEmpty = true,
			},
			limit = {
				desc = "Limits the number of rows in the generated table.",
				trim = true,
			},
		},
		examples = {
			{
				desc = "Pages using {{Template|Icon|TWWHD Eighth Note}}",
				args = {
					template = "Template:Icon",
					parameter = "1",
					header = "Color Name",
					argument = "TWWHD Eighth Note",
				},
			},
			{
				desc = "[[:Category:Articles Using Invalid Icon Names#Summary]]",
				args = {
					template = "Template:Icon",
					parameter = "1",
					header = "Icon Code",
					isValid = "no",
					limit = "3",
				},
			},
		}
	},
	["Arguments/Store"] = {
		purpose = "Stores data regarding template/module usage for the benefit of [[Module:Arguments]].",
		storesData = true,
		categories = {"Metatemplates"},
		paramOrder = {"template", "module", "pageInstance", "parameter", "argument", "isValid"},
		params = {
			template = {
				desc = "The template being used.",
				type = "wiki-template-name",
			},
			module = {
				desc = "The module being used.",
				type = "wiki-page-name",
			},
			pageInstance = {
				desc = "Specifies the instance of the template, when a template is used multiple times on a page.",
				type = "number",
			},
			parameter = {
				desc = "A parameter name.",
				type = "string",
			},
			argument = {
				desc = "The value of the argument corresponding to <code>parameter</code>.",
				type = "string",
			},
			isValid = {
				desc = "<code>1</code> or <code>yes</code> if the argument is valid, <code>0</code> or <code>no</code> if it is not valid.",
				enum = {"1", "0", "yes", "no"},
			},
		}
	}
}

p.Schemas = {
	store = {
		transclusion = {
			type = "record",
			required = true,
			properties = {
				{
					name = "module",
					desc = "A module name. Defaults to <code>mw.getCurrentFrame():getTitle()</code>.",
				},
				{
					name = "args",
					desc = "Template/module arguments.",
					type = "map",
					keys = { 
						oneOf = {
							{
								type = "string"
							},
							{
								type = "number"
							},
						},
					},
					values = { type = "string" },
				},
				{
					name = "isValid",
					type = "boolean",
					desc = "Indicates whether or not the template transclusion or module function call is valid.",
				},
			},
		},
	},
}

p.Documentation = {
	query = {
		params = {"args"},
		returns = string.format("Data from %s.", TABLE_LINK),
		cases = {
			{
				desc = "[[:Category:Articles Using Invalid Color Names#Summary]]",
				args = {
					{
						template = "Template:Color",
						isValid = false,
						limit = 3,
					},
				},
			},
		},
	},
	store = {
		desc = string.format("Stores data in %s.", TABLE_LINK),
		params = {"transclusion"},
		returns = nil,
		cases = {
			{
				args = {
					{
						module = "Module:Arguments",
						isValid = true,
						args = {
							[1] = "foo",
							bar = "baz",
						},
					},
				},
			},
		},
	},
}

return p