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 127 _category_handler (main) (cats, ns_override, is_debug) 157 category_handler (invokable) (frame)	Lua modules required (1) Variable Module Functions used 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 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

local DEFAULT_ALLOWED_NAMESPACES = {
    [""] = true,               -- mainspace
    ["template"] = true,
    ["module"] = true,
    ["file"] = true,
    ["category"] = true,
}

-- 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: check if current namespace is allowed
local function is_allowed_namespace(ns)
    ns = mw.ustring.lower(ns or "")
    return ALLOWED_NAMESPACES[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, is_debug)
    cats = cats or {}
    is_debug = yesno(is_debug, false)

    local frame = mw.getCurrentFrame()
    local parent_title = frame:getParent() and mw.title.new(frame:getParent():getTitle()) or mw.title.getCurrentTitle()

	-- Don't categorize if:
	-- - Debug mode is on (which turns off categories)
	-- - Page is in a suppressed namespace
	-- - Page is not a content page (EG, not /doc or /sandbox)
    if is_debug
        or is_suppressed_namespace(ns_override)
        or not is_allowed_namespace(parent_title.nsText)
    then
        return ''
    end

    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 = frame:getParent().args
	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, is_debug)
end

return p