Módulo:Template invocation

-- Este módulo fornece funções para fazer invocações de predefinições MediaWiki.

local checkType = require('libraryUtil').checkType

local p = {}

------------------------------------------------------------------------
--       Nome:  p.name
--  Propósito:  Encontra um nome de invocação de predefinição a partir
--              de um nome de página ou de um objeto mw.title
--  Descrição:  Esta função detecta se uma sequência/string ou um 
--              objeto mw.title foram passados e usa isso para 
--              encontrar um nome de predefinição conforme usado nas
--              invocações de predefinições.
-- Parâmetros:  title - nome completo da página ou objeto mw.title para
--              a predefinição (sequência/string ou objeto mw.title)
--    Retorno:  Sequência/string
------------------------------------------------------------------------

function p.name(title)
	if type(title) == 'string' then
		title = mw.title.new(title)
		if not title or #title.prefixedText == 0 or #title.interwiki > 0 then
			error("título inválido no parâmetro nº 1 da função 'name'", 2)
		end
	elseif type(title) ~= 'table' or type(title.getContent) ~= 'function' then
		error("o parâmetro nº 1 da função 'name' deve ser uma string ou um objeto mw.title", 2)
	end
	if title.namespace == 10 then
		local text = title.text
		local check = mw.title.new(text, 10)
		-- Exclui o prefixo, a menos que tenhamos algo como "Predefinição:Categoria:Foo", que não pode ser abreviado para "Categoria:Foo".
		return check and mw.title.equals(title, check) and text or title.prefixedText
	elseif title.namespace == 0 then
		return ':' .. title.prefixedText
	else
		return title.prefixedText
	end
end

------------------------------------------------------------------------
--       Nome:  p.invocation
--  Propósito:  Constrói uma invocação de predefinição MediaWiki.
--  Descrição:  Esta função faz uma chamada de predefinição a partir 
--              do nome e os argumentos dados. Observe que não é
--              perfeito: nós não temos como saber o que era espaço 
--              em branco na invocação original, os parâmetros nomeados 
--              serão classificados em ordem alfabética e quaisquer 
--              parâmetros com chaves duplicadas serão removidos.
-- Parâmetros:  name - o nome da predefinição, formatado como 
--                   aparecerá na invocação. (sequência/string)
--              args - uma tabela de argumentos de predefinição. (tabela)
--              format - opções de formatação. (sequência/string, opcional)
--                  Define como "nowiki" para escapar, chaves, barras 
--                  verticais e sinais de igual com suas entidades HTML.  
--                  O padrão é sem escape.
--    Retorno: Sequência/string
------------------------------------------------------------------------

function p.invocation(name, args, format)
	checkType('invocation', 1, name, 'string')
	checkType('invocation', 2, args, 'table')
	checkType('invocation', 3, format, 'string', true)

	-- Valida a tabela args e faz uma cópia para trabalhar. Nós precisamos 
	-- fazer uma cópia da tabela em vez de apenas usar o original, pois 
	-- alguns valores podem ser apagados durante a construção da invocação.
	local invArgs = {}
	for k, v in pairs(args) do
		local typek = type(k)
		local typev = type(v)
		if typek ~= 'string' and typek ~= 'number'
			or typev ~= 'string' and typev ~= 'number'
		then
			error("tabela de argumentos inválidos no parâmetro nº 2 de " ..
			"'invocation' (chaves e valores devem ser strings ou números)", 2)
		end
		invArgs[k] = v
	end

	-- Obtém os separadores a serem usados.
	local seps = {
		openb = '{{',
		closeb = '}}',
		pipe = '|',
		equals = '='
	}
	if format == 'nowiki' then
		for k, v in pairs(seps) do
			seps[k] = mw.text.nowiki(v)
		end
	end

	-- Constrói o corpo da invocação primeiro com argumentos numerados e
	-- depois os nomeados.
	local ret = {}
	ret[#ret + 1] = seps.openb
	ret[#ret + 1] = name
	for k, v in ipairs(invArgs) do
		if type(v) == 'string' and v:find('=', 1, true) then
			-- Provavelmente algo como 1=foo=bar que precisa ser mostrado 
			-- como um argumento nomeado.
		else
			ret[#ret + 1] = seps.pipe
			ret[#ret + 1] = v
			invArgs[k] = nil -- Apaga a chave para que não adicionemos 
							 -- o valor duas vezes
		end
	end
	local keys = {} -- classifica a lista de parâmetros; melhor do que a ordem
					-- arbitrária
	for k, _ in pairs(invArgs) do
		keys[#keys + 1] = k
	end
	table.sort(keys,
		function (a, b)
			-- Classifica primeiro com chaves do tipo número e depois 
			-- sequência/string.
			if type(a) == type(b) then
				return a < b
			elseif type(a) == 'number' then
				return true
			end
		end
	)

	local maybeSpace = '' -- O primeiro parâmetro nomeado não deve ser separado por um espaço
	for _, v in ipairs(keys) do -- Adiciona argumentos nomeados com base na
								-- lista de parâmetros classificada
		ret[#ret + 1] = maybeSpace .. seps.pipe
		ret[#ret + 1] = tostring(v)
		ret[#ret + 1] = seps.equals
		ret[#ret + 1] = invArgs[v]
		maybeSpace = ' '
	end
	ret[#ret + 1] = seps.closeb

	return table.concat(ret)
end

return p