Modul:Arguments/doc

Ez a modul az #invoke-kal hívott modulok paramétereinek egyszerű feldolgozását segíti. Ez egy meta-modul, azaz más modulok használják, ezért az #invoke-kal történő közvetlen hívása értelmetlen. Képességei:

• A paraméterek kezdő és záró szőközöktől való megtisztítása (trim). Az üres paraméterek eldobása
• A paramétereket az aktuális és a szülő feldolgozókeret is egyszerre át tudja adni. (Részletek lejjebb.)
• A paraméterek más közvetlenül Lua modulból vagy egy hibakereső (debug) konzolról is átadhatók.
• A paraméterek, akkor kerülnek átvételre, amikor szükség van rájuk, ezzel a referencia tag-ekből adódó egyes problémák elkerülhetőek.
• A legtöbb képesség testreszabható.

Alap felhasználási mód

Legelőször be kell tölteni a modult. Egyetlen függvényt a getArgs-ot tartalmazza.

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

A legegyszerűbb esetben a getArgs a hívó modul fő függvényből meghívható. Az args változó valójában egy tábla, amely az #invoke-ból jövő paramétereket tartalmazza. (Részletek lejjebb.)

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

function p.main(frame)
	local args = getArgs(frame)
	-- ide jön a főmodul kódja.
end

return p

A javasolt eljárás az, hogy a a függvényt elsősorban az #invoke-ból jövő paraméterek kezelésére használjuk. Ezt azért javasolt, mert ha modulunkat egy másik Lua-modul közvetlenül hívja, mek kell külön keret-objektumot alkalmazni, ez pedig növeli a kód futási teljesítményét.

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

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

function p._main(args)
	-- a fő kód ide kerüljön.
end

return p

Ha több függvényben fel akarjuk használni az #invoke-ból elérhető módon a paramétereket, akkor egy külön függvénybe csomagolhatjuk a getArgs-ot.

local getArgs = require('Modul: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)
	-- Az első függvény kódja...
end

p.func2 = makeInvokeFunc('_func2')

function p._func2(args)
	-- a második függvény kódja
end

return p

Opciók

A következő, az alábbi szakaszokban elmygarázott opciók érhetők el:

local args = getArgs(frame, {
	trim = false,
	removeBlanks = false,
	valueFunc = function (key, value)
		-- a paramétreket feldolgozó kód
	end,
	frameOnly = true,
	parentOnly = true,
	parentFirst = true,
	wrappers = {
		'Sablon:Burkoló sablon',
		'SAblon:Másik burkoló sablon'
	},
	readOnly = true,
	noOverwrite = true
})

Üres szóközök elhagyása és eltávolítása

Az üres paraméterek problémájában gyakran beleütköznek a Médiiawiki sablonokat Lua-kódba áttevőkezdő programozók. A sablon szintaxisában az üres karakterláncok, és a csak fehér karakterekből álló láncokat hamis értékűnek számítanak. Ugyanakkor a Luá-ban ezeket a karakterláncokat igaz értékűnek tekintjük. Ha tehát nem figyelünk ezekre a különbségekre, akkor előfordulhat, hogy a Lua-modulban igaznak teküntünk valamit, amit valójában hamis értékűnek kellene vennünk. Hogy az ilyen helyzeteket elkerülhessük, az a modul alapértelmezésben eltávolítja az üres paramétereket.

Hasonló gondot okozhatnak a névtelen paraméterek is. Jóllehet a fehér karakterek el vannak távolítva az #invoke-ból nevesített paraméterek elejéről és végéről, ez nem történik meg a névtelen, ún. pozicionális paraméterek esetén. A legtöbbször nincs szükség ezekre a szélen lévő fehér karakterekre, ezért ez a modul alapértelmezésben eltávolítja azokat. Ha mégis szükség van az üres paraméterekre, illetve a paraméterszéleken megtalálható fehér karakterekre, például bizonyos sablonok működésének pontos lemásolása céljából, akkor a trim illetve removeBlanks paramétekreket hamisra (false) kell állítani.

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

A paraméterek testreszabott formázása

Néha bizonyos üres paramétereket el kívánunk hagyni, másokat azonban nem, vagy esetleg minden névtelen paramétert kisbetűssé kívánunk tenni. Ilyen feladatokat a valueFunc kapcsoló segítségével tudunk megoldani. A kapcsoló bemenete a egy kétváltozós függvény: key és value. A függvény visszatérési értéke az args táblában a key mezőben található érték.

1. Példa: A függvény az első névtelen paraméter értékét pontosan megtartja, az összes többi paraméter széleiről eltávolítja a fehér karaktereket, és a többi üres paramétert pedig elhagyja.

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. Példa: Eza függvény elhagyja az üres paramétereket és valamennyi értékét kisbetűsíti, de nem szélezi a névtelen paramétereket.

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
})

Megjegyzés: a fenti függvény hibára fut, ha a bemenete nem string típusó, vagy nem nil. Ez olyankor fordulhat elő, ha a getArgs függvényt modulunk fő függvényében használjuk, amelyet viszont egy másik Lua-modul hív nmeg. Ebben az esetben ellenőrizni kell a bemeneti paraméter típusát. Ilyen gond nem lép fel, he egy speciális függvényt használunk fel az #invoke paramétereinek beolvasására. (pl. p.main a fő kódunk és a p._main speciális függvényt alkalmazzuk.

Vegyük észre, hogy valueFunc függvényt szinte minden alkalommal meghívjuk, ha szükségünk van a args tábla egy elemére, ha szempont számunkra a kód hatékonysága, akkor figyeljük, hogy ne maradjanak a kódunkban rossz hatékonyságú elemek.

Keretek és szülő-keretek

Mind az aktuális, mind a szülőprogram kerete adhat át paramétereket az args táblába. A legegyszerűbben ezt egy példán keresztül érthetjük meg. Legyen ez a Modul:ExampleArgs modul. Ez a neki átadott két első pozicionális (névtelen) paramétert írja ki.

Modul:ExampleArgs modulunkat meghívja a Sablon:ExampleArgs sablon, amely a következő kódot tartalmazza: {{#invoke:ExampleArgs|main|firstInvokeArg}}. Ez a hívás "firstInvokeArg"-értéket eredményezi.

Nos, ha most meghívjuk aSablon:ExampleArgs-t, a következő történik:

Code	Result
{{ExampleArgs}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstInvokeArg secondTemplateArg

Három kapcsoló áll rendelkezésünkre, hogy ezt a viselkedést megváltoztassuk: a frameOnly, a parentOnly és a parentFirst. Ha frameOnly kapcsolót használjuk, akkor csak az aktuális keret paramétereit fogadjuk el; ha a parentOnly kapcsolót állítjuk be, akkor csak szülő-keret paramétereit fogadjuk el, ha a parentFirst kapcsolót állítjuk be mindkét paraméter átadásra kerül, de a szülő-keret élvez elsőbbséget az aktuális kerettel szemben. Ezek a TSAblonExampleArgs: futásának eredményei

frameOnly

Kód	Eredmény
{{ExampleArgs}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstInvokeArg

parentOnly

Kód	Eredmény
{{ExampleArgs}}
{{ExampleArgs|firstTemplateArg}}	firstTemplateArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstTemplateArg secondTemplateArg

parentFirst

Kód	Eredmény
{{ExampleArgs}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg}}	firstTemplateArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstTemplateArg secondTemplateArg

Megjegyzések:

1. Ha a frameOnly és a parentOnly kapcsolót is beállítjuk, a modul egyik paramétert sem fogja beolvasni. Valószínűleg ilyet nem akarunk.
2. Bizonyos esetekben a szülő-keret nem elérhető: pl. getArgs a szülő-keretnek és nem az aktuális keretnek ad át. Ebben az esetben csak az aktuális keret paraméterei használhatóak. (hacsak nem a parentOnly be van állítva, mert ilyenkor egyetlen paramétert sem használunk fel. Ilyenkor a parentFirst és frameOnly kapcsolók hatástalanok.

Burkoló sablonok (Wrappers)

A wrappers kapcsolót arra használjuk, hogy megjelöljük az ún. burkoló sablonokat, ezek olyan sablonok, amelyeknek egyetlen funkciója az, hogy egy adott modult meghívjanak. Ha a modul érzékeli, hogy a burkoló sablon hívja, akkor csak a szülősablon keretének paramétereit fogja tekintetbe venni, azaz csak a getArgs-nak átadott keret paramétereit fogja ellenőrizni. Ezzel elérjük, hogy a modult akár

1. invoke-kal, akár burkolósablonnal hívjuk csak a szükséges paramétereket fogja ellenőrizni, növelve ezzel a kód hatékonyságát.

Például: Ha Sablon:Side box összes valódi tartalma (a noinclude tag-ek en kívül): {{#invoke:Side box|main}}, akkor semmi értelme, hogy megpróbáljuk megkeresni az #invoke parancsnak átadott paramétereket, mivel ilyenek egyszerűen nincsenek. Az #invoke paramétereinek fölösleges ellenőrzése elkerülhető parentOnly kapcsoló használatával is, de ha ezt tesszük, akkor nem burkoló sablonokban kiadott #invoke-k paramétereit sem fogjuk látni. Pl. a |text=Some text {{#invoke:Side box|main|text=Some text}} kódja mindig figyelmen kívül maradna, függetlenül attól, hogy mely lapról alkalmaznánk. A wrappers kapcsoló segítségével a 'Sablon:Side box'-ot burkoló sablonként jelöljük meg, így a {{#invoke:Side box|main|text=Some text}} kód a legtöbb lapról működni fog, míg magán a Sablon:Side box lapon továbbra sem történik meg a fölösleges paraméter ellenőrzés.

A "wrapper" (burkoló) sablonokat karakterláncként, vagy azok tömbjeként adhatjuk meg.

local args = getArgs(frame, {
	wrappers = 'Sablon:Burkoló sablon'
})

local args = getArgs(frame, {
	wrappers = {
		'Template:Burkoló 1',
		'Template:Burkoló 2',
		-- akárhány további (burkoló) sablon név megadható itt
	}
})

Megjegyzések:

1. A modul automatikusan érzékeli a ha burkoló sablonból hívják, vagy egy /sandbox allapról, ezért a sandbox ill. homokozó allapokat nem szükséges explicit módon megadni.
2. A wrappers kapcsoló automatikusan igazítja a frameOnly és parentOnly kapcsolókat az értelemszerűen helyes működésre. Például, ha parentOnly kapcsolót a wrappers beállításával automatikusan false-ra állítanánk, akkor a burkolósablonon keresztül történő hívások a keret és a szülőkeret paramétereit minden esetben beolvasnák, míg a nem burkoló sablonokon keresztül történő hívások mindig csak a keret paramétereit adnák át.
3. Ha a wrappers kapcsoló be van állítva, de nem érhető el szülő keret, a modul monden esetben a getArgs-nak átadott keret paramétereit fogja kiolvasni.getArgs.

Writing to the args table

Sometimes it can be useful to write new values to the args table. This is possible with the default settings of this module. (However, bear in mind that it is usually better coding style to create a new table with your new values and copy arguments from the args table as needed.)

args.foo = 'some value'

It is possible to alter this behaviour with the readOnly and noOverwrite options. If readOnly is set then it is not possible to write any values to the args table at all. If noOverwrite is set, then it is possible to add new values to the table, but it is not possible to add a value if it would overwrite any arguments that are passed from #invoke.

Ref tags

This module uses metatables to fetch arguments from #invoke. This allows access to both the frame arguments and the parent frame arguments without using the pairs() function. This can help if your module might be passed ref tags as input.

As soon as ref tags are accessed from Lua, they are processed by the MediaWiki software and the reference will appear in the reference list at the bottom of the article. If your module proceeds to omit the reference tag from the output, you will end up with a phantom reference - a reference that appears in the reference list, but no number that links to it. This has been a problem with modules that use pairs() to detect whether to use the arguments from the frame or the parent frame, as those modules automatically process every available argument.

This module solves this problem by allowing access to both frame and parent frame arguments, while still only fetching those arguments when it is necessary. The problem will still occur if you use pairs(args) elsewhere in your module, however.

Known limitations

The use of metatables also has its downsides. Most of the normal Lua table tools won't work properly on the args table, including the # operator, the next() function, and the functions in the table library. If using these is important for your module, you should use your own argument processing function instead of this module.