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
(add the rest of the features, improve the comments)
m (32 revisions imported from templatewiki:Module:Category_handler)
 
(29 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.
-- Helper functions
cfg.categories = 'categories'
--------------------------------------------------------------------------------
cfg.categoriesYes = 'yes'


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


function CategoryHandler:isSuppressedByArguments()
-- This is a table of namespaces to categorise by default.
return
cfg.defaultNamespaces = {
-- See if a category suppression argument has been set.
0, -- Main
self._nocat == true
6, -- File
or self._categories == false
12, -- Help
or (
14 -- Category
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.
-- 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 dependent modules and declare the table of functions that we will
-- Check whether the category suppression arguments indicate we
-- 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 )
)
-- If there is no pageObject available, then that either means that we are over
end
-- the expensive function limit or that the title specified was invalid. Invalid
-- titles will probably only be a problem during testing, so choose the best
-- default for being over the expensive function limit, i.e. categorise the page.
if not pageObject then
return true
end
-- Only categorise if the relevant options are set.
if args[cfg.nocat] == cfg.nocatTrue
or ( args[cfg.category2] and args[cfg.category2] ~= cfg.category2Yes )
or ( args[cfg.subpage] == cfg.subpageNo and pageObject.isSubpage )
or ( args[cfg.subpage] == cfg.subpageOnly and not pageObject.isSubpage ) then
return false
else
return true
end
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()
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')
if needsBlacklistCheck( args ) and not findBlacklistMatch( pageObject ) then
end
if not nsParamsExist( mappings, args ) then
local ret = {self:parameter('all')}
-- No namespace parameters exist; basic usage.
local numParam = tonumber(nsCategory)
local ndargs = {}
if numParam and numParam >= 1 and math.floor(numParam) == numParam then
for _, nsid in ipairs( cfg.defaultNamespaces ) do
-- nsCategory is an integer
ndargs[ mw.ustring.lower( mw.site.namespaces[ nsid ].name ) ] = args[1]
ret[#ret + 1] = self._args[numParam]
end
else
ndargs.page = args.page
ret[#ret + 1] = nsCategory
local ndresult = NamespaceDetect.main( ndargs )
end
if ndresult then
if #ret < 1 then
ret = ret .. ndresult
return nil
end
else
else
return table.concat(ret)
-- Namespace parameters exist; advanced usage.
end
-- If the all parameter is specified, return it.
elseif self._data.defaultNamespaces[self.title.namespace] then
if args.all then
-- Namespace parameters don't exist, simple usage.
ret = ret .. args.all
return self._args[1]
end
end
return nil
-- 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