MediaWiki:Common.css

2026-09-19T20:10:18Z

Austenasia:

MediaWiki:Common.css

2026-09-19T20:09:39Z

Austenasia:

2026-09-19T20:00:34Z

Austenasia:

2026-09-18T17:39:11Z

Austenasia: 1 revision imported

--- Docbunto is an automatic documentation generator for Scribunto modules.
-- The module is based on LuaDoc and LDoc. It produces documentation in
-- the form of MediaWiki markup, using `@tag`-prefixed comments embedded
-- in the source code of a Scribunto module. The taglet parser & doclet
-- renderer Docbunto uses are also publicly exposed to other modules.
--
-- Docbunto code items are introduced by a block comment (`--[[]]--`), an
-- inline comment with three hyphens (`---`), or an inline `@tag` comment.
-- The module can use static code analysis to infer variable names, item
-- privacy (`local` keyword), tables (`{}` constructor) and functions
-- (`function` keyword). MediaWiki and Markdown formatting is supported.
--
-- Items are usually rendered in the order they are defined, if they are
-- public items, or emulated classes extending the Lua primitives. There
-- are many customisation options available to change Docbunto behaviour.
--
-- @module docbunto
-- @alias p
-- @require Module:I18n
-- @require Module:Lua_lexer
-- @require Module:Unindent
-- @require Module:Yesno
-- @require Module:Arguments
-- @require Module:Documentation
-- @author [[wikia:dev:User:8nml|8nml]] (Fandom Dev Wiki)
-- @author [[User:Awesome Aasim|Awesome Aasim]] (Wikimedia port)
-- @attribution [https://github.com/stevedonovan @stevedonovan] ([https://github.com/stevedonovan/LDoc GitHub])
-- @release beta
-- <nowiki>
local p = {}

-- Module dependencies.
local title = mw.title.getCurrentTitle()
local i18n = require('Module:I18n').loadMessages('Docbunto'):useContentLang()
local references = mw.loadData('Module:Docbunto/references')
local lexer = require('Module:Lua lexer')
local unindent = require('Module:Unindent')
local yesno = require('Module:Yesno')
local doc = require('Module:Documentation')

local fileTooBig
local usingOptionsContent
local hasTodoItems

-- Module variables.
local DEFAULT_TITLE = title.namespace == 828 and doc.getEnvironment({}).templateTitle.text or ''
local DEFAULT_VARIABLE = DEFAULT_TITLE
:gsub('^%u', mw.ustring.lower)
:gsub('%s', '_'):gsub('%p', '.')
local frame, gsub, match

local syntaxhighlightPresent = mw.getCurrentFrame()
:preprocess("<syntaxhighlight lang=\"lua\">-- Lua</syntaxhighlight>")
~= "<syntaxhighlight lang=\"lua\">-- Lua</syntaxhighlight>"

-- Docbunto variables & tag tokens.
local TAG_MULTI = 'M'
local TAG_ID = 'ID'
local TAG_SINGLE = 'S'
local TAG_TYPE = 'T'
local TAG_FLAG = 'N'
local TAG_MULTI_LINE = 'ML'

-- Docbunto processing patterns.
local patterns = {}

--- Configuration options.
-- @table options
-- @field[opt] {boolean} options.all Include local items in
-- documentation.
-- @field[opt] {boolean} options.autodoc Whether the module is being
-- called to automatically provide missing documentation.
-- @field[opt] {boolean} options.boilerplate Removal of
-- boilerplate (license block comments).
-- @field[opt] {string} options.caption Infobox image caption.
-- @field[opt] {boolean} options.code Only document Docbunto code
-- items - exclude article infobox and lede from
-- rendered documentation. Permits article to be
-- edited in VisualEditor.
-- @field[opt] {boolean} options.colon Format tags with a `:` suffix
-- and without the `@` prefix. This bypasses the "doctag
-- soup" some authors complain of.
-- @field[opt] {string} options.image Infobox image.
-- @field[opt] {boolean} options.box Include infobox in output.
-- @field[opt] {boolean} options.footer Append a horizontal line &
-- "generated by Docbunto" to the bottom of the output.
-- @field[opt] {boolean} options.noluaref Don't link to the [[mw:
-- Extension:Scribunto/Lua reference manual|Lua reference manual]] for types.
-- @field[opt] {boolean} options.card Include endmatter card in the
-- output at the end of the documentation.
-- @field[opt] {boolean} options.plain Disable Markdown formatting
-- in documentation.
-- @field[opt] {string} options.preface Preface text to insert
-- between lede & item documentation, used to provide
-- usage and code examples.
-- @field[opt] {boolean} options.simple Limit documentation to
-- descriptions only. Removes documentation of
-- subitem tags such as `@param` and `@field` ([[#Item
-- subtags|see list]]).
-- @field[opt] {boolean} options.sort Sort documentation items in
-- alphabetical order.
-- @field[opt] {boolean} options.strip Remove table index in
-- documentation.
-- @field[opt] {boolean} options.ulist Indent subitems as `<ul>`
-- lists (LDoc/JSDoc behaviour).
-- @field[opt] {boolean} options.verbose Show the code
-- description of a package function when documenting
-- function modules.

-- Docbunto private utilities.
local utils = {}

--- @{string.find} optimisation for @{string} functions.
-- @function utils.strfind_wrap
-- @param {function} strfunc String library function.
-- @return {function} Function wrapped in @{string.find} check.
-- @local
function utils.strfind_wrap(func)
return function(...)
local arg = {...}
if string.find(arg[1], arg[2]) then
return func(...);
end
end
end

--- String concatenation utility.
-- @function join
-- @param {sequence<string>} tbl Table of string segments
-- @return {function} A concatenated string.
-- @local
function utils.join(tbl)
return table.concat(tbl, '')
end

--- Pattern configuration function.
-- Resets patterns for each documentation build.
-- @function utils.configure_patterns
-- @param {options} options Configuration options.
-- @local
function utils.configure_patterns(options)
-- Setup Unicode or ASCII character encoding (optimisation).
gsub = utils.strfind_wrap(
options.unicode
and mw.ustring.gsub
or string.gsub
)
match = utils.strfind_wrap(
options.unicode
and mw.ustring.match
or string.match
)
patterns.DOCBUNTO_SUMMARY =
options.iso639_th
and '^[^ ]+'
or
options.unicode
and '^[^.։。।෴۔።]+[.։。।෴۔።]?'
or '^[^.]+%.?'
patterns.DOCBUNTO_CONCAT = options.iso639_th and '' or ' '
patterns.DOCBUNTO_TYPE = '^{({*[^}]+}*)}%s*'
patterns.DOCBUNTO_WIKITEXT = '^[{|!}:#*=]+[%s-}]+'

-- Setup parsing tag patterns with colon mode support.
patterns.DOCBUNTO_TAG = options.colon and '^%s*(%w+):' or '^%s*@(%w+)'
patterns.DOCBUNTO_TAG_COMMENT = '^[-%s]*' .. patterns.DOCBUNTO_TAG:sub(2)
patterns.DOCBUNTO_TAG_VALUE = patterns.DOCBUNTO_TAG .. '(.*)'
patterns.DOCBUNTO_TAG_MOD_VALUE = patterns.DOCBUNTO_TAG .. '%[([^%]]*)%](.*)'
patterns.DOCBUNTO_TAG_OPTION_VALUE = '(%[[^%]]*%])%s*(.*)'
end

--- Tag processor function.
-- @function utils.process_tag
-- @param {string} str Tag string to process.
-- @return {table} Tag object.
-- @local
function utils.process_tag(str)
local tag = {}

if str:find(patterns.DOCBUNTO_TAG_MOD_VALUE) then
tag.name, tag.modifiers, tag.value = str:match(patterns.DOCBUNTO_TAG_MOD_VALUE)
local modifiers = {}

for m in tag.modifiers:gmatch('[^%s,]+') do
local i = m:find('=')
if i then
local key = mw.text.trim(m:sub(1, i - 1))
local val = mw.text.trim(m:sub(i + 1, #m))
modifiers[key] = val
else
modifiers[m] = true
end
end

if modifiers.optchain then
modifiers.opt = true
modifiers.optchain = nil
end

tag.modifiers = modifiers

else
tag.name, tag.value = str:match(patterns.DOCBUNTO_TAG_VALUE)
end

tag.value = mw.text.trim(tag.value)

if p.tags._type_alias[tag.name] then
if p.tags._type_alias[tag.name] ~= 'variable' then
tag.value = p.tags._type_alias[tag.name] .. ' ' .. tag.value
tag.name = 'field'
end

if tag.value:match('^%S+') ~= '...' then
tag.value = tag.value:gsub('^(%S+)', '{%1}')
end
end

tag.name = p.tags._alias[tag.name] or tag.name

if tag.name ~= 'usage' and tag.value:find(patterns.DOCBUNTO_TYPE) then
tag.type = tag.value:match(patterns.DOCBUNTO_TYPE)
if tag.type:find('^%?') then
tag.type = tag.type:sub(2) .. '|nil'
end
tag.value = tag.value:gsub(patterns.DOCBUNTO_TYPE, '')
end

if (tag.name == 'param' or tag.name == 'field') and tag.value:find(patterns.DOCBUNTO_TAG_OPTION_VALUE) then
tag.value = tag.value:gsub(patterns.DOCBUNTO_TAG_OPTION_VALUE, '%1 %2')
tag.modifiers = tag.modifiers or {}
tag.modifiers.opt = true
end

if p.tags[tag.name] == TAG_FLAG then
tag.value = true
end

return tag
end

--- Module info extraction utility.
-- @function utils.extract_info
-- @param {table} documentation Package doclet info.
-- @return {table} Information name-value map.
-- @local
function utils.extract_info(documentation)
local info = {}

for _, tag in ipairs(documentation.tags) do
if p.tags._module_info[tag.name] then
if info[tag.name] then
if not info[tag.name]:find('^%* ') then
info[tag.name] = '* ' .. info[tag.name]
end
info[tag.name] = info[tag.name] .. '\n* ' .. tag.value

else
info[tag.name] = tag.value
end
end
end

return info
end

--- Type extraction utility.
-- @function utils.extract_types
-- @param {table} item Item documentation data.
-- @return {sequence<string>} Item types.
-- @local
function utils.extract_types(item)
local item_types = {}
for _, tag in ipairs(item.tags) do
if p.tags[tag.name] == TAG_TYPE then
item_types[1] = tag.name

if tag.name == 'variable' then
local implied_local = utils.process_tag('@local')
table.insert(item.tags, mw.clone(implied_local))
item.tags['local'] = mw.clone(implied_local)
end

if
p.tags._generic_tags[item_types[1]] and
not p.tags._project_level[item_types[1]] and
tag.type
then
item_types[#item_types + 1] = tag.type
end
break
end
end
return item_types
end

--- Name extraction utility.
-- @function utils.extract_name
-- @param {table} item Item documentation data.
-- @param {boolean} project Whether the item is project-level.
-- @return {string} Item name.
-- @local
function utils.extract_name(item, opts)
opts = opts or {}
local item_name
for _, tag in ipairs(item.tags) do
if p.tags[tag.name] == TAG_TYPE then
item_name = tag.value; break
end
end

if item_name or not opts.project then
return item_name
end

item_name = item.code:match('\nreturn%s+([%w_]+)')

if item_name == 'p' and not item.tags['alias'] then
local implied_alias = { name = 'alias', value = 'p' }
item.tags['alias'] = implied_alias
table.insert(item.tags, implied_alias)
end

item_name = (item_name and item_name ~= 'p')
and item_name
or item.filename
:gsub('^' .. mw.site.namespaces[828].name .. ':', '')
:gsub('^(%u)', mw.ustring.lower)
:gsub('/', '.'):gsub(' ', '_')

return item_name
end

--- Source code utility for item name detection.
-- @function utils.deduce_name
-- @param {string} tokens Stream tokens for first line.
-- @param {string} index Stream token index.
-- @param {table} opts Configuration options.
-- @param[opt] {boolean} opts.lookahead Whether a variable name succeeds the index.
-- @param[opt] {boolean} opts.lookbehind Whether a variable name precedes the index.
-- @return {string} Item name.
-- @local
function utils.deduce_name(tokens, index, opts)
local name = ''

if opts.lookbehind then
for i2 = index, 1, -1 do
if tokens[i2].type ~= 'keyword' then
name = tokens[i2].data .. name
else
break
end
end

elseif opts.lookahead then
for i2 = index, #tokens do
if tokens[i2].type ~= 'keyword' and not tokens[i2].data:find('^%(') then
name = name .. tokens[i2].data
else
break
end
end
end

return name
end

--- Parses Lua item names to extract a hierarchy.
--- @function utils.parse_hierarchy
-- @param {string} item_name Documentation item name.
-- @return {sequence<string>} List of global keys to index the
-- variable reference.
-- @local
function utils.parse_hierarchy(item_name)
local hierarchy = {}
for _, lexeme in ipairs(lexer(item_name)) do
if lexeme.type == 'ident' or lexeme.type == 'string' or lexeme.type == 'number' then
hierarchy[#hierarchy + 1] = lexeme.text
end
end
return hierarchy
end

--- Code analysis utility.
-- @function utils.code_heuristic
-- @param {table} item Item documentation data.
-- @local
function utils.code_heuristic(item)
local is_section = item.tags['private'] or item.tags['local'] or item.type == 'type'

if item.name and item.type and is_section then
return
end

local tokens = lexer(item.code:match('^[^\n]*'))[1]
local t, i = tokens[1], 1
local item_name, item_type
local lexemes = {}

while t do
if t.type ~= 'whitespace' then
lexemes[#lexemes + 1] = tokens[i]
end

t, i = tokens[i + 1], i + 1
end
t, i = lexemes[1], 1

while t do
if t.data == '=' and not item.name then
item_name = utils.deduce_name(lexemes, i - 1, { lookbehind = true })
end

if t.data == 'function' and not item.name then
item_type = 'function'
if lexemes[i + 1] and lexemes[i + 1].data ~= '(' then
item_name = utils.deduce_name(lexemes, i + 1, { lookahead = true })
end
end

if t.data == '{' or t.data == '{}' and not item.type then
item_type = 'table'
end

if t.data == 'local' and not is_section then
local implied_local = utils.process_tag('@local')
table.insert(item.tags, implied_local)
item.tags['local'] = mw.clone(implied_local)
end

t, i = lexemes[i + 1], i + 1
end

item.name = item.name or item_name or ''
item.type = item.type or item_type
if #(item.types or {}) == 0 then
item.types[1] = item.type
end
end

--- Array hash map conversion utility.
-- @function utils.hash_map
-- @param {table} item Item documentation data array.
-- @return {table} Item documentation data map.
-- @local
function utils.hash_map(array)
local map = array
for _, element in ipairs(array) do
if map[element.name] and not map[element.name].name then
table.insert(map[element.name], mw.clone(element))
elseif map[element.name] and map[element.name].name then
map[element.name] = { map[element.name], mw.clone(element) }
else
map[element.name] = mw.clone(element)
end
end
return map
end

--- Item export utility.
-- @function utils.export_item
-- @param {table} documentation Package documentation data.
-- @param {string} item_reference Identifier name for item.
-- @param {string} item_index Identifier name for item.
-- @param {string} item_alias Export alias for item.
-- @param {boolean} factory_item Whether the documentation item is a factory function.
-- @local
function utils.export_item(documentation, item_reference, item_index, item_alias, factory_item)
for _, item in ipairs(documentation.items) do
if item_reference == item.name then
item.tags['local'] = nil
item.tags['private'] = nil

for index, tag in ipairs(item.tags) do
if p.tags._privacy_tags[tag.name] then
table.remove(item.tags, index)
end
end

item.type, item.types[1] = 'member', 'member'

local accessor
if item_alias:find('^%[') then
accessor = ''
else
local is_class = documentation.type == 'classmod' or factory_item
if is_class and not item.tags['static'] then
accessor = ':'
else
accessor = '.'
end
end

if factory_item then
item.alias = utils.join{
documentation.items[item_index].tags['factory'].value,
accessor,
item_alias
}

else
item.alias = utils.join{
((documentation.tags['alias'] or {}).value or documentation.name),
accessor,
item_alias
}
end

item.hierarchy = utils.parse_hierarchy(item.alias)
break
end
end
end

--- Subitem tag correction utility.
-- @function utils.correct_subitem_tag
-- @param {table} item Item documentation data.
-- @local
function utils.correct_subitem_tag(item)
local field_tag = item.tags['field']
if item.type ~= 'function' or not field_tag then
return
end

if field_tag.name then
field_tag.name = 'param'
else
for _, tag_el in ipairs(field_tag) do
tag_el.name = 'param'
end
end

local param_tag = item.tags['param']
if param_tag and not param_tag.name then
if field_tag.name then
table.insert(param_tag, field_tag)
else
for _, tag_el in ipairs(field_tag) do
table.insert(param_tag, tag_el)
end
end

elseif param_tag and param_tag.name then
if field_tag.name then
param_tag = { param_tag, field_tag }

else
for i, tag_el in ipairs(field_tag) do
if i == 1 then
param_tag = { param_tag }
end
for _, tag_el in ipairs(field_tag) do
table.insert(param_tag, tag_el)
end
end
end

else
param_tag = field_tag
end

item.tags['field'] = nil
end

--- Item override tag utility.
-- @function utils.override_item_tag
-- @param {table} item Item documentation data.
-- @param {string} name Tag name.
-- @param[opt] {string} alias Target alias for tag.
-- @local
function utils.override_item_tag(item, name, alias)
if item.tags[name] then
item[alias or name] = item.tags[name].value
end
end

--- Identity function.
-- @function utils.identity
-- @param x The variable by reference.
-- @return The parameter `x` by reference.
-- @local
function utils.identity(x)
return x
end

--- Argument processing
-- @param {string} funcName name of function
-- @return function to process arguments
-- @local
local function makeInvokeFunc(funcName)
return function (f)
local args = require("Module:Arguments").getArgs(f, {
valueFunc = function (key, value)
if type(value) == 'string' then
value = value:match('^%s*(.-)%s*$') -- Remove whitespace.
if key == 'heading' or value ~= '' then
return value
else
return nil
end
else
return value
end
end
})
return p[funcName](args)
end
end

-- Docbunto rendering logic.
local frontend = {}

--- Markdown header converter.
-- @function urils.markdown_header
-- @param {string} hash Leading hash.
-- @param {string} text Header text.
-- @return {string} MediaWiki header.
-- @local
function frontend.markdown_header(hash, text)
local symbol = '='
return utils.join{
'\n',
symbol:rep(#hash), ' ', text, ' ', symbol:rep(#hash),
'\n'
}
end

--- Item reference formatting.
-- @function urils.item_reference
-- @param {string} ref Item reference.
-- @return {string} Internal MediaWiki link to article item.
-- @local
function frontend.item_reference(ref)
local temp = mw.text.split(ref, '|')
local item = temp[1]
local text = temp[2] or temp[1]

if references.items[item] then
local interwiki = 'mw'
item = interwiki .. references.items[item]
else
item = '#' .. item
end

return mw.text.tag{
name = 'code',
content = utils.join{ '[[', item, '|', text, ']]' }
}
end

--- Doclet type reference preprocessor.
-- Formats types with links to the [[mw:Extension:Scribunto/Lua reference manual|Lua reference manual]].
-- @function frontend.type_reference
-- @param {table} item Item documentation data.
-- @param {options} options Configuration options.
-- @local
function frontend.type_reference(item, options)
local interwiki = 'mw:'

if
not options.noluaref and
item.value and
item.value:match('^%S+') == mw.text.tag('code', nil, '...')
then
item.value = item.value:gsub('^(%S+)', mw.text.tag{
name = 'code',
content = utils.join{ '[[', interwiki, 'Lua reference manual#varargs|...]]' }
})
end

-- Handle tag type references.
item.types = item.types or item.type and { item.type }

if not item.types then
return
end

for index, item_type in ipairs(item.types) do
item.types[index] = item.types[index]:gsub('[%w_. ]+', function(item_type)
local data = references.types[item_type]
local name = data and data.name or item_type
if not name:match('%.') and not name:match('^%u') and data then
name = i18n:msg('type-' .. name)
end
if data and not options.noluaref then
return utils.join{ '[[', interwiki, data.link, '|', name , ']]' }
elseif
item_type:find(i18n:msg('line-no'):gsub('$1', ''))
then
return utils.join { '[[' , options.file , '#L-', item_type:sub(6), '|', name, ']]' }
elseif
not options.noluaref and
not p.tags._generic_tags[item_type]
then
return utils.join { '[[#', item_type, '|', name, ']]' }
end
end)
end

item.type = table.concat(item.types, i18n:msg('separator-dot'))
end

--- Markdown preprocessor to MediaWiki format.
-- @function frontend.markdown
-- @param {string} str Unprocessed Markdown string.
-- @return {string} MediaWiki-compatible markup with HTML formatting.
-- @local
function frontend.markdown(str)
-- Bold & italic tags.
str = str:gsub('%*%*%*([^\n*]+)%*%*%*', '<b><i>%1</i></b>')
str = str:gsub('%*%*([^\n*]+)%*%*', '<b>%1</b>')
str = str:gsub('%*([^\n*]+)%*', '<i>%1</i>')

-- Self-closing header support.
str = str:gsub('%f[^\n%z](#+) *([^\n#]+) *#+%s', frontend.markdown_header)

-- External and internal links.
str = str:gsub('%[([^\n%]]+)%]%(([^\n][^\n)]-)%)', '[%2 %1]')
str = str:gsub('%{@link%s+([^}]+)%}', '[%1]')
str = str:gsub('%@{([^\n}]+)}', frontend.item_reference)

-- Programming & scientific notation.
str = str:gsub('%f["`]`([^\n`]+)`%f[^"`]', '<code><nowiki>%1</nowiki></code>')
str = str:gsub('%$%$([^\n$]+)%$%$', '<math display="inline">%1</math>')

-- Strikethroughs.
str = str:gsub('~~([^\n~]+)~~', '<del>%1</del>')

-- HTML output.
return str
end

--- Doclet function item preprocessor.
-- Formats item name as a function call with top-level arguments.
-- @function frontend.pretask_function_name
-- @param {table} item Item documentation data.
-- @param {options} options Configuration options.
-- @local
function frontend.pretask_function_name(item, options)
local target = item.alias and 'alias' or 'name'

item[target] = item[target] .. '('

if
item.tags['param'] and
item.tags['param'].value and
not item.tags['param'].value:find('^[%w_]+[.[]')
then
if (item.tags['param'].modifiers or {})['opt'] then
local optional = mw.html.create('span')
optional:css('opacity', '0.65')
optional:wikitext(item.tags['param'].value:match('^(%S+)'))
item[target] = item[target] .. tostring(optional)
else
item[target] = item[target] .. item.tags['param'].value:match('^(%S*)')
end

elseif item.tags['param'] then
for index, tag in ipairs(item.tags['param']) do
if not tag.value:find('^[%w_]+[.[]') then
if (tag.modifiers or {})['opt'] then
local param = mw.html.create('span')
param:css('opacity', '0.65')
param:wikitext((index > 1 and ', ' or '') .. tag.value:match('^%S+'))
item[target] = item[target] .. tostring(param)
else
item[target] = item[target] .. (index > 1 and ', ' or '') .. tag.value:match('^(%S+)')
end
end
end
end

item[target] = item[target] .. ')'
end

--- Doclet parameter/field subitem preprocessor.
-- Indents and wraps variable prefix with `code` tag.
-- @function pretask_variable_prefix
-- @param {table} item Item documentation data.
-- @param {options} options Configuration options.
-- @local
function frontend.pretask_variable_prefix(item, options)
local indent_symbol = options.ulist and '*' or ':'
local indent_level, indentation, item_id

if item.value then
indent_level = item.value:match('^%S*') == '...'
and 0
or select(2, item.value:match('^%S*'):gsub('[.[]', ''))
indentation = indent_symbol:rep(indent_level)
item_id = options.item_id
item.value = indentation .. item.value:gsub(
'^(%S+)',
mw.text.tag{
name = 'code',
attrs = { id = item_id .. '~%1' },
content = '%1'
},
1
)

elseif item then
for _, item_el in ipairs(item) do
frontend.pretask_variable_prefix(item_el, options)
end
end
end

--- Doclet usage subitem preprocessor.
-- Formats usage example with `<syntaxhighlight>` tag.
-- @function frontend.pretask_usage_highlight
-- @param {table} item Item documentation data.
-- @param {options} options Configuration options.
-- @local
function frontend.pretask_usage_highlight(item, options)
if item.value then
item.value = unindent(mw.text.trim(item.value))
if item.value:find('^{{.+}}$') then
item.value = item.value:gsub('=', mw.text.nowiki)
local multi_line = item.value:find('\n') and '|m = 1|' or '|'

if item.value:match('^{{([^:]+)') == '#invoke' then
item.value = item.value:gsub('^{{#invoke:', '{{mlx' .. multi_line)

else
if options.entrypoint then
item.value = item.value:gsub('^([^|]+)|%s*([^|}]-)(%s*)([|}])','%1|"%2"%3%4')
end
item.value = item.value:gsub('^{{', '{{tlx' .. multi_line)
end

local highlight_class = tonumber(mw.site.currentVersion:match('^%d%.%d+')) > 1.19
and 'mw-highlight'
or 'mw-geshi'

if item.value:find('\n') then
local highlight_div = mw.html.create('div')
highlight_div.addClass(highlight_class)
highlight_div.addClass('mw-content-ltr')
highlight_div:attr('dir', 'ltr')
highlight_div:wikitext(item.value)
item.value = tostring(highlight_div)

else
item.value = mw.text.tag{
name = 'span',
attrs = { class = 'code' },
content = item.value
}
end

else
local highlight_tag = mw.html.create('syntaxhighlight')
highlight_tag:attr('lang', 'lua')
if not item.value:find('\n') then
highlight_tag:attr('inline', 'inline')
end
highlight_tag:wikitext(item.value)
item.value = tostring(highlight_tag)
end

elseif item then
for _, item_el in ipairs(item) do
frontend.pretask_usage_highlight(item_el, options)
end
end
end

--- Doclet error subitem preprocessor.
-- Formats line numbers (`{#}`) in error tag values.
-- @function frontend.pretask_error_line
-- @param {table} item Item documentation data.
-- @local
function frontend.pretask_error_line(item, options)
if item.name then
local line

if item.modifiers and item.modifiers.line then
line = item.modifiers.line
end

for mod in pairs(item.modifiers or {}) do
if mod:find('^%d+$') then line = mod end
end

if line then
if item.types then
item.types[#item.types + 1] = i18n:msg('line-no', line)

else
item.type = i18n:msg('line-no', line)
end
end

elseif item then
for _, item_el in ipairs(item) do
frontend.pretask_error_line(item_el, options)
end
end
end

--- Doclet item renderer.
-- @function frontend.render_item
-- @param {table} stream Wikitext documentation stream.
-- @param {table} item Item documentation data.
-- @param {options} options Configuration options.
-- @param[opt] {function} pretask Item data preprocessor.
-- @local
function frontend.render_item(stream, item, options, pretask)
if pretask then pretask(item, options) end
local item_name = item.alias or item.name

frontend.type_reference(item, options)

local item_type = item.type

for _, name in ipairs(p.tags._subtype_hierarchy) do
if item.tags[name] then
item_type = item_type .. i18n:msg('separator-dot') .. name
end
end
item_type = i18n:msg('parentheses', item_type)

if options.strip and item.export and item.hierarchy then
item_name = item_name:gsub('^[%w_]+[.[]?', '')
end

-- add single spaces between parentheses similar to
-- MediaWiki documentation
if not item_name:find( '()', 1, true ) then
item_name = item_name:gsub('%(', '( ')
item_name = item_name:gsub('%)', ' )')
end
item_name = item_name:gsub('%[', '[ ')
item_name = item_name:gsub('%]', ' ]')

local code_node = mw.html.create('code')
:attr('id', options.item_id)
:wikitext(item_name)

if not usingOptionsContent then
local span_node = stream:wikitext(';')
:tag('span')
:addClass('plainlinks docbunto-link')
if fileTooBig or not syntaxhighlightPresent then
span_node:wikitext('[{{fullurl:' .. options.file .. '|action=edit#mw-ce-l' .. item.lineno .. '}} ' .. tostring(code_node) .. ']')
elseif title.namespace == 828 and options.file == title.text then
span_node:wikitext('[[' .. '#L-' .. item.lineno .. '|' .. tostring(code_node) .. ']]')
else
span_node:wikitext('[[' .. options.file .. '#L-' .. item.lineno .. '|' .. tostring(code_node) .. ']]')
end
else
stream:wikitext(';' .. tostring(code_node))
end

stream
:wikitext(item_type)
:newline()

if (#(item.summary or '') + #item.description) ~= 0 then
local separator = #(item.summary or '') ~= 0 and #item.description ~= 0
and (item.description:find(patterns.DOCBUNTO_WIKITEXT) and '\n' or patterns.DOCBUNTO_CONCAT)
or ''
local intro = (item.summary or '') .. separator .. item.description
intro = intro
:gsub('\n([{:#*])', '\n:%1')
:gsub('\n\n([^=])', '\n:%1')
stream:wikitext(':' .. intro):newline()
end
end

--- Doclet tag renderer.
-- @function frontend.render_tag
-- @param {table} stream Wikitext documentation stream.
-- @param {string} name Item tag name.
-- @param {table} tag Item tag data.
-- @param {options} options Configuration options.
-- @param[opt] {function} pretask Item data preprocessor.
-- @local
function frontend.render_tag(stream, name, tag, options, pretask)
if pretask then pretask(tag, options) end
if tag.value then
frontend.type_reference(tag, options)
local tag_name = i18n:msg('tag-' .. name, '1')

-- Handle ul/ol/dl comment support.
stream:wikitext(':')
:tag('b')
:wikitext(tag_name)
:done():done()
:wikitext(i18n:msg('separator-semicolon'))
:wikitext((mw.text.trim(tag.value):gsub('\n([{:#*])', '\n:%1')))

if tag.value:find('\n[{:#*]') and (tag.type or (tag.modifiers or {})['opt']) then
stream:newline():wikitext(':')
end

-- Type and optional appositive for tag.
if tag.type and (tag.modifiers or {})['opt'] then
stream:wikitext(i18n:msg{
key = 'parentheses',
args = {
tag.type ..
i18n:msg('separator-colon') ..
i18n:msg('optional')
}
})

elseif tag.type then
stream:wikitext(i18n:msg{
key = 'parentheses',
args = { tag.type }
})

elseif (tag.modifiers or {})['opt'] then
stream:wikitext(i18n:msg{
key = 'parentheses',
args = { i18n:msg('optional') }
})
end

stream:newline()

else
local tag_name = i18n:msg('tag-' .. name, tostring(#tag))
stream
:wikitext(':')
:tag('b')
:wikitext(tag_name)
:done():done()
:wikitext(i18n:msg('separator-semicolon'))
:newline()

for _, tag_el in ipairs(tag) do
frontend.type_reference(tag_el, options)
local marker = options.ulist and '*' or ':'
stream:wikitext(':' .. marker .. tag_el.value:gsub('\n([{:#*])', '\n:' .. marker .. '%1'))

if tag_el.value:find('\n[{:#*]') and (tag_el.type or (tag_el.modifiers or {})['opt']) then
stream:newline():wikitext(':' .. marker .. (tag_el.value:match('^[*:]+') or ''))
end

if tag_el.type and (tag_el.modifiers or {})['opt'] then
stream:wikitext(i18n:msg{
key = 'parentheses',
args = {
tag_el.type ..
i18n:msg('separator-colon') ..
i18n:msg('optional')
}
})

elseif tag_el.type then
stream:wikitext(i18n:msg{
key = 'parentheses',
args = { tag_el.type }
})

elseif (tag_el.modifiers or {})['opt'] then
stream:wikitext(i18n:msg{
key = 'parentheses',
args = { i18n:msg('optional') }
})
end

stream:newline()
end
end
end

--- Template entrypoint for [[Template:Docbunto]].
-- @function p._main
-- @param {table} args Arguments
-- @return {string} Module documentation output.
function p._main(args)
frame = mw.getCurrentFrame()

local modname = mw.text.trim(args[1] or args.file or DEFAULT_TITLE)

local options = {}
options.file = modname
options.all = yesno(args.all or false)
options.autodoc = yesno(args.autodoc or false)
options.boilerplate = yesno(args.boilerplate or options.autodoc or false)
options.box = yesno(args.box or args.infobox or options.autodoc or false)
options.caption = args.caption
options.card = yesno(args.card or (title.namespace == 828 and not options.autodoc))
options.code = yesno(args.code or false)
options.colon = yesno(args.colon or false)
options.footer = yesno(args.footer or title.namespace == 828)
options.image = args.image
options.migration = yesno(args.migration or false)
options.noluaref = yesno(args.noluaref or false)
options.plain = yesno(args.plain or false)
options.preface = args.preface
options.simple = yesno(args.simple or false)
options.sort = yesno(args.sort or false)
options.strip = yesno(args.strip or false)
options.verbose = yesno(args.verbose or false)
options.ulist = yesno(args.ulist or false)
return p.build(modname, options)
end

--- Entrypoint for the module.
-- @function p.main
-- @param {Frame} frame Module frame.
-- @return {string} Module documentation output.
p.main = makeInvokeFunc('_main')

--- Scribunto documentation generator entrypoint.
-- @function p.build
-- @param[opt] {string} modname Module page name (without namespace).
-- Default: second-level subpage.
-- @param[opt] {options} options Configuration options.
function p.build(modname, options)
modname = modname or DEFAULT_TITLE
options = options or {}

local tagdata = p.taglet(modname, options)
local docdata = p.doclet(tagdata, options)

return docdata
end

--- Docbunto taglet parser for Scribunto modules.
-- @function p.taglet
-- @param[opt] {string} modname Module page name (without namespace).
-- @param[opt] {options} options Configuration options.
-- @error[line=1081] {string} 'Lua source code not found in $1'
-- @error[line=1087] {string} 'documentation markup for Docbunto not found in $1'
-- @return {table} Module documentation data.
function p.taglet(modname, options)
modname = modname or DEFAULT_TITLE
options = options or {}

local filepath = mw.site.namespaces[828].name .. ':' .. modname
local content = mw.title.new(filepath):getContent()

-- Content checks.
if options.content then
content = options.content
usingOptionsContent = true
else
content = mw.title.new(filepath):getContent() or error(i18n:msg('no-content', filepath), 0)
end

-- Syntax highlighting is disabled for files above a specific size
fileTooBig = content:len() > 102400

if
not content:match('%-%-%-') and
not content:match(options.colon and '%w+:' or '@%w+')
then
error(i18n:msg('no-markup', filepath))
end

-- Remove leading escapes.
content = content:gsub('^%-%-+%s*<[^>]+>\n', '')

-- Remove closing pretty comments.
content = content:gsub('\n%-%-%-%-%-+(\n[^-]+)', '\n-- %1')

-- Remove boilerplate block comments.
if options.boilerplate then
content = content:gsub('^%-%-%[=*%[\n.-\n%-?%-?%]%=*]%-?%-?%s+', '')
content = content:gsub('%s+%-%-%[=*%[\n.-\n%-?%-?%]%=*]%-?%-?$', '')
end

-- Configure patterns for colon mode and Unicode character encoding.
options.unicode = type(content:find('[^%w%c%p%s]+')) == 'number'
options.iso639_th = type(content:find('\224\184[\129-\155]')) == 'number'
utils.configure_patterns(options)

-- Content lexing.
local lines = lexer(content)
local tokens = {}
local dummy_token = {
data = '',
posFirst = 1,
posLast = 1
}
local token_closure = 0
for _, line in ipairs(lines) do
if #line == 0 then
dummy_token.type = token_closure == 0
and 'whitespace'
or tokens[#tokens].type
table.insert(tokens, mw.clone(dummy_token))
else
for _, token in ipairs(line) do
if token.data:find('^%[=*%[$') or token.data:find('^%-%-%[=*%[$') then
token_closure = 1
end
if token.data:find(']=*]') then
token_closure = 0
end
table.insert(tokens, token)
end
end
end

-- Start documentation data.
local documentation = {}
documentation.filename = filepath
documentation.description = ''
documentation.code = content
documentation.comments = {}
documentation.tags = {}
documentation.items = {}
local line_no = 0
local item_index = 0

-- Taglet tracking variables.
local start_mode = true
local comment_mode = false
local doctag_mode = false

local export_mode = false
local special_tag = false
local pragma_mode = false
local factory_mode = false
local return_mode = false

local comment_tail = ''
local tag_name = ''

local new_item = false
local new_tag = false
local new_tag_item = false
local new_item_code = false
local pretty_comment = false
local comment_brace = false

local t, i, item = tokens[1], 1

local p_success, p_error = pcall(function()

while t do
-- Taglet variable update.
new_item = t.data:find('^%-%-%-') or t.data:find('^%-%-%[%=*%[$')
comment_tail = t.data:gsub('^%-%-+', '')

tag_name = comment_tail:match(patterns.DOCBUNTO_TAG)
tag_name = p.tags._alias[tag_name] or tag_name

new_tag = type(p.tags[tag_name]) == 'string'
local last_token = t.posFirst ~= 1 and 2 or 1
new_tag_item = (
new_tag and i > 1 and tokens[i - last_token].type ~= 'comment'
and not tokens[i - last_token].data:find(patterns.DOCBUNTO_TAG_COMMENT)
)
pretty_comment =
t.data:find('^%-%-%-+%s*$') or
t.data:find('[^-]+%-%-%-+%s*$') or
t.data:find('%-*[ \t]*<nowiki>$') or
t.data:find('%-*[ \t]*<pre>$')
comment_brace =
t.data:find('^%-%-%[=*%[$') or
t.data:find('^%-%-%]=*%]$') or
t.data:find('^%]=*%]%-%-$')
pragma_mode = tag_name == 'pragma'
export_mode = tag_name == 'export' and not doctag_mode
special_tag = pragma_mode or export_mode
local tags, tag, subtokens, separator

-- Line counter.
if t.posFirst == 1 then
line_no = line_no + 1
end

-- Data insertion logic.
if t.type == 'comment' then
if new_item then
comment_mode = true
end
if (new_tag or new_tag_item) and not special_tag then
comment_mode = true
doctag_mode = true
end

-- Module-level documentation taglet.
if start_mode then
table.insert(documentation.comments, t.data)
end

-- Module description.
if
start_mode and comment_mode and
not new_tag and not doctag_mode and
not pretty_comment and not comment_brace
then
separator = mw.text.trim(comment_tail):find(patterns.DOCBUNTO_WIKITEXT)
and '\n'
or (#documentation.description ~= 0 and patterns.DOCBUNTO_CONCAT or '')
documentation.description = utils.join{
documentation.description,
separator,
mw.text.trim(comment_tail)
}
end

-- Switch from module description to module-level tag list.
if start_mode and new_tag and not export_mode then
doctag_mode = true
table.insert(documentation.tags, utils.process_tag(comment_tail))

-- Concatenating module-level tag with more information.
elseif
start_mode and doctag_mode and
not pretty_comment and not comment_brace
then
tags = documentation.tags
if p.tags[tags[#tags].name] == TAG_MULTI then
separator = mw.text.trim(comment_tail):find(patterns.DOCBUNTO_WIKITEXT)
and '\n'
or patterns.DOCBUNTO_CONCAT
tags[#tags].value = utils.join{
tags[#tags].value,
separator,
mw.text.trim(comment_tail)
}
elseif p.tags[tags[#tags].name] == TAG_MULTI_LINE then
tags[#tags].value = utils.join{
tags[#tags].value,
'\n',
comment_tail
}
end
end

-- Detect a new documentation item.
if not start_mode and (new_item or new_tag_item) and not special_tag then
table.insert(documentation.items, {})
item_index = item_index + 1
item = documentation.items[item_index]
item.lineno = line_no
item.code = ''
item.comments = {}
item.description = ''
item.tags = {}
end

-- Concatenate an item with more information.
if
not start_mode and comment_mode and
not new_tag and not doctag_mode and
not pretty_comment and not comment_brace
then
separator = (mw.text.trim(comment_tail):find(patterns.DOCBUNTO_WIKITEXT))
and '\n'
or (#item.description ~= 0 and patterns.DOCBUNTO_CONCAT or '')
item.description = utils.join{
item.description,
separator,
mw.text.trim(comment_tail)
}
end

-- Switch from item information to item tags.
if not start_mode and new_tag and not special_tag then
doctag_mode = true
table.insert(item.tags, utils.process_tag(comment_tail))

-- Extend item tags with lines of further information.
elseif
not start_mode and doctag_mode and
not pretty_comment and not comment_brace
then
tags = item.tags
if p.tags[tags[#tags].name] == TAG_MULTI then
separator = mw.text.trim(comment_tail):find(patterns.DOCBUNTO_WIKITEXT)
and '\n'
or patterns.DOCBUNTO_CONCAT
tags[#tags].value = utils.join{
tags[#tags].value,
separator,
mw.text.trim(comment_tail)
}
elseif p.tags[tags[#tags].name] == TAG_MULTI_LINE then
tags[#tags].value = utils.join{
tags[#tags].value,
'\n',
comment_tail
}
end
end

-- Save pre-item comments to item information.
if not start_mode and (comment_mode or doctag_mode) then
table.insert(item.comments, t.data)
end

-- Export tag support.
if export_mode then
factory_mode = t.posFirst ~= 1
if factory_mode then
item.exports = true
else
documentation.exports = true
end

-- Parse export token data while concatenating code.
subtokens = {}
while t and (not factory_mode or (factory_mode and t.data ~= 'end')) do
if factory_mode then
item.code = utils.join{
item.code,
(t.posFirst == 1 and '\n' or ''),
t.data
}
end

-- Fetch our item export tokens aka "subtokens".
t, i = tokens[i + 1], i + 1
if t and t.posFirst == 1 then
line_no = line_no + 1
end
if t and t.type ~= 'whitespace' and t.type ~= 'keyword' and t.type ~= 'comment' then
table.insert(subtokens, t)
end
end

-- Tracking and boolean variables for parsing exports.
local separator = { [','] = true, [';'] = true }
local brace = { ['{'] = true, ['}'] = true }

local item_reference, item_alias = '', ''
local sequence_index, has_key = 0, false
local subtoken, index = subtokens[2], 2

-- Logic that exports items to an item or module.
while not brace[subtoken.data] do
if subtoken.data == '=' then
has_key = true

elseif not separator[subtoken.data] then
if has_key then
item_reference = item_reference .. subtoken.data
else
item_alias = item_alias .. subtoken.data
end
end

if subtokens[index + 1] and separator[subtokens[index + 1].data] or brace[subtokens[index + 1].data] then
if not has_key then
sequence_index = sequence_index + 1
item_reference, item_alias = item_alias, item_reference
item_alias = '[' .. tostring(sequence_index) .. ']'
end

utils.export_item(documentation, item_reference, item_index, item_alias, factory_mode)
item_reference, item_alias, has_key = '', '', false
end

subtoken, index = subtokens[index + 1], index + 1
end

if not factory_mode then
break -- end of file
else
factory_mode = false -- end of item
end
end

-- Pragma tag support.
if pragma_mode then
tag = utils.process_tag(comment_tail)
if tag.modifiers then
options[tag.value] = yesno((next((tag ).modifiers or {})), true)
elseif tag.value:find(' ') then
local index = tag.value:find(' ')
local key = tag.value:sub(1, index - 1)
local val = tag.value:sub(index + 1)
options[key] = yesno(val)
elseif options[tag.value] == nil then
options[tag.value] = true
end
end
end

-- Package data post-processing.
if (t.type ~= 'comment' or t.data:find('^%-%-%]=*%]$') or t.data:find('^%]=*%]%-%-$')) and (comment_mode or doctag_mode) and start_mode then
documentation.tags = utils.hash_map(documentation.tags)
documentation.name = utils.extract_name(documentation, { project = true })
documentation.info = utils.extract_info(documentation)
documentation.types = utils.extract_types(documentation) or { 'module' }
documentation.type = documentation.types[1]

-- N.B: summary field = 1st comment sentence; description = text remainder.
if #documentation.description ~= 0 then
documentation.summary = match(documentation.description, patterns.DOCBUNTO_SUMMARY)
documentation.description = documentation.description:sub(select(2, documentation.description:find('%s*', #documentation.summary + 1)) + 1)
end

documentation.description = documentation.description:gsub('%s%s+', '\n\n')
documentation.executable = p.tags._code_types[documentation.type] and true or false
utils.correct_subitem_tag(documentation)
utils.override_item_tag(documentation, 'name')
utils.override_item_tag(documentation, 'alias')
utils.override_item_tag(documentation, 'summary')
utils.override_item_tag(documentation, 'description')
utils.override_item_tag(documentation, 'class', 'type')
end

-- Item data post-processing.
if
(t.type ~= 'comment' or t.data:find('^%-%-%]=*%]$') or t.data:find('^%]=*%]%-%-$'))
and (comment_mode or doctag_mode) and item_index ~= 0
then
item.tags = utils.hash_map(item.tags)
item.name = utils.extract_name(item)
item.types = utils.extract_types(item)
item.type = item.types[1]

if #item.description ~= 0 then
item.summary = match(item.description, patterns.DOCBUNTO_SUMMARY)
item.description = item.description:sub(select(2, item.description:find('%s*', #item.summary + 1)) + 1)
end

item.description = item.description:gsub('%s%s+', '\n\n')
new_item_code = true
end

-- Documentation block reset.
if t.type ~= 'comment' or t.data:find('^%-%-%]=*%]$') or t.data:find('^%]=*%]%-%-$') then
start_mode = false
comment_mode = false
doctag_mode = false
export_mode = false
pragma_mode = false
end

-- Don't concatenate module return value into item code.
if t.data == 'return' and t.posFirst == 1 then
return_mode = true
end

-- Item code concatenation.
if item_index ~= 0 and not doctag_mode and not comment_mode and not comment_brace and not return_mode then
separator = #item.code ~= 0 and t.posFirst == 1 and '\n' or ''
item.code = utils.join{ item.code, separator, t.data }

-- Code analysis on item headline.
if new_item_code and item.code:find('\n') and t.posFirst == 1 then
utils.code_heuristic(item)
new_item_code = false
end
end

t, i = tokens[i + 1], i + 1
end

documentation.lineno = line_no

local package_name = (documentation.tags['alias'] or {}).value or documentation.name or DEFAULT_VARIABLE
local package_alias = (documentation.tags['alias'] or {}).value or 'p'
local export_ptn = '^%s([.[])'

for _, item in ipairs(documentation.items) do
if item.name == package_alias or (item.name and item.name:match('^' .. package_alias .. '[.[]')) then
item.alias = item.name:gsub(export_ptn:format(package_alias), documentation.name .. '%1')
end

if
item.name == package_name or
item.tags['export'] or
(item.name and package_name and item.name:find(export_ptn:format(package_name))) or
(item.alias and package_name and item.alias:find(export_ptn:format(package_name)))
then
item.export = true

item.tags['local'] = nil
item.tags['private'] = nil

for index, tag in ipairs(item.tags) do
if tag.name == 'local' or tag.name == 'private' then
table.remove(item.tags, index)
end
end
end

if item.name and (item.name:find('[.:]') or item.name:find('%[[\'"]')) then
item.hierarchy = utils.parse_hierarchy(item.name)
end

item.type = item.type or ((item.alias or item.name or ''):find('[.[]') and 'member' or 'variable')

utils.correct_subitem_tag(item)
utils.override_item_tag(item, 'name')
utils.override_item_tag(item, 'alias')
utils.override_item_tag(item, 'summary')
utils.override_item_tag(item, 'description')
utils.override_item_tag(item, 'class', 'type')
end

-- Sort documentation items by their access level.
-- Items are sorted by whether they are exported at the module level.
-- Items are then subsorted by whether the item is `@local` aka `@private`.
table.sort(documentation.items, function(item1, item2)
local inaccessible1 = item1.tags['local'] or item1.tags['private']
local inaccessible2 = item2.tags['local'] or item2.tags['private']

-- Send package items to the top.
if item1.export and not item2.export then
return true
elseif item2.export and not item1.export then
return false

-- Send private items to the bottom.
elseif inaccessible1 and not inaccessible2 then
return false
elseif inaccessible2 and not inaccessible1 then
return true

-- Optional alphabetical sort.
elseif options.sort then
return (item1.alias or item1.name) < (item2.alias or item2.name)

-- Sort via source code order by default.
else
return item1.lineno < item2.lineno
end
end)

end)

if not p_success then
mw.addWarning("Docbunto error: " .. p_error)
end

return documentation
end

--- Doclet renderer for Docbunto taglet data.
-- @function p.doclet
-- @param {table} data Taglet documentation data.
-- @param[opt] {options} options Configuration options.
-- @return {string} Wikitext documentation output.
function p.doclet(data, options)
local documentation = mw.html.create()
local namespace_ptn = utils.join{ '^', mw.site.namespaces[828].name, ':' }
local codepage = data.filename:gsub(namespace_ptn, '', 1)

options = options or {}
options.file = data.filename
frame = frame or mw.getCurrentFrame():getParent() or mw.getCurrentFrame()

local maybe_md = options.plain and utils.identity or frontend.markdown
local tohtml = function(str)
return frame:preprocess(maybe_md(str))
end

-- Disable edit sections for automatic documentation pages.
if not options.code then
documentation:wikitext(frame:preprocess('__NOEDITSECTION__'))
end

-- Information
if not options.code and options.box then
local custom, infobox = pcall(require, 'Module:Docbunto/infobox')
if custom and type(infobox) == 'function' then
documentation:wikitext(infobox(data, codepage, frame, options, title, maybe_md)):newline()
end
end

-- Documentation lede.
if not options.code and (#(data.summary or '') + #data.description) ~= 0 then
local separator = #(data.summary or '') ~= 0 and #data.description ~= 0
and (data.description:find(patterns.DOCBUNTO_WIKITEXT) and '\n\n' or patterns.DOCBUNTO_CONCAT)
or ''
local intro = utils.join{ data.summary or '', separator, data.description }
intro = tohtml(intro:gsub('^(' .. codepage .. ')', mw.text.tag('b', nil, '%1')))
if options.migration then
documentation:wikitext(frame:preprocess(mw.text.tag{
name = 'syntaxhighlight',
content = intro
})):newline():newline()
else
documentation:wikitext(intro):newline():newline()
end
end

-- Custom documentation preface.
if options.preface then
documentation:wikitext(options.preface):newline():newline()
end

-- Start code documentation.
local codedoc = mw.html.create()
local function_module = data.tags['param'] or data.tags['return']
local header_type =
documentation.type == 'classmod'
and 'class'
or function_module
and 'function'
or 'items'
if (function_module or #data.items ~= 0) and not options.code or options.preface then
codedoc
:tag('h2')
:wikitext(i18n:msg('header-documentation'))
:done()
:newline()
end
if (function_module or #data.items ~= 0) then
codedoc
:tag('h3')
:wikitext(i18n:msg('header-' .. header_type))
:done()
:newline()
end

-- Function module support.
if function_module then
data.type, data.types[1] = 'function', 'function'

options.item_id = data.name
if not options.code or not options.verbose then data.description = '' end
frontend.render_item(codedoc, data, options, frontend.pretask_function_name)

if not options.simple and data.tags['param'] then
frontend.render_tag(codedoc, 'param', data.tags['param'], options, frontend.pretask_variable_prefix)
end
if not options.simple and data.tags['error'] then
frontend.render_tag(codedoc, 'error', data.tags['error'], options, frontend.pretask_error_line)
end
if not options.simple and data.tags['return'] then
frontend.render_tag(codedoc, 'return', data.tags['return'], options)
end
end

-- Render documentation items.
local other_header = false
local private_header = false
local inaccessible
for _, item in ipairs(data.items) do
inaccessible = item.tags['local'] or item.tags['private']
if not options.all and inaccessible then
break
end

if
not other_header and item.type ~= 'section' and item.type ~= 'type' and
not item.export and not item.hierarchy and not inaccessible
then
codedoc
:tag('h3')
:wikitext(i18n:msg('header-other'))
:done()
:newline()
other_header = true
end
if not private_header and options.all and inaccessible then
codedoc
:tag('h3')
:wikitext(i18n:msg('header-private'))
:done()
:newline()
private_header = true
end

if item.type == 'section' then
codedoc
:tag('h3')
:wikitext((mw.ustring.gsub(item.summary or item.alias or item.name, '[.։。।෴۔።]$', '')))
:done()
:newline()
if #item.description ~= 0 then
codedoc:wikitext(mw.text.trim(item.description)):newline()
end

elseif item.type == 'type' then
if options.strip and item.export and item.hierarchy then
if item.alias then
item.alias = item.alias:gsub('^[%w_]+[.[]?', '')
else
item.name = item.name:gsub('^[%w_]+[.[]?', '')
end
end
codedoc
:tag('h3')
:wikitext(mw.text.tag('code', {}, item.alias or item.name))
:done()
:newline()
if (#(item.summary or '') + #item.description) ~= 0 then
local separator = #(item.summary or '') ~= 0 and #item.description ~= 0
and (item.description:find(patterns.DOCBUNTO_WIKITEXT) and '\n\n' or patterns.DOCBUNTO_CONCAT)
or ''
codedoc:wikitext((item.summary or '') .. separator .. item.description):newline()
end

elseif item.type == 'function' then
options.item_id = item.alias or item.name
frontend.render_item(codedoc, item, options, frontend.pretask_function_name)
if not options.simple and item.tags['param'] then
frontend.render_tag(codedoc, 'param', item.tags['param'], options, frontend.pretask_variable_prefix)
end
if not options.simple and item.tags['error'] then
frontend.render_tag(codedoc, 'error', item.tags['error'], options, frontend.pretask_error_line)
end
if not options.simple and item.tags['return'] then
frontend.render_tag(codedoc, 'return', item.tags['return'], options)
end

elseif
item.type == 'table' or
item.type ~= nil and (
item.type == 'member' or
item.type == 'variable'
) and (item.alias or item.name)
then
options.item_id = item.alias or item.name
frontend.render_item(codedoc, item, options)
if not options.simple and item.tags['field'] then
frontend.render_tag(codedoc, 'field', item.tags['field'], options, frontend.pretask_variable_prefix)
end
end

if item.type ~= 'section' and item.type ~= 'type' then
if not options.simple and item.tags['note'] then
frontend.render_tag(codedoc, 'note', item.tags['note'], options)
end
if not options.simple and item.tags['warning'] then
frontend.render_tag(codedoc, 'warning', item.tags['warning'], options)
end
if not options.simple and item.tags['fixme'] then
frontend.render_tag(codedoc, 'fixme', item.tags['fixme'], options)
end
if not options.simple and item.tags['todo'] then
frontend.render_tag(codedoc, 'todo', item.tags['todo'], options)
hasTodoItems = true
end
if not options.simple and item.tags['usage'] then
frontend.render_tag(codedoc, 'usage', item.tags['usage'], options, frontend.pretask_usage_highlight)
end
if not options.simple and item.tags['see'] then
frontend.render_tag(codedoc, 'see', item.tags['see'], options)
end
end
end

-- Render module-level annotations.
local header_level = options.code and 'h3' or 'h2'
local header_text
for _, tag_name in ipairs(p.tags._annotation_hierarchy) do
if data.tags[tag_name] then
header_text = i18n:msg('tag-' .. tag_name, data.tags[tag_name].value and '1' or '2')
header_text = '<' .. header_level .. '>' .. ' ' .. header_text .. ' ' .. '</' .. header_level .. '>'
codedoc:newline():wikitext(header_text):newline()
if data.tags[tag_name].value then
codedoc:wikitext(data.tags[tag_name].value):newline()
else
for _, tag_el in ipairs(data.tags[tag_name]) do
codedoc:wikitext('* ' .. tag_el.value):newline()
end
end
end
end

-- Byline for autogeneration.
if options.footer then
codedoc:newline()
codedoc:tag('hr'):done()
codedoc:newline()
codedoc:tag('p'):css( 'text-align', 'right' ):css('font-size', '80%'):wikitext(i18n:msg('message-autogeneration'))
end

-- Add nowiki tags for EOF termination in tests.
codedoc:tag('nowiki', { selfClosing = true })

-- Code documentation formatting.
codedoc = tohtml(tostring(codedoc))

documentation:wikitext(codedoc)

-- Endmatter table for module information.
if options.card then
local endmatter = mw.html.create('table')
endmatter:addClass('wikitable')
endmatter:css('width', '75%')
endmatter:css('margin', '0 auto 1em auto')

local module_type = data.type == 'module'
and i18n:msg('invocable-module')
or i18n:msg('meta-module')

endmatter
:tag('caption')
:wikitext('Module information card (autogenerated)')

endmatter
:tag('tr')
:tag('th'):attr('scope', 'col'):wikitext('Name'):done()
:tag('th'):attr('scope', 'col'):wikitext('Value'):done()

if options.image or data.info and data.info['image'] then
endmatter
:tag('tr')
:tag('td'):attr('scope', 'row'):wikitext(i18n:msg('endmatter-image')):done()
:tag('td')
:attr('align', 'center')
:wikitext('[[File:' .. (options.image or data.info['image']) .. '|270px|center]]')
:done()
:done()
end

if options.caption or data.info and data.info['caption'] then
endmatter
:tag('tr')
:tag('td'):attr('scope', 'row'):wikitext(i18n:msg('endmatter-caption')):done()
:tag('td')
:attr('align', options.image or data.info['image'] and 'center' or 'left')
:wikitext(tohtml(options.caption or data.info['caption']))
:done()
:done()
end

endmatter
:tag('tr')
:tag('td'):attr('scope', 'row'):wikitext((gsub(i18n:msg('type-variable'), '^%w', mw.ustring.upper))):done()
:tag('td')
:attr('align', options.image or data.info and data.info['image'] and 'center' or 'left')
:wikitext(mw.text.tag({
name = options.image or data.info and data.info['image'] and 'h1' or 'span',
content = mw.text.tag({
name = 'b',
content = mw.text.tag({
name = 'code',
content = data.name or DEFAULT_VARIABLE
})
})
})):done()
:done()
:tag('tr')
:tag('td'):wikitext(i18n:msg('code')):done()
:tag('td'):wikitext(tohtml('[[' .. data.filename .. ']]')):done()
:done()

if data.info and data.info['release'] then
endmatter
:tag('tr')
:tag('td'):attr('scope', 'row'):wikitext(i18n:msg('release-status')):done()
:tag('td'):wikitext(tohtml(data.info['release'])):done()
:done()
end

if data.summary then
endmatter
:tag('tr')
:tag('td'):attr('scope', 'row'):wikitext(i18n:msg('description')):done()
:tag('td'):wikitext(tohtml(data.summary)):done()
:done()
end

if data.info and data.info['author'] then
endmatter
:tag('tr')
:tag('td'):attr('scope', 'row'):wikitext(i18n:msg('author')):done()
:tag('td'):newline():wikitext(tohtml(data.info['author'])):done()
:done()
end

if data.info and data.info['attribution'] then
endmatter
:tag('tr')
:tag('td'):attr('scope', 'row'):wikitext(i18n:msg('using-code-by')):done()
:tag('td'):wikitext(tohtml(data.info['attribution'])):done()
:done()
end

if data.info and data.info['credit'] then
endmatter
:tag('tr')
:tag('td'):attr('scope', 'row'):wikitext(i18n:msg('other-attribution')):done()
:tag('td'):wikitext(tohtml(data.info['credit'])):done()
:done()
end

if data.info and data.info['require'] then
data.info['require'] = data.info['require']
:gsub('^[^[%s]+$', '[[%1]]')
:gsub('%* ([^[%s]+)', '* [[%1]]')
endmatter
:tag('tr')
:tag('td'):attr('scope', 'row'):wikitext(i18n:msg('dependencies')):done()
:tag('td'):newline():wikitext(tohtml(data.info['require'])):done()
:done()
end

if data.info and data.info['demo'] then
endmatter
:tag('tr')
:tag('td'):attr('scope', 'row'):wikitext(i18n:msg('examples')):done()
:tag('td'):wikitext(tohtml(data.info['demo'])):done()
:done()
end

endmatter:newline()
endmatter = tostring(endmatter)
documentation:newline():newline()
documentation:wikitext(endmatter)
end

documentation = tostring(documentation)
if hasTodoItems and options.autodoc
and mw.title.new('Module:' .. options.file).fullText == mw.title.getCurrentTitle().fullText then
documentation = documentation .. '[[Category:' .. i18n:msg('todo') .. ']]'
end
if mw.title.new('Module:Docbunto/styles.css').exists then
documentation = documentation .. frame:extensionTag('templatestyles', '', {src = 'Module:Docbunto/styles.css'})
end
return documentation
end

--- Token dictionary for Docbunto tags.
-- Maps Docbunto tag names to tag tokens.
-- * Multi-line tags use the `'M'` token.
-- * Multi-line preformatted tags use the `'ML'` token.
-- * Identifier tags use the `'ID'` token.
-- * Single-line tags use the `'S'` token.
-- * Flags use the `'N'` token.
-- * Type tags use the `'T'` token.
-- @table p.tags
p.tags = {
-- Item-level tags, available for global use.
['param'] = 'M', ['see'] = 'M', ['note'] = 'M', ['usage'] = 'ML',
['description'] = 'M', ['field'] = 'M', ['return'] = 'M',
['fixme'] = 'M', ['todo'] = 'M', ['warning'] = 'M', ['error'] = 'M';
['class'] = 'ID', ['name'] = 'ID', ['alias'] = 'ID';
['summary'] = 'S', ['pragma'] = 'S', ['factory'] = 'S',
['release'] = 'S', ['author'] = 'S', ['copyright'] = 'S', ['license'] = 'S',
['image'] = 'S', ['caption'] = 'S', ['require'] = 'S', ['attribution'] = 'S',
['credit'] = 'S', ['demo'] = 'S';
['local'] = 'N', ['export'] = 'N', ['private'] = 'N', ['constructor'] = 'N',
['static'] = 'N';
-- Project-level tags, all scoped to a file.
['module'] = 'T', ['script'] = 'T', ['classmod'] = 'T', ['topic'] = 'T',
['submodule'] = 'T', ['example'] = 'T', ['file'] = 'T';
-- Module-level tags, used to register module items.
['function'] = 'T', ['table'] = 'T', ['member'] = 'T', ['variable'] = 'T',
['section'] = 'T', ['type'] = 'T';
}
p.tags._alias = {
-- Normal aliases.
['about'] = 'summary',
['abstract'] = 'summary',
['brief'] = 'summary',
['bug'] = 'fixme',
['argument'] = 'param',
['credits'] = 'credit',
['code'] = 'usage',
['details'] = 'description',
['discussion'] = 'description',
['exception'] = 'error',
['lfunction'] = 'function',
['package'] = 'module',
['property'] = 'member',
['raise'] = 'error',
['requires'] = 'require',
['returns'] = 'return',
['throws'] = 'error',
['typedef'] = 'type',
-- Typed aliases.
['bool'] = 'field',
['func'] = 'field',
['int'] = 'field',
['number'] = 'field',
['string'] = 'field',
['tab'] = 'field',
['vararg'] = 'param',
['tfield'] = 'field',
['tparam'] = 'param',
['treturn'] = 'return'
}
p.tags._type_alias = {
-- Implicit type value alias.
['bool'] = 'boolean',
['func'] = 'function',
['int'] = 'number',
['number'] = 'number',
['string'] = 'string',
['tab'] = 'table',
['vararg'] = '...',
-- Pure typed modifier alias.
['tfield'] = 'variable',
['tparam'] = 'variable',
['treturn'] = 'variable'
}
p.tags._project_level = {
-- Contains code.
['module'] = true,
['script'] = true,
['classmod'] = true,
['submodule'] = true,
['file'] = true,
-- Contains documentation.
['topic'] = true,
['example'] = true
}
p.tags._code_types = {
['module'] = true,
['script'] = true,
['classmod'] = true
}
p.tags._module_info = {
['image'] = true,
['caption'] = true,
['release'] = true,
['author'] = true,
['copyright'] = true,
['license'] = true,
['require'] = true,
['credit'] = true,
['attribution'] = true,
['demo'] = true
}
p.tags._annotation_tags = {
['field'] = true,
['warning'] = true,
['fixme'] = true,
['note'] = true,
['todo'] = true,
['see'] = true
}
p.tags._annotation_hierarchy = {
'warning',
'fixme',
'note',
'todo',
'see'
}
p.tags._privacy_tags = {
['private'] = true,
['local'] = true
}
p.tags._generic_tags = {
['variable'] = true,
['member'] = true
}
p.tags._subtype_tags = {
['factory'] = true,
['local'] = true,
['private'] = true,
['constructor'] = true,
['static'] = true
}
p.tags._subtype_hierarchy = {
'private',
'local',
'static',
'factory',
'constructor'
}

return p

Module:I18n

2026-09-18T17:39:11Z

Austenasia: 1 revision imported

--- I18n library for message storage in Lua datastores.
-- The module is designed to enable message separation from modules &
-- templates. It has support for handling language fallbacks. This
-- module is a Lua port of [[wikia:dev:I18n-js]] and i18n modules that can be loaded
-- by it are editable through [[wikia:dev:I18nEdit]].
--
-- On Wikimedia projects, i18n messages are editable
-- through [[c:Special:PrefixIndex/Data:i18n/|Data:i18n/]] subpages on
-- Wikimedia Commons.
--
-- @module i18n
-- @version 1.4.0
-- @require Module:Entrypoint
-- @require Module:Fallbacklist
-- @author [[wikia:dev:User:KockaAdmiralac|KockaAdmiralac]] (original Fandom implementation)
-- @author [[wikia:dev:User:Speedit|Speedit]] (original Fandom implementation)
-- @author [[User:Awesome Aasim|Awesome Aasim]] (Wikimedia port)
-- @attribution [[wikia:dev:User:Cqm|Cqm]]
-- @release beta
-- @see [[wikia:dev:I18n|I18n guide]]
-- @see [[wikia:dev:I18n-js]]
-- @see [[wikia:dev:I18nEdit]]
-- <nowiki>
local i18n, _i18n = {}, {}

-- Module variables & dependencies.
local title = mw.title.getCurrentTitle()
local fallbacks = require('Module:Fallbacklist')
local entrypoint = require('Module:Entrypoint')
local uselang

--- Argument substitution as $n where n > 0.
-- @function _i18n.handleArgs
-- @param {string} msg Message to substitute arguments into.
-- @param {table} args Arguments table to substitute.
-- @return {string} Resulting message.
-- @local
function _i18n.handleArgs(msg, args)
for i, a in ipairs(args) do
msg = (string.gsub(msg, '%$' .. tostring(i), tostring(a)))
end
return msg
end

--- Checks whether a language code is valid.
-- @function _i18n.isValidCode
-- @param {string} code Language code to check.
-- @return {boolean} Whether the language code is valid.
-- @local
function _i18n.isValidCode(code)
return type(code) == 'string' and #mw.language.fetchLanguageName(code) ~= 0
end

--- Checks whether a message contains unprocessed wikitext.
-- Used to optimise message getter by not preprocessing pure text.
-- @function _i18n.isWikitext
-- @param {string} msg Message to check.
-- @return {boolean} Whether the message contains wikitext.
function _i18n.isWikitext(msg)
return
type(msg) == 'string' and
(
msg:find('%-%-%-%-') or
msg:find('%f[^\n%z][;:*#] ') or
msg:find('%f[^\n%z]==* *[^\n|]+ =*=%f[\n]') or
msg:find('%b<>') or msg:find('\'\'') or
msg:find('%[%b[]%]') or msg:find('{%b{}}')
)
end

--- I18n datastore class.
-- This is used to control language translation and access to individual
-- messages. The datastore instance provides language and message
-- getter-setter methods, which can be used to internationalize Lua modules.
-- The language methods (any ending in `Lang`) are all **chainable**.
-- @type Data
local Data = {}
Data.__index = Data

--- Datastore message getter utility.
-- This method returns localized messages from the datastore corresponding
-- to a `key`. These messages may have `$n` parameters, which can be
-- replaced by optional argument strings supplied by the `msg` call.
--
-- This function supports [[mw:Extension:Scribunto/Lua reference manual#named_arguments|named
-- arguments]]. The named argument syntax is more versatile despite its
-- verbosity; it can be used to select message language & source(s).
-- @function Data:msg
-- @usage
--
-- ds:msg{
-- key = 'message-name',
-- lang = '',
-- args = {...},
-- sources = {}
-- }
--
-- @usage
--
-- ds:msg('message-name', ...)
--
-- @param {string|table} opts Message configuration or key.
-- @param[opt] {string} opts.key Message key to return from the
-- datastore.
-- @param[opt] {table} opts.args Arguments to substitute into the
-- message (`$n`).
-- @param[opt] {table} opts.sources Source names to limit to (see
-- `Data:fromSources`).
-- @param[opt] {table} opts.lang Temporary language to use (see
-- `Data:inLang`).
-- @param[opt] {string} ... Arguments to substitute into the message
-- (`$n`).
-- @error[115] {string} 'missing arguments in Data:msg'
-- @return {string} Localised datastore message or `'<key>'`.
function Data:msg(opts, ...)
local frame = mw.getCurrentFrame()
-- Argument normalization.
if not self or not opts then
error('missing arguments in Data:msg')
end
local key = type(opts) == 'table' and opts.key or opts
local args = opts.args or {...}
-- Configuration parameters.
if opts.sources then
self:fromSources(unpack(opts.sources))
end
if opts.lang then
self:inLang(opts.lang)
end
-- Source handling.
local source_n = self.tempSources or self._sources
local source_i = {}
for n, i in pairs(source_n) do
source_i[i] = n
end
self.tempSources = nil
-- Language handling.
local lang = self.tempLang or self.defaultLang
self.tempLang = nil
-- Message fetching.
local msg
for i, messages in ipairs(self._messages) do
-- Message data.
local msg = (messages[lang] or {})[key]
-- Fallback support (experimental).
for _, l in ipairs((fallbacks[lang] or {})) do
if msg == nil then
msg = (messages[l] or {})[key]
end
end
-- Internal fallback to 'en'.
msg = msg ~= nil and msg or messages.en[key]
-- Handling argument substitution from Lua.
if msg and source_i[i] and #args > 0 then
msg = _i18n.handleArgs(msg, args)
end
if msg and source_i[i] and lang ~= 'qqx' then
return frame and _i18n.isWikitext(msg)
and frame:preprocess(mw.text.trim(msg))
or mw.text.trim(msg)
end
end
return '⧼' .. mw.text.nowiki(key) .. '⧽'
end

--- Datastore template parameter getter utility.
-- This method, given a table of arguments, tries to find a parameter's
-- localized name in the datastore and returns its value, or nil if
-- not present.
--
-- This method always uses the wiki's content language.
-- @function Data:parameter
-- @param {string} parameter Parameter's key in the datastore
-- @param {table} args Arguments to find the parameter in
-- @error[176] {string} 'missing arguments in Data:parameter'
-- @return {string|nil} Parameter's value or nil if not present
function Data:parameter(key, args)
-- Argument normalization.
if not self or not key or not args then
error('missing arguments in Data:parameter')
end
local contentLang = mw.language.getContentLanguage():getCode()
-- Message fetching.
for i, messages in ipairs(self._messages) do
local msg = (messages[contentLang] or {})[key]
if msg ~= nil and args[msg] ~= nil then
return args[msg]
end
for _, l in ipairs((fallbacks[contentLang] or {})) do
if msg == nil or args[msg] == nil then
-- Check next fallback.
msg = (messages[l] or {})[key]
else
-- A localized message was found.
return args[msg]
end
end
-- Fallback to English.
msg = messages.en[key]
if msg ~= nil and args[msg] ~= nil then
return args[msg]
end
end
end

--- Datastore temporary source setter to a specificed subset of datastores.
-- By default, messages are fetched from the datastore in the same
-- order of priority as `i18n.loadMessages`.
-- @function Data:fromSource
-- @param {string} ... Source name(s) to use.
-- @return {Data} Datastore instance.
function Data:fromSource(...)
local c = select('#', ...)
if c ~= 0 then
self.tempSources = {}
for i = 1, c do
local n = select(i, ...)
if type(n) == 'string' and type(self._sources[n]) == 'number' then
self.tempSources[n] = self._sources[n]
end
end
end
return self
end

--- Datastore default language getter.
-- @function Data:getLang
-- @return {string} Default language to serve datastore messages in.
function Data:getLang()
return self.defaultLang
end

--- Datastore language setter to `wgUserLanguage`.
-- @function Data:useUserLang
-- @return {Data} Datastore instance.
-- @note Scribunto only registers `wgUserLanguage` when an
-- invocation is at the top of the call stack.
function Data:useUserLang()
self.defaultLang = i18n.getLang() or self.defaultLang
return self
end

--- Datastore language setter to `wgContentLanguage`.
-- @function Data:useContentLang
-- @return {Data} Datastore instance.
function Data:useContentLang()
self.defaultLang = mw.language.getContentLanguage():getCode()
return self
end

--- Datastore language setter to specificed language.
-- @function Data:useLang
-- @param {string} code Language code to use.
-- @return {Data} Datastore instance.
function Data:useLang(code)
self.defaultLang = _i18n.isValidCode(code)
and code
or self.defaultLang
return self
end

--- Temporary datastore language setter to `wgUserLanguage`.
-- The datastore language reverts to the default language in the next
-- @{Data:msg} call.
-- @function Data:inUserLang
-- @return {Data} Datastore instance.
function Data:inUserLang()
self.tempLang = i18n.getLang() or self.tempLang
return self
end

--- Temporary datastore language setter to `wgContentLanguage`.
-- Only affects the next @{Data:msg} call.
-- @function Data:inContentLang
-- @return {Data} Datastore instance.
function Data:inContentLang()
self.tempLang = mw.language.getContentLanguage():getCode()
return self
end

--- Temporary datastore language setter to a specificed language.
-- Only affects the next @{Data:msg} call.
-- @function Data:inLang
-- @param {string} code Language code to use.
-- @return {Data} Datastore instance.
function Data:inLang(code)
self.tempLang = _i18n.isValidCode(code)
and code
or self.tempLang
return self
end

-- Package functions.

--- Localized message getter by key.
-- Can be used to fetch messages in a specific language code through `uselang`
-- parameter. Extra numbered parameters can be supplied for substitution into
-- the datastore message.
-- @function i18n.getMsg
-- @param {table} frame Frame table from invocation.
-- @param {table} frame.args Metatable containing arguments.
-- @param {string} frame.args[1] ROOTPAGENAME of i18n submodule.
-- @param {string} frame.args[2] Key of i18n message.
-- @param[opt] {string} frame.args.lang Default language of message.
-- @error[271] {string} 'missing arguments in i18n.getMsg'
-- @return {string} I18n message in localised language.
function i18n.getMsg(frame)
if
not frame or
not frame.args or
not frame.args[1] or
not frame.args[2]
then
error('missing arguments in i18n.getMsg')
end
local source = frame.args[1]
local key = frame.args[2]
-- Pass through extra arguments.
local repl = {}
for i, a in ipairs(frame.args) do
if i >= 3 then
repl[i-2] = a
end
end
-- Load message data.
local ds = i18n.loadMessages(source)
-- Pass through language argument.
ds:inLang(frame.args.uselang)
-- Return message.
return ds:msg { key = key, args = repl }
end

--- I18n message datastore loader.
-- @function i18n.loadMessages
-- @param {string} ... ROOTPAGENAME/path for target i18n
-- submodules.
-- @error[322] {string} 'no source supplied to i18n.loadMessages'
-- @return {table} I18n datastore instance.
-- @usage require('Module:I18n').loadMessages('1', '2')
function i18n.loadMessages(...)
local ds
local i = 0
local s = {}
for j = 1, select('#', ...) do
local source = select(j, ...)
if type(source) == 'string' and source ~= '' then
i = i + 1
s[source] = i
if not ds then
-- Instantiate datastore.
ds = {}
ds._messages = {}
-- Set default language.
setmetatable(ds, Data)
ds:useUserLang()
end
source = string.gsub(source, '^.', mw.ustring.upper)
local success, messages = pcall(mw.loadData, mw.ustring.find(source, ':')
and source
or 'Module:' .. source .. '/i18n')
if success then
local msgCopy = {}
local langSecond = nil
for lang_id, msgtbl in pairs(messages) do
if langSecond == nil then
if lang_id == "qqq" or fallbacks[lang_id] ~= nil then
langSecond = false
else
langSecond = true
end
end
for id_lang, msg in pairs(msgtbl) do
if langSecond then
msgCopy[id_lang] = msgCopy[id_lang] or {}
msgCopy[id_lang][lang_id] = msg
else
msgCopy[lang_id] = msgCopy[lang_id] or {}
msgCopy[lang_id][id_lang] = msg
end
end
end
ds._messages[i] = msgCopy
end
local tab = mw.ext.data.get('I18n/' .. source .. '.tab', '_')
local T = {}
if not success and not tab then error("i18n for " .. source .. " is missing") end
for _, row in pairs(tab.data) do -- convert the output into a dictionary table
local id, t = unpack(row)
for lang, msg in pairs(t) do
if not T[lang] then T[lang] = {} end
T[lang][id] = msg
end
end
if not success then
ds._messages[i] = T
else
for lang, msgTbl in pairs(T) do
ds._messages[i][lang] = ds._messages[i][lang] or msgTbl
end
end
end
end
if not ds then
error('no source supplied to i18n.loadMessages')
else
-- Attach source index map.
ds._sources = s
-- Return datastore instance.
return ds
end
end

--- Language code getter.
-- Can validate a template's language code through `uselang` parameter.
-- @function i18n.getLang
-- @return {string} Language code.
function i18n.getLang()
local frame = mw.getCurrentFrame() or {}
local parentFrame = frame.getParent and frame:getParent() or {}

local code = mw.language.getContentLanguage():getCode()
local subPage = title.subpageText

-- Language argument test.
local langOverride =
(frame.args or {}).uselang or
(parentFrame.args or {}).uselang
if _i18n.isValidCode(langOverride) then
code = langOverride

-- Subpage language test.
elseif title.isSubpage and _i18n.isValidCode(subPage) then
code = _i18n.isValidCode(subPage) and subPage or code

-- User language test.
elseif parentFrame.preprocess or frame.preprocess then
uselang = uselang
or parentFrame.preprocess
and parentFrame:preprocess('{{int:lang}}')
or frame:preprocess('{{int:lang}}')
local decodedLang = mw.text.decode(uselang)
if decodedLang ~= '<lang>' and decodedLang ~= '⧼lang⧽' then
code = decodedLang == '(lang)'
and 'qqx'
or uselang
end
end

return code
end

-- Credit to http://stackoverflow.com/a/1283608/2644759
-- cc-by-sa 3.0
local function tableMerge(t1, t2, overwrite)
for k,v in pairs(t2) do
if type(v) == "table" and type(t1[k]) == "table" then
-- since type(t1[k]) == type(v) == "table", so t1[k] and v is true
tableMerge(t1[k], v, overwrite) -- t2[k] == v
else
if overwrite or t1[k] == nil then t1[k] = v end
end
end
return t1
end

--- Given an i18n table instantiates the values (deprecated)
-- @function i18n.loadI18n
-- @param {string} name name of module with i18n
-- @param {table} i18n_arg existing i18n
function i18n.loadI18n(name, i18n_arg)
local exist, res = pcall(require, name)
if exist and next(res) ~= nil then
if i18n_arg then
tableMerge(i18n_arg, res.i18n, true)
end
end
end

--- Loads an i18n for a specific frame (deprecated)
-- @function i18n.loadI18nFrame
-- @param {string} name name of module with i18n
-- @param {table} i18n_arg existing i18n
function i18n.loadI18nFrame(frame, i18n_arg)
return i18n.loadI18n(frame:getTitle().."/i18n", i18n_arg)
end

--- Wrapper for the module.
-- @function i18n.main
-- @param {table} frame Frame invocation object.
-- @return {string} Module output in template context.
-- @usage {{#invoke:i18n|main}}
i18n.main = entrypoint(i18n)

return require("Module:Deprecated")(i18n,
{
["loadI18n"] = {
deprecated = true,
replacement = "use <code>i18n.loadMessages</code>"
},
["loadI18nFrame"] = {
deprecated = true,
replacement = "use <code>i18n.loadMessages</code>"
}
}
)
-- </nowiki>