Модуль:Hatnote/doc

Это страница документации Модуль:Hatnote.

Прежде чем вносить какие-либо изменения в этот модуль, просьба оттестировать их в /песочнице и проверить результат на странице с /контрольными примерами.

Модуль предназначен для реализации hatnote-шаблонов (например, {{основная статья}}, {{см. также}}). Также он содержит несколько функций для работы со ссылками и отслеживания ошибок. См. тесты на странице Шаблон:Основная статья/тесты.

Основные функции

Основные функции содержатся в таблице <syntaxhighlight lang="text" class="" id="" style="" inline="1">p</syntaxhighlight>, все функции можно вызывать как из других модулей, так и через {{#invoke}}. При вызове из модуля функции принимают первым параметром таблицу с аргументами. Все описанные ниже параметры являются аргументами этой таблицы. Некоторые параметры принимают булевоподобные значения: их перечисление можно найти здесь.

`parse_link`

Принимает на вход ссылку, возвращает два значения: целевую страницу и видимую часть ссылки. Если ссылку не удалось разобрать, возвращает <syntaxhighlight lang="text" class="" id="" style="" inline="1">nil</syntaxhighlight>. Наличие квадратных скобок не обязательно.

`format_link`

Формирует вики-ссылку. Превращает <syntaxhighlight lang="text" class="" id="" style="" inline="1">#</syntaxhighlight> в ссылках на разделы в знак параграфа, отбитый пробелами, делая их более читабельными (см. {{ссылка на раздел}}).

Параметры:

первый параметр: название целевой страницы или вики-ссылка.
второй параметр: название раздела. Параметр будет проигнорирован, если раздел уже задан в первом параметре через <syntaxhighlight lang="text" class="" id="" style="" inline="1">#</syntaxhighlight>.
третий параметр: видимый текст ссылки.

`remove_precision`

Убирает уточнение из первого параметра (см. {{без уточнения}}).

`is_disambig`

Функция, определяющая, является ли первый параметр страницей разрешения неоднозначности. Выводит true, когда страница находится в категории «Страницы значений по алфавиту».

`list`

Формирует список из вики-ссылок.

Параметры:

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

Возвращает таблицу, для неё предусмотрен метод <syntaxhighlight lang="text" class="" id="" style="" inline="1">tostring()</syntaxhighlight> и конкатенация. Именованные параметры этой таблицы — булевы переменные, истинные при обнаружении проблем. Отслеживаемые проблемы: <syntaxhighlight lang="text" class="" id="" style="" inline="1">red_link</syntaxhighlight>, <syntaxhighlight lang="text" class="" id="" style="" inline="1">bad_format</syntaxhighlight>, <syntaxhighlight lang="text" class="" id="" style="" inline="1">formatted</syntaxhighlight>, <syntaxhighlight lang="text" class="" id="" style="" inline="1">unparsable_link</syntaxhighlight>. Их описание см. ниже.

`hatnote`

Формирует код <div class="hatnote">...</div>.

Параметры:

первый параметр — текст заметки.
|id =: id заметки.
|extraclasses =: дополнительные классы заметки.
|hide_disambig =: при непустом и неложном значении к тексту добавляется класс <syntaxhighlight lang="text" class="" id="" style="" inline="1">dabhide</syntaxhighlight>, скрывающий подсветку для пользователей гаджета подсветки неоднозначностей.

`main`

Генерирует текст-заметку. Позволяет ссылаться на неограниченное число страниц. Синтаксис:

вызов из вики-текста:

{{#invoke:Hatnote|main|префикс= префикс |префикс мн. ч.= префикс для нескольких ссылок |разделитель списка= разделитель списка |ПИ ссылок= пространство имен  |extraclasses = дополнительные классы |точка= true / false |hide_disambig= true / false}}

вызов из другого модуля:

-- подключение модуля 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>

Параметры:

|prefix = или |префикс =: обязательный параметр, текст перед списком ссылок.
|prefix_plural = или |префикс мн. ч. =: если ссылок несколько, для префикса вместо предыдущего параметра будет использован этот.
|sep = или |разделитель =: разделитель между префиксом и списком ссылок.
|dot = или |точка =: при непустом и неложном значении выводится точка в конце.
|nocat =: при непустом и неложном значении отключается категоризация.
|empty_list_message =: сообщение об ошибке, выводящееся при пустом списке ссылок. По умолчанию — «Не указано ни одной страницы».
|preview_error =: при непустом и неложном значении ошибка при пустом списке ссылок выводится только во время предпросмотра.

Функция также принимает все параметры функций <syntaxhighlight lang="text" class="" id="" style="" inline="1">list</syntaxhighlight> и <syntaxhighlight lang="text" class="" id="" style="" inline="1">hatnote</syntaxhighlight> и передает их без изменения в эти функции.

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

Служебные функции

Находятся в таблице <syntaxhighlight lang="text" class="" id="" style="" inline="1">tr</syntaxhighlight>, предназначены для отслеживания проблем и вывода сообщений об ошибках. Все функции можно вызывать только из других модулей.

`define_categories`

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

`add`

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

`error`

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

Параметры:

<syntaxhighlight lang="text" class="" id="" style="" inline="1">msg</syntaxhighlight>: текст сообщения.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">categories</syntaxhighlight>: либо объект, возвращаемый <syntaxhighlight lang="text" class="" id="" style="" inline="1">define_categories()</syntaxhighlight>, либо строка с категориями.
<syntaxhighlight lang="text" class="" id="" style="" inline="1">preview_only</syntaxhighlight>: при непустом и неложном значении ошибка выводится только во время предпросмотра.

Отслеживаемые случаи

<syntaxhighlight lang="text" class="" id="" style="" inline="1">no_prefix</syntaxhighlight> — не задан префикс. Также выводится сообщение об ошибке.
Категория: Википедия:Страницы с модулем Hatnote без указания префикса
<syntaxhighlight lang="text" class="" id="" style="" inline="1">no_links</syntaxhighlight> — не задано ни одной ссылки. Также выводится сообщение об ошибке (либо в тексте статьи, либо только во время предварительного просмотра, подробнее см. #main-Параметры).
Категория: Википедия:Страницы с модулем Hatnote без ссылок
<syntaxhighlight lang="text" class="" id="" style="" inline="1">red_link</syntaxhighlight> — параметр содержит ссылку на несуществующую статью.
Категория: Википедия:Страницы с модулем Hatnote с красной ссылкой
<syntaxhighlight lang="text" class="" id="" style="" inline="1">bad_format</syntaxhighlight> — параметр содержит разделитель {{!}} вместо параметра |lx = или лишние квадратные скобки.
Категория: Википедия:Страницы с модулем Hatnote с некорректно заполненными параметрами
<syntaxhighlight lang="text" class="" id="" style="" inline="1">formatted</syntaxhighlight> — параметр содержит <syntaxhighlight lang="text" class="" id="" style="" inline="1"><span</syntaxhighlight> (в таком случае он не парсится, а выдаётся в готовом виде). Нужно для поддержки шаблонов {{не переведено}} в качестве параметров.
Категория: Википедия:Страницы с модулем Hatnote с готовым форматированием
<syntaxhighlight lang="text" class="" id="" style="" inline="1">unparsable_link</syntaxhighlight> — параметр содержит нестандартное оформление, которое не может быть разобрано модулем (например, {{см. также|[https://example.com внешние ссылки]}} или {{см. также|посторонний текст помимо [[ссылка|ссылки]]}}).
Категория: Википедия:Страницы с модулем Hatnote с нечитаемой ссылкой

Использование в других модулях

Некоторые функции используются в следующих модулях (Шаблон:Plain link):