Módulo:Testes/Gkiyoshinishimoto/Hatnote

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

Este é um meta-módulo que fornece várias funções para fazer notas de cabeçalho. Ele implementa a predefinição {{Teste/Gkiyoshinishimoto/Hatnote}}, para uso em notas de cabeçalho no topo das páginas. Ele também contém várias funções auxiliares para uso em outros módulos de notas de cabeçalhos Lua.

Uso a partir de texto wiki

As funções neste módulo não podem ser usadas diretamente a partir de "#invoke" e devem ser usadas por meio de predefinições. Consulte Predefinição:Teste/Gkiyoshinishimoto/Hatnote e Predefinição:Teste/Gkiyoshinishimoto/Format link para obter a documentação.

Uso a partir de outros módulos Lua

Para carregar este módulo a partir de outro módulo Lua, use o seguinte código.

local mHatnote = require('Módulo:Testes/Gkiyoshinishimoto/Hatnote')

Você pode então usar as funções conforme documentado abaixo.

Nota de cabeçalho

mHatnote._hatnote(s, options)

Esta função formata a sequência s como uma nota de cabeçalho. Isso inclui s nas marcações <div class="hatnote">...</div>. As opções são fornecidas na tabela options. As opções incluem:

• options.extraclasses - uma série de classes extras para fornecer
• options.selfref - se não for nulo ou falso, adiciona a classe "selfref", usada para denotar auto-referências à Wikipedia (consulte Predefinição:Teste/Gkiyoshinishimoto/Selfref)

As folhas de estilos em cascatas (F.E.C.) da classe de nota de cabeçalho são definidas em Módulo:Testes/Gkiyoshinishimoto/Hatnote/styles.css.

Exemplo 1

mHatnote._hatnote('Isto é uma nota de cabeçalho.')

Produz: <div class="hatnote">Isto é uma nota de cabeçalho.</div>

É mostrado como:

Isto é uma nota de cabeçalho.

Exemplo 2

mHatnote._hatnote('Isto é uma nota de cabeçalho.', {extraclasses = 'boilerplate seealso', selfref = true})

Produz: <div class="hatnote boilerplate seealso selfref">Isto é uma nota de cabeçalho.</div>

É mostrado como:

Isto é uma nota de cabeçalho.

Encontrar a identificação do espaço nomeado

mHatnote.findNamespaceId(link, removeColon)

Localiza a identificação do espaço nomeado da sequência link, que deve ser um nome de página válido, com ou sem o nome da seção. Esta função não funcionará se o nome da página estiver entre colchetes. Ao tentar analisar o nome do espaço nomeado, os dois-pontos são removidos do início da ligação por padrão. Isso é útil se os usuários especificaram dois-pontos quando eles não são estritamente necessários. Se você não precisar verificar os dois-pontos iniciais, defina removeColon como "false".

Exemplos

mHatnote.findNamespaceId('Leão') → 0

mHatnote.findNamespaceId('Categoria:Leões') → 14

mHatnote.findNamespaceId(':Categoria:Leões') → 14

mHatnote.findNamespaceId(':Categoria:Leões', false) → 0 (o espaço nomeado é detectado como ":Categoria" em vez de "Categoria")

Fazer erro de texto wiki

mHatnote.makeWikitextError(msg, helpLink, addTrackingCategory)

Formata a sequência msg como uma mensagem de erro texto wiki vermelha, com ligação opcional para uma página de ajuda helpLink. Normalmente esta função também adiciona Predefinição:Teste/Gkiyoshinishimoto/Clc. Para suprimir a categorização, passe false como terceiro parâmetro da função (addTrackingCategory).

Exemplos:

mHatnote.makeWikitextError('ocorreu um erro') →

mHatnote.makeWikitextError('ocorreu um erro', 'Predefinição:Teste/Gkiyoshinishimoto/Exemplo#Erros') →

Exemplos

Para um exemplo de como este módulo é usado em outros módulos Lua, consulte Módulo:Testes/Gkiyoshinishimoto/Labelled list hatnote.

Notas

--------------------------------------------------------------------------------
--                   Módulo:Testes/Gkiyoshinishimoto/Hatnote                  --
--                                                                            --
-- Este módulo produz ligações ('links') para notas de cabeçalho ('hatnotes') --
-- e ligações ('links') para artigos relacionados. Ele implementa as          --
-- meta-predefinições {{Teste/Gkiyoshinishimoto/Hatnote}} e                   --
-- {{Teste/Gkiyoshinishimoto/Format link}} e inclui funções auxiliares para   --
-- outros módulos de notas de cabeçalho ('hatnotes') 'Lua'.                   --
--------------------------------------------------------------------------------

local libraryUtil = require('libraryUtil')
local checkType = libraryUtil.checkType
local checkTypeForNamedArg = libraryUtil.checkTypeForNamedArg
local mArguments -- inicializa lentamente [[Módulo:Testes/Gkiyoshinishimoto/Arguments]]
local yesno -- inicializa lentamente [[Módulo:Testes/Gkiyoshinishimoto/Yesno]]
local formatLink -- inicializa lentamente [[Módulo:Testes/Gkiyoshinishimoto/Format link]] ._formatLink

local p = {}

--------------------------------------------------------------------------------
-- Funções auxiliares
--------------------------------------------------------------------------------

local function getArgs(frame)
	-- Busca os argumentos do quadro parental. Os espaços em branco são cortados
	-- e os espaços em branco são removidos.
	mArguments = require('Módulo:Testes/Gkiyoshinishimoto/Arguments')
	return mArguments.getArgs(frame, {parentOnly = true})
end

local function removeInitialColon(s)
	-- Remove os dois pontos iniciais de uma sequência ('string'), se presentes.
	return s:match('^:?(.*)')
end

function p.defaultClasses(inline)
	-- Fornece as classes de notas de cabeçalho ('hatnotes') padrões como uma sequência ('string') 
	-- separada por espaço; útil para módulos que lidam de notas de cabeçalho ('hatnotes')
	-- como [[Módulo:Testes/Gkiyoshinishimoto/Hatnote group]].
	return
		(inline == 1 and 'hatnote-inline' or 'hatnote') .. ' ' ..
		'navigation-not-searchable'
end

function p.disambiguate(page, disambiguator)
	-- Formata um título de página com um parêntese de desambiguação,
	-- ou seja, "Exemplo" → "Exemplo (desambiguação)".
	checkType('disambiguate', 1, page, 'string')
	checkType('disambiguate', 2, disambiguator, 'string', true)
	disambiguator = disambiguator or 'desambiguação'
	return mw.ustring.format('%s (%s)', page, disambiguator)
end

function p.findNamespaceId(link, removeColon)
	-- Localiza o 'ID' do espaço nomeado (número do espaço nomeado) de uma 
	-- ligação ('link') ou um nome de página. Essa a função não funcionará se a 
	-- ligação ('link') estiver entre colchetes duplos. Dois pontos são cortados 
	-- desde o início da ligação ('link') por padrão. Para pular o corte dos dois
	-- pontos, defina o parâmetro "removeColon" como falso ('false').
	checkType('findNamespaceId', 1, link, 'string')
	checkType('findNamespaceId', 2, removeColon, 'boolean', true)
	if removeColon ~= false then
		link = removeInitialColon(link)
	end
	local namespace = link:match('^(.-):')
	if namespace then
		local nsTable = mw.site.namespaces[namespace]
		if nsTable then
			return nsTable.id
		end
	end
	return 0
end

function p.makeWikitextError(msg, helpLink, addTrackingCategory, title)
	-- Formata uma mensagem de erro para ser retornada ao texto wiki. Se
	-- "addTrackingCategory" não é falso ('false') após ser retornado a partir de
	-- [[Módulo:Testes/Gkiyoshinishimoto/Yesno]], e se não estivermos em uma 
	-- página de discussão, uma categoria de rastreamento (manutenção) é adicionada.
	checkType('makeWikitextError', 1, msg, 'string')
	checkType('makeWikitextError', 2, helpLink, 'string', true)
	yesno = require('Módulo:Testes/Gkiyoshinishimoto/Yesno')
	title = title or mw.title.getCurrentTitle()
	-- Faz o texto da ligação ('link') de ajuda.
	local helpText
	if helpLink then
		helpText = ' ([[' .. helpLink .. '|ajuda]])'
	else
		helpText = ''
	end
	-- Faz o texto da categoria.
	local category
	if not title.isTalkPage -- Não categoriza as páginas de discussão
		and title.namespace ~= 2 -- Não categoriza o espaço do usuário
		and yesno(addTrackingCategory) ~= false -- Permite optar por não participar
	then
		category = '!Predefinições de nota de cabeçalho com erros'
		category = mw.ustring.format(
			'[[%s:%s]]',
			mw.site.namespaces[14].name,
			category
		)
	else
		category = ''
	end
	return mw.ustring.format(
		'<strong class="error">Erro: %s%s.</strong>%s',
		msg,
		helpText,
		category
	)
end

local curNs = mw.title.getCurrentTitle().namespace
p.missingTargetCat =
	-- Categoria de destino ausente padrão, exportada para uso em módulos relacionados
	((curNs ==  0) or (curNs == 14)) and
	'Artigos com predefinições de nota de cabeçalho direcionados para uma página inexistente' or nil

function p.quote(title)
	-- Coloca os títulos entre aspas. Se o título começar/terminar com aspas,
	-- ajusta desse lado como com {{-'}}
	local quotationMarks = {
		["'"]=true, ['"']=true, ['“']=true, ["‘"]=true, ['”']=true, ["’"]=true
	}
	local quoteLeft, quoteRight = -- Testa se o início/fim são aspas
		quotationMarks[string.sub(title,  1,  1)],
		quotationMarks[string.sub(title, -1, -1)]
	if quoteLeft or quoteRight then
		title = mw.html.create("span"):wikitext(title)
	end
	if quoteLeft  then title:css("padding-left",  "0.15em") end
	if quoteRight then title:css("padding-right", "0.15em") end
	return '"' .. tostring(title) .. '"'
end

--------------------------------------------------------------------------------
-- Hatnote
--
-- Produz o texto de nota de cabeçalho ('hatnote') padrão. Implementa a 
-- predefinição {{Teste/Gkiyoshinishimoto/Hatnote}}.
--------------------------------------------------------------------------------

function p.hatnote(frame)
	local args = getArgs(frame)
	local s = args[1]
	if not s then
		return p.makeWikitextError(
			'nenhum texto especificado',
			'Predefinição:Teste/Gkiyoshinishimoto/Hatnote#Erros',
			args.category
		)
	end
	return p._hatnote(s, {
		extraclasses = args.extraclasses,
		selfref = args.selfref
	})
end

function p._hatnote(s, options)
	checkType('_hatnote', 1, s, 'string')
	checkType('_hatnote', 2, options, 'table', true)
	options = options or {}
	local inline = options.inline
	local hatnote = mw.html.create(inline == 1 and 'span' or 'div')
	local extraclasses
	if type(options.extraclasses) == 'string' then
		extraclasses = options.extraclasses
	end

	hatnote
		:attr('role', 'note')
		:addClass(p.defaultClasses(inline))
		:addClass(extraclasses)
		:addClass(options.selfref and 'selfref' or nil)
		:wikitext(s)

	return mw.getCurrentFrame():extensionTag{
		name = 'templatestyles', args = { src = 'Módulo:Testes/Gkiyoshinishimoto/Hatnote/styles.css' }
	} .. tostring(hatnote)
end

return p