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

<!-- Por favor, adicione categorias onde indicado na parte inferior desta página e as interwikis no Wikidata. -->
<!-- {{Usada em sistema/Testes|em [[:en:MediaWiki:Perfcachedts]]}} (A versão oficial implementada na enwiki.) -->
Este módulo, migrado das origens em [[Módulo:Hatnote]], fornece funcionalidade para formatar ligações{{Nre|nome=link|do inglês ''link''}} para exibição, incluindo a que move a predefinição {{Ligação para predefinição/Testes|Format link}}.

Ele pode formatar ligações{{Nre|nome=link}} 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{{Ill|en||Help:Colon trick|nlk=true}} 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 [[Wikipédia:Ligação vermelha|ligações vermelhas]].

== Uso a partir de texto wiki ==
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:Format link]] para obter a documentação sobre o uso dessa predefinição.

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

<syntaxhighlight lang="lua">
local mFormatLink = require('Módulo:Format link')
</syntaxhighlight>

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

=== _formatLink ===
<syntaxhighlight lang="lua">
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'
}
</syntaxhighlight>

Formata <var>link</var> como uma ligação wiki{{Nre|nome=wikilink|''wikilink''}}. Categorias e arquivos são escapados automaticamente com o truque de dois pontos{{Ill|en||Help:Colon trick|nlk=true}}, e as ligações{{Nre|nome=link}} 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 <var>display</var> estiver presente, ele será usado como um valor de exibição. Qualquer inserção manual da barra vertical (usando a palavra mágica <code><nowiki>{{!}}</nowiki></code> ou similar) presente em <var>link</var> será substituída pelo valor de <var>display</var>, se presente.
* Se o valor <var>target</var> estiver presente, ele substituirá <var>link</var> como um destino, mas o resultado ainda será ''mostrado'' usando o valor de <var>display </var>, ou o resultado da formatação de <var>link</var>.
* Se <var>italicizePage</var> for "''true''", então a parte da página da ligação{{Nre|nome=link}} estará em itálico, se presente.
* Se <var>italicizeSection</var> for "''true''", então a parte da seção da ligação{{Nre|nome=link}} estará em itálico, se presente.
* Se <var>categorizeMissing</var> for uma sequência{{Nre|nome=string|do inglês ''string''}} 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{{Nre|nome=link}} (não importa se através de <var>link</var> ou através de <var>target</var>) não existir.

;Exemplos:
: <syntaxhighlight lang="lua" inline>mFormatLink._formatLink{link = 'Foo#Baz'}</syntaxhighlight> &rarr; <nowiki>[[:Foo#Baz|Foo §&amp;nbsp;Barz]]</nowiki> &rarr; {{Format link|Foo#Baz}}
: <syntaxhighlight lang="lua" inline>mFormatLink._formatLink{link = 'Foo', display = 'Qux'}</syntaxhighlight> &rarr; <nowiki>[[:Foo|Qux]]</nowiki> &rarr; {{Format link|Foo|Qux}}
: <syntaxhighlight lang="lua" inline>mFormatLink._formatLink{link = 'Foo|Baz', display = 'Qux'}</syntaxhighlight> &rarr; <nowiki>[[:Foo|Qux]]</nowiki> &rarr; {{Format link|Foo{{!}}Baz|Qux}}
: <syntaxhighlight lang="lua" inline>mFormatLink._formatLink{link = '#Foo', target = 'Exemplo#Foo'}</syntaxhighlight> &rarr; <nowiki>[[:Exemplo#Foo|§&amp;nbsp;Foo]]</nowiki> &rarr; {{Format link|#Foo||Exemplo#Foo}}
: <syntaxhighlight lang="lua" inline>mFormatLink._formatLink{link = 'O Senhor dos Anéis#Detalhes do enredo', italicizePage = true}</syntaxhighlight> &rarr; <nowiki>[[:O Senhor dos Anéis#Detalhes do enredo|''O Senhor dos Anéis'' §&amp;nbsp;Detalhes do enredo]]</nowiki> &rarr; {{Format link|O Senhor dos Anéis#Detalhes do enredo|italicizepage=true}}
: <syntaxhighlight lang="lua" inline>mFormatLink._formatLink{link = 'en:Cybercrime Prevention Act of 2012#Disini v. Secretary of Justice', italicizeSection = true}</syntaxhighlight> &rarr; <nowiki>[[:en:Cybercrime Prevention Act of 2012#Disini v. Secretary of Justice|Cybercrime Prevention Act of 2012 §&amp;nbsp;''Disini v. Secretary of Justice'']]</nowiki> &rarr; {{Format link|en:Cybercrime Prevention Act of 2012#Disini v. Secretary of Justice|italicizesection=true}}
: <syntaxhighlight lang="lua" inline>mFormatLink._formatLink{link = 'Página inexistente', categorizeMissing = 'Exemplo'}</syntaxhighlight> &rarr; <nowiki>[[:Página inexistente]][[Categoria:Exemplo]]</nowiki> &rarr; {{Format link|Página inexistente}}
: <syntaxhighlight lang="lua" inline>mFormatLink._formatLink{link = 'Existência', categorizeMissing = 'Exemplo'}</syntaxhighlight> &rarr; <nowiki>[[:Existência]]</nowiki> &rarr; {{Format link|Existência}}

=== formatPages ===
<syntaxhighlight lang="lua">
mFormatLink.formatPages(options, pages)
</syntaxhighlight>

Essa função derivada é útil para listas que formatam muitas ligações{{Nre|nome=link}}. Ela formata um arranjo{{Nre|nome=array|do inglês ''array''}} de páginas usando a função [[#_formatLink|_formatLink]] e retorna o resultado como um arranjo{{Nre|nome=array}}. As opções na tabela <var>options</var> são aplicadas e usam os mesmos nomes que as opções para <var>_formatLink</var>.

;Exemplo
:{{Código|<nowiki>mFormatLink.formatPages({categorizeMissing = 'Exemplo'}, {'Foo#Baz', 'Página inexistente'})</nowiki>|lua}} &rarr; {{Código|<nowiki>{'[[:Foo#Baz|Foo §&nbsp;Baz]]', '[[:Página inexistente]][[Categoria:Exemplo]]'}</nowiki>|lua}}

== Erros ==

Se <var>_formatLink</var> for usada e nenhum argumento <var>link</var> nem <var>target</var> 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 <var>_formatLink</var> 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{{Nre|nome=downstream|do inglês ''downstream''}}) quando, de outra forma, chamaria <var>_formatLink</var > com argumentos inadequados.

== Notas ==
{{Reflist|group=lower-alpha}}

<includeonly>{{Testes outro/Testes||
<!-- Por favor, as categorias abaixo desta linha e as interwikis na Wikidata. -->

}}</includeonly><noinclude>
[[en:Module:Format link/doc]]
</noinclude>