Module:Arguments/doc/cs

Varování:

Tato stránka je sdílena mezi několika wiki. Všechny změny této stránky budou automaticky zkopírované na všechny wiki, které se nachází v levém postranním panelu. Prosím pomozte s překladem této stránky.

Tento modul umožňuje snadné zpracování argumentů předávaných z {{#invoke:...}}. Je to metamodul určený pro použití jinými moduly a neměl by být volán přímo z {{#invoke:...}}. Mezi jeho vlastnosti patří:

• Snadné ořezávání argumentů a odstraňování prázdných argumentů.
• Argumenty mohou být předány současně aktuálním rámcem i nadřazeným rámcem. (Další podrobnosti níže.)
• Argumenty lze předávat přímo z jiného modulu Lua nebo z ladicí konzole.
• Argumenty se načítají podle potřeby, což může pomoci vyhnout se (některým) problémům se značkami ‎<ref>.
• Většinu funkcí lze přizpůsobit.

Základní použití

Nejprve je třeba načíst modul. Obsahuje jednu funkci s názvem getArgs.

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

V nejzákladnějším scénáři můžete v hlavní funkci použít getArgs. Proměnná args je tabulka obsahující argumenty z {{#invoke:...}}. (Další podrobnosti najdete níže.)

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

function p.main(frame)
	local args = getArgs(frame)
	-- Zde je kód hlavního modulu.
end

return p

Doporučená praxe je však použít funkci pouze pro zpracování argumentů od {{#invoke:...}}. To znamená, že pokud někdo zavolá váš modul z jiného modulu Lua, nemusíte mít k dispozici rámový objekt, což zlepšuje výkon.

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)
	-- Zde je kód hlavního modulu.
end

return p

Pokud chcete, aby argumenty používalo více funkcí, a také chcete, aby byly přístupné z {{#invoke:...}}, můžete použít funkci wrapper.

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)
	-- Zde je kód pro první funkci.
end

p.func2 = makeInvokeFunc('_func2')

function p._func2(args)
	-- Zde je kód pro druhou funkci.
end

return p

Možnosti

K dispozici jsou následující možnosti. Jsou vysvětleny v následujících částech.

local args = getArgs(frame, {
	trim = false,
	removeBlanks = false,
	valueFunc = function (key, value)
		-- Kód pro zpracování jednoho argumentu
	end,
	frameOnly = true,
	parentOnly = true,
	parentFirst = true,
	wrappers = {
		'Template:A wrapper template',
		'Template:Another wrapper template'
	},
	readOnly = true,
	noOverwrite = true
})

Ořezávání a odstraňování polotovarů

Prázdné argumenty často podrazí kodéry, které jsou novým převodem šablon MediaWiki na Lua. V syntaxi šablony jsou prázdné řetězce a řetězce obsahující pouze mezery považovány za false. V Lua jsou však prázdné řetězce a řetězce obsahující mezery považovány za true. To znamená, že pokud těmto argumentům při psaní svých Lua modulů nevěnujete pozornost, můžete s něčím zacházet jako s true, s čím by ve skutečnosti mělo být zacházeno jako s false. Aby se tomu zabránilo, ve výchozím nastavení tento modul odstraňuje všechny prázdné argumenty.

Podobně mohou bílé znaky způsobit problémy při práci s pozičními argumenty. Přestože jsou mezery oříznuty pro pojmenované argumenty pocházející z {{#invoke:...}}, jsou zachovány pro poziční argumenty. Většinu času není tato další mezera žádoucí, takže tento modul je ve výchozím nastavení ořízne.

Někdy však chcete jako vstup použít prázdné argumenty a někdy chcete ponechat další mezery. To může být nezbytné pro převod některých šablon přesně tak, jak byly napsány. Pokud to chcete udělat, můžete nastavit argumenty trim a removeBlanks na false.

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

Vlastní formátování argumentů

Někdy chcete odstranit některé prázdné argumenty, ale ne jiné, nebo možná budete chtít umístit všechny poziční argumenty malými písmeny. Chcete-li dělat věci, jako je tato, můžete použít možnost valueFunc. Vstupem této možnosti musí být funkce, která přebírá dva parametry, key a value, a vrací jedinou hodnotu. Tato hodnota je to, co získáte, když vstoupíte do pole key v tabulce args.

Příklad 1: Tato funkce zachová mezery pro první poziční argument, ale ořízne všechny ostatní argumenty a odstraní všechny ostatní prázdné argumenty.

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

Příklad 2: Tato funkce odstraní prázdné argumenty a převede všechny argumenty na malá písmena, ale neořízne mezery od pozičních parametrů.

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

Výše uvedené funkce selžou, pokud je předán vstup, který není typu string nebo nil.

To může být případ, kdy používáte funkci getArgs v hlavní funkci vašeho modulu a tato funkce je volána jiným modulem Lua. V tomto případě budete muset zkontrolovat typ vašeho vstupu.

To není problém, pokud používáte funkci speciálně pro argumenty od {{#invoke:...}} (tj. máte funkce p.main a p._main nebo něco podobného).

Příklady 1 a 2 s kontrolou typu

Příklad 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 }) Příklad 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 })

Pamatujte také, že funkce valueFunc je volána víceméně pokaždé, když je požadován argument z tabulky args, takže pokud vám záleží na výkonu, měli byste se ujistit, že se svým kódem neděláte nic neefektivního.

Rámce a nadřazené rámce

Argumenty v tabulce args lze současně předávat z aktuálního rámce nebo z jeho nadřazeného rámce. Abychom pochopili, co to znamená, je nejjednodušší uvést příklad. Řekněme, že máme modul nazvaný Module:ExampleArgs. Tento modul vypíše první dva poziční argumenty, které jsou předány.

kód 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 je pak volán Template:ExampleArgs, který obsahuje kód {{#invoke:ExampleArgs|main|firstInvokeArg}}. Výsledkem je "firstInvokeArg".

Pokud bychom nyní zavolali Template:ExampleArgs, stalo by se následující:

Kód	Výsledek
{{ExampleArgs}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstInvokeArg secondTemplateArg

Pro změnu tohoto chování můžete nastavit tři možnosti: frameOnly, parentOnly a parentFirst. Pokud nastavíte frameOnly, budou přijaty pouze argumenty předané z aktuálního rámce. Pokud nastavíte parentOnly, budou přijaty pouze argumenty předané z nadřazeného rámce. A pokud nastavíte parentFirst, budou argumenty předány z aktuálního i nadřazeného snímku, ale nadřazený snímek bude mít prioritu před aktuálním snímkem. Zde jsou výsledky na Template:ExampleArgs:

frameOnly

Kód	Výsledek
{{ExampleArgs}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstInvokeArg

parentOnly

Kód	Výsledek
{{ExampleArgs}}
{{ExampleArgs|firstTemplateArg}}	firstTemplateArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstTemplateArg secondTemplateArg

parentFirst

Kód	Výsledek
{{ExampleArgs}}	firstInvokeArg
{{ExampleArgs|firstTemplateArg}}	firstTemplateArg
{{ExampleArgs|firstTemplateArg|secondTemplateArg}}	firstTemplateArg secondTemplateArg

1. Pokud nastavíte obě možnosti frameOnly a parentOnly, modul nenačte z {{#invoke:...}} vůbec žádné argumenty. To pravděpodobně není to, co chcete.
2. V některých situacích nemusí být nadřazený rámec dostupný, např. pokud je getArgs předán nadřazený rámec, nikoli aktuální rámec. V tomto případě budou použity pouze argumenty rámce (pokud není nastaveno parentOnly, v takovém případě nebudou použity žádné argumenty) a volby parentFirst a frameOnly nebudou mít žádný účinek.

Wrappers

Volba wrappers se používá k určení omezeného počtu šablon jako šablony obalů, tedy šablon, jejichž jediným účelem je volání modulu. Pokud modul zjistí, že je volán ze šablony wrapperu, zkontroluje pouze argumenty v nadřazeném rámci. Jinak bude kontrolovat pouze argumenty v rámci předaném getArgs. To umožňuje modulům volat buď pomocí {{#invoke:...}} nebo prostřednictvím šablony wrapperu, aniž by došlo ke ztrátě výkonu spojené s nutností kontrolovat rámec i nadřazený rámec pro každé vyhledávání argumentů.

Například jediný obsah {{Navbox}} (s výjimkou obsahu ve značkách ‎<noinclude>...‎</noinclude>) je {{#invoke:Navbox|navbox}}. Nemá smysl kontrolovat argumenty předávané přímo příkazu {{#invoke:...}} pro tuto šablonu, protože tam nikdy nebudou zadány žádné argumenty. Můžeme se vyhnout kontrole argumentů předávaných do {{#invoke:...}} použitím možnosti parentOnly, ale pokud to uděláme, {{#invoke:...}} nebude fungovat ani z jiných stránek. Pokud by tomu tak bylo, pak by |text=nějaký text v kódu {{#invoke:Navbox|navbox|text=nějaký text}} byl zcela ignorován, bez ohledu na to, z jaké stránky byl použit. Použitím možnosti wrappers k určení Template:Navbox jako obalu můžeme zajistit, aby {{#invoke:Navbox|main|text=nějaký text}} fungovalo na většině stránek, aniž by bylo nutné, aby modul kontroloval argumenty na samotné stránce Template:Navbox.

Wrappers lze zadat buď jako řetězec, nebo jako pole řetězců.

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

local args = getArgs(frame, {
	wrappers = {
		'Template:Wrapper 1',
		'Template:Wrapper 2',
		-- Zde lze přidat libovolný počet šablon wrapper.
	}
})

1. Modul automaticky zjistí, zda je volán z podstránky /sandbox šablony wrapperu, takže není potřeba explicitně specifikovat stránky sandboxu.
2. Volba wrappers fakticky změní výchozí hodnotu možností frameOnly a parentOnly. Pokud by například parentOnly bylo explicitně nastaveno na false s nastaveným wrappers, volání přes šablony wrapperu by mělo za následek načtení argumentů rámce i nadřazených argumentů, ačkoli volání, která nejsou přes šablony wrapperu, by vedla k načtení pouze argumentů rámce.
3. Pokud je nastavena volba wrappers a není k dispozici žádný nadřazený rámec, modul vždy získá argumenty z rámce předaného do getArgs.

Zápis do args tabulky

Někdy může být užitečné zapsat nové hodnoty do tabulky args. To je možné s výchozím nastavením tohoto modulu. (Mějte však na paměti, že obvykle je lepší styl kódování vytvořit novou tabulku s novými hodnotami a podle potřeby zkopírovat argumenty z tabulky args.)

args.foo = 'nějaká hodnota'

Toto chování je možné změnit pomocí možností readOnly a noOverwrite. Pokud je nastaveno readOnly, není možné do tabulky args zapisovat vůbec žádné hodnoty. Pokud je nastaveno noOverwrite, pak je možné do tabulky přidávat nové hodnoty, ale není možné přidat hodnotu, pokud by to přepsalo nějaké argumenty předávané z {{#invoke:...}}.

Tagy Ref

Tento modul používá metatables k načítání argumentů z {{#invoke:...}}. To umožňuje přístup k argumentům rámce i argumentům nadřazeného rámce bez použití funkce pairs(). To může pomoci, pokud vašemu modulu mohou být předány tagy ‎<ref> jako vstup.

Jakmile jsou tagy ‎<ref> zpřístupněny z Lua, jsou zpracovány softwarem MediaWiki a reference se objeví v seznamu referencí ve spodní části článku. Pokud váš modul vynechá referenční značku z výstupu, skončíte s fantomovou referencí – referencí, která se objeví v seznamu referencí, ale žádné číslo, které by na ni odkazovalo. To byl problém s moduly, které používají pairs() ke zjištění, zda použít argumenty z rámce nebo nadřazeného rámce, protože tyto moduly automaticky zpracovávají každý dostupný argument.

Tento modul řeší tento problém tím, že umožňuje přístup k argumentům rámce i nadřazeného rámce, přičemž tyto argumenty načítá pouze tehdy, když je to nutné. Problém však bude stále nastávat, pokud jinde ve svém modulu použijete pairs(args).

Známá omezení

Používání metatabulek má i své stinné stránky. Většina běžných nástrojů tabulky Lua nebude správně fungovat v tabulce args, včetně operátoru #, funkce next() a funkcí v knihovně table. Pokud je jejich použití pro váš modul důležité, měli byste místo tohoto modulu použít svou vlastní funkci zpracování argumentů.

Testy

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