Permanently protected module

Módulo:Template wrapper

Origem: Wikipédia, a enciclopédia livre.
Saltar para a navegação Saltar para a pesquisa
Documentação do módulo[ver] [editar] [histórico] [purgar]

Esse módulo deve ser usado em modelos de wrapper ou envelope para permitir que esses modelos forneçam valores de parâmetro padrão e permitam que os editores passem parâmetros adicionais para o modelo de trabalho subjacente.

Ao gravar uma predefinição de wrapper, forneça a esse módulo todos os parâmetros padrão normalmente necessários para usar o modelo de wrapper em seu formato base. Em seguida, os editores usam o modelo de wrapper como está ou podem fornecer parâmetros adicionais de wrapper e canônicos. Qualquer um dos parâmetros canônicos suportados pelo modelo de trabalho pode ser adicionado ao modelo de wrapper ou fornecido pelos editores no espaço do artigo. Quando um editor fornece um parâmetro que possui um valor padrão no modelo de wrapper, o valor fornecido pelo editor substitui o padrão. Quando for necessário remover um parâmetro padrão, os editores podem definir o valor do parâmetro para a palavra-chave especial unset, o que fará com que este módulo de wrapper apague o valor padrão do modelo do wrapper para esse parâmetro. Este módulo descarta os parâmetros nomeados vazios.

Parâmetros posicionais não são normalmente passados ​​para o modelo de trabalho. Definir |_include-posicional=sim passará todos os parâmetros posicionais para o modelo de trabalho. Parâmetros posicionais não podem ser excluídos; Parâmetros posicionais podem ser unset.

Parâmetros que são usados ​​somente pelo wrapper devem ser posicionais (|n=) ou listados em |_exclude= (uma lista separada por vírgulas de parâmetros nomeados). Este módulo não passará parâmetros _excluded para o modelo de trabalho.

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 controle
|_template= - (obrigatório) o nome, sem namespace, do modelo de trabalho (o modelo que é empacotado); veja § _template abaixo
|_exclude= - lista separada por vírgulas de nomes de parâmetros usados pelo modelo de wrapper que não devem ser passados para o template de trabalho; veja § _exclude abaixo
|_reuse= - lista separada por vírgulas de nomes canônicos que têm significado para o modelo de wrapper e para o modelo de trabalho; veja § _reuse abaixo
|_alias-map= - lista separada por vírgula de nomes de parâmetros de wrapper-modelo que devem ser tratados como aliases de parâmetros canônicos de modelos de trabalho especificados; veja § _alias-map abaixo
|_include-posicional= - passa todos os parâmetros posicionais ao modelo de trabalho; veja § _include-posicional abaixo

Definições

parâmetro canonical - um parâmetro suportado e usado pelo modelo de trabalho
parâmetro wrapper - um parâmetro usado pelo modelo wrapper; pode fornecer dados para parâmetros canônicos ou controlar outros aspectos do modelo de wrapper
parâmetro alias - um parâmetro de wrapper que é contextualmente significativo para o modelo de wrapper, mas deve ser renomeado para um parâmetro canônico para uso pelo modelo de trabalho
parâmetro reused - um parâmetro que é compartilhado pelos modelos wrapper e que funciona e foi modificado pelo template wrapper
parâmetro padrão - um parâmetro canônico dado um valor padrão no modelo de wrapper
processamento de parâmetros
wrapper
template
Module:Template wrapper working
predefinição
|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=  →  –––––––→  →  –––––––→  →  –––––––→  →  –––––––→  →  –––→  → 

Detalhes do parâmetro

_ template

O único parâmetro necessário, |_template= fornece o nome, sem namespace, do modelo de trabalho (o modelo que é empacotado). Se este parâmetro for omitido, o módulo: invólucro de modelo emitirá a mensagem de erro:

|_template= em falta ou vazio

_ alias-map

|alias-map= usa uma lista separada por vírgula dos parâmetros do modelo de wrapper que devem ser tratados como aliases dos parâmetros canônicos do modelo de trabalho especificado. Cada elemento de mapeamento da lista tem o formulário:

& lt; from>: & lt; to> - onde: & lt; de> é um nome de parâmetro do wrapper e & lt; to> é um nome de parâmetro canônico

Neste exemplo, pode ser preferível que um modelo de wrapper use |assessor=, que pode ser desconhecido para o modelo de trabalho, mas o modelo de trabalho pode ter um equivalente |autor= no {{#invoke:}} nós escreveríamos:

|_alias-map=assessor:autor

Parâmetros posicionais também podem ser mapeados para parâmetros canônicos:

|_alias-map=1:autor, 2:titulo, 3:lingua

Os parâmetros do wrapper enumerados podem ser mapeados para parâmetros canônicos enumerados usando o especificador # enumerator:

|_alias-map=assessor#:autor#

Dado o exemplo acima, |assessor2= será mapeado para |autor2=; Além disso, |assessor= e |assessor1= serão mapeados para |autor1=

Vários parâmetros de wrapper podem mapear para um único parâmetro canônico:

|_alias-map=1: autor, avaliador: autor

Os parâmetros do wrapper listados em |alias-map= não são passados ​​para o modelo de trabalho. Mapeamento de parâmetros posicionais quando |_include-posicional=sim pode dar resultados indesejáveis. |_alias-map=1:autor e |_include-posicional=yes fará com que todos os outros parâmetros posicionais sejam passados ​​para o modelo de trabalho como é: wrapper template {{{2}}} torna-se o template de trabalho {{{2}}}, etc; O template de trabalho não vai ter {{{1}}}, mas ele terá |author=.

_ reuse

|_reuse= usa uma lista separada por vírgula de parâmetros canônicos que têm significado para o modelo de wrapper e para o modelo de trabalho

Nos casos mais simples, um parâmetro canônico enviado para o modelo de wrapper substitui um parâmetro padrão fornecido no modelo de wrapper. Às vezes, um parâmetro de wrapper é o mesmo que um parâmetro canônico e o modelo de wrapper precisa modificar o valor do parâmetro antes de ser passado para o modelo de trabalho. Neste exemplo, |title= é um parâmetro de wrapper e um parâmetro canônico que o modelo de wrapper precisa modificar antes de passar para o modelo de trabalho. Para fazer isso, primeiro escrevemos:

|_reuse=title

então, no {{# invoke: Template wapper|wrap|_template = ...|...}} do template do wrapper escrevemos:

|title=Modificado {{{title}}}

Parâmetros _reused não podem ser substituídos.

_ exclude

|_exclude= usa uma lista separada por vírgula de parâmetros usados ​​pelo modelo de wrapper que não devem ser passados ​​para o modelo de trabalho. Essa lista se aplica a todos os parâmetros de wrapper e canônicos (incluindo os parâmetros canônicos que são renomeados para os parâmetros de alias) recebidos do modelo de wrapper.

Como exemplo, um modelo de wrapper pode usar |id= para fornecer uma parte do valor atribuído ao parâmetro padrão |url=, portanto, poderíamos escrever:

|_exclude=id

então, no {{# invoke:Template wapper|wrap|_template = ...|...}} do template do wrapper escrevemos:

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

O valor |url= modificado é passado para o template de trabalho, mas |id= e seu valor não é.

Os parâmetros _reused e default não podem ser excluídos

_ include-posicional

|_include-posicional= é um parâmetro booleano que usa apenas um valor: yes; o padrão (vazio, ausente) é no (parâmetros posicionais normalmente excluídos). Quando definido como yes, o wrapper Module: Template passará todos os parâmetros posicionais para o modelo de trabalho.

Veja também § _alias-map.

Substituindo parâmetros padrão

Os editores podem substituir os parâmetros padrão simplesmente definindo o parâmetro padrão para o valor desejado no modelo de wrapper. Este módulo ignora os parâmetros vazios (aqueles parâmetros que são nomeados, mas que não possuem um valor atribuído). Quando for desejável sobrescrever um parâmetro padrão para nenhum valor, use a palavra-chave especial unset. Os parâmetros padrão com este valor são passados para o modelo de trabalho como parâmetros vazios (sem valor atribuído).

Parâmetros _reused não podem ser unset ou sobrescritos.

Ajuda de depuração

Este módulo tem dois pontos de entrada. Um modelo de wrapper pode usar um módulo {{#invoke:}} escrito assim:

{{#invoke:Template wrapper|{{#if:{{{_debug|}}}|lista|embrulhar}}|_template =<modelo de trabalho>|_exclude = _debug, ...|...}}

onde o parâmetro de wrapper |_debug=, definido como qualquer valor, fará com que o módulo renderize a chamada para o modelo de trabalho sem realmente chamar o modelo de trabalho.

Como exemplo, {{citar wikisource}} é um modelo de wrapper que usa {{citation}} como modelo de trabalho. O {{citar wikisource}} aceita parâmetros posicionais, mas {{citation}} não faz com que o modelo do wrapper converta os parâmetros posicionais em parâmetros nomeados, usando o parâmetro |_alias-map=:

<syntaxhighlight lang = "moin"> {{#invoke:Template wapper|{{# if: {|list|wrap}}|_template = citation
|_exclude = ..., _debug <! - detalhes desnecessários omitidos ->
|_alias-map = 1: title, 2: author, 3: language </ syntaxhighlight>

Este exemplo usa parâmetros posicionais e define |_debug=yes para mostrar que o modelo {{citation}} está formado corretamente:

{{citar wikisource|Sentido e sensibilidade|Jane Austen|es|_debug = sim}}
Wikisource-logo.svg es no Wikisource em (erro: código de língua 'Sentido e sensibilidade' não reconhecido!).

e, com |_debug= não definido:

{{citar wikisource|Sentido e sensibilidade|Jane Austen|es|_debug =}}
Wikisource-logo.svg es no Wikisource em (erro: código de língua 'Sentido e sensibilidade' não reconhecido!).

O nome |_debug= é escolhido aqui por conveniência, mas pode ser qualquer coisa desde que corresponda ao {{#if:}} no {{#invoke:}}.

require('Module:No globals');

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,
    };