Module:Category handler: Difference between revisions

Nothing to hide, but nothing to show you either.
Jump to navigation Jump to search
Content added Content deleted
(better fallback behaviour if we are over the expensive function count)
m (32 revisions imported from templatewiki:Module:Category_handler)
 
(24 intermediate revisions by 15 users not shown)
Line 1: Line 1:
----------------------------------------------------------------------
--------------------------------------------------------------------------------
-- --
-- --
-- CATEGORY HANDLER --
-- CATEGORY HANDLER --
-- --
-- --
-- This module implements the {{category handler}} template --
-- This module implements the {{category handler}} template in Lua, --
-- in Lua, with a few improvements: all namespaces and all --
-- with a few improvements: all namespaces and all namespace aliases --
-- namespace aliases are supported, and namespace names are --
-- are supported, and namespace names are detected automatically for --
-- detected automatically for the local wiki. This module --
-- the local wiki. This module requires [[Module:Namespace detect]] --
-- requires [[Module:Namespace detect]] to be available on --
-- and [[Module:Yesno]] to be available on the local wiki. It can be --
-- the local wiki. It can be configured for different wikis --
-- configured for different wikis by altering the values in --
-- [[Module:Category handler/config]], and pages can be blacklisted --
-- by altering the values in the "cfg" table. --
-- from categorisation by using [[Module:Category handler/blacklist]]. --
-- --
-- --
----------------------------------------------------------------------
--------------------------------------------------------------------------------


-- Load required modules
----------------------------------------------------------------------
local yesno = require('Module:Yesno')
-- Configuration data --
-- Language-specific parameter names and values can be set --
-- here. --
----------------------------------------------------------------------


-- Lazily load things we don't always need
local cfg = {}
local mShared, mappings


local p = {}
-- cfg.nocat is the parameter name to suppress categorisation.
-- cfg.nocatTrue is the value to suppress categorisation, and
-- cfg.nocatFalse is the value to both categorise and to skip the
-- blacklist check.
cfg.nocat = 'nocat'
cfg.nocatTrue = 'true'
cfg.nocatFalse = 'false'


--------------------------------------------------------------------------------
-- The parameter name for the legacy "categories" parameter. This
-- Helper functions
-- skips the blacklist if set to the cfg.category2Yes value, and
--------------------------------------------------------------------------------
-- suppresses categorisation if set to the cfg.categoriesNo value.
cfg.categories = 'categories'
cfg.categoriesYes = 'yes'
cfg.categoriesNo = 'no'


local function trimWhitespace(s, removeBlanks)
-- The parameter name for the legacy "category2" parameter. This
if type(s) ~= 'string' then
-- skips the blacklist if set to the cfg.category2Yes value, and
return s
-- suppresses categorisation if present but equal to anything other
end
-- than cfg.category2Yes or cfg.category2Negative.
s = s:match('^%s*(.-)%s*$')
cfg.category2 = 'category2'
if removeBlanks then
cfg.category2Yes = 'yes'
if s ~= '' then
cfg.category2Negative = '¬'
return s
else
return nil
end
else
return s
end
end


--------------------------------------------------------------------------------
-- cfg.subpage is the parameter name to specify how to behave on
-- CategoryHandler class
-- subpages. cfg.subpageNo is the value to specify to not
--------------------------------------------------------------------------------
-- categorise on subpages; cfg.only is the value to specify to only
-- categorise on subpages.
cfg.subpage = 'subpage'
cfg.subpageNo = 'no'
cfg.subpageOnly = 'only'


local CategoryHandler = {}
-- The parameter for data to return in all namespaces.
CategoryHandler.__index = CategoryHandler
cfg.all = 'all'


function CategoryHandler.new(data, args)
-- The parameter name for data to return if no data is specified for
local obj = setmetatable({ _data = data, _args = args }, CategoryHandler)
-- the namespace that is detected. This must be the same as the
-- cfg.other parameter in [[Module:Namespace detect]].
-- Set the title object
cfg.other = 'other'
do
local pagename = obj:parameter('demopage')
local success, titleObj
if pagename then
success, titleObj = pcall(mw.title.new, pagename)
end
if success and titleObj then
obj.title = titleObj
if titleObj == mw.title.getCurrentTitle() then
obj._usesCurrentTitle = true
end
else
obj.title = mw.title.getCurrentTitle()
obj._usesCurrentTitle = true
end
end


-- Set suppression parameter values
-- The parameter name used to specify a page other than the current
for _, key in ipairs{'nocat', 'categories'} do
-- page; used for testing and demonstration. This must be the same
local value = obj:parameter(key)
-- as the cfg.page parameter in [[Module:Namespace detect]].
value = trimWhitespace(value, true)
cfg.page = 'page'
obj['_' .. key] = yesno(value)
end
do
local subpage = obj:parameter('subpage')
local category2 = obj:parameter('category2')
if type(subpage) == 'string' then
subpage = mw.ustring.lower(subpage)
end
if type(category2) == 'string' then
subpage = mw.ustring.lower(category2)
end
obj._subpage = trimWhitespace(subpage, true)
obj._category2 = trimWhitespace(category2) -- don't remove blank values
end
return obj
end


function CategoryHandler:parameter(key)
-- The categorisation blacklist. Pages that match Lua patterns in this
local parameterNames = self._data.parameters[key]
-- list will not be categorised unless any of the following options are
local pntype = type(parameterNames)
-- set: "nocat=false", "categories=yes", or "category2=yes".
if pntype == 'string' or pntype == 'number' then
-- If the namespace name has a space in, it must be written with an
return self._args[parameterNames]
-- underscore, e.g. "Wikipedia_talk". Other parts of the title can have
elseif pntype == 'table' then
-- either underscores or spaces.
for _, name in ipairs(parameterNames) do
cfg.blacklist = {
local value = self._args[name]
'^Main Page$', -- don't categorise the main page.
if value ~= nil then
return value
-- Don't categorise the following pages or their subpages.
end
'^Wikipedia:Cascade%-protected items$',
end
'^Wikipedia:Cascade%-protected items/.*$',
return nil
'^User:UBX$', -- The userbox "template" space.
else
'^User:UBX/.*$',
error(string.format(
'^User_talk:UBX$',
'invalid config key "%s"',
'^User_talk:UBX/.*$',
tostring(key)
), 2)
-- Don't categorise subpages of these pages, but allow
end
-- categorisation of the base page.
end
'^Wikipedia:Template messages/.*$',
'/[aA]rchive' -- Don't categorise archives.
}


function CategoryHandler:isSuppressedByArguments()
-- This is a table of namespaces to categorise by default. They
return
-- should be in the format of parameter names accepted by
-- See if a category suppression argument has been set.
-- [[Module:Namespace detect]].
self._nocat == true
cfg.defaultNamespaces = {
or self._categories == false
'main',
or (
'file',
self._category2
'help',
and self._category2 ~= self._data.category2Yes
'category'
and self._category2 ~= self._data.category2Negative
}
)


-- Check whether we are on a subpage, and see if categories are
----------------------------------------------------------------------
-- suppressed based on our subpage status.
-- End configuration data --
or self._subpage == self._data.subpageNo and self.title.isSubpage
----------------------------------------------------------------------
or self._subpage == self._data.subpageOnly and not self.title.isSubpage
end


function CategoryHandler:shouldSkipBlacklistCheck()
-- Get [[Module:Namespace detect]] and declare the table of functions
-- Check whether the category suppression arguments indicate we
-- that we will return.
-- should skip the blacklist check.
local NamespaceDetect = require('Module:Namespace detect')
return self._nocat == false
local p = {}
or self._categories == true
or self._category2 == self._data.category2Yes
end


function CategoryHandler:matchesBlacklist()
----------------------------------------------------------------------
if self._usesCurrentTitle then
-- Local functions --
return self._data.currentTitleMatchesBlacklist
-- The following are internal functions, which we do not want --
else
-- to be accessible from other modules. --
mShared = mShared or require('Module:Category handler/shared')
----------------------------------------------------------------------
return mShared.matchesBlacklist(

self.title.prefixedText,
-- Find whether we need to return a category or not.
mw.loadData('Module:Category handler/blacklist')
local function needsCategory( pageObject, args )
)
-- Don't categorise if the relevant options are set.
end
if args[cfg.nocat] == cfg.nocatTrue
or args[cfg.categories] == cfg.categoriesNo
or ( args[cfg.category2]
and args[cfg.category2] ~= cfg.category2Yes
and args[cfg.category2] ~= cfg.category2Negative )
then
return false
end
-- If there is no pageObject available, then that either means that we are over
-- the expensive function limit or that the title specified was invalid. Invalid
-- titles will probably only be a problem during testing, so we choose the best
-- fallback for being over the expensive function limit. The fallback behaviour
-- of the old template was to assume the page was not a subpage, so we will do
-- the same here.
if args[cfg.subpage] == cfg.subpageNo and pageObject and pageObject.isSubpage then
return false
end
if args[cfg.subpage] == cfg.subpageOnly
and (not pageObject or (pageObject and not pageObject.isSubpage) ) then
return false
end
return true
end
end


function CategoryHandler:isSuppressed()
-- Find whether we need to check the blacklist or not.
-- Find if categories are suppressed by either the arguments or by
local function needsBlacklistCheck( args )
-- matching the blacklist.
if args[cfg.nocat] == cfg.nocatFalse
return self:isSuppressedByArguments()
or args[cfg.categories] == cfg.categoriesYes
or not self:shouldSkipBlacklistCheck() and self:matchesBlacklist()
or args[cfg.category2] == cfg.category2Yes then
return false
else
return true
end
end
end


function CategoryHandler:getNamespaceParameters()
-- Searches the blacklist to find a match with the page object. The
if self._usesCurrentTitle then
-- string searched is the namespace plus the title, including subpages.
return self._data.currentTitleNamespaceParameters
-- Returns true if there is a match, otherwise returns false.
else
local function findBlacklistMatch( pageObject )
if not pageObject then return end
if not mappings then
mShared = mShared or require('Module:Category handler/shared')
mappings = mShared.getParamMappings(true) -- gets mappings with mw.loadData
-- Get the title to check.
end
local title = pageObject.nsText -- Get the namespace.
return mShared.getNamespaceParameters(
-- Append a colon if the namespace isn't the blank string.
if #title > 0 then
self.title,
mappings
title = title .. ':' .. pageObject.text
)
else
end
title = pageObject.text
end
-- Check the blacklist.
for i, pattern in ipairs( cfg.blacklist ) do
if mw.ustring.match( title, pattern ) then
return true
end
end
return false
end
end


function CategoryHandler:namespaceParametersExist()
-- Find whether any namespace parameters have been specified.
-- Find whether any namespace parameters have been specified.
-- Mappings is the table of parameter mappings taken from
-- We use the order "all" --> namespace params --> "other" as this is what
-- [[Module:Namespace detect]].
-- the old template did.
local function nsParamsExist( mappings, args )
if args[cfg.all] or args[cfg.other] then
if self:parameter('all') then
return true
return true
end
end
for ns, params in pairs( mappings ) do
if not mappings then
mShared = mShared or require('Module:Category handler/shared')
for i, param in ipairs( params ) do
mappings = mShared.getParamMappings(true) -- gets mappings with mw.loadData
if args[param] then
end
return true
for ns, params in pairs(mappings) do
end
for i, param in ipairs(params) do
end
if self._args[param] then
end
return false
return true
end
end
end
if self:parameter('other') then
return true
end
return false
end
end


function CategoryHandler:getCategories()
-- The main structure of the module. Checks whether we need to categorise,
local params = self:getNamespaceParameters()
-- and then passes the relevant arguments to [[Module:Namespace detect]].
local function _main( args )
local nsCategory
for i, param in ipairs(params) do
-- Get the page object and argument mappings from
local value = self._args[param]
-- [[Module:Namespace detect]], to save us from having to rewrite the
if value ~= nil then
-- code.
nsCategory = value
local pageObject = NamespaceDetect.getPageObject( args[cfg.page] )
break
local mappings = NamespaceDetect.getParamMappings()
end
end
-- Check if we need a category or not, and return nothing if not.
if nsCategory ~= nil or self:namespaceParametersExist() then
if not needsCategory( pageObject, args ) then return end
-- Namespace parameters exist - advanced usage.
if nsCategory == nil then
local ret = '' -- The string to return.
nsCategory = self:parameter('other')
-- Check blacklist if necessary.
end
if not needsBlacklistCheck( args )
local ret = {self:parameter('all')}
or not findBlacklistMatch( pageObject ) then
local numParam = tonumber(nsCategory)
if numParam and numParam >= 1 and math.floor(numParam) == numParam then
if not nsParamsExist( mappings, args ) then
-- nsCategory is an integer
-- No namespace parameters exist; basic usage. Pass args[1] to
ret[#ret + 1] = self._args[numParam]
-- [[Module:Namespace detect]] using the default namespace
else
-- parameters, and return the result.
ret[#ret + 1] = nsCategory
local ndargs = {}
end
for _, ndarg in ipairs( cfg.defaultNamespaces ) do
if #ret < 1 then
ndargs[ndarg] = args[1]
return nil
end
else
ndargs.page = args.page
return table.concat(ret)
local ndresult = NamespaceDetect.main( ndargs )
end
if ndresult then
elseif self._data.defaultNamespaces[self.title.namespace] then
ret = ret .. ndresult
-- Namespace parameters don't exist, simple usage.
end
return self._args[1]
else
end
-- Namespace parameters exist; advanced usage.
return nil
-- If the all parameter is specified, return it.
if args.all then
ret = ret .. args.all
end
-- Get the arguments to pass to [[Module:Namespace detect]].
local ndargs = {}
for ns, params in pairs( mappings ) do
for _, param in ipairs( params ) do
ndargs[param] = args[param] or args[cfg.other] or nil
end
end
if args.other then
ndargs.other = args.other
end
if args.page then
ndargs.page = args.page
end
local data = NamespaceDetect.main( ndargs )
-- Work out what to return based on the result of the namespace
-- detect call.
local datanum = tonumber( data )
if type( datanum ) == 'number' then
-- "data" is a number, so return that positional parameter.
-- Remove non-positive integer values, as only positive integers
-- from 1-10 were used with the old template.
if datanum > 0
and math.floor( datanum ) == datanum
and args[datanum] then
ret = ret .. args[ datanum ]
end
else
-- "data" is not a number, so return it as it is.
if type(data) == 'string' then
ret = ret .. data
end
end
end
end
return ret
end
end


----------------------------------------------------------------------
--------------------------------------------------------------------------------
-- Exports
-- Global functions --
--------------------------------------------------------------------------------
-- The following functions are global, because we want them --
-- to be accessible from #invoke and from other Lua modules. --
-- At the moment only the main function is here. It processes --
-- the arguments and passes them to the _main function. --
----------------------------------------------------------------------


local p = {}
function p.main( frame )

-- If called via #invoke, use the args passed into the invoking
function p._exportClasses()
-- template, or the args passed to #invoke if any exist. Otherwise
-- Used for testing purposes.
-- assume args are being passed directly in.
return {
local origArgs
CategoryHandler = CategoryHandler
if frame == mw.getCurrentFrame() then
}
origArgs = frame:getParent().args
end
for k, v in pairs( frame.args ) do

origArgs = frame.args
function p._main(args, data)
break
data = data or mw.loadData('Module:Category handler/data')
end
local handler = CategoryHandler.new(data, args)
else
if handler:isSuppressed() then
origArgs = frame
return nil
end
end
return handler:getCategories()
end


function p.main(frame, data)
-- Trim whitespace and remove blank arguments for the following args:
data = data or mw.loadData('Module:Category handler/data')
-- 1, 2, 3 etc., "nocat", "categories", "subpage", and "page".
local args = {}
local args = require('Module:Arguments').getArgs(frame, {
wrappers = data.wrappers,
for k, v in pairs( origArgs ) do
valueFunc = function (k, v)
v = mw.text.trim(v) -- Trim whitespace.
v = trimWhitespace(v)
if type(k) == 'number'
if type(k) == 'number' then
or k == cfg.nocat
if v ~= '' then
or k == cfg.categories
return v
or k == cfg.subpage
else
or k == cfg.page then
return nil
if v ~= '' then
end
args[k] = v
else
end
return v
else
end
args[k] = v
end
end
})
end
return p._main(args, data)
-- Lower-case "nocat", "categories", "category2", and "subpage". These
-- parameters are put in lower case whenever they appear in the old
-- template, so we can just do it once here and save ourselves some work.
local lowercase = { cfg.nocat, cfg.categories, cfg.category2, cfg.subpage }
for _, v in ipairs( lowercase ) do
if args[v] then
args[v] = mw.ustring.lower( args[v] )
end
end
return _main( args )
end
end



Latest revision as of 18:08, 6 September 2020

Documentation for this module may be created at Module:Category handler/doc

--------------------------------------------------------------------------------
--                                                                            --
--                              CATEGORY HANDLER                              --
--                                                                            --
--      This module implements the {{category handler}} template in Lua,      --
--      with a few improvements: all namespaces and all namespace aliases     --
--      are supported, and namespace names are detected automatically for     --
--      the local wiki. This module requires [[Module:Namespace detect]]      --
--      and [[Module:Yesno]] to be available on the local wiki. It can be     --
--      configured for different wikis by altering the values in              --
--      [[Module:Category handler/config]], and pages can be blacklisted      --
--      from categorisation by using [[Module:Category handler/blacklist]].   --
--                                                                            --
--------------------------------------------------------------------------------

-- Load required modules
local yesno = require('Module:Yesno')

-- Lazily load things we don't always need
local mShared, mappings

local p = {}

--------------------------------------------------------------------------------
-- Helper functions
--------------------------------------------------------------------------------

local function trimWhitespace(s, removeBlanks)
	if type(s) ~= 'string' then
		return s
	end
	s = s:match('^%s*(.-)%s*$')
	if removeBlanks then
		if s ~= '' then
			return s
		else
			return nil
		end
	else
		return s
	end
end

--------------------------------------------------------------------------------
-- CategoryHandler class
--------------------------------------------------------------------------------

local CategoryHandler = {}
CategoryHandler.__index = CategoryHandler

function CategoryHandler.new(data, args)
	local obj = setmetatable({ _data = data, _args = args }, CategoryHandler)
	
	-- Set the title object
	do
		local pagename = obj:parameter('demopage')
		local success, titleObj
		if pagename then
			success, titleObj = pcall(mw.title.new, pagename)
		end
		if success and titleObj then
			obj.title = titleObj
			if titleObj == mw.title.getCurrentTitle() then
				obj._usesCurrentTitle = true
			end
		else
			obj.title = mw.title.getCurrentTitle()
			obj._usesCurrentTitle = true
		end
	end

	-- Set suppression parameter values
	for _, key in ipairs{'nocat', 'categories'} do
		local value = obj:parameter(key)
		value = trimWhitespace(value, true)
		obj['_' .. key] = yesno(value)
	end
	do
		local subpage = obj:parameter('subpage')
		local category2 = obj:parameter('category2')
		if type(subpage) == 'string' then
			subpage = mw.ustring.lower(subpage)
		end
		if type(category2) == 'string' then
			subpage = mw.ustring.lower(category2)
		end
		obj._subpage = trimWhitespace(subpage, true)
		obj._category2 = trimWhitespace(category2) -- don't remove blank values
	end
	return obj
end

function CategoryHandler:parameter(key)
	local parameterNames = self._data.parameters[key]
	local pntype = type(parameterNames)
	if pntype == 'string' or pntype == 'number' then
		return self._args[parameterNames]
	elseif pntype == 'table' then
		for _, name in ipairs(parameterNames) do
			local value = self._args[name]
			if value ~= nil then
				return value
			end
		end
		return nil
	else
		error(string.format(
			'invalid config key "%s"',
			tostring(key)
		), 2)
	end
end

function CategoryHandler:isSuppressedByArguments()
	return
		-- See if a category suppression argument has been set.
		self._nocat == true
		or self._categories == false
		or (
			self._category2
			and self._category2 ~= self._data.category2Yes
			and self._category2 ~= self._data.category2Negative
		)

		-- Check whether we are on a subpage, and see if categories are
		-- suppressed based on our subpage status.
		or self._subpage == self._data.subpageNo and self.title.isSubpage
		or self._subpage == self._data.subpageOnly and not self.title.isSubpage
end

function CategoryHandler:shouldSkipBlacklistCheck()
	-- Check whether the category suppression arguments indicate we
	-- should skip the blacklist check.
	return self._nocat == false
		or self._categories == true
		or self._category2 == self._data.category2Yes
end

function CategoryHandler:matchesBlacklist()
	if self._usesCurrentTitle then
		return self._data.currentTitleMatchesBlacklist
	else
		mShared = mShared or require('Module:Category handler/shared')
		return mShared.matchesBlacklist(
			self.title.prefixedText,
			mw.loadData('Module:Category handler/blacklist')
		)
	end
end

function CategoryHandler:isSuppressed()
	-- Find if categories are suppressed by either the arguments or by
	-- matching the blacklist.
	return self:isSuppressedByArguments()
		or not self:shouldSkipBlacklistCheck() and self:matchesBlacklist()
end

function CategoryHandler:getNamespaceParameters()
	if self._usesCurrentTitle then
		return self._data.currentTitleNamespaceParameters
	else
		if not mappings then
			mShared = mShared or require('Module:Category handler/shared')
			mappings = mShared.getParamMappings(true) -- gets mappings with mw.loadData
		end
		return mShared.getNamespaceParameters(
			self.title,
			mappings
		)
	end
end

function CategoryHandler:namespaceParametersExist()
	-- Find whether any namespace parameters have been specified.
	-- We use the order "all" --> namespace params --> "other" as this is what
	-- the old template did.
	if self:parameter('all') then
		return true
	end
	if not mappings then
		mShared = mShared or require('Module:Category handler/shared')
		mappings = mShared.getParamMappings(true) -- gets mappings with mw.loadData
	end
	for ns, params in pairs(mappings) do
		for i, param in ipairs(params) do
			if self._args[param] then
				return true
			end
		end
	end
	if self:parameter('other') then
		return true
	end
	return false
end

function CategoryHandler:getCategories()
	local params = self:getNamespaceParameters()
	local nsCategory
	for i, param in ipairs(params) do
		local value = self._args[param]
		if value ~= nil then
			nsCategory = value
			break
		end
	end
	if nsCategory ~= nil or self:namespaceParametersExist() then
		-- Namespace parameters exist - advanced usage.
		if nsCategory == nil then
			nsCategory = self:parameter('other')
		end
		local ret = {self:parameter('all')}
		local numParam = tonumber(nsCategory)
		if numParam and numParam >= 1 and math.floor(numParam) == numParam then
			-- nsCategory is an integer
			ret[#ret + 1] = self._args[numParam]
		else
			ret[#ret + 1] = nsCategory
		end
		if #ret < 1 then
			return nil
		else
			return table.concat(ret)
		end
	elseif self._data.defaultNamespaces[self.title.namespace] then
		-- Namespace parameters don't exist, simple usage.
		return self._args[1]
	end
	return nil
end

--------------------------------------------------------------------------------
-- Exports
--------------------------------------------------------------------------------

local p = {}

function p._exportClasses()
	-- Used for testing purposes.
	return {
		CategoryHandler = CategoryHandler
	}
end

function p._main(args, data)
	data = data or mw.loadData('Module:Category handler/data')
	local handler = CategoryHandler.new(data, args)
	if handler:isSuppressed() then
		return nil
	end
	return handler:getCategories()
end

function p.main(frame, data)
	data = data or mw.loadData('Module:Category handler/data')
	local args = require('Module:Arguments').getArgs(frame, {
		wrappers = data.wrappers,
		valueFunc = function (k, v)
			v = trimWhitespace(v)
			if type(k) == 'number' then
				if v ~= '' then
					return v
				else
					return nil
				end
			else
				return v
			end
		end
	})
	return p._main(args, data)
end

return p