模块:Cargo

此模块的文档可以在模块:Cargo/doc创建

-- 可调用的功能：cacheQueryResults, getQueryResultsFromWikitext
-- cargo表用于存储该模块的函数和变量；extCargo为引入Cargo扩展的功能
-- checkType从libraryUtil模块中引入checkType函数来检查参数类型（libraryUtil好像没有用）
-- mArguments存储Arguments模块中getArgs函数获取的模板参数
-- cache用于缓存Cargo查询的结果
local cargo = {}
local extCargo = mw.ext.cargo
local checkType = require( 'libraryUtil' ).checkType
local mArguments
local cache = {}
-- 将表t中每个键值对格式化为k:v的格式并插入到stringTable中
-- 使用逗号将stringTable中所有字符串连接起来，只返回字符串
local function flattenTableToString( t )
	local stringTable = {}
	for k, v in pairs( t ) do
		table.insert( stringTable, string.format( '%s:%s', k, v ) )
	end
	return table.concat( stringTable, ',' )
end
-- 将Cargo查询的results表按format格式化为Wiki文本
-- 如果format为debug，则用<pre>标签把结果表字符串（dumpObject方法）包裹后返回
-- format不指定的情况下，创建一个带有wikitable类的表格，遍历results中的每一行结果创建表格行，返回键值对
local function formatQueryResultsToWikitext( results, format )
	if format == 'debug' then
		return '<pre>' .. mw.dumpObject( results ) .. '</pre>'
	else
		local table = mw.html.create( 'table' ):addClass( 'wikitable' )
		local headerRow = mw.html.create( 'tr' )
		table:node( headerRow )
		for i, result in pairs( results ) do
			local bodyRow = mw.html.create( 'tr' )
			for k, v in pairs( result ) do
				if i == 1 then
					headerRow:tag( 'th' ):wikitext( k )
				end
				bodyRow:tag( 'td' ):wikitext( v )
			end
			table:node( bodyRow )
		end
		return tostring( table )
	end
end
-- 缓存Cargo查询结果，检查并初始化缓存表中相应的索引（3层嵌套表）
local function cacheQueryResults( results, tables, fields, argsString )
	if not cache[ tables ] then
		cache[ tables ] = {}
	end
	if not cache[ tables ][ fields ] then
		cache[ tables ][ fields ] = {}
	end
	if not cache[ tables ][ fields ][ argsString ] then
		cache[ tables ][ fields ][ argsString ] = {}
	end
	cache[ tables ][ fields ][ argsString ] = results
end
-- 执行cargo_query并返回结果（部分参数见：https://www.mediawiki.org/wiki/Extension:Cargo/Other_features#Lua_support）
-- tables为查询的表格名，fields为查询的字段名，args为查询的其他参数，默认为空表
function cargo.getQueryResults( tables, fields, args, shouldCache )
	args = args or {}
	-- shouldCache表示是否缓存结果，默认为true
	if shouldCache ~= false then shouldCache = true end
	-- checkType的用法是检查@param1的函数中第@param2个参数传入的参数值@param3是否为期望的类型@param4
	-- 如果并非正确的类型，会抛出错误
	checkType( 'Module:Cargo/cargo.getQueryResults', 1, tables, 'string' )
	checkType( 'Module:Cargo/cargo.getQueryResults', 2, fields, 'string' )
	checkType( 'Module:Cargo/cargo.getQueryResults', 3, args, 'table' )
	local argsString = flattenTableToString( args )
	-- 若缓存中有查询结果，直接返回查询结果
	if shouldCache and cache[ tables ] and cache[ tables ][ fields ] and cache[ tables ][ fields ][ argsString ] then
		return cache[ tables ][ fields ][ argsString ]
	end
    -- 否则，使用pcall调用extCargo.query执行查询，如果查询失败，报错
    -- pcall的用法是检测@param1函数以及传递给它的参数是否成功执行，成功的话success为true，否则false
	local success, results = pcall( extCargo.query, tables, fields, args )
	if not success then
		error( 'Failed to query Cargo table' )
	end
	-- 缓存查询结果
	if shouldCache then
		cacheQueryResults( results, tables, fields, argsString )
	end
	return results
end
-- 实现Cargo query功能，引入Arguments模块获取模板参数getArgs
-- 从模板参数中提取tables和fields，构建查询参数表args，包含where、join等参数
-- 调用getQueryResults函数执行查询
function cargo.getQueryResultsFromWikitext( frame )
	mArguments = require( 'Module:Arguments' )
	local templateArgs = mArguments.getArgs( frame )
	local tables = templateArgs[ 'tables' ]
	local fields = templateArgs[ 'fields' ]
	if not tables or not fields then
		error( 'Missing tables or fields parameter' )
	end
	local args = {
		[ 'where' ] = templateArgs[ 'where' ],
		[ 'join' ]  = templateArgs[ 'join on' ],
		[ 'groupBy' ]  = templateArgs[ 'group by' ],
		[ 'having' ] = templateArgs[ 'having' ],
		[ 'orderBy' ] = templateArgs[ 'order by' ],
		[ 'limit' ] = templateArgs[ 'limit' ],
		[ 'offset' ] = templateArgs[ 'offset' ]
	}
	local results = cargo.getQueryResults( tables, fields, args )
	local format = templateArgs[ 'format' ]
	return formatQueryResultsToWikitext( results, format )
end
-- 不返回任何值，返回本模块，供其他模块或页面使用其中的函数
return cargo