Редактирование: Модуль:Hatnote/doc

{{Docpage}}{{Рейтинг модуля|protected}}
{{Используйте песочницу|testcases-other=Шаблон:Основная статья/тесты}}
Модуль предназначен для реализации hatnote-шаблонов (например, {{T|Основная статья}}, {{T|См. также}}). Также он содержит несколько функций для работы со ссылками и отслеживания ошибок. См. тесты на странице [[Шаблон:Основная статья/тесты]].

== Основные функции ==
Основные функции содержатся в таблице {{Code|P}}, все функции можно вызывать как из других модулей, так и через {{Mwmw|invoke}}. При вызове из модуля функции принимают первым параметром таблицу с аргументами. Все описанные ниже параметры являются аргументами этой таблицы. Некоторые параметры принимают булевоподобные значения: их перечисление можно найти [[Модуль:Yesno|здесь]].

=== <code>parse_link</code> ===
Принимает на вход ссылку, возвращает два значения: целевую страницу и видимую часть ссылки. Если ссылку не удалось разобрать, возвращает {{Code|Nil}}. Наличие квадратных скобок не обязательно.

=== <code>format_link</code> ===
Формирует вики-ссылку. Превращает {{Code|#}} в ссылках на разделы в знак параграфа, отбитый пробелами, делая их более читабельными (см. {{T|Ссылка на раздел}}). 

Параметры:
* первый параметр: название целевой страницы или вики-ссылка.
* второй параметр: название раздела. Параметр будет проигнорирован, если раздел уже задан в первом параметре через {{Code|#}}.
* третий параметр: видимый текст ссылки.

=== <code>remove_precision</code> ===
Убирает уточнение из первого параметра (см. {{T|Без уточнения}}).

=== <code>is_disambig</code> ===
Функция, определяющая, является ли первый параметр [[РуСказки:Неоднозначность|страницей разрешения неоднозначности]]. Список шаблонов неоднозначностей берется со страницы [[MediaWiki:Disambiguationspage]].

=== <code>list</code> ===
Формирует список из вики-ссылок.

Параметры:
* нумерованные параметры — ссылки на страницы.
* {{Para|l1}}, {{Para|l2}} и т. д. — текст ссылок.
* {{Para|list_sep}} или {{Para|разделитель списка}}: разделитель списка, по умолчанию — {{No wikify|«, »}}.
* {{Para|natural_join}}: при неложном значении вместо последнего разделителя выводится союз «и».
* {{Para|links_ns}} или {{Para|ПИ ссылок}}: ко всем ссылкам добавляется префикс указанного пространства имен.
* {{Para|bold_links}} или {{Para|ссылки болдом}}: при непустом и неложном значении каждая ссылка выделяется полужирным.

Возвращает таблицу, для неё предусмотрен метод {{Code|tostring()}} и конкатенация. Именованные параметры этой таблицы — булевы переменные, истинные при обнаружении проблем. Отслеживаемые проблемы: {{Code|red_link}}, {{Code|bad_format}}, {{Code|formatted}}, {{Code|unparsable_link}}. Их описание [[#Отслеживаемые случаи|см. ниже]].

=== <code>hatnote</code> ===
Формирует код {{Tag|div|params=class="hatnote"|content=...}}.

Параметры:
* первый параметр — текст заметки.
* {{Para|id}}: id заметки.
* {{Para|extraclasses}}: дополнительные классы заметки.
* {{Para|hide_disambig}}: при непустом и неложном значении к тексту добавляется класс {{Code|dabhide}}, скрывающий подсветку для пользователей [[Википедия:Гаджеты/Выделение неоднозначностей|гаджета подсветки неоднозначностей]].

=== <code>main</code> ===
Генерирует текст-заметку. Позволяет ссылаться на неограниченное число страниц.
Синтаксис:
* вызов из вики-текста:
: {{Tpre|#invoke:Hatnote|main|префикс{{=}} ''префикс''{{Optp|префикс мн. ч.{{=}} ''префикс для нескольких ссылок''|разделитель списка{{=}} ''разделитель списка''|ПИ ссылок{{=}} ''пространство имен'' |extraclasses {{=}} ''дополнительные классы''|точка{{=}} ''true{{\}}false''|hide_disambig{{=}} ''true{{\}}false''|_spaced=yes}}}}
* вызов из другого модуля:
: <source lang="lua">
-- подключение модуля
local hatnote = require('Модуль:Hatnote').main

-- пример использования без изменения категорий по умолчанию
local res1 = hatnote{
    'Какая-то статья',
    l1 = 'Какой-нибудь текст ссылки',
    prefix = 'Основная статья:',
    prefix_plural = 'Основные статьи:',
    dot = true,
    nocat = args.nocat -- следует всегда передавать nocat, если он предусмотрен
}

-- и с изменением
local res2 = hatnote({
    'Еще какая-то статья',
    prefix = 'См. также:',
    list_sep = '; ',
    natural_join = false,
    nocat = args.nocat
}, {
    red_link = 'Википедия:Статьи с шаблоном «См. также» с красными ссылками'
})
</source>

{{Видимый якорь|Параметры:|main-Параметры}}
* {{Para|prefix}} или {{Para|префикс}}: обязательный параметр, текст перед списком ссылок.
* {{Para|prefix_plural}} или {{Para|префикс мн. ч.}}: если ссылок несколько, для префикса вместо предыдущего параметра будет использован этот.
* {{Para|sep}} или {{Para|разделитель}}: разделитель между префиксом и списком ссылок.
* {{Para|dot}} или {{Para|точка}}: при непустом и неложном значении выводится точка в конце.
* {{Para|nocat}}: при непустом и неложном значении отключается категоризация.
* {{Para|empty_list_message}}: сообщение об ошибке, выводящееся при пустом списке ссылок. По умолчанию — «Не указано ни одной страницы».
* {{Para|preview_error}}: при непустом и неложном значении ошибка при пустом списке ссылок выводится только во время предпросмотра.
Функция также принимает все параметры функций {{Code|list}} и {{Code|hatnote}} и передает их без изменения в эти функции.

Вторым параметром (при вызове через другой модуль) функция принимает таблицу с переназначенными категориями. Их идентификаторы [[#Отслеживаемые случаи|см. ниже]]:

== Служебные функции ==
Находятся в таблице {{Code|tr}}, предназначены для отслеживания проблем и вывода сообщений об ошибках. Все функции можно вызывать только из других модулей.

=== <code>define_categories</code> ===
<source lang="lua">tr.define_categories(tracking_categories)</source>
Создает объект, представляющий собой таблицу с категориями и функцией для их добавления. Первым параметром передается ассоциированный массив с идентификаторами отслеживающих категорий.

==== <code>add</code> ====
<source lang="lua">categories:add(type, nocat)</source>
или
<source lang="lua">categories:add(category_name, nocat)</source>
Добавляет в таблицу категории. Первый параметр — либо идентификатор, объявленный в {{Code|define_categories()}}, либо название категории. Второй параметр — отключение категоризации.

=== <code>error</code> ===
<source lang="lua">tr.error(msg, categories, preview_only)</source>
Выводит сообщение об ошибке. Если ошибка генерируется шаблоном, то отображается название этого шаблона; если прямым вызовом через {{Mwmw|invoke}}, то название вызываемого модуля.

Параметры:
* {{Code|msg}}: текст сообщения.
* {{Code|categories}}: либо [[#define_categories|объект]], возвращаемый {{Code|define_categories()}}, либо строка с категориями.
* {{Code|preview_only}}: при непустом и неложном значении ошибка выводится только во время предпросмотра.

== Отслеживаемые случаи ==
* {{Code|no_prefix}} — не задан префикс. Также выводится сообщение об ошибке.
*: Категория: {{Cl|РуСказки:Страницы с модулем Hatnote без указания префикса}}
* {{Code|no_links}} — не задано ни одной ссылки. Также выводится сообщение об ошибке (либо в тексте статьи, либо только во время предварительного просмотра, подробнее см. [[#main-Параметры]]).
*: Категория: {{Cl|РуСказки:Страницы с модулем Hatnote без ссылок}}
* {{Code|red_link}} — параметр содержит ссылку на несуществующую статью.
*: Категория: {{Cl|РуСказки:Страницы с модулем Hatnote с красной ссылкой}}
* {{Code|bad_format}} — параметр содержит разделитель {{Tc|!}} вместо параметра {{Para|l''x''}} или лишние квадратные скобки.
*: Категория: {{Cl|РуСказки:Страницы с модулем Hatnote с некорректно заполненными параметрами}}
* {{Code|formatted}} — параметр содержит {{Code|<nowiki><span</nowiki>}} (в таком случае он не парсится, а выдаётся в готовом виде). Нужно для поддержки шаблонов {{T|Не переведено}} в качестве параметров.
*: Категория: {{Cl|РуСказки:Страницы с модулем Hatnote с готовым форматированием}}
* {{Code|unparsable_link}} — параметр содержит нестандартное оформление, которое не может быть разобрано модулем (например, {{Tc|см. также|<nowiki>[https://example.com внешние ссылки]</nowiki>}} или {{Tc|См. также|<nowiki>посторонний текст помимо [[ссылка|ссылки]]</nowiki>}}).
*: Категория: {{Cl|РуСказки:Страницы с модулем Hatnote с нечитаемой ссылкой}}

== Использование в других модулях ==
Некоторые функции используются в следующих модулях ({{Plain link|url= https://ru.wikipedia.org/w/index.php?search=insource%3A%2Frequire+%2A%5C%28%3F+%2A%5B%27%22%5D+%2A%28%5BMm%5Dodule%7C%5B%D0%9C%D0%BC%5D%D0%BE%D0%B4%D1%83%D0%BB%D1%8C%29+%2A%3A+%2A%5BHh%5Datnote+%2A%5B%27%22%5D%2F&title=%D0%A1%D0%BB%D1%83%D0%B6%D0%B5%D0%B1%D0%BD%D0%B0%D1%8F:%D0%9F%D0%BE%D0%B8%D1%81%D0%BA&profile=advanced&fulltext=1&ns828=1|name= проверить}}):
* [[Модуль:ФИО]]
* [[Модуль:Другие значения]]
* [[Модуль:Основная статья]]