Module:Sandbox/Nihiltres/Category manager

This module implements a simple tool for managing category output in modules.

Usage

The module cannot be used from wikitext. It can be imported to another module using code similar to the following:

local catMan = require("Module:Category manager")

Category-list table format

Each function in the module takes a table as its first parameter, and that table is used as the list of categories. These tables are assumed to only be manipulated by this module's functions, but there is no protection against external manipulation; there's just basic type/value validation. Each item in a category-list table has its category name (without prefix) as its key; duplicate categories are therefore impossible. Values for each key can either be true (no sort key) or a string containing that sort key. A false value or any other type of value will cause errors. There are three functions for manipulating a category list table, and their individual documentation follows.

Functions

addCategory

Usage:

• catMan.addCategory(catList, name)
• catMan.addCategory(catList, name, sortKey)

The addCategory function adds a category by setting the key from name in the catList table to either true or the provided sortKey value if present.

If an existing category is added a second time, its value will be overwritten with the new value; for this reason the module does not include a separate function for setting sort keys.

The catList parameter must be a table, the name parameter must be a non-empty, non-whitespace string, and sortKey must be either a string or nil.

removeCategory

Usage:

• catMan.removeCategory(catList, name)

The removeCategory function removes a category by setting the key from name to nil in the catList table.

The catList parameter must be a table, and the name parameter must be a non-empty, non-whitespace string.

writeCategoryList

Usage:

• catMan.writeCategoryList(catList)
• catMan.writeCategoryList(catList, nullify)

The writeCategoryList function produces a string containing all the categories in the table formatted as wikitext. Optionally, a boolean nullify parameter may be provided, and if true, it will cause the function to output an empty string. This is useful as it makes it easy to disable category output through a parameter, probably in conjunction with Module:Yesno.

The catList parameter must be a table formatted according to the category-list table format, and the nullify parameter must be either a boolean or nil.

---

local checkType = require('libraryUtil').checkType
local p = {}

--Global strings and forms
local defaults = {
	badCatListFormat = "Bad category list format (key: %s, value: %s)",
	categoryForm = "[[Category:%s]]",
	keyedCategoryForm = "[[Category:%s|%s]]",
	missingNameMsg = "Missing category name"
}

--Adds a category to the provided category list; sortKey is optional
function p.addCategory(catList, name, sortKey)
	--Check and normalize parameters
	checkType('addCategory', 1, catList, 'table')
	checkType('addCategory', 2, name, 'string')
	name = mw.text.trim(name)
	checkType('addCategory', 3, sortKey, 'string', true)
	if #name == 0 then error(defaults.missingNameMsg, 2) end
	if sortKey == nil or #sortKey == 0 then sortKey = nil end

	--Add category to category list
	catList[name] = sortKey or true
end

--Removes a category from the provided category list
function p.removeCategory(catList, name)
	--Check and normalize parameters
	checkType('removeCategory', 1, catList, 'table')
	checkType('removeCategory', 2, name, 'string')
	name = mw.text.trim(name)
	if #name == 0 then error(defaults.missingNameMsg, 2) end

	--Remove category from category list
	catList[name] = nil
end

--Converts a category list to a string containing its categories as wikitext
function p.writeCategoryList(catList, nullify)
	checkType('removeCategory', 1, catList, 'table')
	checkType('removeCategory', 2, name, 'boolean', true)

	if nullify then return "" end
	
	local constructedList = {}
	for k, v in pairs(catList) do
		if (
			type(k) ~= "string" or
			(
				(type(v) ~= "boolean" or v == false) and
				(type(v) ~= "string")
			)
		) then
			error(
				string.format(
					defaults.badCatListFormat,
					mw.dumpObject(k),
					mw.dumpObject(v)
				),
				2
			)	
		end
		table.insert(
			constructedList,
			(v == true) and
				string.format(defaults.categoryForm, k) or
				string.format(defaults.keyedCategoryForm, k, v)
		)
	end
	return table.concat(constructedList)
end

return p