Module:Category handler

Module documentation[view] [edit] [history] [purge]

This module may be invoked by templates using its corresponding template Template:Category handler, or used directly from other modules.

Module:Category handler is ready for use. This message indicates that a module is ready for use, or has recently been repaired. This message may be removed once this module has been used on several pages or once it is verified to work as intended. Details: Functionally complete. Default lists may be adjusted still.

Introspection summary for Module:Category handler
Functions provided (2) Line Function Params 110 _category_handler (main) (cats, ns_override, suffixes, is_debug) 140 category_handler (invokable) (frame)	Lua modules required (2) Variable Module Functions used getArgs Module:Arguments getArgs yesno Module:Yesno yesno

No function descriptions were provided. The Lua code may have further information.

---

-- This module follows [[User:Ganaram inukshuk/Provisional style guide for Lua]]
local getArgs = require("Module:Arguments").getArgs
local yesno = require("Module:Yesno")

local p = {}

-- Basic category handler, based on Wikipedia's category handler. It categorizes
-- pages, given a table of categories as input, and suppresses categorization if
-- the page is in the table of excluded namespaces, or table of excluded 
-- suffixes (subpages).
-- The most common categorizing templates that have/require complex rules are:
-- - Infoboxes; these usually shouldn't categorize if they're outside the main
--   namespace.
-- - Certain mboxes; some mboxes categorize certain pages, but they shouldn't
--   categorize their own documentation.

-- Default list of namespaces in which to suppress categorization. Most
-- categorizing templates are expected to be placed in main, template, or
-- module; those that don't are likely special-use templates (like idiosyncratic
-- and editable user page) which likely won't need this module, or templates
-- with very basic categorization rules for which this is overkill.
-- Adjust as needed!
local DEFAULT_SUPPRESSED_NAMESPACES = {
    ["talk"] = true,
    ["user"] = true,
    ["user talk"] = true,
    ["file talk"] = true,
    ["mediawiki talk"] = true,
    ["template talk"] = true,
    ["help"] = true,
    ["help talk"] = true,
    ["category talk"] = true,
    ["module talk"] = true,
    ["xenharmonic wiki"] = true,
    ["xenharmonic wiki talk"] = true,
    ["media"] = true,
}
-- Inversely, the following namespaces are unsuppressed: main, file, mediawiki,
-- template, category, module

-- Default list of page suffixes in which to suppress categorization.
-- Adjust as needed!
local DEFAULT_SUPPRESSED_SUFFIXES = {
	"doc",
	"sandbox",
}

-- Helper function: check if current namespace is excluded
-- Accepts an optional table, containing or overriding other namespaces' rules
local function is_suppressed_namespace(ns_override)
	-- Get current namespace, as lowercase
	local curr_ns = mw.ustring.lower(mw.title.getCurrentTitle().nsText or '')
	
	-- Build table of suppressed namespaces; start with default list
	local namespaces = {}
	for k, v in pairs(DEFAULT_SUPPRESSED_NAMESPACES) do
		namespaces[k] = v
	end

	-- Then extend/override list using ns_override, if available
	if type(ns_override) == "table" then
		for k, v in pairs(ns_override) do
			namespaces[k] = v
		end
	end

	-- Return; if no namespace found, default to false
	return namespaces[curr_ns] or false
end

-- Helper function
-- Checks whether the page title ends in a suppressed suffix
-- Accepts an opiontal table, containing additional suffixes to suppress
-- Suffix and custom suffixes are lowercased to guarantee matching
local function has_suppressed_suffix(suffixes_override)
	local title = mw.title.getCurrentTitle()
	local pagename = mw.ustring.lower(title.text)

	-- Build table of suppressed suffixes, start with default suffixes
	local suffixes = {}
	for _, suffix in ipairs(DEFAULT_SUPPRESSED_SUFFIXES) do
		table.insert(suffixes, suffix)
	end

	-- Then append additional suffixes, if available (append, not replace)
	if type(suffixes_override) == "table" then
		for _, suffix in ipairs(suffixes_override) do
			table.insert(suffixes, suffix)
		end
	end

	-- Find and match suffix
	for _, suffix in ipairs(suffixes) do
		suffix = mw.ustring.lower(mw.text.trim(suffix or ''))	-- Also normalize
		if suffix ~= '' then
			local pattern = '/' .. mw.ustring.gsub(suffix, '([%^%$%(%)%%%.%[%]%*%+%-%?])', '%%%1') .. '$'
			if mw.ustring.match(pagename, pattern) then
				return true
			end
		end
	end

	return false
end

-- "Main" function; can be called by other modules
-- Categorizes a page, given a table of categories
-- Disallows categories if it's in a suppressed namespace or the page has a
-- suppressed suffix (subpage)
function p._category_handler(cats, ns_override, suffixes, is_debug)
	local cats = cats or {}
	local is_debug = yesno(is_debug, false)
	
	-- Test values; should be commented out for normal use
	--local cats = cats or {"Abstract MOS patterns", "7-tone scales"}
	--local ns_override = ns_override or { ["module"] = true }
	
	-- If in a suppressed namespace/prefix, or in debug mode (suppresses ALL
	-- categorization) don't bother
	if is_suppressed_namespace(ns_override) 
		or has_suppressed_suffix(suffixes)
		or is_debug then
		return ''
	end

	-- Otherwise, categorize
	local result = ''
	for _, cat in ipairs(cats) do
		cat = mw.text.trim(cat or '')
		if cat ~= '' then
			result = result .. string.format('[[Category:%s]]', cat)
		end
	end

	return result
end


-- Wrapper for templates calling via #invoke
function p.category_handler(frame)
	local args = getArgs(frame)
	local cats_unparsed        = args["categories" ] or ""
	local excluded_ns_unparsed = args["excluded_ns"] or ""
	local suffixes_unparsed    = args["suffixes"   ] or ""
	local is_debug = yesno(args["debug"], false)		-- Parse debug mode; setting this to TRUE disables all categories

	-- Parse categories
	local cats = {}
	for cat in mw.text.gsplit(cats_unparsed, "[,\n]") do
		cat = mw.text.trim(cat)
		if cat ~= "" then
			table.insert(cats, cat)
		end
	end

	-- Parse excluded namespaces
	-- These are added in addition to the default list
	-- This currently can't force-allow suppressed namespaces as template input,
	-- only disallow additional namespaces
	local ns_override = {}
	for ns in mw.text.gsplit(excluded_ns_unparsed, "[;\n]") do
		ns = mw.text.trim(ns)
		if ns ~= "" then
			ns_override[ns] = true
		end
	end

	-- Parse excluded suffixes
	local suffixes = {}
	for suffix in mw.text.gsplit(suffixes_unparsed, "[;\n]") do
		suffix = mw.text.trim(suffix)
		if suffix ~= "" then
			table.insert(suffixes, suffix)
		end
	end

	return p._category_handler(cats, ns_override, suffixes, is_debug)
end

return p