Módulo:Arguments/doc
<section begin=header />
<section end=header />
Este módulo facilita o processamento dos argumentos passados por um comando #invoke. Ele é um meta-módulo, destinado ao uso por outros módulos, e não deve ser chamado diretamente a partir de #invoke. Suas funcionalidades incluem:
- Fácil remoção dos argumentos em branco e dos espaços em branco em torno dos argumentos.
- Os argumentos podem ser passados tanto pelo frame atual quanto pelo frame parental ao mesmo tempo. (Mais detalhes abaixo.)
- Os argumentos podem ser passados diretamente a partir de outro módulo Lua ou a partir do console de depuração.
- A maioria das funcionalidades pode ser personalizada.
Uso básico
Primeiro, você precisa carregar o módulo. Ele contém uma função, chamada getArgs.
<syntaxhighlight lang="lua"> local getArgs = require('Module:Arguments').getArgs </syntaxhighlight>
No cenário mais básico, você pode utilizar s getArgs dentro de sua função principal, main. A variável args é uma tabela contendo os argumentos a partir de #invoke. (Ver abaixo para detalhes.)
<syntaxhighlight lang="lua"> local getArgs = require('Module:Arguments').getArgs local p = {}
function p.main(frame) local args = getArgs(frame) -- O código principal do módulo vai aqui. end
return p </syntaxhighlight>
Prática recomendada
No entanto, a prática recomendada é usar uma função separada como ponto de entrada a partir de #invoke apenas para processar os argumentos. Isso permite que outros módulos Lua chamem sua lógica principal diretamente, melhorando o desempenho ao evitar a sobrecarga de interação com o objeto frame.
<syntaxhighlight lang="lua"> local getArgs = require('Module:Arguments').getArgs local p = {}
function p.main(frame) local args = getArgs(frame) return p._main(args) end
function p._main(args) -- O código principal do módulo vai aqui. end
return p </syntaxhighlight>
A forma como isso é chamado a partir de uma predefinição é {{#invoke:Example|main}} (opcionalmente com alguns parâmetros como {{#invoke:Example|main|arg1=value1|arg2=value2}}), e a forma como isso é chamado a partir de um módulo é <syntaxhighlight lang=lua inline>require('Module:Example')._main({arg1 = 'value1', arg2 = value2, 'spaced arg3' = 'value3'})</syntaxhighlight>. O que este segundo faz é construir uma tabela com os argumentos nela, e então passa essa tabela para a função p._main(args), que a utiliza nativamente.
Múltiplas funções
Se você quer que várias funções utilizem os argumentos, e você também quer que eles sejam acessíveis a partir de #invoke, você pode utilizar uma função wrapper.
<syntaxhighlight lang="lua"> local getArgs = require('Module:Arguments').getArgs
local function makeInvokeFunc(funcName) return function (frame) local args = getArgs(frame) return p[funcName](args) end end
local p = {}
p.func1 = makeInvokeFunc('_func1')
function p._func1(args) -- O código para a primeira função vai aqui. end
p.func2 = makeInvokeFunc('_func2')
function p._func2(args) -- O código para a segunda função vai aqui. end
return p </syntaxhighlight>
Opções
Estão disponíveis as seguintes opções. Elas são explicadas nas seções abaixo.
<syntaxhighlight lang="lua"> local args = getArgs(frame, { trim = false, removeBlanks = false, valueFunc = function (key, value) -- Código para processar um argumento end,
frameOnly = true, parentOnly = true, parentFirst = true,
wrappers = { 'Predefinição:Uma predefinição wrapper', 'Predefinição:Outra predefinição wrapper' },
readOnly = true, noOverwrite = true }) </syntaxhighlight>
Remoção de espaços em branco
O MediaWiki corta os espaços em branco dos argumentos nomeados provenientes a partir de #invoke ou uma chamada de predefinição, mas preserva os espaços em branco dos argumentos posicionais. Por padrão, este módulo ajuda a cortar os espaços em branco dos argumentos posicionais também. Para preservar os espaços em branco nos argumentos posicionais, defina a opção trim como false.
<syntaxhighlight lang="lua"> local args = getArgs(frame, { trim = false, }) </syntaxhighlight>
Remoção de argumentos em branco
"Argumentos em branco" são os argumentos a partir de #invoke ou predefinição que são sequências (strings) em branco ou consistem apenas de espaços em branco. Por padrão, este módulo remove todos os argumentos em branco. Para preservar os argumentos em branco, defina a opção removeBlanks como false.
<syntaxhighlight lang="lua"> local args = getArgs(frame, { removeBlanks = false }) </syntaxhighlight>
Isso pode ser necessário para a operação de algumas predefinições.
Nota: Ao converter predefinições MediaWiki para Lua, lembre-se de que, em Lua, as sequências (strings) em branco e sequências (strings) compostas apenas por espaços em branco são consideradas verdadeiras. Se você não prestar atenção a esses argumentos em branco ao escrever seus módulos Lua, poderá tratar algo como verdadeiro, mas que, na verdade, deveria ser tratado como falso.
Quando a opção valueFunc é fornecida, a função valueFunc será responsável por lidar com os argumentos em branco, e a opção removeBlanks não terá efeito.
Formatação personalizada dos argumentos
Algumas vezes você quer remover alguns argumentos em branco mas não outros, ou talvez converter os valores de todos os argumentos posicionais para minúsculas. Para fazer coisas deste tipo você pode usar a opção valueFunc. Este parâmetro aceita como entrada uma função que recebe dois parâmetros, key e value, e retorna um único valor. Este valor é o que será obtido ao acessar o campo key da tabela args.
Exemplo 1: esta função preserva os espaços em branco do primeiro argumento posicional, mas remove-os dos demais e também remove os demais argumentos em branco. <syntaxhighlight lang="lua"> local args = getArgs(frame, { valueFunc = function (key, value) if key == 1 then return value elseif value then value = mw.text.trim(value) if value ~= then return value end end return nil end }) </syntaxhighlight>
Exemplo 2: esta função remove parâmetros em branco e converte todos os argumentos para minúsculas, mas não remove espaços dos argumentos posicionais. <syntaxhighlight lang="lua"> local args = getArgs(frame, { valueFunc = function (key, value) if not value then return nil end value = mw.ustring.lower(value) if mw.ustring.find(value, '%S') then return value end return nil end }) </syntaxhighlight>
Nota: a função acima falhará se receber como entrada algo que não seja do tipo string ou nil. Isso pode ocorrer se utilizar a função getArgs na função principal (main) do seu módulo, e aquela função for chamada por outro módulo Lua. Neste caso, você precisará conferir o tipo de sua entrada. Esse problema não ocorre se utilizar uma função especifica para lidar com os argumentos a partir de #invoke (isto é, se houver uma função p.main e uma p._main, ou algo parecido).
Exemplos 1 e 2 com checagem de tipo
|
|---|
|
Exemplo 1: <syntaxhighlight lang="lua"> local args = getArgs(frame, { valueFunc = function (key, value) if key == 1 then return value elseif type(value) == 'string' then value = mw.text.trim(value) if value ~= then return value else return nil end else return value end end }) </syntaxhighlight> Exemplo 2: <syntaxhighlight lang="lua"> local args = getArgs(frame, { valueFunc = function (key, value) if type(value) == 'string' then value = mw.ustring.lower(value) if mw.ustring.find(value, '%S') then return value else return nil end else return value end end }) </syntaxhighlight> |
Além disso, por favor note que a função valueFunc é chamada praticamente a cada vez que um argumento é requisitado a partir da tabela args, então se você se preocupa com o desempenho você deve se certificar de não fazer nada ineficiente com o seu código.
Frames e frames parentais
Os argumentos da tabela args podem ser passados simultaneamente a paetir do frame atual ou de seu frame parental. Para entender o que isso significa, é mais fácil dar um exemplo. Digamos que temos um módulo chamado Módulo:ExampleArgs. Este módulo imprime os dois primeiros parâmetros posicionais que ele recebe.
Código de Módulo:ExampleArgs
|
|---|
|
<syntaxhighlight lang="lua"> local getArgs = require('Módulo:Arguments').getArgs local p = {} function p.main(frame) local args = getArgs(frame) return p._main(args) end function p._main(args) local first = args[1] or local second = args[2] or return first .. ' ' .. second end return p </syntaxhighlight> |
A Predefinição:ExampleArgs contém o código {{#invoke:ExampleArgs|main|''firstInvokeArg''}}.
Agora, se chamarmos a Predefinição:ExampleArgs, acontece o seguinte:
| Código | Resultado |
|---|---|
{{#invoke:ExampleArgs|main|''firstInvokeArg''}}
(chama #invoke diretamente sem predefinição)
|
firstInvokeArg
(chama #invoke diretamente sem predefinição) |
{{ExampleArgs}}
|
firstInvokeArg |
{{ExampleArgs|firstTemplateArg}}
|
firstInvokeArg |
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}
|
firstInvokeArg secondTemplateArg |
Há três opções que você pode definir para alterar este comportamento: frameOnly, parentOnly e parentFirst. Se você definir frameOnly então só serão aceitos os argumentos passados a partir do frame atual; se você definir parentOnly então só serão aceitos os argumentos passados a partir do frame parental; e se você definir parentFirst os argumentos serão passados a partir de ambos os frames, mas os a partir do frame parental terão prioridade sobre o frame atual. Estes são os resultados em termos da Predefinição:ExampleArgs:
frameOnly
| Código | Resultado |
|---|---|
{{ExampleArgs}}
|
firstInvokeArg |
{{ExampleArgs|firstTemplateArg}}
|
firstInvokeArg |
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}
|
firstInvokeArg |
parentOnly
| Código | Resultado |
|---|---|
{{ExampleArgs}}
|
|
{{ExampleArgs|firstTemplateArg}}
|
firstTemplateArg |
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}
|
firstTemplateArg secondTemplateArg |
parentFirst
| Código | Resultado |
|---|---|
{{ExampleArgs}}
|
firstInvokeArg |
{{ExampleArgs|firstTemplateArg}}
|
firstTemplateArg |
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}
|
firstTemplateArg secondTemplateArg |
Notas:
- Se você definir tanto a opção
frameOnlyquanto a opçãoparentOnly, o módulo não vai obter nenhum argumento de#invoke. Isso provavelmente não é o que você quer. - Em algumas situações pode não estar disponível um módulo pai, por exemplo, se for passado para getArgs o frame pai em vez do frame atual. Neste caso, somente os argumentos do frame serão utilizados (a não ser que parentOnly esteja definido, mas neste caso nenhum argumento será utilizado) e as opções
parentFirsteframeOnlynão terão qualquer efeito.
Wrappers
A opção wrappers é utilizada para especificar um número limitado de predefinições wrappers, isto é, predefinições cujo único objetivo é chamar um módulo. Se o módulo detecta que está sendo chamado de uma predefinição wrapper, ele procurará apenas os argumentos do frame parental; caso contrário ele procurará apenas argumentos no frame passado para getArgs. Isso permite que os módulos sejam chamados tanto por #invoke quanto através de uma predefinição wrapper sem a perda de desempenho associada à checagem tanto do frame quanto do frame parental ao verificar cada argumento.
Por exemplo, o conteúdo da en:Template:Side box (excluindo o conteúdo das tags <noinclude>...</noinclude>) é {{#invoke:Side box|main}}. Não faz sentido procurar argumentos passados diretamente para a declaração #invoke desta predefinição, pois nenhum argumento jamais será especificado lá. Podemos evitar a busca destes argumentos passados para #invoke utilizando a opção parentOnly, mas se fizermos isso então a #invoke também não funcionará a partir de outras páginas. Se esse fosse o caso, o |text=Algum texto no código {{#invoke:Side box|main|text=Algum texto}} seria completamente ignorado, não importando em que página ele tivesse sido usado. Utilizando a opção wrappers para especificar ':en:Template:Side box' como um wrapper, podemos fazer com que {{#invoke:Side box|main|text=Algum texto}} funcione na maioria das páginas, sem exigir que o módulo tenha que procurar argumentos na própria página da en:Template:Side box.
Os wrappers podem ser especificados tanto como uma sequências de caracteres (string) quanto como um arranjo (array) de sequências de caracteres.
<syntaxhighlight lang="lua"> local args = getArgs(frame, { wrappers = 'Predefinição:Predefinição de invólucro' }) </syntaxhighlight>
<syntaxhighlight lang="lua"> local args = getArgs(frame, { wrappers = { 'Predefinição:Um invólucro', 'Predefinição:Outro invólucro', -- Pode-se inserir qualquer número de invólucros aqui. } }) </syntaxhighlight>
A opção wrappers altera os comportamentos padrão das opções frameOnly e parentOnly.
Comportamento de frameOnly e de parentOnly em relação com predefinições wrappers
| ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Os argumentos do frame não serão utilizados.
|
Notas:
- O módulo detectará automaticamente se ele está sendo chamado da subpágina /Testes da predefinição wrapper, então não há necessidade de especificar as páginas de testes explicitamente.
- Se a opção wrappers estiver definida e não houver um frame parental disponível, o módulo sempre obterá os argumentos a partir do frame passado para
getArgs.
Gravar na tabela de argumentos
Algumas vezes pode ser útil gravar novos valores na tabela de argumentos. Isso é possível com a configuração padrão do módulo. (No entanto, tenha em mente que geralmente um estilo de programação melhor seria criar uma nova tabela com os seus novos argumentos e copiar os argumentos da tabela args conforme fossem necessários.)
<syntaxhighlight lang="lua"> args.foo = 'algum valor' </syntaxhighlight>
É possível alterar este comportamento com as opções readOnly e noOverwrite. Se for definido readOnly então não será possível gravar quaisquer valores na tabela args. Se for definido noOverwrite, então será possível incluir novos valores na tabela, exceto se eles fossem sobrescrever argumentos que foram passados por #invoke.
Elementos "ref"
Este módulo utiliza metatables para obter argumentos a partir de #invoke. Isso permite acesso tanto aos argumentos do frame atual quanto do frame parental sem ter que utilizar a função pairs(). Isso ajuda se o seu módulo pode receber elementos <ref>...</ref> como entrada.
Assim que os elementos <ref>...</ref> são acessados em Lua, eles são processados pelo software do MediaWiki e a referência aparecerá na lista de referências do artigo. Se o seu módulo omite o elemento de referência de sua saída, você obterá uma referência fantasma - uma referência que aparece na lista de referências, mas sem números ligando-se a ela. Esse problema ocorreu com módulos que usam pairs() para detectar se devem ser utilizados argumentos do frame atual ou de seu parental, porque tais módulos processam automaticamente todos os argumentos disponíveis.
Este módulo resolve esse problema permitindo o acesso tanto aos argumentos do frame atual quanto aos do frame parental, ao mesmo tempo em que só requisita esses argumentos quando são necessários. No entanto, o problema ainda ocorrerá se você utilizar pairs(args) em outros lugares do seu módulo.
Limitações conhecidas
O uso de metatables também tem aspectos negativos. A maioria das ferramentas normais para tabelas em Lua não funcionarão adequadamente na tabela args, incluindo o operador #, a função next(), e as funções da biblioteca table. Se o uso disso é importante para o seu módulo, você deve utilizar a sua própria função de processamento de argumentos em vez deste módulo.