Módulo:Template wrapper

Documentación del módulo

A continuación se muestra la documentación transcluida desde la subpágina /doc. [salta a la caja de código]

---

Este módulo se utilizará en plantillas de contenedor para permitir que proporcionen valores de parámetros predeterminados y permitir a los editores pasar parámetros adicionales a la plantilla de trabajo subyacente.

Al escribir una plantilla de contenedor, proporcione a este módulo todos los parámetros predeterminados normalmente necesarios para usar la plantilla contenedor en su forma base. Luego, los editores pueden usar la plantilla contenedor tal cual o pueden proporcionar parámetros adicionales de contenedor y canónicos. Cualquiera de los parámetros canónicos admitidos por la plantilla de trabajo puede agregarse a la plantilla del contenedor o ser suministrado por los editores en el espacio del artículo. Cuando un editor proporciona un parámetro que tiene un valor predeterminado en la plantilla contenedor, el valor proporcionado por el editor anula el valor predeterminado. Cuando es necesario eliminar un parámetro predeterminado, los editores pueden establecer el valor del parámetro en la palabra clave especial unset, lo que hará que este módulo contenedor elimine el valor predeterminado de la plantilla de contenedor para ese parámetro. Este módulo descarta los parámetros con nombre vacíos.

Los parámetros posicionales normalmente no se pasan a la plantilla de trabajo. La configuración de |_include-positional=yes pasará todos los parámetros posicionales a la plantilla de trabajo. Los parámetros posicionales no pueden excluirse, y pueden ser unset.

Los parámetros que solo utiliza el reiniciador deben ser posicionales (|n=) o enumerados en |_exclude= (una lista de parámetros con nombre separados por comas). Este módulo no pasará los parámetros _excluded a la plantilla de trabajo.

Uso

{{#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>|...}}

Parámetros de control

|_template= - (requerido) el nombre, sin espacio de nombres, de la plantilla de trabajo (la plantilla que está envuelta); véase §_template a continuación

|_exclude=: lista de nombres de parámetros separados por comas utilizados por la plantilla de contenedor que no se deben pasar a la plantilla de trabajo; véase §_exclude a continuación

|_reuse=: lista de nombres canónicos separados por comas que tienen significado tanto para la plantilla de contenedor como para la plantilla de trabajo; véase §_reuse a continuación

|_alias-map=: lista separada por comas de nombres de parámetros de plantilla de envoltura que deben tratarse como alias de parámetros canónicos de plantilla de trabajo especificados; véase §_alias-map a continuación

|_include-positional= - pasa todos los parámetros posicionales a la plantilla de trabajo; véase §_include-positional a continuación

Definiciones

parámetro canónico: un parámetro admitido y utilizado por la plantilla de trabajo

parámetro de contenedor: un parámetro utilizado por la plantilla de contenedor; puede proporcionar datos para parámetros canónicos o controlar otros aspectos de la plantilla de envoltura

parámetro alias: un parámetro de contenedor que es contextualmente significativo para la plantilla de contenedor pero debe renombrarse a un parámetro canónico para que la plantilla de trabajo lo use

parámetro reutilizado: un parámetro que comparten las plantillas de contenedor y de trabajo y que ha sido modificado por la plantilla de contenedor

parámetro predeterminado: un parámetro canónico dado un valor predeterminado en la plantilla de contenedor

parameter processing

wrapper template		Module:Template wrapper												working template
|canonical parameters=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	filter exclued parameters		working template
|wrapper parameters=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→
		|_exclude=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→		→
		|_include-positional=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→
		|_alias-map=	→	convert alias parameters to canonical parameters	→	|canonical parameters=	→	–––––––→	→	–––––––→	→				→
					→		→	modify reused canonical parameters
|alias parameters=	→	–––––––→	→						→	|reused parameters=	→	–––→	→
		|_reuse=	→	–––––––→	→	–––––––→	→
|canonical parameters=	→	–––––––→	→	–––––––→	→	–––––––→	→
		|default parameters=	→	–––––––→	→	–––––––→	→	–––––––→	→	–––––––→	→	–––→	→

Detalles del parámetro

template

El único parámetro requerido, |_template= proporciona el nombre, sin espacio de nombres, de la plantilla de trabajo (la plantilla que está envuelta). Si se omite este parámetro, el Módulo: contenedor de plantillas emitirá el mensaje de error:

alias-map

|alias-map= toma una lista separada por comas de parámetros de plantilla de envoltura que deben tratarse como alias de parámetros canónicos de plantilla de trabajo especificados. Cada elemento de mapeo de la lista tiene la forma:

<from>:<to> – where: <from> es un nombre de parámetro de wrapper y <to> es un nombre de parámetro canónico.

En este ejemplo, puede ser preferible que una plantilla de envoltura use |assessor= que puede ser desconocida para la plantilla de trabajo pero la plantilla de trabajo puede tener un |author= equivalente, por lo que en el {{#invoke:}} se escribirá:

|_alias-map=assessor:author

Los parámetros posicionales también pueden asignarse a parámetros canónicos:

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

Los parámetros de contenedor enumerados pueden asignarse a parámetros canónicos enumerados utilizando el especificador de enumerador #:

|_alias-map=assessor#:author#

Dado el ejemplo anterior, |assessor2= se asignará a |author2=; también, |assessor= y |assessor1= se asignarán a |author1=

Múltiples parámetros de contenedor pueden aplicarse sobre un solo parámetro canónico:

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

Los parámetros del contenedor enumerados en |alias-map= no se pasan a la plantilla de trabajo. Aplicar parámetros posicionales cuando |_include-positional=yes puede dar resultados no deseados. |_alias-map=1:author y |_include-positional=yes harán que todos los demás parámetros posicionales se pasen a la plantilla de trabajo tal como están: la plantilla de contenedor {{{2}}} se convierte en la plantilla de trabajo {{{2}}}, etc. la plantilla de trabajo no obtendrá {{{1}}}, aunque obtendrá |author=.

reuse

|_reuse= toma una lista separada por comas de parámetros canónicos que tienen significado tanto para la plantilla de contenedor como para la plantilla de trabajo

En los casos más simples, un parámetro canónico pasado a la plantilla de contenedor anula un parámetro predeterminado proporcionado en la plantilla de contenedor. A veces, un parámetro de contenedor es igual a un parámetro canónico y la plantilla de contenedor necesita modificar el valor del parámetro antes de pasar a la plantilla de trabajo. En este ejemplo, |title= es un parámetro contenedor y un parámetro canónico que la plantilla contenedor necesita modificar antes de pasar a la plantilla de trabajo. Para hacer esto primero escribimos:

|_reuse=title

luego, en la plantilla {{#invoke:Template wapper|wrap|_template=...|...}} de la envoltura, escribimos:

|title=Modified {{{title}}}

Los parámetros _reused no pueden ser anulados.

excluir

|_exclude= toma una lista de parámetros separados por comas utilizados por la plantilla de contenedor que no se deben pasar a la plantilla de trabajo. Esta lista se aplica a todos los parámetros de contenedor y canónicos (incluidos los parámetros canónicos que se renombran como parámetros de alias) recibidos de la plantilla de contenedor.

Como ejemplo, una plantilla de contenedor podría usar |id= para proporcionar una parte del valor asignado al parámetro predeterminado |url=, por lo que escribiríamos:

|_exclude=id

luego, en la plantilla {{#invoke:Template wapper|wrap|_template=...|...}} de la envoltura, escribimos:

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

El valor |url= modificado se pasa a la plantilla de trabajo pero |id= y su valor no.

Los parámetros _reused y predeterminados no se pueden excluir.

incluye

|_include-positional= es un parámetro booleano que solo toma un valor: yes; el valor predeterminado (vacío, faltante) es no (parámetros posicionales normalmente excluidos). Cuando se establece en yes, Módulo: el contenedor de plantillas pasará todos los parámetros posicionales a la plantilla de trabajo.

Véase también §_alias-map.

anulación de parámetros predeterminados

Los editores pueden anular los parámetros predeterminados simplemente configurando el parámetro predeterminado al valor deseado en la plantilla de envoltura. Este módulo ignora los parámetros vacíos (aquellos parámetros que se nombran pero que no tienen un valor asignado). Cuando sea conveniente anular un parámetro predeterminado a ningún valor, use la palabra clave especial unset. Los parámetros predeterminados con este valor se pasan a la plantilla de trabajo como parámetros vacíos (sin valor asignado).

Los parámetros _reused no pueden ser unset o anulados.

---

Esta documentación está transcluida desde Módulo:Template wrapper/doc.
Por favor, añade las categorías en la subpágina de documentación y los interwikis en Wikidata. Subpáginas de este módulo.

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)
	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

	return frame:preprocess (table.concat ({'<code style="color:inherit; background:inherit; border:none;"><nowiki>{{', template, ' |', table.concat( args, ' |' ), '}}</nowiki></code>'}));	-- render the template
end


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

return {
	list = list,
	wrap = wrap,
	};