此模块的文档可以在模块: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