-- This module follows [[User:Ganaram inukshuk/Provisional style guide for Lua]]
local getArgs = require("Module:Arguments").getArgs
local p = {}
-- Produces a hatnote that is placed on the top of a documentation page (either
-- template or module documentation) and can autodetect and categorize:
-- - FOR MODULES:
-- - whether a module has an accompanying template (overridable)
-- - whether a module is meant as a library for other modules
-- - FOR TEMPLATES:
-- - whether a template has an accompanying module (overridable)
-- - what functions from which modules are invoked
-- Options for specific types of templates and modules include:
-- - (TEMPLATES) whether it's a metatemplate
-- - (MODULES) whether it's a metamodule (used the same way as a metatemplate,
-- but direct use of module code is allowed)
-- Helper function
-- Detect whether a page exists, where fullpagename is "Namespace:Title"
local function page_exists(fullpagename)
local title = mw.title.new(fullpagename)
if title and title.exists then
return true
else
return false
end
end
-- Helper function
-- Categorizes pages if they're in the right namespace, and based on the nature
-- of the page
local function categorize(namespace, pagename, is_lua_based_template)
local is_lua_based_template = is_lua_based_template or false
local cats = ""
if pagename:sub(-4) == "/doc" then
-- Documentation subpages
if namespace == "Template" then
cats = "[[Category:Template documentation]]"
elseif namespace == "Module" then
cats = "[[Category:Module documentation]]"
end
else
-- Main pages
if namespace == "Template" then
cats = "[[Category:Templates]]"
if is_lua_based_template then
cats = cats .. " [[Category:Lua-based templates]]"
end
elseif namespace == "Module" then
cats = "[[Category:Lua modules]]"
else
--cats = "[[Category:Templates in the incorrect namespace]]"
end
end
return cats
end
-- Helper function
-- Creates an additional hatnote denoting which functions are invoked from which
-- modules, if a has more than one invoke.
local function make_invocation_hatnote(invokes)
local hatnote = ""
if #invokes == 0 then
return ""
else
hatnote = "This template invokes the following functions:"
local calls = {}
for _, call in ipairs(invokes) do
table.insert(calls, string.format("'''%s''' from [[Module:%s]]", call.func, call.module))
end
return string.format(":''%s %s''\n", hatnote, table.concat(calls, ", "))
end
end
-- Helper function to handle modules
function p.make_module_hatnote(header, corr_template, has_template)
if header == "dualuse" then
if has_template then
return string.format(
"This module may be invoked by templates using its corresponding [[%s|template]], or used directly from other modules.",
corr_template
)
else
return string.format(
"This module has a template that is currently missing. [[Special:EditPage/%s]]",
corr_template
)
end
elseif header == "metatemplate" then
if has_template then
return string.format(
"This module implements a metatemplate, and may be invoked by templates using its corresponding [[%s|template]], or used directly from other modules.",
corr_template
)
else
return "This module is used to create other Lua-based templates and has no corresponding template."
end
elseif header == "noinvoke" then
if has_template then
return string.format(
"This module should not be invoked directly; use its corresponding [[%s|template]] instead.",
corr_template
)
else
return string.format(
"This module implements a template that is currently missing. [[Special:EditPage/%s]]",
corr_template
)
end
elseif header == "library" or header == "metamodule" then
return "This module primarily serves as a library for other modules and has no corresponding template."
else
if has_template and header ~= "" then
return string.format("%s. This module implements [[%s]].", header, corr_template)
elseif has_template and header == "" then
return string.format("This module implements [[%s]].", corr_template)
else
return header
end
end
end
-- Helper function to handle templates
function p.make_template_hatnote(header, corr_module, has_module)
if header == "dualuse" then
if has_module then
return string.format(
"This template is implemented by the Lua module [[%s]]. See its module page for Lua-based template implementation.",
corr_module
)
else
return string.format(
"This template is implemented by a module that is currently missing. [[Special:EditPage/%s]]",
corr_module
)
end
elseif header == "metatemplate" then
if has_module then
return string.format(
"This template is a metatemplate. It is used to build other templates and should not be used standalone, except for testing or simple usage. This template is implemented by the Lua module [[%s]].",
corr_module
)
else
return "This template is a metatemplate. It is used to build other templates and should not be used standalone, except for testing or simple usage."
end
elseif header == "noinvoke" or header == "library" or header == "metamodule" then
return "This template has a header option in the wrong namespace. It should be used within the Module namespace."
else
if has_module and header ~= "" then
return string.format("%s. This template is implemented by the Lua module [[%s]].", header, corr_module)
elseif has_module and header == "" then
return string.format("This template is implemented by the Lua module [[%s]].", corr_module)
else
return header
end
end
end
-- Main function
function p._dochead(args)
local namespace = args["namespace"]
local pagename = args["pagename"]
local header = args["header"] or "none"
local corr_template = args["temp"] or ("Template:" .. pagename)
local corr_module = args["mod"] or ("Module:" .. pagename)
-- Normalize namespace prefixes
if not corr_template:match("^Template:") then
corr_template = "Template:" .. corr_template
end
if not corr_module:match("^Module:") then
corr_module = "Module:" .. corr_module
end
-- If header is none, skip everything
if header == "none" then
return categorize(namespace, pagename)
end
-- Remove /doc suffix, if this is on a /doc page
corr_template = corr_template:gsub("/doc$", "")
corr_module = corr_module:gsub("/doc$", "")
-- Call appropriate hatnote-making function
local has_template = page_exists(corr_template)
local has_module = page_exists(corr_module)
local result = ""
if namespace == "Module" then
result = p.make_module_hatnote(header, corr_template, has_template)
elseif namespace == "Template" then
result = p.make_template_hatnote(header, corr_module, has_module)
else
result = "This template is in the wrong namespace. It should be within the Template or Module namespaces."
end
-- Categorization and output
local has_link = namespace == "Template" and has_module
if result == "" then
return categorize(namespace, pagename, has_link)
else
return string.format(":''%s'' %s\n", result, categorize(namespace, pagename, has_link))
end
end
-- Wrapper to be invoked
function p.dochead(frame)
local args = getArgs(frame, { removeBlanks = true }) or {}
local title = mw.title.getCurrentTitle()
-- Extract or parse args
args["namespace"] = args["namespace"] or title.nsText
args["pagename" ] = args["pagename" ] or title.text
-- Extract header or set it to defaults
if args["header"] == nil or args["header"] == "" then
if args["namespace"] == "Module" then
args["header"] = "noinvoke"
else
args["header"] = ""
end
end
-- Extract template/module names, or autogenerate them
args["temp"] = args["temp"] or ("Template:" .. args["pagename"])
args["mod" ] = args["mod" ] or ("Module:" .. args["pagename"])
return p._dochead(args)
end
return p
.svg){kind=icon}
