Tekst źródłowy strony Moduł:Arguments/doc/cs

<noinclude><!--
-->{{#ifeq:{{SUBPAGENAME}}|doc||{{Documentation subpage}}}}<!--
--><languages /><!--
--></noinclude>{{#switch:
| =
<includeonly>{{Languages|Module:Arguments/doc}}</includeonly>
<!-- Add categories where indicated at the bottom of this page and interwikis at Wikidata -->
{{Used in system}}
{{Module rating|release}}
{{Module rating|protected}}

Tento modul umožňuje snadné zpracování argumentů předávaných z {{Magic word|#invoke|...|ext=Scribunto|code=1|nowrap=1}}.
Je to metamodul určený pro použití jinými moduly a neměl by být volán přímo z {{tlc|<nowiki>#invoke:...</nowiki>}}.
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 {{xtag|ref}}.
* Většinu funkcí lze přizpůsobit.

<span id="Basic_use"></span>
== Základní použití ==
Nejprve je třeba načíst modul.
Obsahuje jednu funkci s názvem <code>getArgs</code>.

<syntaxhighlight lang="lua">
local getArgs = require('Module:Arguments').getArgs
</syntaxhighlight>

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

<syntaxhighlight lang="lua">
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
</syntaxhighlight>

Doporučená praxe je však použít funkci pouze pro zpracování argumentů od {{tlc|<nowiki>#invoke:...</nowiki>}}.
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.

<syntaxhighlight lang="lua">
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
</syntaxhighlight>

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

<syntaxhighlight lang="lua">
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
</syntaxhighlight>

<span id="Options"></span>
=== Možnosti ===
K dispozici jsou následující možnosti.
Jsou vysvětleny v následujících částech.

<syntaxhighlight lang="lua">
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
})
</syntaxhighlight>

<span id="Trimming_and_removing_blanks"></span>
=== 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 <code>false</code>.
V Lua jsou však prázdné řetězce a řetězce obsahující mezery považovány za <code>true</code>.
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 <code>true</code>, s čím by ve skutečnosti mělo být zacházeno jako s <code>false</code>.
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 {{tlc|<nowiki>#invoke:...</nowiki>}}, 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 <code>trim</code> a <code>removeBlanks</code> na <code>false</code>.

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
	trim = false,
	removeBlanks = false
})
</syntaxhighlight>

<span id="Custom_formatting_of_arguments"></span>
=== 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 <code>valueFunc</code>.
Vstupem této možnosti musí být funkce, která přebírá dva parametry, <code>key</code> a <code>value</code>, a vrací jedinou hodnotu.
Tato hodnota je to, co získáte, když vstoupíte do pole <code>key</code> v tabulce <code>args</code>.

'''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.

<syntaxhighlight lang="lua">
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
})
</syntaxhighlight>

'''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ů.

<syntaxhighlight lang="lua">
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
})
</syntaxhighlight>

{{Note|text=
Výše uvedené funkce selžou, pokud je předán vstup, který není typu <code>string</code> nebo <code>nil</code>.
To může být případ, kdy používáte funkci <code>getArgs</code> 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 {{tlc|<nowiki>#invoke:...</nowiki>}} (tj. máte funkce <code>p.main</code> a <code>p._main</code> nebo něco podobného).
}}

{{Collapse top|1=Příklady 1 a 2 s kontrolou typu}}
Příklad 1:
<syntaxhighlight lang="lua">
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
})
</syntaxhighlight>

Příklad 2:
<syntaxhighlight lang="lua">
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
})
</syntaxhighlight>
{{Collapse bottom}}

Pamatujte také, že funkce <code>valueFunc</code> je volána víceméně pokaždé, když je požadován argument z tabulky <code>args</code>, 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.

<span id="Frames_and_parent_frames"></span>
=== Rámce a nadřazené rámce ===

Argumenty v tabulce <code>args</code> 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ý <code>Module:ExampleArgs</code>.
Tento modul vypíše první dva poziční argumenty, které jsou předány.

{{Collapse top|1=kód Module:ExampleArgs}}
<syntaxhighlight lang="lua">
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
</syntaxhighlight>
{{Collapse bottom}}

<code>Module:ExampleArgs</code> je pak volán <code>Template:ExampleArgs</code>, který obsahuje kód <code><nowiki>{{#invoke:ExampleArgs|main|firstInvokeArg}}</nowiki></code>.
Výsledkem je "firstInvokeArg".

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

{{(!}} class="wikitable" style="width: 50em; max-width: 100%;"
{{!}}-
! style="width: 60%;" {{!}} Kód
! style="width: 40%;" {{!}} Výsledek
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
{{!}} firstInvokeArg secondTemplateArg
{{!)}}

Pro změnu tohoto chování můžete nastavit tři možnosti: <code>frameOnly</code>, <code>parentOnly</code> a <code>parentFirst</code>.
Pokud nastavíte <code>frameOnly</code>, budou přijaty pouze argumenty předané z aktuálního rámce. Pokud nastavíte <code>parentOnly</code>, budou přijaty pouze argumenty předané z nadřazeného rámce. A pokud nastavíte <code>parentFirst</code>, 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 <code>Template:ExampleArgs</code>:

<dl>
<dt><code>frameOnly</code></dt>
<dd>
{{(!}} class="wikitable" style="width: 50em; max-width: 100%;"
{{!}}-
! style="width: 60%;" {{!}} Kód
! style="width: 40%;" {{!}} Výsledek
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
{{!}} firstInvokeArg
{{!)}}
</dd>

<dt><code>parentOnly</code></dt>
<dd>
{{(!}} class="wikitable" style="width: 50em; max-width: 100%;"
{{!}}-
! style="width: 60%;" {{!}} Kód
! style="width: 40%;" {{!}} Výsledek
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs}}</nowiki></code>
{{!}}
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
{{!}} firstTemplateArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
{{!}} firstTemplateArg secondTemplateArg
{{!)}}
</dd>

<dt><code>parentFirst</code></dt>
<dd>
{{(!}} class="wikitable" style="width: 50em; max-width: 100%;"
{{!}}-
! style="width: 60%;" {{!}} Kód
! style="width: 40%;" {{!}} Výsledek
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs}}</nowiki></code>
{{!}} firstInvokeArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg}}</nowiki></code>
{{!}} firstTemplateArg
{{!}}-
{{!}} <code><nowiki>{{ExampleArgs|firstTemplateArg|secondTemplateArg}}</nowiki></code>
{{!}} firstTemplateArg secondTemplateArg
{{!)}}
</dd>
</dl>

{{Note|text=
{{Ordered list
|1=
Pokud nastavíte obě možnosti <code>frameOnly</code> a <code>parentOnly</code>, modul nenačte z {{tlc|<nowiki>#invoke:...</nowiki>}} 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 <code>getArgs</code> 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 <code>parentOnly</code>, v takovém případě nebudou použity žádné argumenty) a volby <code>parentFirst</code> a <code>frameOnly</code> nebudou mít žádný účinek.
}}
}}

=== Wrappers ===

Volba <code>wrappers</code> 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 <code>getArgs</code>.
To umožňuje modulům volat buď pomocí {{tlc|<nowiki>#invoke:...</nowiki>}} 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 {{tlx|Navbox}} (s výjimkou obsahu ve značkách {{tag|noinclude}}) je <code><nowiki>{{#invoke:Navbox|navbox}}</nowiki></code>.
Nemá smysl kontrolovat argumenty předávané přímo příkazu {{tlc|<nowiki>#invoke:...</nowiki>}} pro tuto šablonu, protože tam nikdy nebudou zadány žádné argumenty.
Můžeme se vyhnout kontrole argumentů předávaných do {{tlc|<nowiki>#invoke:...</nowiki>}} použitím možnosti <code>parentOnly</code>, ale pokud to uděláme, {{tlc|<nowiki>#invoke:...</nowiki>}} nebude fungovat ani z jiných stránek.
Pokud by tomu tak bylo, pak by {{tmpl|0={{para|text|$1}}|nějaký text}} v kódu {{tmpl|0={{tlc|<nowiki>#invoke:Navbox</nowiki>|navbox|3=text=$1}}|nějaký text}} byl zcela ignorován, bez ohledu na to, z jaké stránky byl použit.
Použitím možnosti <code>wrappers</code> k určení [[Template:Navbox]] jako obalu můžeme zajistit, aby {{tmpl|0={{tlc|<nowiki>#invoke:Navbox</nowiki>|main|3=text=$1}}|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ů.

<syntaxhighlight lang="lua">
local args = getArgs(frame, {
	wrappers = 'Template:Wrapper template'
})
</syntaxhighlight>

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

{{Note|text=
{{Ordered list
|1=
Modul automaticky zjistí, zda je volán z podstránky <code>/sandbox</code> šablony wrapperu, takže není potřeba explicitně specifikovat stránky sandboxu.
|2=
Volba <code>wrappers</code> fakticky změní výchozí hodnotu možností <code>frameOnly</code> a <code>parentOnly</code>.
Pokud by například <code>parentOnly</code> bylo explicitně nastaveno na <code>false</code> s nastaveným <code>wrappers</code>, 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 <code>wrappers</code> a není k dispozici žádný nadřazený rámec, modul vždy získá argumenty z rámce předaného do <code>getArgs</code>.
}}
}}

=== Zápis do <code>args</code> tabulky ===
Někdy může být užitečné zapsat nové hodnoty do tabulky <code>args</code>.
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 <code>args</code>.)

<syntaxhighlight lang="lua">
args.foo = 'nějaká hodnota'
</syntaxhighlight>

Toto chování je možné změnit pomocí možností <code>readOnly</code> a <code>noOverwrite</code>.
Pokud je nastaveno <code>readOnly</code>, není možné do tabulky <code>args</code> zapisovat vůbec žádné hodnoty.
Pokud je nastaveno <code>noOverwrite</code>, 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 {{tlc|<nowiki>#invoke:...</nowiki>}}.

<span id="Ref_tags"></span>
=== Tagy Ref ===
Tento modul používá [[mw:Special:MyLanguage/Extension:Scribunto/Lua reference manual#Metatables|metatables]] k načítání argumentů z {{tlc|<nowiki>#invoke:...</nowiki>}}.
To umožňuje přístup k argumentům rámce i argumentům nadřazeného rámce bez použití funkce <code>pairs()</code>.
To může pomoci, pokud vašemu modulu mohou být předány tagy {{xtag|ref}} jako vstup.

Jakmile jsou tagy {{xtag|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í <code>pairs()</code> 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 <code>pairs(args)</code>.

<span id="Known_limitations"></span>
=== 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 <code>args</code>, včetně operátoru <code>#</code>, funkce <code>next()</code> a funkcí v knihovně <code>table</code>.
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ů.

<span id="Tests"></span>
== Testy ==
{{ModuleQuality}}
<includeonly>{{Sandbox other||
<!-- Categories below this line; interwikis at Wikidata -->
[[Category:Lua metamodules{{#translation:}}]]
}}</includeonly><noinclude>
[[Category:Module documentation pages{{#translation:}}]]
</noinclude>
| #default=
  {{#invoke:Template translation|renderTranslatedTemplate|template=Module:Arguments/doc|noshift=1|uselang={{int:lang}}}}
}}