-- 本模块提供对从 #invoke 传递给 Scribunto 的参数进行简单处理的功能。
-- 它旨在供其他 Lua 模块使用，不应直接从 #invoke 调用。
local libraryUtil = require('libraryUtil')
local checkType = libraryUtil.checkType
local arguments = {}
-- 生成四种不同的 tidyVal 函数，这样我们就不必每次调用时都检查选项。
local function tidyValDefault(key, val)
if type(val) == 'string' then
val = val:match('^%s*(.-)%s*$')
if val == '' then
return nil
else
return val
end
else
return val
end
end
local function tidyValTrimOnly(key, val)
if type(val) == 'string' then
return val:match('^%s*(.-)%s*$')
else
return val
end
end
local function tidyValRemoveBlanksOnly(key, val)
if type(val) == 'string' then
if val:find('%S') then
return val
else
return nil
end
else
return val
end
end
local function tidyValNoChange(key, val)
return val
end
local function matchesTitle(given, title)
local tp = type( given )
return (tp == 'string' or tp == 'number') and mw.title.new( given ).prefixedText == title
end
function arguments.getArgs(frame, options)
checkType('getArgs', 1, frame, 'table', true)
checkType('getArgs', 2, options, 'table', true)
frame = frame or {}
options = options or {}
--[[
-- 获取参数表。如果传递了有效的 frame 对象，根据选项设置和父 frame 的可用性，
-- 获取 frame 参数 (fargs) 和父 frame 参数 (pargs)。如果没有传递有效的 frame 对象，
-- 说明我们是从另一个 Lua 模块或调试控制台调用的，因此假设直接传递了参数表，
-- 并将其分配给新变量 (luaArgs)。
--]]
local fargs, pargs, luaArgs
if type(frame.args) == 'table' and type(frame.getParent) == 'function' then
if options.wrappers then
--[[
-- wrappers 选项使 Module:Arguments 在 frame 参数表或父参数表中查找参数，
-- 但不会同时查找两者。这意味着用户可以使用 #invoke 语法或包装器模板，
-- 而不会因为同时在 frame 和父 frame 中查找参数而导致性能损失。
-- 如果 Module:Arguments 在 options.wrapper 中找到父 frame 的标题，
-- 它将在父 frame 中查找参数；否则将在传递给 getArgs 的 frame 对象中查找参数。
--]]
local parent = frame:getParent()
if not parent then
fargs = frame.args
else
local title = parent:getTitle():gsub('/sandbox$', '')
local found = false
if matchesTitle(options.wrappers, title) then
found = true
elseif type(options.wrappers) == 'table' then
for _,v in pairs(options.wrappers) do
if matchesTitle(v, title) then
found = true
break
end
end
end
-- 我们在这里特别测试 false，这样 nil（默认值）的行为就像 true。
if found or options.frameOnly == false then
pargs = parent.args
end
if not found or options.parentOnly == false then
fargs = frame.args
end
end
else
-- options.wrapper 未设置，因此检查其他选项。
if not options.parentOnly then
fargs = frame.args
end
if not options.frameOnly then
local parent = frame:getParent()
pargs = parent and parent.args or nil
end
end
if options.parentFirst then
fargs, pargs = pargs, fargs
end
else
luaArgs = frame
end
-- 设置参数表的优先级顺序。如果变量为 nil，则不会添加到表中，
-- 这样可以避免 frame/父 args 和 Lua args 之间的冲突。
local argTables = {fargs}
argTables[#argTables + 1] = pargs
argTables[#argTables + 1] = luaArgs
--[[
-- 生成 tidyVal 函数。如果用户已指定，则使用该函数；如果没有，
-- 则根据所选选项选择四个函数之一。这样我们就不必在每次调用函数时
-- 都调用 options 表。
--]]
local tidyVal = options.valueFunc
if tidyVal then
if type(tidyVal) ~= 'function' then
error(
"bad value assigned to option 'valueFunc'"
.. '(function expected, got '
.. type(tidyVal)
.. ')',
2
)
end
elseif options.trim ~= false then
if options.removeBlanks ~= false then
tidyVal = tidyValDefault
else
tidyVal = tidyValTrimOnly
end
else
if options.removeBlanks ~= false then
tidyVal = tidyValRemoveBlanksOnly
else
tidyVal = tidyValNoChange
end
end
--[[
-- 设置 args、metaArgs 和 nilArgs 表。args 将是函数访问的表，
-- metaArgs 将保存实际参数。nil 参数在 nilArgs 中缓存，
-- 元表将它们全部连接在一起。
--]]
local args, metaArgs, nilArgs, metatable = {}, {}, {}, {}
setmetatable(args, metatable)
local function mergeArgs(tables)
--[[
-- 接受多个表作为输入，并将它们的键和值合并到一个表中。
-- 如果值已存在，则不会被覆盖；列在前面的表具有优先权。
-- 我们还在缓存 nil 值，如果它们是 's'（软），则可以被覆盖。
--]]
for _, t in ipairs(tables) do
for key, val in pairs(t) do
if metaArgs[key] == nil and nilArgs[key] ~= 'h' then
local tidiedVal = tidyVal(key, val)
if tidiedVal == nil then
nilArgs[key] = 's'
else
metaArgs[key] = tidiedVal
end
end
end
end
end
--[[
-- 定义元表行为。参数在 metaArgs 表中缓存，并且只从参数表中获取一次。
-- 从参数表中获取参数是本模块中最耗费资源的步骤，因此我们尽可能避免这样做。
-- 因此，nil 参数也在 nilArgs 表中缓存。此外，我们在元表中记录 pairs 和 ipairs
-- 何时被调用，这样我们就不会在参数表上多次运行 pairs 和 ipairs。
-- 如果 pairs 已经运行过，我们也不会在 fargs 和 pargs 上运行 ipairs，
-- 因为所有参数都已经被复制过来了。
--]]
metatable.__index = function (t, key)
--[[
-- 当 args 表被索引时获取参数。首先我们检查值是否已缓存，如果没有，
-- 则尝试从参数表中获取。检查缓存时，我们需要先检查 metaArgs，再检查 nilArgs，
-- 因为两者可能同时不为 nil。如果参数不在 metaArgs 中，我们还会检查
-- pairs 是否已经运行。如果 pairs 已经运行，我们返回 nil。
-- 这是因为所有参数都已经被 mergeArgs 函数复制到 metaArgs 中，
-- 意味着任何其他参数都必须是 nil。
--]]
local val = metaArgs[key]
if val ~= nil then
return val
elseif metatable.donePairs or nilArgs[key] then
return nil
end
for _, argTable in ipairs(argTables) do
local argTableVal = tidyVal(key, argTable[key])
if argTableVal ~= nil then
metaArgs[key] = argTableVal
return argTableVal
end
end
nilArgs[key] = 'h'
return nil
end
metatable.__newindex = function (t, key, val)
-- 当模块尝试向 args 表添加新值或尝试更改现有值时调用此函数。
if options.readOnly then
error(
'could not write to argument table key "'
.. tostring(key)
.. '"; the table is read-only',
2
)
elseif options.noOverwrite and args[key] ~= nil then
error(
'could not write to argument table key "'
.. tostring(key)
.. '"; overwriting existing arguments is not permitted',
2
)
elseif val == nil then
--[[
-- 如果参数将被覆盖为 nil，我们需要擦除 metaArgs 中的值，
-- 这样 __index、__pairs 和 __ipairs 就不会使用之前存在的值（如果存在）；
-- 我们还需要在 nilArgs 中记录 nil，这样如果再次访问该值，
-- 就不会在参数表中查找它。
--]]
metaArgs[key] = nil
nilArgs[key] = 'h'
else
metaArgs[key] = val
end
end
metatable.__pairs = function ()
--[[
-- 当在 args 表上运行 pairs 时调用。
--]]
if not metatable.donePairs then
mergeArgs(argTables)
metatable.donePairs = true
end
return next, metaArgs, nil
end
local function inext(t, i)
-- 这使用了我们的 __index 元方法
local v = t[i + 1]
if v ~= nil then
return i + 1, v
end
end
metatable.__ipairs = function (t)
--[[
-- 当在 args 表上运行 ipairs 时调用。
--]]
return inext, t, 0
end
return args
end
return arguments
