Модуль:Hatnote/doc

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

Этот модуль относится к критическим. У него очень много включений или он используется с подстановкой. Из-за опасности вандализма или ошибочного редактирования он был защищён.

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

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

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

Основные функции содержатся в таблице p, все функции можно вызывать как из других модулей, так и через {{#invoke}}. При вызове из модуля функции принимают первым параметром таблицу с аргументами. Все описанные ниже параметры являются аргументами этой таблицы. Некоторые параметры принимают булевоподобные значения: их перечисление можно найти здесь.

`parse_link`

Принимает на вход ссылку, возвращает два значения: целевую страницу и видимую часть ссылки. Если ссылку не удалось разобрать, возвращает nil. Наличие квадратных скобок не обязательно.

`format_link`

Формирует вики-ссылку. Превращает # в ссылках на разделы в знак параграфа, отбитый пробелами, делая их более читабельными (см. {{ссылка на раздел}}).

Параметры:

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

`remove_precision`

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

`is_disambig`

Функция, определяющая, является ли первый параметр страницей разрешения неоднозначности. Список шаблонов неоднозначностей берется со страницы MediaWiki:Disambiguationspage.

`list`

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

Параметры:

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

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

`hatnote`

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

Параметры:

первый параметр — текст заметки.
|id=: id заметки.
|extraclasses=: дополнительные классы заметки.
|hide_disambig=: при непустом и неложном значении к тексту добавляется класс dabhide, скрывающий подсветку для пользователей гаджета подсветки неоднозначностей.

`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 = 'Википедия:Статьи с шаблоном «См. также» с красными ссылками'
})

Параметры:

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

Функция также принимает все параметры функций list и hatnote и передает их без изменения в эти функции.

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

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

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

`define_categories`

tr.define_categories(tracking_categories)

Создает объект, представляющий собой таблицу с категориями и функцией для их добавления. Первым параметром передается ассоциированный массив с идентификаторами отслеживающих категорий.

`add`

categories:add(type, nocat)

или

categories:add(category_name, nocat)

Добавляет в таблицу категории. Первый параметр — либо идентификатор, объявленный в define_categories(), либо название категории. Второй параметр — отключение категоризации.

`error`

tr.error(msg, categories, preview_only)

Выводит сообщение об ошибке. Если ошибка генерируется шаблоном, то отображается название этого шаблона; если прямым вызовом через {{#invoke}}, то название вызываемого модуля.

Параметры:

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

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

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

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

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