Module:Arguments/doc/cs
Toto je dokumentace podstránky Module:Arguments/doc. Obsahuje informace o použití, kategorie a další obsah, který není součástí původní stránky Module. |
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 se používá v systémových zprávách. Jeho změny mohou způsobit okamžité změny uživatelského rozhraní MediaWiki. Chcete-li se vyhnout rozsáhlému narušení, měly by být všechny změny nejprve otestovány na podstránce /sandbox nebo /testcases tohoto module nebo ve vašem vlastním uživatelském prostoru.Testované změny pak mohou být přidány v jedné jediné úpravě do tohoto modulu. Před implementací prodiskutujte jakékoli změny na diskusní stránce. |
Tento modul je hodnocen jako připraven pro všeobecné použití. Dosáhl zralé formy a předpokládá se, že je bez chyb a je připraven k použití, kdekoli je to vhodné. Je připraven zmínit se na stránkách nápovědy a dalších zdrojích jako možnost, kterou se mohou naučit noví uživatelé. Aby se snížilo zatížení serveru a špatný výstup, měl by být vylepšen pomocí testování v izolovaném prostoru spíše než opakovanými úpravami metodou pokus-omyl. |
Tento modul podléhá stránkové ochraně. Je to vysoce viditelný modul, který používá velmi velký počet stránek. Protože vandalismus nebo chyby by ovlivnily mnoho stránek a dokonce i triviální úpravy by mohly způsobit značné zatížení serverů, je chráněn před úpravami. |
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
})
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.
{{#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
- Pokud nastavíte obě možnosti
frameOnly
aparentOnly
, modul nenačte z{{#invoke:...}}
vůbec žádné argumenty. To pravděpodobně není to, co chcete. - 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í nastavenoparentOnly
, v takovém případě nebudou použity žádné argumenty) a volbyparentFirst
aframeOnly
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.
}
})
- Modul automaticky zjistí, zda je volán z podstránky
/sandbox
šablony wrapperu, takže není potřeba explicitně specifikovat stránky sandboxu. - Volba
wrappers
fakticky změní výchozí hodnotu možnostíframeOnly
aparentOnly
. Pokud by napříkladparentOnly
bylo explicitně nastaveno nafalse
s nastavenýmwrappers
, 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. - 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 dogetArgs
.
<span id="Writing_to_the_args
_table">
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
Module:Arguments | success: 51, error: 0, skipped: 0 |
Module:Arguments/sandbox | success: 51, error: 0, skipped: 0 |
- See test cases
- Diff sandbox code