Module:Category handler

Module:Category handler/doc
----------------------------------------------------------------------------------------------------------
--                                                                                                      --
--                                          CATEGORY HANDLER                                            --
--                                                                                                      --
--      This module implements the  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  and          --
--       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 .
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 .
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. "World Heritage Encyclopedia_talk".
-- Other parts of the title can have either underscores or spaces.
cfg.blacklist = {
    '^Main Page$', -- don't categorise the main page.
    
    -- Don't categorise the following pages or their subpages.
    '^World Heritage Encyclopedia:Cascade%-protected items$',
    '^World Heritage Encyclopedia:Cascade%-protected items/.*$',
    '^User:UBX$', -- The userbox "template" space.
    '^User:UBX/.*$',
    '^User_talk:UBX$',
    '^User_talk:UBX/.*$',
    
    -- Don't categorise subpages of these pages, but allow
    -- categorisation of the base page.
    '^World Heritage Encyclopedia:Template messages/.+$',
    
    '/[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 .
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
-- .
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. "World Heritage Encyclopedia 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 .
function p._main(args)
    -- Get the page object and argument mappings from
    -- , 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
            --  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 .
            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
This article was sourced from Creative Commons Attribution-ShareAlike License; additional terms may apply. World Heritage Encyclopedia content is assembled from numerous content providers, Open Access Publishing, and in compliance with The Fair Access to Science and Technology Research Act (FASTR), Wikimedia Foundation, Inc., Public Library of Science, The Encyclopedia of Life, Open Book Publishers (OBP), PubMed, U.S. National Library of Medicine, National Center for Biotechnology Information, U.S. National Library of Medicine, National Institutes of Health (NIH), U.S. Department of Health & Human Services, and USA.gov, which sources content from all federal, state, local, tribal, and territorial government publication portals (.gov, .mil, .edu). Funding for USA.gov and content contributors is made possible from the U.S. Congress, E-Government Act of 2002.
 
Crowd sourced content that is contributed to World Heritage Encyclopedia is peer reviewed and edited by our editorial staff to ensure quality scholarly research articles.
 
By using this site, you agree to the Terms of Use and Privacy Policy. World Heritage Encyclopedia™ is a registered trademark of the World Public Library Association, a non-profit organization.