Exibir código-fonte para Módulo:Arguments/doc

<section begin=header />
{{#ifeq:{{#invoke:String|find|{{FULLPAGENAME}}|Testes}}|0|<includeonly>{{Module rating|p}}{{alto risco|2020985}}</includeonly>}}<!-- if pagename does not contain sandbox -->
<section end=header />

Este módulo facilita o processamento dos argumentos passados por um comando <code>#invoke</code>. Ele é um meta-módulo, destinado ao uso por outros módulos, e não deve ser chamado diretamente a partir de <code>#invoke</code><!---->. 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 <code>getArgs</code>.

<syntaxhighlight lang="lua">
local getArgs = require('Module:Arguments').getArgs
</syntaxhighlight>

No cenário mais básico, você pode utilizar s <code>getArgs</code> dentro de sua função principal, <code>main</code>. A variável <code>args</code> é uma tabela contendo os argumentos a partir de <code>#invoke</code>. (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 <code>#invoke</code> 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 <code>frame</code>.

<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 é <code><nowiki>{{#invoke:Example|main}}</nowiki></code> (opcionalmente com alguns parâmetros como <code><nowiki>{{#invoke:Example|main|arg1=value1|arg2=value2}}</nowiki></code>), 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 <code>#invoke</code>, 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 <code>trim</code> como <code>false</code>.

<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 <code>removeBlanks</code> como <code>false</code>.

<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 <code>valueFunc</code> é fornecida, a função <code>valueFunc</code> será responsável por lidar com os argumentos em branco, e a opção <code>removeBlanks</code> 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 <code>valueFunc</code>. Este parâmetro aceita como entrada uma função que recebe dois parâmetros, <code>key</code> e <code>value</code>, e retorna um único valor. Este valor é o que será obtido ao acessar o campo <code>key</code> da tabela <code>args</code>.

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 <code>string</code> ou <code>nil</code>. Isso pode ocorrer se utilizar a função <code>getArgs</code> 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 <code>p.main</code> e uma <code>p._main</code>, ou algo parecido).

{{cot|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>
{{cob}}

Além disso, por favor note que a função <code>valueFunc</code> é chamada praticamente a cada vez que um argumento é requisitado a partir da tabela <code>args</code>, 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 <code>args</code> 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 <code>Módulo:ExampleArgs</code>. Este módulo imprime os dois primeiros parâmetros posicionais que ele recebe.

{{cot|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>
{{cob}}

A <code>Predefinição:ExampleArgs</code> contém o código <code><nowiki>{{#invoke:ExampleArgs|main|''firstInvokeArg''}}</nowiki></code>.

Agora, se chamarmos a <code>Predefinição:ExampleArgs</code>, acontece o seguinte:

{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Código
! style="width: 40%;" | Resultado
|-
| <pre>{{#invoke:ExampleArgs|main|''firstInvokeArg''}}
	
(chama #invoke diretamente sem predefinição)</pre>
| ''firstInvokeArg''
	
(chama #invoke diretamente sem predefinição)
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| ''firstInvokeArg'' secondTemplateArg
|}

Há três opções que você pode definir para alterar este comportamento: <code>frameOnly</code>, <code>parentOnly</code> e <code>parentFirst</code>. Se você definir <code>frameOnly</code> então só serão aceitos os argumentos passados a partir do ''frame'' atual; se você definir <code>parentOnly</code> então só serão aceitos os argumentos passados a partir do ''frame'' parental; e se você definir <code>parentFirst</code> 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 <code>Predefinição:ExampleArgs</code>:

'''frameOnly'''
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Código
! style="width: 40%;" | Resultado
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| ''firstInvokeArg''
|}

'''parentOnly'''
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Código
! style="width: 40%;" | Resultado
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
|
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstTemplateArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstTemplateArg secondTemplateArg
|}

'''parentFirst'''
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Código
! style="width: 40%;" | Resultado
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstTemplateArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstTemplateArg secondTemplateArg
|}

Notas:
# Se você definir tanto a opção <code>frameOnly</code> quanto a opção <code>parentOnly</code>, o módulo não vai obter nenhum argumento de <code>#invoke</code>. 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 <code>parentFirst</code> e <code>frameOnly</code> nã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 {{tag|noinclude}}) é <code><nowiki>{{#invoke:Side box|main}}</nowiki></code>. 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 {{Parâmetro|text|Algum texto}} no código <code><nowiki>{{#invoke:Side box|main|text=Algum texto}}</nowiki></code> seria completamente ignorado, não importando em que página ele tivesse sido usado. Utilizando a opção <code>wrappers</code> para especificar ':en:Template:Side box' como um wrapper, podemos fazer com que <code><nowiki>{{#invoke:Side box|main|text=Algum texto}}</nowiki></code> 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 <code>wrappers</code> altera os comportamentos padrão das opções <code>frameOnly</code> e <code>parentOnly</code>.

{{collapse top|title=Comportamento de ''frameOnly'' e de ''parentOnly'' em relação com predefinições ''wrappers''}}

; Se <code>Predefinição:ExampleArgs</code> for especificada como uma predefinição wrapper:

; <code>parentOnly</code> é verdadeiro ou indefinido

Os argumentos do ''frame'' não serão utilizados.

{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Código
! style="width: 40%;" | Resultado
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
|
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstTemplateArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstTemplateArg secondTemplateArg
|}

; <code>parentOnly</code> é falso, <code>parentFirst</code> é falso ou indefinido

{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Código
! style="width: 40%;" | Resultafo
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| ''firstInvokeArg'' secondTemplateArg
|}

; <code>parentOnly</code> é falso, <code>parentFirst</code> é verdadeiro
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Código
! style="width: 40%;" | Resultado
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstTemplateArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstTemplateArg secondTemplateArg
|}

; Se <code>wrappers</code> estiver definido, mas <code>Predefinição:ExampleArgs</code> não estiver na lista de <code>wrappers</code>:

; <code>frameOnly</code> é verdadeiro ou indefinido

{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Código
! style="width: 40%;" | Resultado
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| ''firstInvokeArg''
|}

; <code>frameOnly</code> é falso, <code>parentFirst</code> é falso ou indefinido
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Código
! style="width: 40%;" | Resultado
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| ''firstInvokeArg'' secondTemplateArg
|}

; <code>frameOnly</code> é falso, <code>parentFirst</code> é verdadeiro
{| class="wikitable" style="width: 50em; max-width: 100%;"
|-
! style="width: 60%;" | Código
! style="width: 40%;" | Resultado
|-
| <code><nowiki>{{ExampleArgs}}</nowiki></code>
| ''firstInvokeArg''
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
| firstTemplateArg
|-
| <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
| firstTemplateArg secondTemplateArg
|}
{{collapse bottom}}

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 <code>getArgs</code>.

===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 <code>args</code> conforme fossem necessários.)

<syntaxhighlight lang="lua">
args.foo = 'algum valor'
</syntaxhighlight>

É possível alterar este comportamento com as opções <code>readOnly</code> e <code>noOverwrite</code>. Se for definido <code>readOnly</code> então não será possível gravar quaisquer valores na tabela <code>args</code>. Se for definido <code>noOverwrite</code>, então será possível incluir novos valores na tabela, exceto se eles fossem sobrescrever argumentos que foram passados por <code>#invoke</code>.

===Elementos "ref"===
Este módulo utiliza [[mw:Extension:Scribunto/Lua reference manual#Metatables|metatables]] para obter argumentos a partir de <code>#invoke</code>. Isso permite acesso tanto aos argumentos do ''frame'' atual quanto do ''frame'' parental sem ter que utilizar a função <code>pairs()</code>. Isso ajuda se o seu módulo pode receber elementos {{tag|ref}} como entrada.

Assim que os elementos {{tag|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 <code>pairs()</code> 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 <code>pairs(args)</code> 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 <code>args</code>, incluindo o operador <code>#</code>, a função <code>next()</code>, 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.

==Ver também==
* [[Wikipédia:Projetos/Scribunto]]
<includeonly>
<!-- Categorias aqui e links para outros idiomas no Wikidata -->
{{#ifeq:{{SUBPAGENAME}}|Testes||
[[Categoria:!Módulos]]
[[Categoria:!Metamódulos Lua]]
}}</includeonly>
<noinclude>
[[Categoria:Páginas de documentação de módulos]]
</noinclude>