پودمان:Format link

توضیحات پودمان[نمایش] [ویرایش] [تاریخچه] [پاکسازی]

این پودمان، که از پودمان ریشه‌ای خود پودمان:Hatnote تفکیک شده‌است، توابعی را برای قالب‌بندی پیوندها برای نمایش ارائه می‌دهد. از جمله توابعی که از الگوی {{قالب‌بندی پیوند}} پشتیبانی می‌کنند.

این پودمان قادر است تا پیوندها به بخش‌های صفحه‌ها را با استفاده از نماد بخش («§») به‌طور کاربرپسندی قالب‌بندی کند، به‌طور خودکار نام رده‌ها و پرونده‌ها را با لم دونقطه پیوند دهد، و حاوی توابعی برای ایتالیک کردن نام صفحه یا بخش، و برای شناسایی و رده‌بندی نتایجی است که تولید پیوند قرمز می‌کنند.

استفاده از درون ویکی‌متن

توابع این پودمان را نمی‌توان به‌طور مستقیم و با استفاده از تابع تجزیه‌گر #درخواست (یا ‎#invoke) صدا زد و در عوض باید از طریق الگوها مورد استفاده قرار گیرد. لطفاً برای آگاهی از چگونگی استفاده از الگو:قالب‌بندی پیوند، مستندات الگو در صفحهٔ خودش را ببینید.

استفاده از درون سایر پودمان‌های لوآ

برای بارگیری این پودمان در درون یک پودمان دیگر، از دستور زیر استفاده کنید:

local mFormatLink = require('Module:Format link')

پس از آن می‌توانید از توابع این پودمان به‌شکلی که در زیر آمده استفاده کنید.

_formatLink

mFormatLink._formatLink{
    link = 'پیوند',
    display = 'نمایش',
    target = 'هدف',
    italicizePage = true,
    italicizeSection = true,
    categorizeMissing = 'صفحه‌هایی که از پیوندهای قرمز قالب‌بندی‌شده استفاده می‌کنند'
}

مقدار واردشده به link را به‌عنوان ویکی‌پیوند قالب‌بندی می‌کند. رده‌ها و پرونده‌ها به‌طور خودکار با استفاده از لم دونقطه پیونددهی می‌شوند و پیوندها به بخش‌های صفحه‌ها، به‌جای استفاده از قالب پیش‌فرض مدیاویکی به‌شکل صفحه#بخش، به‌طور خودکار به‌شکل صفحه § بخش قالب‌بندی می‌شوند.

گزینه‌های مختلفی هستند که بر روی خروجی تأثیرگذارند و آن را تغییر می‌دهند:

• اگر مقداری به پارامتر display وارد شده‌باشد، آن مقدار به‌عنوان مقدار قابل نمایش مورد استفاده قرار خواهد گرفت. مقدار واردشده در display در صورت وجود بر هرگونه لوله‌دهی دستی (استفاده از کلمهٔ جادویی {{!}} یا مشابه آن) که در link موجود باشد، ارجحیت دارد.
• اگر مقداری به پارامتر target وارد شده‌باشد، به‌عنوان هدف بر مقدار موجود در link ارجحیت خواهد داشت، اما نتیجه همچنان با استفاده از مقدار display یا نتیجهٔ قالب‌بندی link نمایش خواهد یافت.
• اگر italicizePage صحیح باشد، آنگاه بخش «صفحه» در پیوند در صورت وجود به‌صورت ایتالیک درمی‌آید.
• اگر italicizeSection صحیح باشد، آنگاه بخش «بخش» در پیوند در صورت وجود به‌صورت ایتالیک درمی‌آید.
• اگر categorizeMissing یک رشتهٔ غیرخالی باشد، آنگاه آن مقدار به‌عنوان نام یک رده در نظر گرفته خواهد شد و آن رده، در صورت موجود نبودن هدف پیوند به صفحه اعمال خواهد شد (فرقی نمی‌کند که پیوند از طریق link وارد شده‌باشد یا از طریق target).

نمونه‌ها

mFormatLink._formatLink{link = 'فلان#بهمان'} ← [[:فلان#بهمان|فلان § بهمان]] ← فلان § بهمان

mFormatLink._formatLink{link = 'بیسار', display = 'چیز'} ← [[:بیسار|چیز]] ← چیز

mFormatLink._formatLink{link = 'فلان|بهمان', display = 'بیسار'} ← [[:فلان|بهمان]] ← بیسار

mFormatLink._formatLink{link = '#فلان', target = 'نمونه#فلان'} ← [[:نمونه#فلان|§ فلان]] ← § فلان

mFormatLink._formatLink{link = 'ارباب حلقه‌ها#داستان و شخصیت‌پردازی', italicizePage = true} ← [[:ارباب حلقه‌ها#داستان و شخصیت‌پردازی|''ارباب حلقه‌ها'' § داستان و شخصیت‌پردازی]] ← ارباب حلقه‌ها § داستان و شخصیت‌پردازی

mFormatLink._formatLink{link = 'محمود دولت‌آبادی#کلیدر', italicizeSection = true} ← [[:محمود دولت‌آبادی#کلیدر|محمود دولت‌آبادی § ''کلیدر'']] ← محمود دولت‌آبادی § کلیدر

mFormatLink._formatLink{link = 'صفحهٔ ناموجود', categorizeMissing = 'نمونه'} ← [[:صفحهٔ ناموجود]][[رده:نمونه]] ← صفحهٔ ناموجود

mFormatLink._formatLink{link = 'موجودیت', categorizeMissing = 'نمونه'} ← [[:موجودیت]] ← موجودیت

formatPages

mFormatLink.formatPages(options, pages)

این تابع مشتق‌شده برای فهرست‌هایی مفید است که تعدا زیادی از پیوندها را قالب‌بندی می‌کنند. این تابع آرایه‌ای از صفحه‌هایی را که از تابع ‎_formatLink استفاده می‌کنند را قالب‌بندی می‌کند و نتیجه را در قالب یک آرایه برمی‌گرداند. گزینه‌های موجود در جدول options نیز بر آن‌ها اعمال می‌شوند و از نام‌های مشابه با گزینه‌های تابع ‎_formatLink بهره‌مند هستند.

نمونه

mFormatLink.formatPages({categorizeMissing = 'نمونه'}, {'فلان#بهمان', 'صفحهٔ ناموجود'}) → {'[[:فلان#بهمان|فلان § بهمان]]', '[[:صفحهٔ ناموجود]][[رده:نمونه]]'}

خطاها

اگر ‎_formatLink به‌کار رفته‌باشد و هیچ‌یک از آرگومان‌های link یا target وارد نشده‌باشند، این پودمان به‌جای خروجی معمول خود، یک خطا تولید می‌کند. چرا که قادر نیست خروجی معتبری را تولید کند.

برای رفع حل این مشکل می‌توانید پارامترهای متناسب را برای تابع ‎_formatLink وارد کنید، یا این که ممکن است لازم باشد تا اطمینان حاصل کنید که یک خطای تشریحی‌تر توسط الگو یا پودمانی در سطوح پایین‌تر تولید می‌شود؛ چرا که در غیر این صورت، آن الگو یا پودمان تابع ‎_formatLink را با آرگومان‌های ناکافی صدا خواهد زد.

توضیحات بالا تراگنجانده‌شده از پودمان:Format link/توضیحات است. (ویرایش | تاریخچه)
ویرایشگران می‌توانند در صفحات تمرین (ایجاد | آینه) و آزمایشی (ایجاد) این پودمان را آزمایش کنند.
زیرصفحه‌های این پودمان.

--------------------------------------------------------------------------------
-- Format link
--
-- Makes a wikilink from the given link and display values. Links are escaped
-- with colons if necessary, and links to sections are detected and displayed
-- with " § " as a separator rather than the standard MediaWiki "#". Used in
-- the {{format link}} template.
--------------------------------------------------------------------------------
local libraryUtil = require('libraryUtil')
local checkType = libraryUtil.checkType
local checkTypeForNamedArg = libraryUtil.checkTypeForNamedArg
local mArguments -- lazily initialise [[Module:Arguments]]
local mError -- lazily initialise [[Module:Error]]
local yesno -- lazily initialise [[Module:Yesno]]

local p = {}

--------------------------------------------------------------------------------
-- Helper functions
--------------------------------------------------------------------------------

local function getArgs(frame)
	-- Fetches the arguments from the parent frame. Whitespace is trimmed and
	-- blanks are removed.
	mArguments = require('Module:Arguments')
	return mArguments.getArgs(frame, {parentOnly = true})
end

local function removeInitialColon(s)
	-- Removes the initial colon from a string, if present.
	return mw.ustring.match(s, '^:?(.*)')
end

local function maybeItalicize(s, shouldItalicize)
	-- Italicize s if s is a string and the shouldItalicize parameter is true.
	if s and shouldItalicize then
		return '<i>' .. s .. '</i>'
	else
		return s
	end
end

local function parseLink(link)
	-- Parse a link and return a table with the link's components.
	-- These components are:
	-- - link: the link, stripped of any initial colon (always present)
	-- - page: the page name (always present)
	-- - section: the page name (may be nil)
	-- - display: the display text, if manually entered after a pipe (may be nil)
	link = removeInitialColon(link)

	-- Find whether a faux display value has been added with the {{!}} magic
	-- word.
	local prePipe, display = mw.ustring.match(link, '^(.-)|(.*)$')
	link = prePipe or link

	-- Find the page, if it exists.
	-- For links like [[#Bar]], the page will be nil.
	local preHash, postHash = mw.ustring.match(link, '^(.-)#(.*)$')
	local page
	if not preHash then
		-- We have a link like [[Foo]].
		page = link
	elseif preHash ~= '' then
		-- We have a link like [[Foo#Bar]].
		page = preHash
	end

	-- Find the section, if it exists.
	local section
	if postHash and postHash ~= '' then
		section = postHash
	end
	
	return {
		link = link,
		page = page,
		section = section,
		display = display,
	}
end

local function formatDisplay(parsed, options)
	-- Formats a display string based on a parsed link table (matching the
	-- output of parseLink) and an options table (matching the input options for
	-- _formatLink).
	local page = maybeItalicize(parsed.page, options.italicizePage)
	local section = maybeItalicize(parsed.section, options.italicizeSection)
	if (not section) then
		return page
	elseif (not page) then
		return mw.ustring.format('§&nbsp;%s', section)
	else
		return mw.ustring.format('%s §&nbsp;%s', page, section)
	end
end

local function missingArgError(target)
	mError = require('Module:Error')
	return mError.error{message =
		'خطا:پیوند یا هدف مشخص نشده‌است! ([[' .. target .. '#خطاها|راهنما]])'
	}
end

--------------------------------------------------------------------------------
-- Main functions
--------------------------------------------------------------------------------

function p.formatLink(frame)
	-- The formatLink export function, for use in templates.
	yesno = require('Module:Yesno')
	local args = getArgs(frame)
	local link = args[1] or args.link or args['پیوند']
	local target = args[3] or args.target or args['هدف']
	if not (link or target) then
		return missingArgError('الگو:قالب‌بندی پیوند')
	end

	return p._formatLink{
		link = link,
		display = args[2] or args.display or args['نمایش'],
		target = target,
		italicizePage = yesno(args.italicizepage or args['صفحه ایتالیک']),
		italicizeSection = yesno(args.italicizesection or args['بخش ایتالیک']),
		categorizeMissing = args.categorizemissing or args['رده‌بندی ناموجودها']
	}
end

function p._formatLink(options)
	-- The formatLink export function, for use in modules.
	checkType('_formatLink', 1, options, 'table')
	local function check(key, expectedType) --for brevity
		checkTypeForNamedArg(
			'_formatLink', key, options[key], expectedType or 'string', true
		)
	end
	check('link')
	check('display')
	check('target')
	check('italicizePage', 'boolean')
	check('italicizeSection', 'boolean')
	check('categorizeMissing')

	-- Normalize link and target and check that at least one is present
	if options.link == '' then options.link = nil end
	if options.target == '' then options.target = nil end
	if not (options.link or options.target) then
		return missingArgError('پودمان:Format link')
	end

	local parsed = parseLink(options.link)
	local display = options.display or parsed.display
	local catMissing = options.categorizeMissing
	local category = ''

	-- Find the display text
	if not display then display = formatDisplay(parsed, options) end

	-- Handle the target option if present
	if options.target then
		local parsedTarget = parseLink(options.target)
		parsed.link = parsedTarget.link
		parsed.page = parsedTarget.page
	end

	-- Test if page exists if a diagnostic category is specified
	if catMissing and (mw.ustring.len(catMissing) > 0) then
		local title = nil
		if parsed.page then title = mw.title.new(parsed.page) end
		if title and (not title.isExternal) and (not title.exists) then
			category = mw.ustring.format('[[رده:%s]]', catMissing)
		end
	end
	
	-- Format the result as a link
	if parsed.link == display then
		return mw.ustring.format('[[:%s]]%s', parsed.link, category)
	else
		return mw.ustring.format('[[:%s|%s]]%s', parsed.link, display, category)
	end
end

--------------------------------------------------------------------------------
-- Derived convenience functions
--------------------------------------------------------------------------------

function p.formatPages(options, pages)
	-- Formats an array of pages using formatLink and the given options table,
	-- and returns it as an array. Nil values are not allowed.
	local ret = {}
	for i, page in ipairs(pages) do
		ret[i] = p._formatLink{
			link = page,
			categorizeMissing = options.categorizeMissing,
			italicizePage = options.italicizePage,
			italicizeSection = options.italicizeSection
		}
	end
	return ret
end

return p