Модуль:Tools/doc: различия между версиями

Материал из Кадровый состав НКВД 1935-1939
Перейти к навигации Перейти к поиску
Нет описания правки
Нет описания правки
 
Строка 80: Строка 80:
Формирует текст для выходного потока.
Формирует текст для выходного потока.


При наличии сносок или источников обращается к модулю {{tl|Module:RefTools}}.
При наличии сносок или источников обращается к модулю {{tl|Module:RefTools}}, при наличии источников — к функции <code>link</code> модуля {{tl|Модуль:Сайт}} (через tools.formatIfUrl, см. ниже).


== fotmatIfUrl ==
== formatIfUrl ==
Преобразование параметра в красивую ссылку, если он представляет собой URL
Преобразование параметра в красивую ссылку, если он представляет собой URL
: <code>text, noURL = tools.formatIfUrl( whatwherefrom, txt )</code>
: <code>text, noURL = tools.formatIfUrl( whatwherefrom, txt )</code>
* <code>whatwherefrom</code> — формат ссылки (<code>'what'</code> — сайт, <code>'where'</code> — на сайте, <code>'from'</code> — ???)  
* <code>whatwherefrom</code> — формат ссылки (<code>'what'</code> — сайт, <code>'where'</code> — на сайте, <code>'from'</code> — ???)
* <code>txt</code> — обрабатываемый параметр
* <code>txt</code> — обрабатываемый параметр


Возвращает параметр (если это был URL, то преобразованный) и true в качестве второго результата, если преобразования не было.
Возвращает параметр (если это был URL, то преобразованный) и true в качестве второго результата, если преобразования не было.
Для преобразования вызывается функция <code>link</code> модуля {{tl|Модуль:Сайт}}.
== segment ==
Формирование ссылки на страницу места службы.
: <code>text = tools.segment( segmentName )</code>
* <code>segmentName</code> — наименование места службы
Функция возвращает ссылку в формате «[url segmentName]».
== name ==
Добавление подкраски для индекса тезки в имени персоналии
: <code>text = tools.name( name, idx )</code>
* <code>name</code> — имя персоналии
* <code>idx</code> — индекс тезки (если он не задан в первом параметре) или nil.
Функция возвращает текстовое представление имени с обрамлением индекса тезки тегом <code>&lt;span&gt;</code>.
== splitName ==
Разбор имени, использованного для указания персоналии (на страницах документов и т. п.).
: <code>last, first, middle, idx, warning, normalized = tools.splitName( name, redlink )</code>
* <code>name</code> — имя персоналии
* <code>redlink</code> — разбор выполняется для страницы несуществующего персонажа или страницы разрешения неоднозначности.
Возвращает разобранное по элементам (фамилия, имя, отчество, индекс тезки) имя.
Для многословных элементов: граница фамилии определяется по запятой, а имя всегда считается однословным.
Сведения об обнаруженных при разборе ошибках помещаются в массив текстовых строк <code>warning</code> (отсутствие ошибок — пустой массив).
Последний элемент <code>normalized</code>, возвращаемый функцией, содержит имя, записанное в эталонной форме (инициалы с точками и проч.) без индекса тезки.
Используется модулями {{tl| Персона }}, {{tl| Упоминание }}, {{tl| Новый персонаж }}.
== cargoString ==
Формирует условие для sql-запроса в зависимости от того, является ли значение пустым (IS NULL) или нет (= x).
: <code>text = tools.cargoString( value )</code>
* <code>value</code> — имя персоналии
Поскольку [[mw:Extension:Cargo|Cargo]] всегда сохраняет пустые строки как NULL, функция формирует условие в зависимости от значения либо в виде <code>= 'value'</code>, либо  <code>IS NULL</code>.
== podvigLink ==
Расшифровка параметра шаблона «подвиг» (сведений с сайта ОБД МО «Подвиг народа»).
: <code>text = tools.podvigLink( str, imagesBase )</code>
* <code>str</code> — значение параметра «подвиг» (см. описание шаблона {{tl |  Персона }})
* <code>imageBase</code> — признак использования нестандартного URL для изображений (используется в шаблоне {{tl |  Представление }})
Функция возвращает текстовую строку для включения в выходной текст. Раньше вторым параметром возвращался признак того, что ссылка на сайт ОБД МО указывает не на страницу награждения, а на страницу картотеки (теперь его всегда нет!)

Текущая версия от 00:27, 29 января 2018

Набор вспомогательных функций для других модулей.

errorMsg

Форматирование сообщения об ошибке вызова шаблона.

text = errorMsg( tpt, errorTxt, errorAdvice )
  • tpt — имя шаблона (без префикса «Шаблон:»)
  • errorTxt — диагностика
  • errorAdvice — дополнительные сведения об ошибке («Используйте формат обращения ...»)

Функция возвращает строку, содержащее отформатированное сообщение и задание категории «Страницы с ошибкой вызова шаблона ...».

checkargs

Проверка и нормализация аргументов

modArgs, hasArg = tools.checkargs( args, names )
  • args — таблица аргументов
  • names — описание допустимых аргументов в формате: ключ_допустимого аргумента = значение_по_умолчанию

Если значение_по_умолчанию равно true, то это означает, что соответствующий аргумент не имеет значения по умолчанию. В противном случае аргументы, ключи которых отсутствуют в исходной таблице args или имеют значение пустой строки, получают указанное значение_по_умолчанию.

При успешной проверке (в исходной таблице args нет элементов с ключами, отсутствующими в names) функция возвращает таблицу modArgs со всеми элементами (включая добавленные значения по умолчанию) и признак наличия элементов в исходной таблице аргументов. Последнее полезно, чтобы предупреждать ошибки, связанные с тем, что движок MediaWiki в ходе обработки страницы не интерпретирует повторно шаблоны без параметров; для повторного парсинга необходимо наличие у шаблона хотя бы пустого параметра.

При обнаружении в исходной таблице args первого же ключа отсутствующего в names, функция возвращает пару значений nil, лишний_ключ.

При возвращении значений (кроме значений по умолчанию) осуществляется нормализация: пробельные символы в начале и конце значения убираются, пустые значения превращаются в nil.

parseDate

Преобразование текстовой даты в стандартный внутренний формат

fdate, year, month, day = tools.parseDate( indate, border )
  • indate — дата в произвольном пользовательском формате
  • border — минимальный год (XIX века!) для дат, в которых год задан двумя цифрами

Возвращает fdate в формате гггг-мм-чч и числовые значения года, месяца и дня. Для неполных дат (год или месяц+год) текстовая строка укорочена, а вместо соответствующих числовых значений возвращается nil. При пустой дате на входе возвращает пустую строку. При ошибке возвращает nil.

reparseDate

Преобразование даты в стандартном внутреннем формате гггг-мм-чч в стандартный печатный формат (чч.мм.гггг)

text = tools.reparseDate( value )
  • value — дата в стандартном внутреннем формате

Обрабатывает в том числе и неполные даты (укороченные строки). При пустой дате отдает прочерк («—»).

textDate

Преобразование даты в стандартном внутреннем формате гггг-мм-чч в текстовый формат (с месяцем прописью).

text = tools.textDate( value, p )
  • value — дата в стандартном внутреннем формате
  • p — падеж ('i' — именительный (по умолчанию), 'g' — родительный)

Возвращает текст с месяцем прописью и словом «год» в конце. Падеж значим для неполных дат. При пустой дате отдает прочерк («—»).

phrase

Преобразование текста в предложение

mText = tools.phrase( text )

Преобразование текста в предложение (первая буква делается прописной, в конце добавляется точка.

noPhrase

Преобразование текста для использования внутри предложения

mText = tools.noPhrase( text )

Преобразование текста в не-предложение (первая буква делается строчной, завершающая точка, если она есть, упраздняется).

db

Криворуко сделанный (не через метатаблицу) доступ к данным

result = tools.db( base, elem, field )

Функция возвращает элемент (запись) таблицы db с ключом elem, а если задано имя поля field — соответствующее поле этой записи. Если запись содержит поле redirect, то происходит переадресация на элемент с указанным в поле redirect ключом.

commonParams

Обработка универсальных параметров шаблонов страниц персоналий

text = tools.commonParams( addendum, reference, source )
  • addendum — дополнение
  • reference — сноска
  • source — ссылка на первоисточник

Формирует текст для выходного потока.

При наличии сносок или источников обращается к модулю {{Lua-logo-nolabel.svg RefTools}} , при наличии источников — к функции link модуля {{Lua-logo-nolabel.svg Сайт}}  (через tools.formatIfUrl, см. ниже).

formatIfUrl

Преобразование параметра в красивую ссылку, если он представляет собой URL

text, noURL = tools.formatIfUrl( whatwherefrom, txt )
  • whatwherefrom — формат ссылки ('what' — сайт, 'where' — на сайте, 'from' — ???)
  • txt — обрабатываемый параметр

Возвращает параметр (если это был URL, то преобразованный) и true в качестве второго результата, если преобразования не было. Для преобразования вызывается функция link модуля {{Lua-logo-nolabel.svg Сайт}} .

segment

Формирование ссылки на страницу места службы.

text = tools.segment( segmentName )
  • segmentName — наименование места службы

Функция возвращает ссылку в формате «[url segmentName]».

name

Добавление подкраски для индекса тезки в имени персоналии

text = tools.name( name, idx )
  • name — имя персоналии
  • idx — индекс тезки (если он не задан в первом параметре) или nil.

Функция возвращает текстовое представление имени с обрамлением индекса тезки тегом <span>.

splitName

Разбор имени, использованного для указания персоналии (на страницах документов и т. п.).

last, first, middle, idx, warning, normalized = tools.splitName( name, redlink )
  • name — имя персоналии
  • redlink — разбор выполняется для страницы несуществующего персонажа или страницы разрешения неоднозначности.

Возвращает разобранное по элементам (фамилия, имя, отчество, индекс тезки) имя. Для многословных элементов: граница фамилии определяется по запятой, а имя всегда считается однословным. Сведения об обнаруженных при разборе ошибках помещаются в массив текстовых строк warning (отсутствие ошибок — пустой массив). Последний элемент normalized, возвращаемый функцией, содержит имя, записанное в эталонной форме (инициалы с точками и проч.) без индекса тезки.

Используется модулями {{ Персона }} , {{ Упоминание }} , {{ Новый персонаж }} .

cargoString

Формирует условие для sql-запроса в зависимости от того, является ли значение пустым (IS NULL) или нет (= x).

text = tools.cargoString( value )
  • value — имя персоналии

Поскольку Cargo всегда сохраняет пустые строки как NULL, функция формирует условие в зависимости от значения либо в виде = 'value', либо IS NULL.

podvigLink

Расшифровка параметра шаблона «подвиг» (сведений с сайта ОБД МО «Подвиг народа»).

text = tools.podvigLink( str, imagesBase )
  • str — значение параметра «подвиг» (см. описание шаблона {{ Персона }} )
  • imageBase — признак использования нестандартного URL для изображений (используется в шаблоне {{ Представление }} )

Функция возвращает текстовую строку для включения в выходной текст. Раньше вторым параметром возвращался признак того, что ссылка на сайт ОБД МО указывает не на страницу награждения, а на страницу картотеки (теперь его всегда нет!)