Módulo:Testes/Gkiyoshinishimoto/Labelled list hatnote

Documentação do módulo[ver] [editar] [histórico] [purgar]

Este módulo fornece várias funções que facilitam a implementação de notas de cabeçalho que assumem a forma de um rótulo na frente de uma lista de páginas, por exemplo,

Rótulo: A, B, e C

Uso

labelledList

Invocar a função labelledList() é suficiente para implementar a maioria dessas predefinições:

{{#invoke:Testes/Gkiyoshinishimoto/Labelled list hatnote|labelledList|rótulo universal}}

ou

{{#invoke:Testes/Gkiyoshinishimoto/Labelled list hatnote|labelledList|Rótulo singular|Rótulo plural}}

Por exemplo, fornecer "Ver também" em vez de "Rótulo universal" duplica a funcionalidade de {{Teste/Gkiyoshinishimoto/See also}}, enquanto fornecer "Artigo principal" e "Artigos principais" em vez de "Rótulo singular" e "Rótulo plural" duplica a funcionalidade (espaço nomeado de artigos) de {{Teste/Gkiyoshinishimoto/Main}}.

Se o terceiro e o quarto rótulos forem fornecidos, eles serão usados no caso em que qualquer uma das páginas de destino estiver fora do espaço nomeado do artigo, por exemplo, {{Teste/Gkiyoshinishimoto/Main}} pode ser implementado assim:

{{#invoke:Testes/Gkiyoshinishimoto/Labelled list hatnote|labelledList|Artigo principal|Artigos principais|Página principal|Páginas principais}}

preprocessDisplays

A função preprocessDisplays() pega uma lista bruta de argumentos e combina em qualquer argumento de exibição. Por exemplo, {{Teste/Gkiyoshinishimoto/See also|1|l1=Um}} inicialmente tem a tabela de argumentos {'1', ['l1'] = 'Um'}; esta tabela iria combiná-los na tabela {'1|Um'}. Ela substitui a inserção manual da barra vertical (por exemplo, {{Teste/Gkiyoshinishimoto/See also|1{{!}}2|l1=Um}} → {'1|Um'}) e comprime arranjos esparsos se um parâmetro for ignorado ou deixado em branco.

Exemplo:

local mLabelledList = require('Módulo:Testes/Gkiyoshinishimoto/Labelled list hatnote')
local pages = mLabelledList.preprocessDisplays(args)

_labelledList

Para módulos que precisam modificar um pouco a funcionalidade enquanto ainda a usam, _labelledList() fornece alguma flexibilidade. Leva três parâmetros:

1. Uma lista de páginas, preferencialmente pré-processada e comprimida por preprocessDisplays
2. Uma tabela de rótulos, onde o primeiro item é o rótulo singular ou universal e o segundo é um rótulo plural ou uma cópia do primeiro.
3. Uma tabela de opções, preferencialmente contendo:
   • uma sequência template com o título completo da predefinição. O padrão é o título deste módulo.
   • uma sequência de category (ou nil) conforme obtida por makeWikitextError de Módulo:Testes/Gkiyoshinishimoto/Hatnote, para desabilitar opcionalmente as categorias de erro
   • uma sequência selfref (ou nil) conforme obtida por _hatnote para habilitar a opção "selfref"

Exemplo:

local mLabelledList = require('Módulo:Testes/Gkiyoshinishimoto/Labelled list hatnote')
return mLabelledList._labelledList(pages, labels, options)

Erros

Este módulo faz com que as predefinições baseadas nele produzam uma mensagem de erro se nenhum nome de página for fornecido como parâmetro de predefinição. Normalmente, elas devem levar de volta às seções "Erros" na documentação dessas predefinições. No entanto, se essas predefinições usarem um módulo com _labelledList() e não fornecerem um item template em sua tabela de opções, esse erro retornará aqui por padrão. O erro pode ser resolvido fornecendo pelo menos um parâmetro de nome de página válido para a predefinição em questão; o problema na predefinição pode ser corrigido fornecendo algum valor ao item template da tabela _labelledList() options.

Notas

</noinclude> </noinclude>

--------------------------------------------------------------------------------
--                               Lista rotulada                               --
--                                                                            --
-- Este módulo faz o trabalho principal de criar uma nota ('hatnote')         --
-- composta por uma lista prefixada por um rótulo terminado em dois pontos,   --
-- ou seja, "Rótulo: ['andList' de páginas]",                                 --
-- para {{Teste/Gkiyoshinishimoto/Ver também}} e predefinições similares.     --   
--------------------------------------------------------------------------------

local mHatnote = require('Módulo:Testes/Gkiyoshinishimoto/Hatnote')
local mHatlist = require('Módulo:Testes/Gkiyoshinishimoto/Hatnote list')
local mArguments -- inicializa lentamente
local yesno -- inicializa lentamente
local p = {}

-- Padrões globais para este módulo
local defaults = {
	label = 'Ver também', -- Recurso ('fallback') final para argumento de rótulo ('label')
	labelForm = '%s: %s',
	prefixes = {'label', 'label ', 'l'},
	template = 'Módulo:Testes/Gkiyoshinishimoto/Labelled list hatnote'
}

-- Sequências ('strings') de mensagem localizáveis
local msg = {
	errorSuffix = '#Erros',
	noInputWarning = 'nenhum nome de página especificado',
	noOutputWarning =
		"'''[[%s]] — sem saída: nenhuma das páginas de destino existe.'''"
}

-- Função auxiliar que pré-combina parâmetros de exibição em argumentos de página.
-- Também compacta arranjos esparsos, como um efeito colateral desejável.
function p.preprocessDisplays (args, prefixes)
	-- Os prefixos especificam quais parâmetros, em ordem, devem ser verificados quanto às opções a serem mostradas
	-- Cada um deles tem números anexados automaticamente, por exemplo 'label1', 'label 1' e 'l1'
	prefixes = prefixes or defaults.prefixes
	local indices = {}
	local sparsePages = {}
	for k, v in pairs(args) do
		if type(k) == 'number' then
			indices[#indices + 1] = k
			local display
			for i = 1, #prefixes do
				display = args[prefixes[i] .. k]
				if display then break end
			end
			sparsePages[k] = display and
				string.format('%s|%s', string.gsub(v, '|.*$', ''), display) or v
		end
	end
	table.sort(indices)
	local pages = {}
	for k, v in ipairs(indices) do pages[#pages + 1] = sparsePages[v] end
	return pages
end

-- Função auxiliar para obter um destino de página de uma sequência ('string') de página processada
-- por exemplo. "Página|Rótulo" → "Página" ou "Destino" → "Destino"
local function getTarget(pagename)
 	local pipe = string.find(pagename, '|')
	return string.sub(pagename, 0, pipe and pipe - 1 or nil)
end

-- Produz uma nota ('hatnote') de lista de páginas rotuladas.
-- O quadro principal (definição da predefinição) leva 1 ou 2 argumentos, para um rótulo singular 
-- e (opcionalmente) plural, respectivamente:
-- * {{#invoke:Testes/Gkiyoshinishimoto/Labelled list hatnote|labelledList|Rótulo singular|Rótulo plural}}
-- A predefinição resultante usa os parâmetros de nome de página e rótulo normalmente.
function p.labelledList (frame)
	mArguments = require('Módulo:Testes/Gkiyoshinishimoto/Arguments')
	yesno = require('Módulo:Testes/Gkiyoshinishimoto/Yesno')
	local labels = {frame.args[1] or defaults.label}
	labels[2] = frame.args[2] or labels[1]
	labels[3] = frame.args[3] -- ('no defaulting')
	labels[4] = frame.args[4] -- ('no defaulting')
	local template = frame:getParent():getTitle()
	local args = mArguments.getArgs(frame, {parentOnly = true})
	local pages = p.preprocessDisplays(args)
	local options = {
		category = yesno(args.category),
		extraclasses = frame.args.extraclasses,
		ifexists = yesno(frame.args.ifexists),
		namespace = frame.args.namespace or args.namespace,
		selfref = yesno(frame.args.selfref or args.selfref),
		template = template
	}
	return p._labelledList(pages, labels, options)
end

function p._labelledList (pages, labels, options)
	if options.ifexists then
		for k = #pages, 1, -1 do -- itera para trás para permitir remoções suaves
			local v = pages[k]
			local title = mw.title.new(getTarget(v), namespace)
			if (v == '') or title == nil or not title.exists then
				table.remove(pages, k)
			end
		end
	end
	labels = labels or {}
	label = (#pages == 1 and labels[1] or labels[2]) or defaults.label
	for k, v in pairs(pages) do 
		if mHatnote.findNamespaceId(v) ~= 0 then
			label =
				(
					#pages == 1 and
					(labels[3] or labels[1] or defaults.label) or
					(labels[4] or labels[2] or defaults.label)
				) or defaults.label
		end
	end
	if #pages == 0 then
		if options.ifexists then
			mw.addWarning(
				string.format(
					msg.noOutputWarning, options.template or defaults.template
				)
			)
			return ''
		else
			return mHatnote.makeWikitextError(
				msg.noInputWarning,
				(options.template or defaults.template) .. msg.errorSuffix,
				options.category
			)
		end
	end
	local text = string.format(
		options.labelForm or defaults.labelForm,
		label,
		mHatlist.andList(pages, true)
	)
	local hnOptions = {
		extraclasses = options.extraclasses,
		selfref = options.selfref
	}
	return mHatnote._hatnote(text, hnOptions)
end

return p