ماڊيول:Arguments/doc

This is the documentation page for ماڊيول:Arguments

هي سانچو ھزارين صفحن تي استعمال ٿئي ٿو.

وڏي پيماني تي خلل ۽ غير ضروري سرور لوڊ کان بچڻ لاءِ، هن سانچي ۾ ڪا به تبديلي ڪرڻ کان اڳ ان کي پهريان ان جي /sandbox يا /testcases ذيلي صفحن ۾ آزمائي ڏسو، يا پنهنجي يوزر اسپيس ۾.

آزمائشي تبديليون پوءِ هڪ ئي ترميم سان هن صفحي ۾ شامل ڪري سگهجن ٿيون۔ مهرباني ڪري تبديليون لاڳو ڪرڻ کان اڳ بحث صفحي تي انهن بابت ڳالهه ٻولهه ڪرڻ تي غور ڪريو۔

هي ماڊيول #invoke مان موڪليل دليلن (arguments) کي آسان نموني سان پروسيس ڪرڻ لاءِ استعمال ٿيندو آهي. هي هڪ ميٽا-ماڊيول آهي، جيڪو ٻين ماڊيولن جي استعمال لاءِ ٺاهيو ويو آهي، ۽ ان کي سڌو #invoke ذريعي سڏڻ نه گهرجي. هن جون خاصيتون هيٺ ڏجن ٿيون:

دليلن کي آساني سان مختصر ڪرڻ (غير ضروري خالي جڳهن کي ختم ڪرڻ) ۽ خالي دليلن کي هٽائڻ.
دليل هڪ ئي وقت موجوده فريم ۽ اصل فريم ٻنهي مان موڪلي سگهجن ٿا. (هيٺ وڌيڪ وضاحت ڏنل آهي.)
دليل سڌو ڪنهن ٻئي لئا ماڊيول مان يا ڊي بگ ڪنسول مان به موڪلي سگهجن ٿا.
دليل ضرورت مطابق حاصل ڪيا وڃن ٿا، جنهن سان <ref>...</ref> ٽيگ سان لاڳاپيل ڪجهه مسئلن کان بچي سگهجي ٿو.
گهڻيون خاصيتون ضرورت مطابق ترتيب ڏئي سگهجن ٿيون.

بنيادي استعمال

پهريان، اوھان کي ماڊيول لوڊ ڪرڻو پوندو. ھن ۾ ھڪ فنڪشن موجود آھي، جنھن جو نالو getArgs آھي.

local getArgs = require('ماڊيول:Arguments').getArgs

سڀ کان سادي حالت ۾، اوھان getArgs کي پنھنجي مکيه فنڪشن اندر استعمال ڪري سگھو ٿا. متغير args ھڪ ٽيبل آھي جنھن ۾ #invoke مان ايندڙ دليل (arguments) شامل ھوندا آھن. (تفصيل ھيٺ ڏسو.)

local getArgs = require('Module:Arguments').getArgs
local p = {}

function p.main(frame)
	local args = getArgs(frame)
	-- ماڊيول جو مکيه ڪوڊ ھتي ايندو.
end

return p

پر سفارش ڪيل طريقو اھو آھي ته #invoke مان ايندڙ دليلن کي پروسيس ڪرڻ لاءِ الڳ فنڪشن استعمال ڪيو وڃي. ان جو فائدو اھو آھي ته جيڪڏھن ڪو ٻيو Lua ماڊيول اوھان جي ماڊيول کي سڏي، تڏھن frame آبجيڪٽ جي ضرورت نه پوندي، جنهن سان ڪارڪردگي بھتر ٿئي ٿي.

local getArgs = require('Module:Arguments').getArgs
local p = {}

function p.main(frame)
	local args = getArgs(frame)
	return p._main(args)
end

function p._main(args)
	-- ماڊيول جو مکيه ڪوڊ ھتي ايندو.
end

return p

جيڪڏهن اوهان چاهيو ٿا ته ڪيترائي فنڪشن ساڳيا دليل استعمال ڪن، ۽ ساڳئي وقت انهن کي #invoke مان پڻ استعمال ڪري سگهجي، ته اوهان ھڪ wrapper فنڪشن استعمال ڪري سگھو ٿا.

local getArgs = require('Module:Arguments').getArgs

local function makeInvokeFunc(funcName)
	return function (frame)
		local args = getArgs(frame)
		return p[funcName](args)
	end
end

local p = {}

p.func1 = makeInvokeFunc('_func1')

function p._func1(args)
	-- پهرين فنڪشن جو ڪوڊ ھتي ايندو.
end

p.func2 = makeInvokeFunc('_func2')

function p._func2(args)
	-- ٻئي فنڪشن جو ڪوڊ ھتي ايندو.
end

return p

اختيار (Options)

ھيٺيان اختيار موجود آھن. انهن جي وضاحت ھيٺين حصن ۾ ڪئي وئي آھي.

local args = getArgs(frame, {
	trim = false,
	removeBlanks = false,
	valueFunc = function (key, value)
		-- ھڪ دليل کي پروسيس ڪرڻ لاءِ ڪوڊ
	end,
	frameOnly = true,
	parentOnly = true,
	parentFirst = true,
	wrappers = {
		'Template:A wrapper template',
		'Template:Another wrapper template'
	},
	readOnly = true,
	noOverwrite = true
})

خالي قدر ختم ڪرڻ ۽ خالي جڳهن کي ٽرم ڪرڻ

خالي دليل اڪثر انهن پروگرامرن لاءِ مسئلو بڻجن ٿا جيڪي ميڊياوڪي ٽيمپليٽن کي لوئا ۾ تبديل ڪرڻ شروع ڪندا آهن. سانچي جي نحو (syntax) ۾، خالي اسٽرنگ يا صرف خالي جڳهن تي مشتمل اسٽرنگ کي ڪوڙو سمجھيو ويندو آھي. پر لوئا ۾، خالي اسٽرنگ ۽ خالي جڳهن تي مشتمل اسٽرنگ کي سچو سمجھيو ويندو آھي. ان جو مطلب اھو آھي ته جيڪڏهن اوهان اهڙن دليلن جو خيال نه رکو، ته اوهان ڪا اهڙي قدر سچو سمجهي سگهو ٿا جيڪا اصل ۾ ڪوڙو هجڻ گهرجي. هن مسئلي کان بچڻ لاءِ، هي ماڊيول ڊيفالٽ طور سڀ خالي دليل ختم ڪري ڇڏيندو آهي. ساڳي طرح، پوزيشن واري دليلن سان ڪم ڪندي خالي جڳهيون مسئلا پيدا ڪري سگهن ٿيون. جيتوڻيڪ نالي وارن دليلن لاءِ خالي جاء پاڻمرادو مختصث ٿي ويندي آهي، پوزيشن واري دليلن لاءِ اهو برقرار رهندو آهي. گهڻو ڪري اها اضافي جڳهه گهربل نه هوندي آهي، تنهنڪري هي ماڊيول ڊيفالٽ طور ان کي مختصر ڪري ڇڏيندو آهي. پر ڪڏهن ڪڏهن اوهان خالي دليل کي انپٽ طور استعمال ڪرڻ چاهيو ٿا، يا اضافي خالي جاء برقرار رکڻ چاهيو ٿا. اهڙي حالت ۾، اوهان trim ۽ removeBlanks کي false ڪري سگهو ٿا.

local args = getArgs(frame, {
	trim = false,
	removeBlanks = false
})

دليلن جي حسبِ ضرورت فارميٽنگ

ڪڏهن ڪڏهن اوهان ڪجهه خالي دليل ختم ڪرڻ چاهيو ٿا پر سڀ نه، يا شايد اوهان پوزيشن واري دليلن کي ننڍن اکرن ۾ تبديل ڪرڻ چاهيو ٿا. اهڙي ڪم لاءِ valueFunc اختيار استعمال ڪيو ويندو آهي.

هن اختيار لاءِ هڪ فنڪشن ڏنو ويندو آهي جيڪو ٻه پيرا ميٽر وٺندو آهي: key ۽ value. هي فنڪشن هڪ قدر واپس ڪندو آهي، جيڪا args ٽيبل ۾ ان key جي حيثيت سان استعمال ٿيندي.

مثال 1: هي فنڪشن پهرين پوزيشن واري دليلن لاءِ خالي جايون برقرار رکي ٿو، پر ٻين سڀني دليلن کي مختصر ڪري ٿو ۽ خالي دليل ختم ڪري ٿو.

local args = getArgs(frame, {
	valueFunc = function (key, value)
		if key == 1 then
			return value
		elseif value then
			value = mw.text.trim(value)
			if value ~= '' then
				return value
			end
		end
		return nil
	end
})

مثال 2: هي فنڪشن سڀ خالي دليل ختم ڪري ٿو ۽ سڀ دليل ننڍن اکرن ۾ تبديل ڪري ٿو، پر پوزيشن واري پيراميٽرن مان خالي جايون مختصر نٿو ڪري.

local args = getArgs(frame, {
	valueFunc = function (key, value)
		if not value then
			return nil
		end
		value = mw.ustring.lower(value)
		if mw.ustring.find(value, '%S') then
			return value
		end
		return nil
	end
})

نوٽ: مٿي ڏنل فنڪشن تڏهن ناڪام ٿي سگهن ٿا جيڪڏهن انپٽ string يا nil کان سواءِ ڪنهن ٻئي قسم جو هجي. اهو تڏهن ٿي سگهي ٿو جڏهن اوهان getArgs کي پنهنجي ماڊيول جي مکيه فنڪشن ۾ استعمال ڪيو، ۽ اهو فنڪشن ڪنهن ٻئي Lua ماڊيول طرفان سڏيو وڃي. اهڙي حالت ۾ اوهان کي انپٽ جو قسم چيڪ ڪرڻو پوندو.

قسم جي چڪاس سان مثال 1 ۽ 2

مثال 1:

local args = getArgs(frame, {
	valueFunc = function (key, value)
		if key == 1 then
			return value
		elseif type(value) == 'string' then
			value = mw.text.trim(value)
			if value ~= '' then
				return value
			else
				return nil
			end
		else
			return value
		end
	end
})

مثال 2:

local args = getArgs(frame, {
	valueFunc = function (key, value)
		if type(value) == 'string' then
			value = mw.ustring.lower(value)
			if mw.ustring.find(value, '%S') then
				return value
			else
				return nil
			end
		else
			return value
		end
	end
})

مهرباني ڪري ياد رکو ته valueFunc فنڪشن تقريباً هر ڀيري هلندو آهي جڏهن args ٽيبل مان ڪو دليل حاصل ڪيو وڃي. تنهنڪري جيڪڏهن اوهان ڪارڪردگي بابت فڪر مند آهيو ته پڪ ڪريو ته اوهان جو ڪوڊ غير مؤثر يا ڳرو عمل نه ڪري رهيو هجي.

فريم ۽ پيرنٽ فريم

args ٽيبل ۾ دليل (arguments) هڪ ئي وقت موجوده فريم (current frame) مان يا ان جي پيرنٽ فريم (parent frame) مان پاس ڪري سگهجن ٿا. هن ڳالهه کي سمجهڻ لاءِ مثال ڏسڻ آسان آهي. فرض ڪريو ته اسان وٽ هڪ ماڊيول آهي جنهن جو نالو Module:ExampleArgs آهي. هي ماڊيول ان کي ڏنل پهريان ٻه پوزيشنل دليل (positional arguments) پرنٽ ڪري ٿو.

Module:ExampleArgs code

local getArgs = require('Module:Arguments').getArgs
local p = {}

function p.main(frame)
local args = getArgs(frame)
return p._main(args)
end

function p._main(args)
local first = args[1] or ''
local second = args[2] or ''
return first .. ' ' .. second
end

return p

ان کان پوءِ Module:ExampleArgs کي Template:ExampleArgs ذريعي سڏيو ويندو آهي، جنهن ۾ هي ڪوڊ شامل آهي {{#invoke:ExampleArgs|main|firstInvokeArg}}.

هن جو نتيجو ٿيندو: firstInvokeArg.

هاڻي جيڪڏهن اسان Template:ExampleArgs کي سڏيون، ته هيٺيون عمل ٿيندو:

ڪوڊ	نتيجو
`{{ExampleArgs}}`	firstInvokeArg
`{{ExampleArgs\|firstTemplateArg}}`	firstInvokeArg
`{{ExampleArgs\|firstTemplateArg\|secondTemplateArg}}`	firstInvokeArg secondTemplateArg

هن رويي (behaviour) کي تبديل ڪرڻ لاءِ ٽي آپشن مقرر ڪري سگهجن ٿا: frameOnly، parentOnly ۽ parentFirst.

جيڪڏهن frameOnly مقرر ڪيو وڃي ته رڳو اهي دليل قبول ڪيا ويندا جيڪي موجوده فريم (current frame) مان پاس ڪيا ويا هجن.
جيڪڏهن parentOnly مقرر ڪيو وڃي ته رڳو اهي دليل قبول ڪيا ويندا جيڪي پيرنٽ فريم (parent frame) مان پاس ڪيا ويا هجن.
جيڪڏهن parentFirst مقرر ڪيو وڃي ته دليل موجوده فريم ۽ پيرنٽ فريم ٻنهي مان پاس ٿي سگهن ٿا، پر پيرنٽ فريم کي موجوده فريم تي ترجيح حاصل هوندي.

هيٺ Template:ExampleArgs جي لحاظ سان نتيجا ڏيکاريا ويا آهن:

frameOnly

ڪوڊ	نتيجو
`{{ExampleArgs}}`	firstInvokeArg
`{{ExampleArgs\|firstTemplateArg}}`	firstInvokeArg
`{{ExampleArgs\|firstTemplateArg\|secondTemplateArg}}`	firstInvokeArg

parentOnly

ڪوڊ	نتيجو
`{{ExampleArgs}}`
`{{ExampleArgs\|firstTemplateArg}}`	firstTemplateArg
`{{ExampleArgs\|firstTemplateArg\|secondTemplateArg}}`	firstTemplateArg secondTemplateArg

parentFirst

ڪوڊ	نتيجو
`{{ExampleArgs}}`	firstInvokeArg
`{{ExampleArgs\|firstTemplateArg}}`	firstTemplateArg
`{{ExampleArgs\|firstTemplateArg\|secondTemplateArg}}`	firstTemplateArg secondTemplateArg

نوٽس:

جيڪڏهن توهان frameOnly ۽ parentOnly ٻنهي اختيارن کي مقرر ڪريو ٿا ته ماڊيول #invoke مان ڪوبه دليل (arguments) حاصل نه ڪندو. عام طور تي اهو اوهان جي مراد نه هوندو.
ڪڏهن ڪڏهن parent frame موجود نه هوندو، مثال طور جڏهن getArgs کي موجوده frame بدران parent frame ڏنو وڃي. اهڙي حالت ۾ صرف frame جا دليل استعمال ٿيندا (جيستائين parentOnly مقرر نه هجي، جنهن صورت ۾ ڪوبه دليل استعمال نه ٿيندو)، ۽ parentFirst ۽ frameOnly اختيارن جو ڪو اثر نه ٿيندو.

Wrappers

wrappers اختيار استعمال ڪيو ويندو آهي ته ڪجهه محدود ٽيمپليٽن کي wrapper templates طور مقرر ڪيو وڃي، يعني اهڙا ٽيمپليٽ جن جو واحد مقصد ماڊيول کي سڏڻ هوندو آهي. جيڪڏهن ماڊيول سڃاڻي وٺي ته ان کي wrapper template مان سڏيو ويو آهي ته اهو صرف parent frame مان دليل چيڪ ڪندو؛ ٻي صورت ۾ اهو صرف ان frame مان دليل چيڪ ڪندو جيڪو getArgs کي ڏنو ويو آهي. اهڙي طريقي سان ماڊيول کي يا ته #invoke ذريعي يا wrapper template ذريعي سڏڻ ممڪن ٿئي ٿو بغير ان ڪارڪردگي جي نقصان جي جيڪو هر دليل جي ڳولا لاءِ frame ۽ parent frame ٻنهي کي چيڪ ڪرڻ سان پيدا ٿيندو آهي.

مثال طور Template:Side box جو سڄو مواد (سواءِ <noinclude>...</noinclude> ٽيگن اندر موجود مواد جي) صرف هي آهي: {{#invoke:Side box|main}}.

هن ٽيمپليٽ لاءِ #invoke ۾ سڌو ڏنل دليلن کي چيڪ ڪرڻ جو ڪو مطلب نه آهي، ڇاڪاڻ⁠تہ اتي ڪڏهن به دليل ڏنا نه ويندا. اسان parentOnly اختيار استعمال ڪري #invoke مان ايندڙ دليلن کي چيڪ ڪرڻ کان بچي سگهون ٿا، پر جيڪڏهن ائين ڪيو وڃي ته پوءِ #invoke ٻين صفحن تان ڪم نه ڪندو. ان حالت ۾ هي ڪوڊ:

{{#invoke:Side box|main|text=Some text}}

ان ۾ موجود |text=Some text مڪمل طور نظرانداز ٿي ويندو، ڀلي اهو ڪنهن به صفحي تان استعمال ڪيو وڃي.

پر جيڪڏهن wrappers اختيار استعمال ڪري 'Template:Side box' کي wrapper طور مقرر ڪيو وڃي ته پوءِ

{{#invoke:Side box|main|text=Some text}}

گهڻن صفحن تان صحيح ڪم ڪندو، ۽ ساڳي وقت Template:Side box واري صفحي تي دليلن کي چيڪ ڪرڻ جي ضرورت به نه رهندي.

Wrappers کي يا ته هڪ string طور يا string جي array طور مقرر ڪري سگهجي ٿو.

local args = getArgs(frame, {
	wrappers = 'Template:Wrapper template'
})

local args = getArgs(frame, {
	wrappers = {
		'Template:Wrapper 1',
		'Template:Wrapper 2',
		-- هتي وڌيڪ wrapper templates شامل ڪري سگهجن ٿا.
	}
})

نوٽس:

ماڊيول پاڻمرادو سڃاڻي وٺندو جيڪڏهن ان کي wrapper template جي /sandbox ذيلي صفحي تان سڏيو ويو هجي، تنهنڪري sandbox صفحن کي الڳ بيان ڪرڻ جي ضرورت ناهي.
wrappers اختيار اصل ۾ frameOnly ۽ parentOnly اختيارن جي ڊيفالٽ رويي کي تبديل ڪري ٿو. مثال طور جيڪڏهن parentOnly کي واضح طور false تي مقرر ڪيو وڃي جڏهن wrappers به مقرر هجي ته wrapper templates ذريعي سڏجڻ تي frame ۽ parent ٻنهي جا دليل لوڊ ٿيندا، جڏهن ته wrapper کان سواءِ سڏجڻ تي صرف frame جا دليل لوڊ ٿيندا.
جيڪڏهن wrappers مقرر هجي ۽ parent frame موجود نه هجي ته ماڊيول هميشه getArgs کي ڏنل frame مان دليل حاصل ڪندو.

args ٽيبل ۾ لکت

ڪڏهن ڪڏهن args ٽيبل ۾ نيون قيمتون شامل ڪرڻ مفيد هوندو آهي. هن ماڊيول جي ڊيفالٽ سيٽنگن سان اهو ممڪن آهي. (پر عام طور بهتر پروگرامنگ طرز اهو آهي ته نئين قيمتن لاءِ نئون ٽيبل ٺاهيو ۽ ضرورت مطابق args مان دليل نقل ڪريو.)

args.foo = 'some value'

هي رويو readOnly ۽ noOverwrite اختيارن سان تبديل ڪري سگهجي ٿو. جيڪڏهن readOnly مقرر هجي ته args ٽيبل ۾ ڪا به قيمت لکڻ ممڪن نه هوندي. جيڪڏهن noOverwrite مقرر هجي ته نيون قيمتون شامل ڪري سگهجن ٿيون، پر اهڙي صورت ۾ شامل نه ٿيون ڪري سگهجن جڏهن اهي #invoke مان ايندڙ دليل کي مٽائين.

Ref ٽيگ

هي ماڊيول metatables استعمال ڪري #invoke مان دليل حاصل ڪري ٿو. ان سان pairs() استعمال ڪرڻ کان سواءِ frame ۽ parent frame ٻنهي مان دليل حاصل ڪري سگهجن ٿا. اهو خاص طور تي مددگار آهي جڏهن ماڊيول کي <ref>...</ref> ٽيگ ان پٽ طور ملي سگهن.

جڏهن Lua مان <ref>...</ref> ٽيگ تائين رسائي ڪئي وڃي ٿي ته MediaWiki سافٽويئر ان کي فوراً پروسيس ڪري ٿو ۽ اهو حوالن جي فهرست ۾ ظاهر ٿي وڃي ٿو. جيڪڏهن ماڊيول پوءِ ان ref ٽيگ کي آئوٽ پٽ مان حذف ڪري ڇڏي ته هڪ phantom reference پيدا ٿي سگهي ٿو — يعني حوالن جي فهرست ۾ حوالو ته موجود هجي پر ان ڏانهن وڃڻ لاءِ ڪو نمبر موجود نه هجي.

اهو مسئلو انهن ماڊيولن ۾ ڏٺو ويو آهي جيڪي pairs() استعمال ڪري اهو طئي ڪن ٿا ته frame جا دليل استعمال ڪجن يا parent frame جا، ڇو ته اهي ماڊيول سڀئي موجود دليل پاڻمرادو پروسيس ڪندا آهن.

هي ماڊيول ان مسئلي کي حل ڪري ٿو، ڇاڪاڻ⁠تہ اهو صرف ضرورت پوڻ تي ئي دليل حاصل ڪري ٿو. بهرحال جيڪڏهن توهان پنهنجي ماڊيول ۾ ٻي هنڌ pairs(args) استعمال ڪندا ته اهو مسئلو وري به ٿي سگهي ٿو.

معلوم حدبنديون

metatables جي استعمال جا ڪجهه نقصان به آهن. Lua جي عام ٽيبل اوزارن مان ڪيترائي args ٽيبل تي صحيح ڪم نٿا ڪن، جن ۾ شامل آهن:

# آپريٽر
next() فنڪشن
table لائبريري جا فنڪشن

جيڪڏهن اهي اوزار توهان جي ماڊيول لاءِ ضروري هجن ته پوءِ هن ماڊيول بدران پنهنجو دليل پروسيس ڪرڻ وارو فنڪشن استعمال ڪرڻ بهتر آهي.