跳转到内容

模組:Template wrapper

本页使用了标题或全文手工转换
被永久保护的模块
维基百科，自由的百科全书
文档图示 模块文档[查看] [编辑] [历史] [清除缓存]

本模块用于将模板封装（英语：Wikipedia:Wrapper templates），以提供默认参数值，并允许编者向底层工作模板传递额外参数。

在编写封装模板时，应为此模块提供使用封装模板所需的所有默认参数。然后，编者可以直接使用封装模板，也可以提供其他封装和规范参数。工作模板支持的所有规范参数都可以添加到封装模板中，或由编者中条目中提供。当编者提供的参数在封装模板中有默认值时，编者提供的值会覆盖默认值。如果需要移除默认参数，编者可以将该参数值设置为关键字unset。参数留空时本模块会将其丢弃。

匿名参数通常不会传递给工作模板。设置|_include-positional=yes时将所有匿名参数传递给工作模板。匿名参数不能被排除；匿名参数也可以设为unset。

仅由封装模板使用的参数，要么是匿名参数（{{{n}}}），要么在|_exclude=中列出。本模块不会将_excluded参数传递给工作模板。

用法

{{#invoke:Template wrapper|wrap|_template=working template|_exclude=named parameter, named parameter, ...|_reuse=named parameter, named parameter, ...|_alias-map=alias parameter:canonical parameter|_include-positional=yes|<default parameter>|<default parameter>|...}}

控制参数（详见下方说明）
|_template= – （必须）工作模板（即被封装的模板）的名称（不带“Template:”命名空间前缀）
|_exclude= – 仅在封装模板中使用、不传递给工作模板的参数列表，以逗号分隔
|_reuse= – 复用参数列表，以逗号分隔，这些参数由封装模板和工作模板共用
|_alias-map= – 封装参数至规范参数的映射列表，使用逗号分隔，作用是指定规范参数的别名
|_include-positional= – 填写yes时将所有匿名参数传递给工作模板
定义
规范参数（canonical parameter）：工作模板支持和使用的参数
封装参数（wrapper parameter）：封装模板使用的参数；可为规范参数提供数据，或用于控制封装模板
别名参数（alias parameter）：对封装模板具有上下文意义的封装参数，但必须重命名为规范参数以供工作模板使用
复用参数（reused parameter）：由封装模板和工作模板共用的参数，传入工作模板时已被封装模板修改
默认参数（default parameter）在封装模板中给出默认值的规范参数
参数处理
封装模板
（wrapper
template）		 Module:Template wrapper 工作模板
（working
template）
|规范参数=  →  –––––––→  →  –––––––→  →  –––––––→  →  –––––––→  →  –––––––→  →  过滤
排除参数		 working
template
|封装参数=  →  –––––––→  →  –––––––→  →  –––––––→  →  –––––––→  →  –––––––→  → 
  |_exclude=  →  –––––––→  →  –––––––→  →  –––––––→  →  –––––––→  →   → 
  |_include-positional=  →  –––––––→  →  –––––––→  →  –––––––→  →  –––––––→  → 
  |_alias-map=  →  转换别名参数
为规范参数		  →  |规范参数=  →  –––––––→  →  –––––––→  →   → 
   →   →  修改复用的
规范参数
|别名参数=  →  –––––––→  →   →  |复用参数=  →  –––→  → 
  |_reuse=  →  –––––––→  →  –––––––→  → 
|规范参数=  →  –––––––→  →  –––––––→  →  –––––––→  → 
  |默认参数=  →  –––––––→  →  –––––––→  →  –––––––→  →  –––––––→  →  –––→  → 

参数

_template

唯一必需的参数，|_template=提供工作模板（被封装的模板）的名称（不带“Template:”命名空间前缀）。

_alias-map

|_alias-map=封装参数至规范参数的映射列表，使用逗号分隔，作用是指定工作模板规范参数在封装模板中的别名。每项映射格式如下：

<from>:<to> – 其中<from>是封装模板的参数名，<to>是规范参数名

例如封装模板中要使用|assessor=参数，在工作模板中没有|assessor=参数，但有等效的|author=参数，这时可写为：

|_alias-map=assessor:author

匿名参数也可以映射为规范参数：

|_alias-map=1:author, 2:title, 3:language

可以使用#枚举符将封装参数枚举映射至规范参数：

|_alias-map=assessor#:author#

多个封装参数可以映射到一个规范参数：

|_alias-map=1:author, assessor:author

|alias-map=中列出的封装参数不会传递给工作模板。设置|_include-positional=yes时映射匿名参数可能导致不良后果。同时设置|_alias-map=1:author和|_include-positional=yes时，封装模板中的{{{1}}}传入工作模板的|author=，其他匿名参数也会传入工作模板，即封装模板的{{{2}}}传递为工作模板的{{{2}}}等等。

_reuse

|_reuse=规范参数列表，使用逗号分隔，这些参数对封装模板和工作模板都有意义。

在最简单的情况下，传入封装模板的规范参数会覆盖封装模板中提供的默认参数。有时，一个封装参数与规范参数的名称相同，并且需要在封装模板中对参数值修改后再传入给工作模板。例如，|title=既是封装参数，也是规范参数，封装模板需要将其修改后再传入工作模板。为此，我们首先编写：

|_reuse=title

之后，在封装模板的{{#invoke:Template wrapper|wrap|_template=...|...}}中编写：

|title=Modified {{{title}}}

复用参数不能被覆盖。

_exclude

|_exclude=仅在封装模板中使用、不传递给工作模板的参数列表，以逗号分隔。此列表适用于从封装模板接收的所有封装参数和规范参数（包括已重命名为别名参数的规范参数）。

例如，封住模板使用|id=参数的值作为默认参数|url=的部分内容，可以这样写：

|_exclude=id

之后，在封装模板的{{#invoke:Template wrapper|wrap|_template=...|...}}中编写：

|url=https://example.com/{{{id}}}

这样，被修改后的|url=参数值被传递给工作模板，但|id=参数不传递。

复用参数和默认参数不应被排除。

_include-positional

|_include-positional=填写yes时将所有匿名参数传递给工作模板，默认状态（留空/取消该参数）为排除匿名参数。

覆盖默认参数

编者只需在封装模板中将默认参数设置为所需值，即可覆盖默认参数。参数值留空时将被忽略，若要将默认参数设为空值，请填写关键字unset，以将该默认参数将作为空（无赋值）参数传递给工作模板。

复用参数不能设为unset或被覆盖。

调试/文档模式

This module has two entry points. A wrapper template might use a module {{#invoke:}} written like this:

{{#invoke:Template wrapper|{{#if:{{{_debug|}}}|list|wrap}}|_template=<working template>|_exclude=_debug, ...|...}}

where the |_debug= wrapper parameter, set to any value, will cause the module to render the call to the working template without actually calling the working template.

As an example, {{cite wikisource}} is a wrapper template that uses {{citation}} as its working template. {{cite wikisource}} accepts positional parameters but {{citation}} does not so the wrapper template must convert the positional parameters to named parameters which it does using the |_alias-map= parameter: 

{{#invoke:template wrapper|{{#if:{{{_debug|}}}|list|wrap}}|_template=citation
  |_exclude=..., _debug <!-- unnecessary detail omitted -->
  |_alias-map=1:title, 2:author, 3:language

This example uses positional parameters and sets |_debug=yes to show that the {{citation}} template is correctly formed:

{{cite wikisource|Sentido y sensibilidad|Jane Austen|es|_debug=yes}}
Jane Austen. 链接至维基文库 Sentido y sensibilidad. 维基文库 （西班牙文）. 

and, with |_debug= unset:

{{cite wikisource|Sentido y sensibilidad|Jane Austen|es|_debug=}}
Jane Austen. 链接至维基文库 Sentido y sensibilidad. 维基文库 （西班牙文）. 

The |_debug= name is chosen here for convenience but may be anything so long as it matches the {{#if:}} in the {{#invoke:}}.

You may also call the link function to get something like the left-hand side of Template:yy. This is essentially the list function with the template name turned into a link. Template:Yytop Template:Yy Template:Yybottom 

require('strict');

local error_msg = '<span style=\"font-size:100%\" class=\"error\"><code style=\"color:inherit; border:inherit; padding:inherit;\">&#124;_template=</code> missing or empty</span>';


--[[--------------------------< I S _ I N _ T A B L E >--------------------------------------------------------

scan through tbl looking for value; return true if found, false else

]]

local function is_in_table (tbl, value)
    for k, v in pairs (tbl) do
        if v == value then return true end
    end
    return false;
end


--[[--------------------------< A D D _ P A R A M E T E R >----------------------------------------------------

adds parameter name and its value to args table according to the state of boolean list argument; kv pair for
template execution; k=v string for template listing.

]]

local function add_parameter (k, v, args, list)
	if list then
		table.insert( args, table.concat ({k, '=', v}));						-- write parameter names and values to args table as string
	else
		args[k] = v;															-- copy parameters to args table
	end
end


--[[--------------------------< A L I A S _ M A P _ G E T >----------------------------------------------------

returns a table of local template (parent frame) parameter names and the target template names that match where
in [key]=<value> pairs where:
	[key] is local template parameter name (an alias)
	<value> is target template parameter name (the canonical parameter name used in the working template)

The parameter |_alias-map= has the form:
	|_alias-map=<list>
where <list> is a comma-separated list of alias / canonical parameter name pairs in the form
	<from> : <to>
where:
	<from> is the local template's parameter name (alias)
	<to> is the target template's parameter name (canonical)
	for enumerated parameters place an octothorp (#) where the enumerator digits are placed in the parameter names:
		<from#> : <to#>

]]

local function alias_map_get (_alias_map)
	local T = mw.text.split (_alias_map, '%s*,%s*');							-- convert the comma-separated list into a table of alias pairs
	local mapped_aliases = {};													-- mapped aliases will go here
	local l_name, t_name;														-- parameter names
	
	for _, alias_pair in ipairs (T) do											-- loop through the table of alias pairs
		l_name, t_name = alias_pair:match ('(.-)%s*:%s*(.+)');					-- from each pair, get local and target parameter names
		if l_name and t_name then												-- if both are set
			if tonumber (l_name) then
				l_name = tonumber (l_name);										-- convert number-as-text to a number
			end
			mapped_aliases[l_name] = t_name;									-- add them to the map table
		end
	end

	return mapped_aliases;
end


--[[--------------------------< F R A M E _ A R G S _ G E T >--------------------------------------------------

Fetch the wrapper template's 'default' and control parameters; adds default parameters to args

returns content of |_template= parameter (name of the working template); nil else

]]

local function frame_args_get (frame_args, args, list)
	local template;

	for k, v in pairs (frame_args) do											-- here we get the wrapper template's 'default' parameters
		if 'string' == type (k) and (v and ('' ~= v)) then						-- do not pass along positional or empty parameters
			if '_template' == k then
				template = v;													-- save the name of template that we are wrapping
			elseif '_exclude' ~= k and '_reuse' ~= k and '_include-positional' ~= k  and '_alias-map' ~= k then	-- these already handled so ignore here; 
				add_parameter (k, v, args, list);								-- add all other parameters to args in the style dictated by list
			end
		end
	end

	return template;															-- return contents of |_template= parameter
end


--[=[--------------------------< P F R A M E _ A R G S _ G E T >------------------------------------------------

Fetches the wrapper template's 'live' parameters; adds live parameters that aren't members of the exclude table to
args table; positional parameters may not be excluded

no return value

]=]

local function pframe_args_get (pframe_args, args, exclude, _include_positional, list)
	for k, v in pairs (pframe_args) do
		if 'string' == type (k) and not is_in_table (exclude, k) then			-- do not pass along excluded parameters
			if v and ('' ~= v) then												-- pass along only those parameters that have assigned values
				if 'unset' == v:lower() then									-- special keyword to unset 'default' parameters set in the wrapper template
					v = '';														-- unset the value in the args table
				end
				add_parameter (k, v, args, list)								-- add all other parameters to args in the style dictated by list; alias map only supported for local-template parameters
			end
		end
	end

	if _include_positional then
		for i, v in ipairs (pframe_args) do										-- pass along positional parameters
			if 'unset' == v:lower() then										-- special keyword to unset 'default' parameters set in the wrapper template
				v = '';															-- unset the value in the args table
			end
			add_parameter (i, v, args, list);
		end
	end
end


--[[--------------------------< _ M A I N >--------------------------------------------------------------------

Collect the various default and live parameters into args styled according to boolean list.

returns name of the working or listed template or nil for an error message

]]

local function _main (frame, args, list)
	local template;
	local exclude = {};															-- table of parameter names for parameters that are not passed to the working template
	local reuse_list = {};														-- table of pframe parameter names whose values are modified before they are passed to the working template as the same name
	local alias_map = {};														-- table that maps parameter aliases to working template canonical parameter names
	local _include_positional;
	
	if frame.args._exclude and ('' ~= frame.args._exclude) then					-- if there is |_exclude= and it's not empty
		exclude = mw.text.split (frame.args._exclude, "%s*,%s*");				-- make a table from its contents
	end
																				-- TODO: |_reuse= needs a better name (|_reuse=)
	if frame.args._reuse and ('' ~= frame.args._reuse) then					-- if there is |_reuse= and it's not empty
		reuse_list = mw.text.split (frame.args._reuse, "%s*,%s*");				-- make a table from its contents
	end

	if frame.args['_alias-map'] and ('' ~= frame.args['_alias-map']) then		-- if there is |_alias-map= and it's not empty
		alias_map = alias_map_get (frame.args['_alias-map']);					-- make a table from its contents
	end

	template = frame_args_get (frame.args, args, list);							-- get parameters provided in the {{#invoke:template wrapper|...|...}}
	if nil == template or '' == template then									-- this is the one parameter that is required by this module
		return nil;																-- not present, tell calling function to emit an error message
	end
	
	_include_positional = 'yes' == frame.args['_include-positional'];			-- when true pass all positional parameters along with non-excluded named parameters to ...
																				-- ... the working template; positional parameters are not excludable
																				
	local _pframe_args = frame:getParent().args;								-- here we get the wrapper template's 'live' parameters from pframe.args
	local pframe_args = {};														-- a local table that we can modify

	for k, v in pairs (_pframe_args) do											-- make a copy that we can modify
		pframe_args[k] = v;
	end
	
-- here we look for pframe parameters that are aliases of canonical parameter names; when found
-- we replace the alias with the canonical.  We do this here because the reuse_list works on
-- canonical parameter names so first we convert alias parameter names to canonical names and then
-- we remove those canonical names from the pframe table that are reused (provided to the working
-- template through the frame args table)

	for k, v in pairs (alias_map) do											-- k is alias name, v is canonical name
		if pframe_args[k] then													-- if pframe_args has parameter with alias name
			pframe_args[v] = _pframe_args[k];									-- create new canonical name with alias' value
			pframe_args[k] = nil;												-- unset the alias
		end
	end

	for k, v in pairs (pframe_args) do											-- do enumerated parameter alias -> canonical translation
		if 'string' == type (k) then											-- only named parameters can be enumerated
			if alias_map[k..'#'] then											-- non-enumerated alias matches enumerated parameter pattern? enumerator at end only
				pframe_args[alias_map[k..'#']:gsub('#', '')] = v;				-- remove '#' and copy parameter to pframe_args table
				pframe_args[k] = nil;											-- unset the alias
			elseif k:match ('%d+') then											-- if this parameter name contains digits
				local temp = k:gsub ('%d+', '#');								-- make a copy; digits replaced with single '#'
				local enum = k:match ('%d+');									-- get the enumerator
				
				if alias_map[temp] then											-- if this parameter is a recognized enumerated alias
					pframe_args[alias_map[temp]:gsub('#', enum)] = v;			-- use canonical name and replace '#' with enumerator and add to pframe_args
					pframe_args[k] = nil;										-- unset the alias
				end
			end
		end
	end

-- pframe parameters that are _reused are 'reused' have the form something like this:
--	|chapter=[[wikisource:{{{chapter}}}|{{{chapter}}}]]
-- where a parameter in the wrapping template is modified and then passed to the working template
-- using the same parameter name (in this example |chapter=)

																				-- remove parameters that will be reused
	for k, v in ipairs (reuse_list) do											-- k is numerical index, v is canonical parameter name to ignore
		if pframe_args[v] then													-- if pframe_args has parameter that should be ignored
			pframe_args[v] = nil;												-- unset the ignored parameter
		end
	end

	pframe_args_get (pframe_args, args, exclude, _include_positional, list);	-- add parameters and values to args that are not listed in the exclude table

	return template;															-- args now has all default and live parameters, return working template name
end


--[[--------------------------< W R A P >----------------------------------------------------------------------

Template entry point.  Call this function to 'execute' the working template

]]

local function wrap (frame)
	local args = {};															-- table of default and live parameters and their values to be passed to the wrapped template
	local template;																-- the name of the working template

	template = _main (frame, args, false);										-- get default and live parameters and the name of the working template
	if not template then														-- template name is required
		return error_msg;														-- emit error message and abandon if template name not present
	end

	return frame:expandTemplate {title=template, args=args};					-- render the working template
end


--[[--------------------------< L I S T >----------------------------------------------------------------------

Template entry point.  Call this function to 'display' the source for the working template.  This function added
as a result of a TfD here: Wikipedia:Templates_for_discussion/Log/2018_April_28#Module:PassArguments

This function replaces a similarly named function which was used in {{cite compare}} and {{cite compare2}}

Values in the args table are numerically indexed strings in the form 'name=value'

]]

local function list(frame, do_link)
	local args = {};						-- table of default and live parameters and their values to be passed to the listed template
	local template;							-- the name of the listed template

	template = _main (frame, args, true);	-- get default and live parameters and the name of the listed template
	if not template then					-- template name is required
		return error_msg;					-- emit error message and abandon if template name not present
	end
	if do_link then
		template = ('[[%s|%s]]'):format(frame:expandTemplate{ title='Transclude', args = {template} }, template)
	end
	table.sort(args)
	for i = 1, #args do
		local stripped = args[i]:match('^' .. i .. '=([^=]*)$')
		if stripped then args[i] = stripped else break end
	end
	return frame:preprocess(table.concat({
		'<code style="color:inherit; background:inherit; border:none;">&#123;&#123;',
		template,
		('<wbr><nowiki>|%s</nowiki>'):rep(#args):format(unpack(args)), '&#125;&#125;</code>'}));	-- render the template
end

local function link (frame)
	return list(frame, true)
end

--[[--------------------------< E X P O R T E D   F U N C T I O N S >------------------------------------------
]]

return {
	link = link,
	list = list,
	wrap = wrap,
	};
检索自“https://zh.wikipedia.org/w/index.php?title=Module:Template_wrapper&oldid=82697461”