Module:Arguments/doc/nl

Deze module biedt eenvoudige verwerking aan van argumenten die door {{#invoke:...}} zijn doorgegeven. Het is een meta-module, bedoeld voor gebruik door andere modules, en mag niet direct vanaf {{#invoke:...}} worden aangeroepen. De functies bevatten:

• Eenvoudig trimmen van argumenten en verwijderen van lege argumenten.
• Argumenten kunnen tegelijkertijd door zowel het huidige frame als het bovenliggende frame worden doorgegeven. (Meer details hieronder.)
• Argumenten kunnen rechtstreeks vanuit een andere Lua-module of vanuit de debug-console worden doorgegeven.
• Argumenten worden indien nodig opgehaald, wat kan helpen om (sommige) problemen met de ‎<ref> tags te voorkomen.
• De meeste functies kunnen worden aangepast.

Basisgebruik

Eerst moet u de module laden. Het bevat één functie, getArgs.

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

In het meest eenvoudige scenario kunt u getArgs gebruiken binnen uw hoofdfunctie. De variabele args is een tabel met de argumenten van {{#invoke:...}}. (Voor meer details zie hieronder.)

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

function p.main(frame)
	local args = getArgs(frame)
	-- Hier komt de hoofdmodule.
end

return p

De aanbevolen praktijk is echter om een functie alleen te gebruiken voor het verwerken van argumenten vanaf {{#invoke:...}}. Dit betekent dat als iemand de module uit een andere Lua-module roept, men geen frame-object hoeft te hebben, wat de prestaties verbetert.

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)
	-- Hier komt de code van de hoofdmodule.
end

return p

Als u meerdere functies wilt gebruiken om de argumenten te gebruiken, en u wilt ook dat ze vanaf {{#invoke:...}} toegankelijk zijn, kunt u een wrapper-functie gebruiken.

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

local p = {}

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

p.func1 = makeInvokeFunc('_func1')

function p._func1(args)
	-- De code voor de eerste functie komt hier.
end

p.func2 = makeInvokeFunc('_func2')

function p._func2(args)
	-- De code voor de tweede functie komt hier.
end

return p

Opties

De volgende opties zijn beschikbaar: Deze worden in de onderstaande secties uitgelegd.

local args = getArgs(frame, {
	trim = false,
	removeBlanks = false,
	valueFunc = function (key, value)
		-- Code voor het verwerken van een argument
	end,
	frameOnly = true,
	parentOnly = true,
	parentFirst = true,
	wrappers = {
		'Template:A wrapper template',
		'Template:Another wrapper template'
	},
	readOnly = true,
	noOverwrite = true
})

Trimmen en verwijderen van spaties

Lege argumenten zorgen vaak voor problemen bij programmeurs die nieuw zijn bij het omzetten van MediaWiki-sjablonen naar Lua. In de sjabloonsyntaxis worden lege teksten en teksten die alleen uit spaties bestaan als false beschouwd. In Lua worden deze beide echter als true beschouwd. Dit betekent dat als men niet let op dergelijke argumenten let wanneer men een Lua-modules schrijft, men iets als true zou kunnen behandelen dat eigenlijk als false zou moeten worden behandeld. Om dit te voorkomen verwijdert deze module standaard alle lege argumenten.

Op dezelfde manier kan witruimte (spaties) problemen veroorzaken bij het omgaan met positionele argumenten. Hoewel witruimte is getrimd voor benoemde argumenten die afkomstig zijn van {{#invoke:...}}, wordt het bewaard voor positionele argumenten. De meeste tijd is deze extra witruimte niet gewild, dus trimt deze module het standaard af.

Soms wil men echter lege argumenten gebruiken als input, en soms wil men extra witruimte behouden. Dit kan nodig zijn om sommige sjablonen precies zoals ze werden geschreven om te zetten. Als men dit wil doen, kan men de argumenten trim en removeBlanks instellen op false.

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

Aangepaste opmaak van argumenten

Soms wil men enkele lege argumenten verwijderen, maar niet andere, of misschien wil men al de positionele argumenten in kleine letters omzetten. Om zoiets te doen kan men de optie valueFunc gebruiken. De invoer van deze optie moet een functie zijn die twee parameters, key en value, heeft en een enkele waarde teruggeeft. Deze waarde wordt verkregen wanneer u het veld key in de tabel args opzoekt.

Voorbeeld 1: Deze functie behoudt witruimte voor het eerste positionele argument, maar trimt alle andere argumenten en verwijdert alle andere lege argumenten.

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

Voorbeeld 2: Deze functie verwijdert lege argumenten en zet alle argumenten om in kleine letters, maar trimt geen witruimte van positionele parameters.

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

De bovenstaande functies zullen falen als invoert wordt doorgegeven die niet van type string of nil is.

Dit kan het geval zijn als u de functie getArgs gebruikt in de hoofdfunctie van uw module, en die functie wordt aangeroepen door een andere Lua-module. In dit geval moet u het type van uw invoer controleren.

Dit is geen probleem als u een functie gebruikt speciaal voor argumenten van {{#invoke:...}} (d.w.z. u heeft functies van p.main en p._main of iets soortgelijks).

Voorbeelden 1 en 2 met typecontrole

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

Houd er ook rekening mee dat de functie valueFunc meer of minder wordt aangeroepen elke keer dat een argument wordt gevraagd uit de args tabel, dus als u om prestaties geeft moet u ervoor zorgen dat u niets inefficiënt doet in uw code.

Frames en bovenliggende frames

Argumenten in de tabel args kunnen tegelijkertijd worden doorgegeven vanuit het huidige frame of vanuit het bovenliggende frame (parent). Om beter te begrijpen wat dit betekent, geven we een voorbeeld. Laten we zeggen dat we een module Module:ExampleArgs hebben. Deze module print de eerste twee positionele argumenten die het ontvangt.

code Module:ExampleArgs
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 wordt dan aangeroepen door Template:ExampleArgs, die de code {{#invoke:ExampleArgs|main|firstInvokeArg}} bevat. Dit geeft het resultaat "firstInvokeArg".

Als we nu Template:ExampleArgs zouden aanroepen, zou het volgende gebeuren:

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

Er zijn drie opties die u kunt instellen om dit gedrag te veranderen: frameOnly, parentOnly en parentFirst. Als u frameOnly instelt, worden alleen de argumenten die zijn overgebracht uit het huidige frame geaccepteerd; als u parentOnly instelt, zullen alleen de argumenten die zijn overgenomen uit het bovenliggende frame worden geaccepteerd; en als u parentFirst instelt, dan zullen argumenten worden overgebracht van zowel het huidige als het bovenliggende frame, maar het bovenliggende frame zal voorrang hebben boven het huidige frame. Dit zijn de resultaten in termen van Template:ExampleArgs:

frameOnly

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

parentOnly

Code	Resultaat
{{ExampleArgs}}
{{ExampleArgs|firstTemplateArg}}	firstTemplateArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstTemplateArg secondTemplateArg

parentFirst

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

1. Als u de opties frameOnly en parentOnly instelt, zal de module helemaal geen argumenten ophalen van {{#invoke:...}}. Dit is waarschijnlijk niet wat u wilt.
2. In sommige situaties is een bovenliggend frame mogelijk niet beschikbaar, bijvoorbeeld als getArgs juist wordt doorgegeven door het bovenliggende frame. In dit geval worden alleen de frame-argumenten gebruikt (tenzij parentOnly is ingesteld, in welk geval geen argumenten worden gebruikt) en hebben de opties parentFirst en frameOnly geen effect.

Wrappers

De optie wrapperse wordt gebruikt om een beperkt aantal sjablonen op te geven als wrapper-sjablonen, dat wil zeggen sjablonen waarvan het enige doel is om een module aan te roepen. Als de module ziet dat deze wordt aangeroepen vanuit een wrapper-sjabloon, controleert deze alleen op argumenten in het bovenliggende frame; Anders wordt er alleen gecontroleerd op argumenten in het frame dat is doorgegeven aan getArgs. Dit maakt het mogelijk om modules aan te roepen met {{#invoke:...}} of via een wrapper-sjabloon zonder het verlies aan prestaties vanwege het moeten controleren van zowel het frame als het bovenliggende frame voor elke zoekopdracht naar argumenten.

Voorbeeld: de enige inhoud van {{Navbox}} (exclusief inhoud in tags ‎<noinclude>...‎</noinclude>) is {{#invoke:Navbox|navbox}}. Het is niet zinvol om de argumenten die rechtstreeks worden overgedragen aan het statement {{#invoke:...}} voor dit sjabloon te controleren, omdat er nooit argumenten worden gespecificeerd. We kunnen voorkomen dat argumenten die naar {{#invoke:...}} worden overgedragen worden gecontroleerd door de optie parentOnly te gebruiken, maar als we dit doen, zal {{#invoke:...}} ook niet werken vanaf andere pagina's. Als dit het geval zou zijn, dan zou |text=Wat tekst in de code {{#invoke:Navbox|navbox|text=Sommige tekst}} volledig worden genegeerd, ongeacht vanaf welke pagina het werd gebruikt. Door de optie wrappers te gebruiken om Template:Navbox als wrapper op te geven, kunnen we {{#invoke:Navbox|main|text=Sommige tekst}} laten werken vanaf de meeste pagina's, terwijl het nog steeds niet vereist is dat de module controleert op argumenten op de pagina Template:Navbox zelf.

Wrappers kunnen worden gespecificeerd als een string of als een matrix strings.

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

local args = getArgs(frame, {
	wrappers = {
		'Template:Wrapper 1',
		'Template:Wrapper 2',
		-- Hier kan elk aantal wrapper-sjablonen worden toegevoegd.
	}
})

1. De module detecteert automatisch of het wordt aangeroepen vanaf de subpagina /sandbox van een wrapper-sjabloon, dus het is niet nodig om zandbak-pagina's expliciet op te geven.
2. De optie wrappers verandert effectief de standaard van de opties frameOnly en parentOnly. Als bijvoorbeeld parentOnly expliciet op false met wrappers werd ingesteld, zouden aanroepen via wrapper-sjablonen resulteren in het laden van zowel frame als bovenliggende frame argumenten, hoewel aanroepen zonder wrapper-sjablonen alleen argumenten van het frame zouden worden geladen.
3. Als de optie wrappers is ingesteld en er geen bovenliggend frame beschikbaar is, krijgt de module altijd de argumenten van het frame overgedragen naar getArgs.

Schrijven naar de tabel args

Soms kan het nuttig zijn om nieuwe waarden in de tabel args te schrijven. Dit is mogelijk met de standaardinstellingen van deze module. (Houd er echter rekening mee dat het meestal beter is om een nieuwe tabel met uw nieuwe waarden te maken en indien nodig argumenten uit de tabel args te kopiëren.)

args.foo = 'een waarde'

Het is mogelijk om dit gedrag te veranderen met de opties readOnly en noOverwrite. Als readOnly is ingesteld, is het niet mogelijk om waarden in de tabel args te schrijven. Als noOverwrite is ingesteld, is het mogelijk om nieuwe waarden toe te voegen aan de tabel, maar het is niet mogelijk om een waarde toe te voegen als het argumenten zou overschrijven die worden doorgegeven vanaf {{#invoke:...}}.

Ref tags

Deze module gebruikt meta-tabellen om argumenten uit {{#invoke:...}} op te halen. Dit maakt toegang tot zowel de frame-argumenten als de bovenliggende frame-argumenten mogelijk zonder de functie pairs() te gebruiken. Dit kan helpen als uw module tags ‎<ref> als invoer kan doorsturen.

Zodra ‎<ref> tags vanaf Lua worden gehaald, worden ze verwerkt door de MediaWiki-software en de referentie verschijnt in de referentielist onderaan het artikel. Als uw module de referentie-tag uit de uitvoer weglaat, krijgt u een fantoom-referentie - een referentie die in de referentielist verschijnt, maar geen nummer dat ermee verbinding maakt. Dit is een probleem met modules die pairs() gebruiken om te detecteren of ze de argumenten uit het frame of het bovenliggende frame moeten gebruiken, omdat die modules automatisch elk beschikbaar argument verwerken.

Deze module lost dit probleem op door toegang te geven tot zowel frame- als bovenliggende frame-argumenten, terwijl deze nog steeds alleen worden opgehaald wanneer dat nodig is. Het probleem zal echter nog steeds optreden als u pairs(args) elders in uw module gebruikt.

Bekende beperkingen

Het gebruik van meta-tabellen heeft ook zijn nadelen. De meeste normale Lua-tabel-hulpmiddelen werken niet goed op de tabel args, inclusief de operator #, de functie next() en de functies in de bibliotheek table. Als het gebruik van deze is belangrijk voor uw module, moet u uw eigen functie voor argument-verwerking maken in plaats van deze module te gebruiken.

Testen

Test Status

Module:Arguments	success: 51, error: 0, skipped: 0
Module:Arguments/sandbox	success: 51, error: 0, skipped: 0

• See test cases
• Diff sandbox code