查看“︁Module:Arguments”︁的源代码

-- 本模块提供对从 #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