Módulo:Testes/Gkiyoshinishimoto/Format link

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

Este módulo, migrado das origens em Módulo:Testes/Gkiyoshinishimoto/Hatnote, fornece funcionalidade para formatar ligações^[a] para exibição, incluindo a que move a predefinição {{Teste/Gkiyoshinishimoto/Format link}}.

Ele pode formatar ligações^[a] de seção com o símbolo de seção ("§") e espaços em branco apropriados, automaticamente escapa nomes de categoria e arquivo com o truque de dois pontos [en] e inclui funcionalidade para colocar em itálico o nome da página ou seção, e para detectar e categorizar os resultados que produzem ligações vermelhas.

Uso a partir de texto wiki[editar código-fonte]

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

Uso a partir de outros módulos Lua[editar código-fonte]

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

local mFormatLink = require('Módulo:Testes/Gkiyoshinishimoto/Format link')

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

_formatLink[editar código-fonte]

mFormatLink._formatLink{
    link = 'Ligação',
    display = 'Texto a ser mostrado',
    target = 'Destino',
    italicizePage = true,
    italicizeSection = true,
    categorizeMissing = '!Páginas que utilizam ligações vermelhas formatadas'
}

Formata link como uma ligação wiki^[b]. Categorias e arquivos são escapados automaticamente com o truque de dois pontos [en], e as ligações^[a] para as seções são formatadas automaticamente como página § seção, em vez do padrão MediaWiki de página#seção.

Várias opções modificam a saída:

Se o valor display estiver presente, ele será usado como um valor de exibição. Qualquer inserção manual da barra vertical (usando a palavra mágica {{!}} ou similar) presente em link será substituída pelo valor de display, se presente.
Se o valor target estiver presente, ele substituirá link como um destino, mas o resultado ainda será mostrado usando o valor de display , ou o resultado da formatação de link.
Se italicizePage for "true", então a parte da página da ligação^[a] estará em itálico, se presente.
Se italicizeSection for "true", então a parte da seção da ligação^[a] estará em itálico, se presente.
Se categorizeMissing for uma sequência^[c] preenchida (que é não vazia), então esse valor é usado como um nome de categoria, e essa categoria será aplicada se o destino resultante da ligação^[a] (não importa se através de link ou através de target) não existir.

Exemplos: mFormatLink._formatLink{link = 'Foo#Baz'} → [[:Foo#Baz|Foo § Barz]] → Foo § Baz; mFormatLink._formatLink{link = 'Foo', display = 'Qux'} → [[:Foo|Qux]] → Qux; mFormatLink._formatLink{link = 'Foo|Baz', display = 'Qux'} → [[:Foo|Qux]] → Qux; mFormatLink._formatLink{link = '#Foo', target = 'Exemplo#Foo'} → [[:Exemplo#Foo|§ Foo]] → § Foo; mFormatLink._formatLink{link = 'O Senhor dos Anéis#Detalhes do enredo', italicizePage = true} → [[:O Senhor dos Anéis#Detalhes do enredo|''O Senhor dos Anéis'' § Detalhes do enredo]] → O Senhor dos Anéis § Detalhes do enredo; mFormatLink._formatLink{link = 'en:Cybercrime Prevention Act of 2012#Disini v. Secretary of Justice', italicizeSection = true} → [[:en:Cybercrime Prevention Act of 2012#Disini v. Secretary of Justice|Cybercrime Prevention Act of 2012 § ''Disini v. Secretary of Justice'']] → en:Cybercrime Prevention Act of 2012 § Disini v. Secretary of Justice; mFormatLink._formatLink{link = 'Página inexistente', categorizeMissing = 'Exemplo'} → [[:Página inexistente]][[Categoria:Exemplo]] → Página inexistente; mFormatLink._formatLink{link = 'Existência', categorizeMissing = 'Exemplo'} → [[:Existência]] → Existência

formatPages[editar código-fonte]

mFormatLink.formatPages(options, pages)

Essa função derivada é útil para listas que formatam muitas ligações^[a]. Ela formata um arranjo^[d] de páginas usando a função _formatLink e retorna o resultado como um arranjo^[d]. As opções na tabela options são aplicadas e usam os mesmos nomes que as opções para _formatLink.

Exemplo: mFormatLink.formatPages({categorizeMissing = 'Exemplo'}, {'Foo#Baz', 'Página inexistente'}) → {'[[:Foo#Baz|Foo § Baz]]', '[[:Página inexistente]][[Categoria:Exemplo]]'}

Erros[editar código-fonte]

Se _formatLink for usada e nenhum argumento link nem target for fornecido, o módulo produzirá uma mensagem de erro em vez de sua saída normal, já que ele não pode então produzir uma saída válida.

Você pode resolver esse erro fornecendo os parâmetros apropriados para _formatLink ou pode querer garantir que um erro mais descritivo seja fornecido por uma predefinição ou um módulo (relativos a uma fase do processo^[e]) quando, de outra forma, chamaria _formatLink com argumentos inadequados.

Notas[editar código-fonte]

↑ ^a ^b ^c ^d ^e ^f ^g do inglês link
↑ wikilink
↑ do inglês string
↑ ^a ^b do inglês array
↑ do inglês downstream

A documentação acima é transcluída de Módulo:Testes/Gkiyoshinishimoto/Format link/doc. (editar | histórico)
Editores podem experimentar nas páginas de teste (criar | espelhar) e de exemplos para testes (criar) deste módulo.
Subpáginas deste módulo.

--------------------------------------------------------------------------------
-- Format link
--
-- Cria uma ligação wiki ('wikilink') a partir da ligação ('link') fornecida e 
-- mostra os valores. As ligações ('links') são escapadas com dois pontos, se 
-- necessário, e as ligações ('links') para as seções são detectados e mostradas
-- com " § " como separador em vez do "#" padrão no MediaWiki. Usado na 
-- predefinição {{Teste/Gkiyoshinishimoto/Format link}}.
--------------------------------------------------------------------------------
local libraryUtil = require('libraryUtil')
local checkType = libraryUtil.checkType
local checkTypeForNamedArg = libraryUtil.checkTypeForNamedArg
local mArguments -- inicializa lentamente [[Módulo:Testes/Gkiyoshinishimoto/Arguments]]
local mError -- inicializa lentamente [[Módulo:Testes/Gkiyoshinishimoto/Error]]
local yesno -- inicializa lentamente [[Módulo:Testes/Gkiyoshinishimoto/Yesno]]

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

local function maybeItalicize(s, shouldItalicize)
	-- Coloca "s" em itálico se "s" for uma sequência ('string') e o parâmetro
	-- "shouldItalicize" for verdadeiro ("true").
	if s and shouldItalicize then
		return '<i>' .. s .. '</i>'
	else
		return s
	end
end

local function parseLink(link)
	-- Analisa uma ligação ('link') e retorna uma tabela com os componentes da 
	-- ligação ('link'). Esses componentes são:
	-- - link: a ligação ('link'), sem os dois pontos iniciais (sempre presente)
	-- - page: o nome da página (sempre presente)
	-- - section: o nome da página (pode ser nulo)
	-- - display: o texto a ser mostrado, se inserido manualmente após uma 
	-- barra vertical ('pipe') (pode ser nulo)
	link = removeInitialColon(link)

	-- Localiza se um valor a ser mostrado falso foi adicionado com a 
	-- palavra mágica {{!}}.
	local prePipe, display = link:match('^(.-)|(.*)$')
	link = prePipe or link

	-- Localiza a página, se ela existir.
	-- Para ligações ('links') como [[#Algo]], a página será nula.
	local preHash, postHash = link:match('^(.-)#(.*)$')
	local page
	if not preHash then
		-- Temos uma ligação ('link') como [[Algo]].
		page = link
	elseif preHash ~= '' then
		-- Temos uma ligação ('link') como [[Algo#Algo]].
		page = preHash
	end

	-- Localiza a seção, se ela existir.
	local section
	if postHash and postHash ~= '' then
		section = postHash
	end
	
	return {
		link = link,
		page = page,
		section = section,
		display = display,
	}
end

local function formatDisplay(parsed, options)
	-- Formata uma sequência ('string') a ser mostrada com base em uma tabela 
	-- de ligações ('links') analisadas (correspondendo à saída de "parseLink") e 
	-- uma tabela de opções (combinando com as opções de entrada para "_formatLink").
	local page = maybeItalicize(parsed.page, options.italicizePage)
	local section = maybeItalicize(parsed.section, options.italicizeSection)
	if (not section) then
		return page
	elseif (not page) then
		return mw.ustring.format('§&nbsp;%s', section)
	else
		return mw.ustring.format('%s §&nbsp;%s', page, section)
	end
end

local function missingArgError(target)
	mError = require('Módulo:Testes/Gkiyoshinishimoto/Error')
	return mError.error{message =
		'Erro: Nenhuma ligação ou destino especificado! ([[' .. target .. '#Erros|ajuda]])'
	}
end

--------------------------------------------------------------------------------
-- Funções principais
--------------------------------------------------------------------------------

function p.formatLink(frame)
	-- A função de exportação "formatLink", para uso em predefinições.
	yesno = require('Módulo:Testes/Gkiyoshinishimoto/Yesno')
	local args = getArgs(frame)
	local link = args[1] or args.link
	local target = args[3] or args.target
	if not (link or target) then
		return missingArgError('Predefinição:Teste/Gkiyoshinishimoto/Format link')
	end

	return p._formatLink{
		link = link,
		display = args[2] or args.display,
		target = target,
		italicizePage = yesno(args.italicizepage),
		italicizeSection = yesno(args.italicizesection),
		categorizeMissing = args.categorizemissing
	}
end

function p._formatLink(options)
	-- A função de exportação "formatLink", para uso em módulos.
	checkType('_formatLink', 1, options, 'table')
	local function check(key, expectedType) -- para brevidade
		checkTypeForNamedArg(
			'_formatLink', key, options[key], expectedType or 'string', true
		)
	end
	check('link')
	check('display')
	check('target')
	check('italicizePage', 'boolean')
	check('italicizeSection', 'boolean')
	check('categorizeMissing')

	-- Normaliza a ligação ('link') e o destino e verifica se pelo menos um está presente
	if options.link == '' then options.link = nil end
	if options.target == '' then options.target = nil end
	if not (options.link or options.target) then
		return missingArgError('Módulo:Testes/Gkiyoshinishimoto/Format link')
	end

	local parsed = parseLink(options.link)
	local display = options.display or parsed.display
	local catMissing = options.categorizeMissing
	local category = ''

	-- Localiza o texto a ser mostrado
	if not display then display = formatDisplay(parsed, options) end

	-- Lida com a opção de destino, se presente
	if options.target then
		local parsedTarget = parseLink(options.target)
		parsed.link = parsedTarget.link
		parsed.page = parsedTarget.page
	end

	-- Testa se a página existe se uma categoria de diagnóstico for especificada
	if catMissing and (mw.ustring.len(catMissing) > 0) then
		local title = nil
		if parsed.page then title = mw.title.new(parsed.page) end
		if title and (not title.isExternal) then
			local success, exists = pcall(function() return title.exists end)
			if success and not exists then
				category = mw.ustring.format('[[Categoria:%s]]', catMissing)
			end
		end
	end
	
	-- Formata o resultado como uma ligação ('link')
	if parsed.link == display then
		return mw.ustring.format('[[:%s]]%s', parsed.link, category)
	else
		return mw.ustring.format('[[:%s|%s]]%s', parsed.link, display, category)
	end
end

--------------------------------------------------------------------------------
-- Funções de conveniência derivadas
--------------------------------------------------------------------------------

function p.formatPages(options, pages)
	-- Formata um arranjo de páginas usando "formatLink" e a tabela de opções 
	-- dada,e o retorna como um arranjo. Valores nulos não são permitidos.
	local ret = {}
	for i, page in ipairs(pages) do
		ret[i] = p._formatLink{
			link = page,
			categorizeMissing = options.categorizeMissing,
			italicizePage = options.italicizePage,
			italicizeSection = options.italicizeSection
		}
	end
	return ret
end

return p

[link-1] ↑ ^a ^b ^c ^d ^e ^f ^g do inglês link

[wikilink-2] wikilink

[string-3] ês string

[array-4] ês array

[downstream-5] ês downstream

[a]

[b]

[c]

[d]

[e]