Module:Category handler

This module implements the {{category handler}} template. The category handler template helps other templates to automate both categorization and category suppression. For information about using the category handler template in other templates, please see the template documentation. Keep reading for information about using the category handler module in other Lua modules, or for information on exporting this module to other wikis.

Use from other Lua modules

When not to use this module

For cases where a module only needs to categorise in one of the namespaces main (articles), file (images) or category, then using this module is overkill. Instead, you can simply get a title object using mw.title.getCurrentTitle and check the nsText field. For example:

local title = mw.title.getCurrentTitle()
if title.nsText == 'File' then
    -- do something
end

However, if your module needs to categorize in any other namespace, then we recommend you use this module, since it provides proper category suppression and makes it easy to select how to categorize in the different namespaces.

Namespaces

This module detects and groups all the different namespaces used on Wikipedia into several types. These types are used as parameter names in this module.

main = Main/article space, as in normal Wikipedia articles.

talk = Any talk space, such as page names that start with "Talk:", "User talk:", "File talk:" and so on.

user, wikipedia, file ... = The other namespaces except the talk pages. Namespace aliases are also accepted. See the table below for the full list.

other = Any namespaces that were not specified as a parameter to the template. See examples below.

List of possible namespace parameters

(excluding talk and other)

Namespace	Aliases
main
user
n8	project
file	image
mediawiki
template
help
category
property
concept
forum
smw/schema
module
update
gswiki
guild
pilot
item
mission
guide
character
ship
attribute
transcript

Basic usage

This module takes two or more parameters. Here's an example using a hello world program:

p = {}
local categoryHandler = require( 'Module:Category handler' ).main
 
function p.main( frame )
    local result = 'Hello world!'
    local category = categoryHandler{
        '[[Category:Somecat]]',
        nocat = frame.args.nocat -- So "nocat=true/false" works
    }
    category = category or '' -- Check that we don't have a nil value for the category variable.
    return result .. category
end
 
return p

The above example uses the default settings for the category handler module. That means the example module will categorize on pages in the following namespaces:

main, file, help, category, portal and book

But it will not categorize in any other namespaces, e.g.:

talk, user, wikipedia, mediawiki, template ...

And it will not categorize on blacklisted pages. (See section blacklist below.)

The reason the category handler module does not categorize in some of the namespaces is that in those namespaces most modules and templates are just demonstrated or listed, not used. Thus most modules and templates should not categorize in those namespaces.

Any module or template that is meant for one or more of the namespaces where this module categorizes can use the basic syntax as shown above.

Advanced usage

This module takes one or more parameters named after the different page types as listed in section namespaces above. By using those parameters you can specify exactly in which namespaces your template should categorize. Like this:

p = {}
local categoryHandler = require( 'Module:Category handler' ).main
 
function p.main( frame )
    local result = 'This is a module meant for articles and talk pages.'
    local category = categoryHandler{
        main = '[[Category:Somecat1]]', -- Categorize in main (article) space
        talk = '[[Category:Somecat2]]', -- Categorize in talk space
        nocat = frame.args.nocat -- So "nocat=true/false" works
    }
    category = category or '' -- Check that we don't have a nil value for the category variable.
    return result .. category
end
 
return p

The above module will only categorize in main and talk space. But it will not categorize on /archive pages since they are blacklisted. (See section blacklist below.) And if you need to demonstrate (discuss) the module on a talkpage, then you can feed "nocat='true'" to prevent that template from categorizing. (See section nocat below.) Like this:

== My new module ==
Hey guys, have you seen my new module?
{{#invoke:mymodule|main|nocat=true}}
Nice, isn't it?
--~~~~

Sometimes we want to use the same category in several namespaces, then do like this:

p = {}
local categoryHandler = require( 'Module:Category handler' ).main
 
function p.main( frame )
    local result = 'This is a module used in several namespaces.'
    local category = categoryHandler{
        main = '[[Category:Somecat1]]',
        [ 1 ] = '[[Category:Somecat2]]', -- For help and user space
        help = 1,
        user = 1,
        talk = '', -- No categories on talk pages
        other = '[[Category:Somecat3]]', -- For all other namespaces
        nocat = frame.args.nocat -- So "nocat=true/false" works
    }
    category = category or '' -- Check that we don't have a nil value for the category variable.
    return result .. category
end
 
return p

In the above example we use a numbered parameter to feed one of the categories, and then we tell this module to use that numbered parameter for both the help and user space.

The category handler module understands an unlimited number of numbered parameters.

The other parameter defines what should be used in the remaining namespaces that have not explicitly been fed data.

Note the empty but defined talk parameter. That stops this module from showing what has been fed to the other parameter, when in talk space.

The category handler module also has a parameter called all. It works like this:

p = {}
local categoryHandler = require( 'Module:Category handler' ).main
 
function p.main( frame )
    local result = 'This is a module used in all namespaces.'
    local category = categoryHandler{
        all = '[[Category:Somecat1]]', -- Categorize in all namespaces
        nocat = frame.args.nocat -- So "nocat=true/false" works
    }
    category = category or '' -- Check that we don't have a nil value for the category variable.
    return result .. category
end
 
return p

The above example will categorize in all namespaces, but not on blacklisted pages. If you want to demonstrate that module on a page, then use "nocat=true" to prevent the template from categorizing.

We suggest avoiding the all parameter, since modules and templates should preferably only categorize in the namespaces they need to.

The all parameter can also be combined with the rest of the parameters. Like this:

p = {}
local categoryHandler = require( 'Module:Category handler' ).main
 
function p.main( frame )
    local result = 'This is a module used in all namespaces.'
    local category = categoryHandler{
        all = '[[Category:Somecat1]]', -- Categorize in all namespaces
        main = '[[Category:Somecat2]]', -- And add this in main space
        other = '[[Category:Somecat3]]', -- And add this in all other namespaces
        nocat = frame.args.nocat -- So "nocat=true/false" works
    }
    category = category or '' -- Check that we don't have a nil value for the category variable.
    return result .. category
end
 
return p

If the above module is placed on an article, then it will add the categories "Somecat1" and "Somecat2". But on all other types of pages it will instead add "Somecat1" and "Somecat3". As the example shows, the all parameter works independently of the rest of the parameters.

Subpages

The category handler module understands the subpage parameter. Like this:

p = {}
local categoryHandler = require( 'Module:Category handler' ).main
 
function p.main( frame )
    local result = 'This is a module used in all namespaces.'
    local category = categoryHandler{
        subpage = 'no' -- Don't categorize on subpages
        wikipedia = '[[Category:Somecat]]',
        nocat = frame.args.nocat -- So "nocat=true/false" works
    }
    category = category or '' -- Check that we don't have a nil value for the category variable.
    return result .. category
end
 
return p

If "subpage='no'" then this template will not categorize on subpages. For the rare occasion you only want to categorize on subpages, then use "subpage='only'". If subpage is empty or undefined then this template categorizes both on basepages and on subpages.

Blacklist

This module has a blacklist of the pages and page types where templates should not auto-categorize. Thus modules that use this meta-template will for instance not categorize on /archive pages and on the subpages of Wikipedia:Template messages.

If you want a template to categorize on a blacklisted page, then feed "nocat = false" to the module when you place it on the page, thus skipping the blacklist check. Note that this module only categorizes if it has data for the namespace. For instance, if the basic syntax is used (see basic usage above), then even if you set "nocat = false" the template will not categorize on a talk page, since it has no data for talk pages. But it has data for help space, so on a blacklisted help page it will categorize.

The blacklist is located in the configuration table cfg.blacklist near the top of the module code.

The "nocat" parameter

This module understands the nocat parameter:

• If "nocat = true" then this template does not categorize.
• If nocat is nil then this template categorizes as usual.
• If "nocat = false" this template categorizes even when on blacklisted pages. (See section blacklist above.)
• The nocat parameter also accepts aliases for true and false as defined by Module:Yesno, e.g. "yes", "y", "true", and 1 for true, and "no", "n", "false", and 0 for false.

Modules and templates that use {{category handler}} should forward nocat, so they too understand nocat. The code "nocat = frame.args.nocat" shown in the examples on this page does that.

The "categories" parameter

For backwards compatibility this module also understands the categories parameter. It works the same as nocat. Like this:

• If "categories = false" then this template does not categorize.
• If categories is empty or undefined then this template categorizes as usual.
• If "categories = true" this template categorizes even when on blacklisted pages.
• The categories parameter also accepts aliases for true and false as defined by Module:Yesno, e.g. "yes", "y", "true", and 1 for true, and "no", "n", "false", and 0 for false.

The "category2" parameter

For backwards compatibility this template kind of supports the old "category =" parameter. But the parameter name "category" is already used in this module to feed category data for when in category space. So instead this template uses category2 for the usage similar to nocat. Like this:

• If "category2 = "" (empty but defined), or "category2 = 'no'", or if category2 is fed any other data (except as described in the next two points), then this template does not categorize.
• If category2 is undefined or if "category2 = '¬'", then this template categorizes as usual.
• If "category2 = 'yes'" this template categorizes even when on blacklisted pages.

Categories and text

Besides from categories, you can feed anything else to this module, for instance some text. Like this:

p = {}
local categoryHandler = require( 'Module:Category handler' ).main

function p.main( frame )
    local result = 'This is a module used on talk pages.'
    local category = categoryHandler{
        talk = '[[Category:Somecat]]',
        other = '<p class="error">This module should only be used on talk pages.</p>',
        nocat = frame.args.nocat -- So "nocat=true/false" works
    }
    category = category or '' -- Check that we don't have a nil value for the category variable.
    return result .. category
end

return p

When the module code above is used on anything other than a talk page, it will look like this:

This is a module used on talk pages.

That text will not show on blacklisted pages, so don't use this method to show any important information. Feeding "nocat = 'true'" to the template hides the text, just as it suppresses any categories.

The "page" parameter

For testing and demonstration purposes this module can take a parameter named page. Like this:

p = {}
local categoryHandler = require( 'Module:Category handler' ).main
 
function p.main( frame )
    local category = categoryHandler{
        main = 'Category:Some cat',
        talk = 'Category:Talk cat',
        nocat = frame.args.nocat, -- So "nocat=true/false" works
        page = 'User talk:Example'
    }
    return category
end
 
return p

In the above code we on purpose left out the brackets around the category names so we see the output on the page. No matter on what kind of page the code above is used it will return this:

The page parameter makes this module behave exactly as if on that page. Even the blacklist works. The pagename doesn't have to be an existing page.

If the page parameter is empty or undefined, the name of the current page determines the result.

You can make it so your module also understands the page parameter. That means you can test how your template will categorize on different pages, without having to actually edit those pages. Then do like this:

p = {}
local categoryHandler = require( 'Module:Category handler' ).main

function p.main( frame )
    local category = categoryHandler{
        main = 'Category:Some cat',
        talk = 'Category:Talk cat',
        nocat = frame.args.nocat, -- So "nocat=true/false" works
        page = frame.args.page -- For testing
    }
    return category
end

return p

Parameters

List of all parameters:

• First positional parameter - for default settings
• subpage = 'no' / 'only'
• 1, 2, 3 ...
• all = '[[Category:Somecat]]' / 'Text'
• main = 1, 2, 3 ... / '[[Category:Somecat]]' / 'Text'
• ...
• other = 1, 2, 3 ... / '[[Category:Somecat]]' / 'Text'
• nocat = frame.args.nocat / true / false / 'yes' / 'no' / 'y' / 'n' / 'true' / 'false' / 1 / 0
• categories = frame.args.categories / false / true / 'no' / 'yes' / 'n' / 'y' / 'false' / 'true' / 0 / 1
• category2 = frame.args.category or '¬' / 'no' / 'not defined' / '¬' / 'yes'
• page = frame.args.page / 'User:Example'

Note that empty values to the "main" ... "other" parameters have special meaning (see examples above). The "all" parameter doesn't understand numbered parameters, since there should never be a need for that.

Exporting to other wikis

This module can be exported to other wikis by changing the configuration values in the cfg table. All the variable values are configurable, so after the configuration values have been set there should be no need to alter the main module code. Details of each configuration value are included in the module code comments. In addition, this module requires Module:Namespace detect to be available on the local wiki.

See also

• {{Category handler}} – for using this module with templates, rather than Lua modules.
• Wikipedia:Category suppression – The how-to guide.
• Wikipedia:WikiProject Category Suppression – The WikiProject.
• Wikipedia:Namespace – Lists all the namespaces.

---

--[=[ <pre>
-- Implements [Template:Ctg]
-- Sorts pages into a category more appropriately than pagename alone
-- Default and custom rules are outlined at [[Template:Category handler/doc]]
--]=]

local p = {}

local ucf = require('Module:Paramtest').ucfirst

local curpage = mw.title.getCurrentTitle()

function p.main(frame)
	local ns = curpage.namespace

	-- Just don't bother unless we're in content namespaces
	if not (ns == 0 or ns == 120) then
		return ''
	end

	local args = frame:getParent().args 
	local cats = {}

	for _, v in ipairs(args) do
		local cat_x = {}

		-- Replace underscores with spaces
		-- Condense and trim white-space; remove new lines (just in case)
		v = mw.text.trim(v)
			:gsub('[_%s]+',' ')
			:gsub('\n','')

		-- Snip category name now, up to the index of the first set of two colons
		-- If no colons, just use the whole string
		local cat_n = (v:match('^([^:]+)::') or v)
				:gsub('[Cc]ategory:%s*','')

		-- Set category name to the name just snipped
		cat_x.name = cat_n

		-- Page title includes matched text
		-- Matched text is defined by ::ifmatches[text]
		-- or if empty, defaults to category name
		if v:find('::ifmatches') then
			-- Look for brackets used as delimiters and capture them all
			local match_set = v:match('::ifmatches(%[[^:]+%])')

			-- If none are found, use the pagename
			if not match_set then
				cat_x.ifmatch = {cat_n}
			else
				cat_x.ifmatch = {}
				-- Split match into table, delimited by brackets
				match_set = mw.text.split(match_set,'[%]%[]+')

				-- Add to match table; only if not blank
				-- An empty string is created by "[" at the beginning
				for _, w in ipairs(match_set) do
					if w:find('%S') then
						table.insert(cat_x.ifmatch,w)
					end
				end
			end

			-- Iterate through and escape all metacharacters
			-- Prevents errors when they're passed to string.match() below
			-- Make everything lowercase
			for i, w in ipairs(cat_x.ifmatch) do
				cat_x.ifmatch[i] = w:gsub(
						-- Chars: - ^ $ * ( ) + ?
						'([%-^$*()+?])',
						'%%%1'):lower()
			end
		end

		-- Text to strip from the front of the sort
		-- Can be user defined with ::remove[text]
		-- Defaults to category name exactly
		-- Escape metacharacters to prevent errors when they're passed to string.match() below
		cat_x.trim = string.gsub(
				v:match('::remove%[%s*([^]:]+)%s*%]') or
					cat_n,
					-- Chars: - ^ $ * ( ) + ?
					'([%-^$*()+?])',
					'%%%1')

		-- Add category and its rules into the list
		table.insert(cats,cat_x)
	end

	return p._main(cats)
end

function p._main(cat_list)
	-- Pagename, exactly, in all lowercase, and escaped (used for matching)
	local pagename = curpage.text
	local pagelc = pagename:lower()
	local pageesc = pagelc:gsub(
				-- Chars: - ^ $ * ( ) + ?
				'([%-^$*()+?])',
				'%%%1')
	-- Return table
	local ctg = {}

	for _, v in ipairs(cat_list) do
		-- Category name and in lowercase
		local cn = v.name
		local cnl = cn:lower()
		-- Text to remove
		local rmv = v.trim:lower()

		-- Little thing that checks pagename against everything in the matches table
		-- If there's no table, keep as false (it won't matter)
		local pagematches = false
		if v.ifmatch then
			for _, w in ipairs(v.ifmatch) do
				-- Look for exact match, and with faux-singular too
				if pagelc:find(w) or
				(w:find('s$') and 
					pagelc:find(w:match('(.*)s$')))
				then
					pagematches = true
				end
			end
		end

		-- Create a second string that counts as the singular of the text to remove
		-- If it works as a singular, and the page name is singular, then use it too
		-- Otherwise, just make it the same as rmv
		local rmvpl = rmv
		if rmv:find('s$') then
			rmvpl = rmv:match('(.*)s$')
			if pagelc:find('^'..rmvpl) and
			(not pagelc:find('^'..rmv))
			then
				-- Nothing
			else
				rmvpl = rmv
			end
		end

		-- If v.ifmatch is not specified or
		-- It is and the pattern matches any part of the pagename
		-- Continue to add categories
		if (not v.ifmatch) or
			(v.ifmatch and pagematches)
		then
			-- If the pagename matches category name exactly
			-- Or either is a simple plural of the other
			-- Or the text to remove exactly
			-- Sort to front
			if pagelc:find('^'..cnl..'$') or
				cnl:find('^'..pageesc..'s$') or
				pagelc:find('^'..cnl..'s$') or
				pagelc:find('^'..rmv..'$')
			then
				table.insert(ctg,string.format('[[Category:%s| ]]',cn))

			-- If the pagename begins with the category name
			-- Sort with beginning remove
			elseif pagelc:find('^'..rmv) or 
				pagelc:find('^'..rmvpl)
			then
				-- Offset by an extra character if it's not plural
				-- Or the page starts with plural
				if rmvpl == rmv then
					offset = 1
				else
					offset = 0
				end

				-- Unescape metacharacters for proper length
				local key = pagename:sub( #(rmv:gsub('%%','')) + offset )

				key = ucf(mw.text.trim(key))

				-- Remove punctuation from start if leftover
				-- Such as "/" leftover on subpages
				-- Or "(" for disambiguated pages
				if key:find('^%p') then
					key = ucf(key:sub(2))
				-- Just in case, remove "s" preceding punctuation
				elseif key:find('^S%p') then
					key = ucf(key:sub(3))
				end

				table.insert(ctg,string.format('[[Category:%s|%s]]',cn,key))

			-- Everything else just gets the category added plainly
			else
				table.insert(ctg,string.format('[[Category:%s]]',cn))
			end
		end
	end

	return table.concat(ctg)
end

return p