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.

This is the main module for the following templates:

• Template:Arguments
• Template:Arguments/Store

In addition, this module exports the following functions.

fetchTransclusions

fetchTransclusions(args)

Parameters

• args

  template

  The template name to fetch tranclusions for.

  keyParameter

  The name of one of the template's required parameters. Must be present in all stored transclusions of the template.

  [limit]

  The number of transclusions to return.

Returns

• A list of tranclusions.

Examples

#	Input	Output
1	fetchTransclusions({ limit = 2, template = "Template:Transcript Copy", keyParameter = "fromPage", })	{ { module = "Module:Transcript", isValid = true, template = "Template:Transcript Copy", _pageName = "Beedle's Assistant", arguments = { storedAs = { value = "Rock Spire Shop Ship Letter", isValid = true, }, fromPage = { value = "Beedle", isValid = true, }, }, }, { module = "Module:Transcript", isValid = true, template = "Template:Transcript Copy", _pageName = "Big Chance Extravaganza", arguments = { storedAs = { value = "Big Chance Extravaganza Letter", isValid = true, }, fromPage = { value = "Beedle", isValid = true, }, }, }, { module = "Module:Transcript", isValid = true, template = "Template:Transcript Copy", _pageName = "Letter", arguments = { fromPage = { value = "Beedle", isValid = true, }, }, }, }

query

query(args)

Returns

• Data from Special:CargoTables/TransclusionArguments.

Examples

#	Input	Output
Category:Articles Using Invalid Color Names#Summary
2	query({ isValid = false, template = "Template:Color", limit = 3, })	{ { module = "Module:Color", argument = "SSBU Challenges Adventure", parameter = "1", pageInstance = "1", isValid = "0", template = "Template:Color", _pageName = "Challenge", }, { module = "Module:Color", argument = "SSBU Challenges Online", parameter = "1", pageInstance = "2", isValid = "0", template = "Template:Color", _pageName = "Challenge", }, { module = "Module:Color", argument = "SSBU Challenges Other", parameter = "1", pageInstance = "3", isValid = "0", template = "Template:Color", _pageName = "Challenge", }, }

store

store(transclusion)

Stores data in Special:CargoTables/TransclusionArguments.

Parameters

• transclusion

  [module]

  A module name. Defaults to mw.getCurrentFrame():getTitle().

  [args]

  Template/module arguments.

  [isValid]

  Indicates whether or not the template transclusion or module function call is valid.

Examples

#	Input
3	store({ module = "Module:Arguments", isValid = true, args = {"foo", bar = "baz"}, })

---

local p = {}

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

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)
	local allPages = utilsTable.map(arguments, "_pageName")
	allPages = utilsTable.unique(allPages)
	arguments = utilsTable.groupBy(arguments, "argument")
	arguments = utilsTable.mapValues(arguments, utilsTable._map("_pageName"))
	arguments = utilsTable.mapValues(arguments, utilsTable.unique)
	
	local rows = {}
	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})
	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 purgeLink = mw.title.getCurrentTitle():fullUrl({
		action = "purge"
	})
	local purgeButton = string.format('<span style="margin-left: 0.5rem; font-weight: normal;">&lsqb;[%s purge]&rsqb;</span>', purgeLink)

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

function p.fetchTransclusions(args)
	local limit = args.limit
	local template = args.template
	local keyParameter = args.keyParameter

	local arguments = p.query({
		template = args.template
	})
	-- Sort arguments by page, ensuring that the key parameter is first
	arguments = utilsTable.sortBy(arguments, function(argument)
		local parameterSortKey = argument.parameter == keyParameter and "0" or "1"
		return argument._pageName..parameterSortKey
	end)

	local transclusions = {}
	local currentTransclusion = { isValid = true, arguments = {} }
	for i, argument in ipairs(arguments) do
		local isKey = argument.parameter == keyParameter
		if isKey and limit and #transclusions == limit then
			break
		elseif isKey and i ~= 1 then
			table.insert(transclusions, currentTransclusion)
			currentTransclusion = { isValid = true, arguments = {} }
		end
		local isValid = argument.isValid == "1"
		currentTransclusion.isValid = currentTransclusion.isValid and isValid
		utilsTable.merge(currentTransclusion, {
			module = argument.module,
			template = argument.template,
			_pageName = argument._pageName,
		})
		currentTransclusion.arguments[argument.parameter] = {
			isValid = isValid,
			value = argument.argument,
		}
	end
	table.insert(transclusions, currentTransclusion)
	return transclusions
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 or 5000,
	})
	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.",
				default = 5000,
				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 [[Template: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"},
			},
		}
	}
}

function p.Schemas()
	return {
		fetchTransclusions = {
			args = {
				type = "record",
				required = true,
				properties = {
					{
						name = "template",
						required = true,
						type = "string",
						desc = "The template name to fetch tranclusions for.",
					},
					{
						name = "keyParameter",
						required = true,
						type = "string",
						desc = "The name of one of the template's required parameters. Must be present in all stored transclusions of the template.",
					},
					{
						name = "limit",
						type = "number",
						desc = "The number of transclusions to return."
					},
				},
			},
		},
		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.",
					},
				},
			},
		},
	}
end

function p.Documentation()
	return {
		fetchTransclusions = {
			params = {"args"},
			returns = "A list of tranclusions.",
			cases = {
				{
					args = {
						{
							template = "Template:Transcript Copy",
							keyParameter = "fromPage",
							limit = 2,
						}
					}
				},
			},
		},
		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",
							},
						},
					},
				},
			},
		},
	}
end

return p