Module:Autocat

Lua

CodeDiscussionEditHistoryLinksLink count Subpages:DocumentationTestsResultsSandboxLive code All modules

This module is rated as beta, and is ready for widespread use. It is still new and should be used with some caution to ensure the results are as expected.

The AutoCat module contains a function to select one or more categories from a list of candidates. It can only be used from other Scribuntu modules.

Usage

local autocat = require "Module:AutoCat"
categories = autocat.autoCat(candidates, criterion, sortkey)

Parameters

candidates

Required: A string with the candidates for the categories. The string is built as follows:

• Every candidate consists of the category name, optionally with a colon (:) and a sortkey appended.

Examples:

Books from Argentina just refers to the Category:Books from Argentina without any specific sortkey.

Books from Argentina:* adds the sortkey “*”. This corresponds to the wikitext syntax [[Category:Books from Argentina|*]].

• A chain consists of one or more candidates, separated by a semicolon (;). The function chooses the first candidate in the list with an existing category page. If none of the categories has an existing page, the last one in the list is chosen nevertheless.

Examples:

Houses in Mowgli's town;Houses in India:*;Houses in Asia:* will choose the second candidate, because the first does not exist. The third is not even examined.

Vineyards on Mars;Vineyards in the solar system;Vineyards in the milky way will choose the third candidate (even though none exists at all) and result in a red category link.

You can avoid the red category link by adding ;- at the end of the chain:

Vineyards on Mars;Vineyards in the solar system;Vineyards in the milky way;- will not choose any of the categories.

• The complete candidate list consists of one or more chains, separated by newlines.

The function will select none or one appropriate category from each of the chains according to the rules above and return the wikitext for including these categories in a page.

criterion

Optional: A string with the criterion to build “... by criterion” metacategory names.

If this is provided, the the function will, for each of the candidates it examines, first try the metacategory and prefer that if it exists. Note that when the metacategory is chosen, the sortkey built in the candidate list is not used.

sortkey

Optional: A sortkey that will be used for both “raw” categories and metacategories.

The combination of the three parameters allows us to follow sortkey conventions on Commons as in the following example:

autocat.autoCat("Schools in Lombardy:+;Schools in Italy:+", "city", "Bergamo")

will output the first of the following category links where the category page is found:

[[Category:Schools in Lombary by city|Bergamo]] (note the “+” prefix is removed)

[[Category:Schools in Lombary|+Bergamo]] (note the “+” prefix is used)

[[Category:Schools in Italy by city|Bergamo]] (note the “+” prefix is removed)

[[Category:Schools in Italy|+Bergamo]] (note the “+” prefix is used)

Code

-- =============================================================================
-- Automatically add categories to a page
-- =============================================================================

require("strict")

local makesortkey  = require "Module:MakeSortKey"

local p = {}

-- -----------------------------------------------------------------------------
-- Main function
-- -----------------------------------------------------------------------------

function p.autoCat(candidates, criterion, sortkey)
	-- Make sure that sortkey is not nil
	local sortkey2 = sortkey or ""
	-- Compile list of categories to include
	local result = ""
	for chain in candidates:gmatch("[^\n]+") do
		local category, sortkey1
		for candidate in chain:gmatch("[^;]+") do
			local base
			base, sortkey1 = candidate:match("(.*):(.*)")
			if not base then
				base = candidate
				sortkey1 = ""
			end
			if base ~= "-" then
				-- First try meta category "by criterion"
				if criterion then
					category = "Category:" .. base .. " by " .. criterion
					if mw.title.new(category).exists then
						sortkey1 = ""	-- No sort prefix in meta categories
						break
					end
				end
				-- Then try the base category
				category = "Category:" .. base
				if mw.title.new(category).exists then
					break
				end
			else
				-- "-" means we don't want any category at this point
				category = nil
			end
		end
		if category then
			result = result .. "[[" .. category
			if sortkey1 .. sortkey2 ~= "" then
				result = result .. "|" .. makesortkey.makeSortKey(sortkey1 .. sortkey2)
			end
			result = result .. "]]"
		end
	end
	return result
end

-- =============================================================================

return p