Модуль:Сьпіс верхніх зносак

Дакумэнтацыю да гэтага модуля можна стварыць у Модуль:Сьпіс верхніх зносак/Дакумэнтацыя

--------------------------------------------------------------------------------
--                       Модуль:Сьпіс верхніх зносак                          --
--                                                                            --
-- Гэты модуль стварае і фарматуе сьпісы для верхніх зносак. У прыватнасьці,  --
-- ён прыдатны для выкарыстаньня ў такіх шаблёнах, як {{Пра}},                --
-- {{Перанакіроўваецца сюды}} і падобных.                                     --
--------------------------------------------------------------------------------

local mArguments --лянівая ініцыялізацыя
local mHatnote = require('Модуль:Іншае значэньне')
local libraryUtil = require('libraryUtil')
local checkType = libraryUtil.checkType
local p = {}

--------------------------------------------------------------------------------
-- Дапаможныя функцыі па стварэньні тэксту сьпісаў
--------------------------------------------------------------------------------

--табліца дапомных значэньняў, якія прымяняюцца ў дапаможных функцыях
local stringifyListDefaultOptions = {
	conjunction = "і",
	separator = ",",
	altSeparator = ";",
	space = " ",
	formatted = false
}

-- Проста ўтварае радок сьпісу; не павінна выклікацца непасрэдна
function stringifyList(list, options)
	-- Праверкі тыпаў, дапомных значэньняў, скаротаў
	checkType("stringifyList", 1, list, "table")
	if #list == 0 then return nil end
	checkType("stringifyList", 2, options, "table", true)
	options = options or {}
	for k, v in pairs(stringifyListDefaultOptions) do
		if options[k] == nil then options[k] = v end
	end
	local s = options.space
	-- Калі патрэбна, адфарматаваць сьпіс
	if options.formatted then list = mHatnote.formatPages(unpack(list)) end
	-- Задаць разьдзяляльнік; калі ён сустракаецца ў якім-небудзь элемэнце, то ўзяць іншы разьдзяляльнік
	local separator = options.separator
	--шукае толькі тэкст вываду
	local function searchDisp(t, f)
		return string.find(string.sub(t, (string.find(t, '|') or 0) + 1), f)
	end
	for k, v in pairs(list) do
		if searchDisp(v, separator) then
			separator = options.altSeparator
			break
		end
	end
	-- Задаць каньюнкцыю, ужыць оксфардзкую коску, мусова ўжыць коску, калі #1 мае "§"
	local conjunction = s .. options.conjunction .. s
	if #list == 2 and searchDisp(list[1], "§") or #list > 2 then
		conjunction = separator .. conjunction
	end
	-- Вярнуць фарматаваны радок
	return mw.text.listToText(list, separator .. s, conjunction)
end

--DRY function
function conjList (conj, list, fmt)
	return stringifyList(list, {conjunction = conj, formatted = fmt})
end

-- Утварае радок сьпісу зь "і" ці "або"
function p.andList (...) return conjList("і", ...) end
function p.orList (...) return conjList("або", ...) end

--------------------------------------------------------------------------------
-- Пра … глядзіце
--
-- Стварае сьпіс "Пра X, глядзіце [[Y]]." з парамэтраў. Прызначаная для
-- шаблёнаў {{Пра}}, {{Перанакіроўваецца сюды}} ды ім падобных.
--------------------------------------------------------------------------------

--табліца дапомных значэньняў, якія прымяняюцца ў групе функцый „Пра … глядзіце“
local forSeeDefaultOptions = {
	andKeyword = 'і',
	title = mw.title.getCurrentTitle().text,
	otherText = 'іншыя значэньні',
	forSeeForm = 'Пра %s глядзіце %s.',
}

--Зьлівае падвойныя знакі прыпынку
function punctuationCollapse (text)
	local replacements = {
		["%.%.$"] = ".",
		["%?%.$"] = "?",
		["%!%.$"] = "!",
		["%.%]%]%.$"] = ".]]",
		["%?%]%]%.$"] = "?]]",
		["%!%]%]%.$"] = "!]]"
	}
	for k, v in pairs(replacements) do text = string.gsub(text, k, v) end
	return text
end

-- Структуруе аргумэнты ў табліцу для будучага радку, & парамэтры
function p.forSeeArgsToTable (args, from, options)
	-- Праверкі тыпаў і дапомныя значэньні
	checkType("forSeeArgsToTable", 1, args, 'table')
	checkType("forSeeArgsToTable", 2, from, 'number', true)
	from = from or 1
	checkType("forSeeArgsToTable", 3, options, 'table', true)
	options = options or {}
	for k, v in pairs(forSeeDefaultOptions) do
		if options[k] == nil then options[k] = v end
	end
	-- maxArg атрымліваецца ўручную, бо getArgs() і table.maxn не сябруюць
	local maxArg = 0
	for k, v in pairs(args) do
		if type(k) == 'number' and k > maxArg then maxArg = k end
	end
	-- Structure the data out from the parameter list:
	-- * forTable is the wrapper table, with forRow rows
	-- * Rows are tables of a "use" string & a "pages" table of pagename strings
	-- * Blanks are left empty for defaulting elsewhere, but can terminate list
	local forTable = {}
	local i = from
	local terminated = false
	-- If there is extra text, and no arguments are given, give nil value
	-- to not produce default of "For other uses, see foo (disambiguation)"
	if options.extratext and i > maxArg then return nil end
	-- Loop to generate rows
	repeat
		-- New empty row
		local forRow = {}
		-- On blank use, assume list's ended & break at end of this loop
		forRow.use = args[i]
		if not args[i] then terminated = true end
		-- New empty list of pages
		forRow.pages = {}
		-- Insert first pages item if present
		table.insert(forRow.pages, args[i + 1])
		-- If the param after next is "and", do inner loop to collect params
		-- until the "and"'s stop. Blanks are ignored: "1|and||and|3" → {1, 3}
		while args[i + 2] == options.andKeyword do
			if args[i + 3] then 
				table.insert(forRow.pages, args[i + 3])
			end
			-- Increment to next "and"
			i = i + 2
		end
		-- Increment to next use
		i = i + 2
		-- Append the row
		table.insert(forTable, forRow)
	until terminated or i > maxArg
	
	return forTable
end

-- Stringifies a table as formatted by forSeeArgsToTable
function p.forSeeTableToString (forSeeTable, options)
	-- Type-checks and defaults
	checkType("forSeeTableToString", 1, forSeeTable, "table", true)
	checkType("forSeeTableToString", 2, options, "table", true)
	options = options or {}
	for k, v in pairs(forSeeDefaultOptions) do
		if options[k] == nil then options[k] = v end
	end
	-- Stringify each for-see item into a list
	local strList = {}
	if forSeeTable then
		for k, v in pairs(forSeeTable) do
			local useStr = v.use or options.otherText
			local pagesStr = p.andList(v.pages, true) or mHatnote._formatLink{link = mHatnote.disambiguate(options.title)}
			local forSeeStr = string.format(options.forSeeForm, useStr, pagesStr)
			forSeeStr = punctuationCollapse(forSeeStr)
			table.insert(strList, forSeeStr)
		end
	end
	if options.extratext then table.insert(strList, punctuationCollapse(options.extratext..'.')) end
	-- Return the concatenated list
	return table.concat(strList, ' ')
end

-- Produces a "For X, see [[Y]]" string from arguments. Expects index gaps
-- but not blank/whitespace values. Ignores named args and args < "from".
function p._forSee (args, from, options)
	local forSeeTable = p.forSeeArgsToTable(args, from, options)
	return p.forSeeTableToString(forSeeTable, options)
end

-- As _forSee, but uses the frame.
function p.forSee (frame, from, options)
	mArguments = require('Модуль:Аргумэнты')
	return p._forSee(mArguments.getArgs(frame), from, options)
end

return p