Module:Category handler

----------------------------------------------------------------------------------------------------------
--                                                                                                      --
--                                          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 the "cfg" table.                                                      --
--                                                                                                      --
----------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------------
--                                          Configuration data                                          --
--                      Language-specific parameter names and values can be set here.                   --
----------------------------------------------------------------------------------------------------------

local cfg = {}

-- The following config values set the names of parameters that suppress categorisation. They are used
-- with Module:Yesno, and work as follows:
--
-- cfg.nocat:
-- Result of yesno(args[cfg.nocat])         Effect
-- true                                     Categorisation is suppressed
-- false                                    Categorisation is allowed, and the blacklist check is skipped
-- nil                                      Categorisation is allowed
--
-- cfg.categories:
-- Result of yesno(args[cfg.categories])    Effect
-- true                                     Categorisation is allowed, and the blacklist check is skipped
-- false                                    Categorisation is suppressed
-- nil                                      Categorisation is allowed
cfg.nocat = 'nocat'    
cfg.categories = 'categories'

-- The parameter name for the legacy "category2" parameter. This skips the blacklist if set to the
-- cfg.category2Yes value, and suppresses categorisation if present but equal to anything other than
-- cfg.category2Yes or cfg.category2Negative.
cfg.category2 = 'category2'
cfg.category2Yes = 'yes'
cfg.category2Negative = '¬'

-- cfg.subpage is the parameter name to specify how to behave on 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'

-- The parameter for data to return in all namespaces.
cfg.all = 'all'

-- The parameter name for data to return if no data is specified for the namespace that is detected. This
-- must be the same as the cfg.other parameter in [[Module:Namespace detect]].
cfg.other = 'other'

-- The parameter name used to specify a page other than the current page; used for testing and
-- demonstration. This must be the same as the cfg.page parameter in [[Module:Namespace detect]].
cfg.page = 'page'

-- The categorisation blacklist. Pages that match Lua patterns in this list will not be categorised.
-- (However, see the explanation of cfg.nocat, cfg.categories and cfg.category2 for some exceptions.)
-- If the namespace name has a space in, it must be written with an underscore, e.g. "Wikipedia_talk".
-- Other parts of the title can have either underscores or spaces.
cfg.blacklist = {
	'^Main Page$', -- don't categorise the main page.
	'/[aA]rchive' -- Don't categorise archives.
}

-- This is a table of namespaces to categorise by default. They should be in the format of parameter
-- names accepted by [[Module:Namespace detect]].
cfg.defaultNamespaces = {
	'main',
	'file',
	'help',
	'category'
}

----------------------------------------------------------------------------------------------------------
--                                          End configuration data                                      --
----------------------------------------------------------------------------------------------------------

-- Get dependent modules
local nsDetect = require('Module:Namespace detect')
local yesno = require('Module:Yesno')

----------------------------------------------------------------------------------------------------------
--                                          Local functions                                             --
--      The following are internal functions, which we do not want to be accessible from other modules. --
----------------------------------------------------------------------------------------------------------

-- Find whether we need to return a category or not.
local function needsCategory(pageObject, args)
	-- Don't categorise if the relevant options are set.
	if yesno(args[cfg.nocat])
		or yesno(args[cfg.categories]) == false
		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

-- Find whether we need to check the blacklist or not.
local function needsBlacklistCheck(args)
	if yesno(args[cfg.nocat]) == false
		or yesno(args[cfg.categories]) == true
		or args[cfg.category2] == cfg.category2Yes
	then
		return false
	else
		return true
	end
end

-- Find whether any namespace parameters have been specified.
-- Mappings is the table of parameter mappings taken from
-- [[Module:Namespace detect]].
local function nsParamsExist(mappings, args)
	if args[cfg.all] or args[cfg.other] then
		return true
	end
	for ns, params in pairs(mappings) do
		for i, param in ipairs(params) do
			if args[param] then
				return true
			end
		end
	end
	return false
end

----------------------------------------------------------------------------------------------------------
--										  Global functions											--
--	  The following functions are global, because we want them to be accessible from #invoke and	  --
--	  from other Lua modules.																		 --
----------------------------------------------------------------------------------------------------------

local p = {}

-- Find if a string matches the blacklist. Returns the match if one is found, or nil otherwise.
-- Input should be a page title with a namespace prefix, e.g. "Wikipedia talk:Articles for deletion".
function p.matchesBlacklist(page)
	if type(page) ~= 'string' then return end
	for i, pattern in ipairs(cfg.blacklist) do
		local match = mw.ustring.match(page, pattern)
		if match then
			return match
		end
	end
end

-- The main structure of the module. Checks whether we need to categorise,
-- and then passes the relevant arguments to [[Module:Namespace detect]].
function p._main(args)
	-- Get the page object and argument mappings from
	-- [[Module:Namespace detect]], to save us from having to rewrite the
	-- code.
	local pageObject = nsDetect.getPageObject(args[cfg.page])
	local mappings = nsDetect.getParamMappings()
	
	if not needsCategory(pageObject, args) then return end
	
	local ret = ''
	-- Check blacklist if necessary.
	if not needsBlacklistCheck(args) or not p.matchesBlacklist(pageObject.prefixedText) then
		if not nsParamsExist(mappings, args) then
			-- No namespace parameters exist; basic usage. Pass args[1] to
			-- [[Module:Namespace detect]] using the default namespace
			-- parameters, and return the result.
			local ndargs = {}
			for _, ndarg in ipairs(cfg.defaultNamespaces) do
				ndargs[ndarg] = args[1]
			end
			ndargs.page = args.page
			ndargs.demospace = args.demospace
			local ndresult = nsDetect._main(ndargs)
			if ndresult then
				ret = ret .. ndresult
			end
		else
			-- Namespace parameters exist; advanced usage.
			-- If the all parameter is specified, return it.
			local all = args.all
			if type(all) == 'string' then
				ret = ret .. 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
			ndargs.other = args.other
			ndargs.page = args.page
			ndargs.demospace = args.demospace
			
			local data = nsDetect._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 then
					local dataArg = args[datanum]
					if type(dataArg) == 'string' then
						ret = ret .. dataArg
					end
				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

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

	-- Trim whitespace and remove blank arguments for the following args:
	-- 1, 2, 3 etc., "nocat", "categories", "subpage", and "page".
	local args = {}
	for k, v in pairs(origArgs) do
		if type(v) == 'string' then
			v = mw.text.trim(v) -- Trim whitespace.
		end
		if type(k) == 'number'
			or k == cfg.nocat
			or k == cfg.categories
			or k == cfg.subpage
			or k == cfg.page
		then
			if v ~= '' then
				args[k] = v
			end
		else
			args[k] = v
		end
	end
	
	-- 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
		local argVal = args[v]
		if type(argVal) == 'string' then
			args[v] = mw.ustring.lower(argVal)
		end
	end
	
	return p._main(args)
end

return p