Extension:Scribunto/Lua reference manual
Tato příručka je založena na rozšíření Lua . Některé části jsou odvozeny z Lua 5.1 referenčního manuálu, který je dostupný pod MIT licencí.
Tato stránka dokumentuje nejnovější verzi rozšíření Scribunto. Některé funkce ještě nemusí být nasazeny. |
Úvod
Začínáme
Na wiki MediaWiki s povoleným Scribunto vytvořte stránku s názvem začínajícím na Module:
, například "Module:Bananas".
Na tuto novou stránku zkopírujte následující text:
local p = {} --p znamená balíček
function p.hello( frame )
return "Hello, world!"
end
return p
Uložte to a poté na jinou (nemodulovou) stránku, jako na sandbox page, napište:
{{#invoke:Bananas|hello}}
Až na to, že byste měli nahradit "Bananas" jakkoli, co jste nazvali modul. To zavolá funkci "hello" exportovanou z tohoto modulu. {{#invoke:Bananas|hello}}
bude nahrazeno textem, který funkce vrátila, v tomto případě "Hello, world!"
Obecně je dobré vyvolat kód Lua z kontextu šablony. To znamená, že z pohledu volající stránky je syntaxe nezávislá na tom, zda je logika šablony implementována v Lua nebo ve wikitextu. Také se vyhne zavedení další složité syntaxe do jmenného prostoru obsahu wiki.
Struktura modulu
Samotný modul musí vrátit tabulku Lua obsahující funkce, které může {{#invoke:}}
volat.
Obecně, jak je uvedeno výše, je deklarována lokální proměnná obsahující tabulku, funkce jsou přidány do této tabulky a tabulka je vrácena na konec kódu modulu.
Jakékoli funkce, které nejsou přidány do této tabulky, ať už lokální nebo globální, nebudou přístupné pro {{#invoke:}}
, ale globální mohou být přístupné z jiných modulů načtených pomocí require()
.
Obecně je dobrým stylem modulu deklarovat všechny funkce a proměnné jako místní.
Přístup k parametrům z wikitextu
Funkce volané {{#invoke:}}
budou předány jediným parametrem, kterým je frame objekt. Pro přístup k parametrům předávaným do {{#invoke:}}
bude kód obvykle používat tabulku args
daného objektu frame. Je také možné přistupovat k parametrům předávaným do šablony obsahující {{#invoke:}}
pomocí frame:getParent()
a přístupu k args
daného frame.
Tento objekt frame se také používá pro přístup ke kontextově specifickým funkcím analyzátoru wikitextu, jako je volání funkcí analyzátoru, rozšiřující šablony a rozšiřování libovolných řetězců wikitextu .
Vracející se text
Funkce modulu by měla obvykle vracet jeden řetězec; jakékoli vrácené hodnoty budou předány přes tostring() a poté zřetězeny bez oddělovače. Tento řetězec je začleněn do wikitextu jako výsledek {{#invoke:}}
.
V tomto okamžiku analýzy stránky již byly šablony rozšířeny, funkce analyzátoru a značky rozšíření již byly zpracovány a pre-save transforms (tj. už se stalo). Modul proto nemůže tyto funkce použít ve svém výstupním textu. Pokud například modul vrátí "Hello, [[world]]! {{welcome}}"
, stránka bude číst "Hello, world! {{welcome}}".
Na druhou stranu subst je zpracováno v dřívější fázi zpracování, takže s {{subst:#invoke:}}
budou zpracovány pouze další pokusy o substituci. Protože neúspěšné nahrazení zůstane ve wikitextu, bude poté zpracováno při další úpravě. Tomu je třeba se obecně vyhnout.
Dokumentace modulu
Scribunto umožňuje dokumentaci modulů automatickým přidružením modulu k dokumentační stránce wikitextu. Ve výchozím nastavení se pro tento účel používá podstránka modulu "/doc" a je umístěna nad zdrojovým kódem modulu na stránce modulu. Například dokumentace pro "Module:Bananas" by byla na "Module:Bananas/doc".
To lze nakonfigurovat pomocí stránky Nápověda:Systémové zprávy :
scribunto-doc-page-name
— nastaví název stránky použité pro dokumentaci. Název modulu (bez předpony Module:) je předán jako$1
. Pokud jsou ve jmenném prostoru modulu, zde uvedené stránky budou interpretovány jako wikitext spíše než zdroj Lua a nelze je použít s{{#invoke:}}
. Výchozí hodnota je "Module:$1/doc", tj. podstránka /doc modulu. Všimněte si, že v této zprávě nelze použít funkce analyzátoru a další rozšíření složené závorky.scribunto-doc-page-does-not-exist
— zpráva se zobrazí, pokud stránka dokumentu neexistuje. Název stránky je předán jako$1
. Výchozí hodnota je prázdná.scribunto-doc-page-show
— zpráva se zobrazí, pokud stránka dokumentu existuje. Název stránky je předán jako$1
. Výchozí nastavení je převést stránku dokumentace.scribunto-doc-page-header
— záhlaví zobrazené při prohlížení samotné stránky dokumentace. Název modulu (s prefixem Module:), který je dokumentován, je předán jako$1
. Ve výchozím nastavení se jednoduše zobrazí krátké vysvětlení kurzívou.
Upozorňujeme, že moduly nelze přímo kategorizovat a nelze do nich přímo přidávat odkazy na interwiki.
Ty lze umístit na stránku dokumentace do tagů <includeonly>...</includeonly>
, kde budou aplikovány na modul, když se stránka dokumentace přenese na stránku modulu.
Přejmenování nebo přesun modulů
Chcete-li modul přejmenovat nebo přesunout, použijte odkaz Přesunout stránku na postranním panelu Nástroje. Můžete přesunout jak samotný modul, tak i podstránku obsahující jeho dokumentaci.
Chcete-li ručně vytvořit přesměrování modulu, použijte následující syntaxi:
return require [[Module:Foo]]
Nahraďte Foo
názvem modulu, na který chcete přesměrovat.
Jazyk Lua
Tokeny
Jméno (nazývané také identifikátor) v Lua může být libovolný řetězec písmen, číslic a podtržítek, který nezačíná číslicí. V názvech se rozlišují velká a malá písmena; "foo", "Foo" a "FOO" jsou různá jména.
Následující klíčová slova jsou vyhrazena a nelze je použít jako názvy:
and
break
do
else
elseif
end
false
for
function
if
in
local
nil
not
or
repeat
return
then
true
until
while
Názvy začínající podtržítkem následovaným velkými písmeny jsou vyhrazeny pro interní globální proměnné Lua.
Další tokeny jsou:
#
%
(
)
*
+
,
-
--
.
..
...
/
:
;
<
<=
=
==
>
>=
[
]
^
{
}
~=
Komentáře
Komentář začíná znakem --
kdekoli mimo řetězec. Pokud za --
bezprostředně následuje úvodní dlouhá závorka, komentář pokračuje do odpovídající uzavírací dlouhé závorky. Jinak komentář běží na konec aktuálního řádku.
-- Komentář v Lua začíná dvojitou pomlčkou a běží na konec řádku.
--[[ Víceřádkové řetězce a komentáře
jsou ohraničeny dvojitými hranatými závorkami. ]]
--[=[ Komentáře jako tento mohou mít vnořené další ---[[komentáře]]. ]=]
--[==[ Komentáře jako tento mohou mít i jiné
--[===[ dlouhé --[=[komentáře]=] --vnořené
]===] vícekrát, i když jsou všechny
--[[ neohraničeny odpovídajícími dlouhými závorkami! ]===]
]==]
Datové typy
Lua je dynamicky typovaný jazyk, což znamená, že proměnné a argumenty funkcí nemají žádný typ, pouze hodnoty, které jsou jim přiřazeny. Všechny hodnoty nesou typ.
Lua má osm základních datových typů, avšak pouze šest je relevantních pro rozšíření Scribunto. Funkce type()
vrátí typ hodnoty.
Funkce tostring()
převede hodnotu na řetězec. Funkce tonumber()
převede hodnotu na číslo, pokud je to možné, a jinak vrátí nulu. Neexistují žádné explicitní funkce pro převod hodnoty na jiné datové typy.
Čísla jsou automaticky převedena na řetězce při použití tam, kde se očekává řetězec, např. při použití s operátorem zřetězení. Řetězce rozpoznávané funkcí tonumber()
jsou automaticky převedeny na čísla při použití s aritmetickými operátory. Když se očekává logická hodnota, všechny hodnoty kromě nula a false jsou považovány za pravdivé.
nil
"nil"
je datový typ nil
, který představuje absenci hodnoty.
Nil nelze použít jako klíč v tabulce a není žádný rozdíl mezi nepřiřazeným klíčem tabulky a klíčem, kterému je přiřazena nulová hodnota.
Při převodu na řetězec je výsledek "nil"
. Při převodu na booleovskou hodnotu je nil považováno za nepravdivé.
Poznámka: Lua v některých omezených situacích rozlišuje mezi nil
a vůbec ničím.
Například tostring(nil)
vrátí "nil"
, ale tostring()
vyvolá chybu, protože první parametr je povinný.
Toto rozlišení je zvláště důležité pro funkci select().
boolean
Booleovské hodnoty jsou true
a false
.
Při převodu na řetězec je výsledek "true"
nebo "false"
.
Na rozdíl od mnoha jiných jazyků nemusí být booleovské hodnoty přímo převedeny na čísla. A na rozdíl od mnoha jiných jazyků, pouze false
a nul jsou považovány za false pro booleovskou konverzi. Číslo 0 a prázdný řetězec se považují za pravdivé.
řetězec
Lua řetězce jsou považovány za sérii 8bitových bajtů. Je na aplikaci, aby je interpretovala v jakémkoli konkrétním kódování.
Řetězcové literály mohou být odděleny buď jednoduchými nebo dvojitými uvozovkami ('
nebo "
). Jako JavaScript a na rozdíl od PHP mezi nimi není žádný rozdíl. Jsou rozpoznány následující sekvence escape:
\a
(zvonek, byte 7)\b
(backspace, byte 8)\t
(horizontální tab, byte 9)\n
(nový řádek, byte 10)\v
(vertikální tab, byte 11)\f
(form feed, byte 12)\r
(carriage return, byte 13)\"
(double quote, byte 34)\'
(single quote, byte 39)\\
(backslash, byte 92)
Doslovný nový řádek může být také zahrnut do řetězce tak, že jej předchází zpětné lomítko. Bajty lze také zadat pomocí escape sekvence '\ddd', kde ddd je desetinná hodnota bajtu v rozsahu 0–255. Chcete-li zahrnout znaky Unicode pomocí sekvencí escape, musí být specifikovány jednotlivé bajty pro kódování UTF-8. Obecně bude jednodušší zadávat znaky Unicode přímo.
Doslovné řetězce lze také definovat pomocí dlouhých závorek.
Úvodní dlouhá závorka se skládá z otevírací hranaté závorky následované nulou nebo více stejnými znaménky, za nimiž následuje další otevírací hranatá závorka, např. [[
, [=[
nebo [=====[
.
Otevírací dlouhá závorka musí odpovídat odpovídající zavírací dlouhé závorce, např. ]]
, ]=]
nebo ]=====]
.
Ve speciálním případě, pokud je po úvodní dlouhé závorce bezprostředně následován nový řádek, nový řádek není zahrnut do řetězce, ale nový řádek těsně před uzavírací dlouhou závorkou je zachován.
Řetězce oddělené dlouhými závorkami neinterpretují escape sekvence.
-- dlouhý řetězec
foo = [[
bar\tbaz
]]
-- je ekvivalentní tomuto řetězci oddělenému uvozovkami
foo = 'bar\\tbaz\n'
Všimněte si, že všechny řetězce jsou považovány za pravdivé, když jsou převedeny na booleovské. To je na rozdíl od většiny ostatních jazyků, kde je prázdný řetězec obvykle považován za nepravdivý.
číslo
Lua má pouze jeden číselný typ, který je obvykle interně reprezentován jako 64bitová hodnota s plovoucí desetinnou čárkou s dvojitou přesností. V tomto formátu mohou být celá čísla mezi -9007199254740991
(-253 + 1) a 9007199254740991
(253 - 1) reprezentována přesně. Větší čísla a čísla se zlomkovou částí mohou trpět zaokrouhlovací chybou.
Číselné konstanty se zadávají pomocí tečky (.
) jako oddělovač desetinných míst a bez oddělovačů seskupení, např. 123456.78
.
Čísla mohou být také reprezentována pomocí E notace bez mezer, např. 1.23e-10
e-10, 1.23e-10
e20 nebo 1.23e-10
e5.
Celá čísla mohou být také specifikována v hexadecimálním zápisu pomocí předpony 0x
, např. 0x3A
.
S malým počtem číselných hodnot se zachází zvláštním způsobem:
- Kladné a záporné nekonečno, které jsou vyhodnoceny jako větší nebo menší než každé jiné číslo (kromě NaN - viz níže). Lze k nim přistupovat dvěma způsoby: prostřednictvím knihovny
math
, jakomath.huge
a-math.huge
, nebo pomocí numerických operací jako1/0
a-1/0
. - Lua občas rozlišuje
0
a-0
(více informací o nulách se znaménkem viz IEEE 754).0
a-0
jsou přísně ekvivalentní pro téměř všechny účely, ale chovají se odlišně v malém počtu numerických operací (např.1/0
vrátí nekonečno , zatímco1/-0
vrací záporné nekonečno). Rozdíl také ovlivňuje převody z čísla na řetězec (a naopak). - Pozitivní a negativní NaN (znamenající Not a Number). Žádná konstanta není poskytnuta pro žádnou z nich, ale
0/0
se vyhodnotí jako negativní NaN. Všimněte si, že obě NaN mají jedinečnou kvalitu, kterou jakékoli srovnání, které je zahrnuje, vyhodnotí jakofalse
(což znamená, že se ani nevyhodnotí jako sobě rovné). Jediný praktický rozdíl mezi těmito dvěma je převod typu do az řetězce (viz níže).
Všimněte si, že všechna čísla (včetně 0
, -0
, nekonečna a NaN) jsou při převodu na booleovské hodnoty považována za pravdivá. To je na rozdíl od většiny ostatních jazyků, kde se 0
obvykle považuje za nepravdu. Při převodu na řetězec jsou konečná čísla reprezentována v desítkové soustavě a zápisu E, pokud je 1014 nebo větší (např. "1e+14"
); nekonečna jsou "inf"
a "-inf"
; a NaN jsou "nan"
a "-nan"
.
Známá chyba: interpret Lua bude se všemi výskyty 0
a -0
zacházet jako s tím, který z nich narazí jako první když je skript zkompilován, což znamená, že návratové hodnoty tostring(0)
, 1/-0
(a tak dále) jsou ovlivněny tím, kde se v kódu vyskytují.
To může způsobit neočekávané výsledky, zejména pokud jsou všechny instance 0
při návratu převedeny na "-0"
.
V případě potřeby to lze obejít vygenerováním nulových hodnot pomocí tonumber("0")
a tonumber("-0")
, které zřejmě nezpůsobují ani nejsou ovlivněny problém. Viz [1].
tabulka
Tabulky Lua jsou asociativní pole, podobně jako pole PHP a objekty JavaScriptu.
Tabulky se vytvářejí pomocí složených závorek. Prázdná tabulka je {}
. Pro naplnění polí při vytváření může být do složených závorek zahrnut seznam specifikátorů polí oddělených čárkou nebo středníkem. Mohou mít několik podob:
- expression2|expression1]]] = expression2</tvar> používá (první) hodnotu expression1 jako klíč a (první) hodnotu expression2 jako hodnotu.
name = expression
|name]] = expression</tvar> je ekvivalentní["
name"] = expression
expression
je zhruba ekvivalentní[i] = výraz
, kde i je celé číslo začínající na 1 a zvyšující se s každou specifikací pole tohoto formuláře. Pokud se jedná o poslední specifikátor pole a výraz má více hodnot, použijí se všechny hodnoty; jinak zůstane zachováno pouze první.
K polím v tabulce se přistupuje pomocí zápisu v závorkách, např. table[key]
. K řetězcovým klíčům, které jsou také platné names, lze také přistupovat pomocí tečkové notace, např. table.key
odpovídá table['key']
. Volání funkce, která je hodnotou v tabulce, může používat zápis dvojtečkou. Například table:func( ... )
, což odpovídá table['func']( table, ... )
nebo table.func( table, ... )
.
Pole (také nazývané sekvence nebo seznam) je tabulka s nenulovými hodnotami pro všechna kladná celá čísla od 1 do N a bez hodnoty (nula) pro všechna kladná celá čísla větší než N. Mnoho funkcí Lua pracuje pouze s poli a ignoruje klíče s kladnými celými čísly.
Na rozdíl od mnoha jiných jazyků, jako je PHP nebo JavaScript, lze jako klíč použít jakoukoli hodnotu kromě nil a NaN a neprovádí se žádná konverze typu. Všechny jsou platné a odlišné:
-- Vytvoření tabulky
t = {}
t["foo"] = "foo"
t.bar = "bar"
t[1] = "jedna"
t[2] = "dva"
t[3] = "tři"
t[12] = "číslo dvanáct"
t["12"] = "řetězec dvanáct"
t[true] = "true"
t[tonumber] = "ano, i funkce mohou být klíče tabulky"
t[t] = "ano, tabulka může být také klíčem k tabulce. Dokonce i sama o sobě."
-- Vznikne tak tabulka zhruba ekvivalentní výše uvedené
t2 = {
foo = "foo",
bar = "bar",
"jedna",
"dva",
[12] = "číslo dvanáct"
["12"] = "řetězec dvanáct"
"tři"
[true] = "true",
[tonumber] = "ano, i funkce mohou být klíče tabulky"
}
t2[t2] = "ano, tabulka může být také klíčem k tabulce. Dokonce i sama o sobě."
Podobně jakákoliv hodnota kromě nil může být uložena jako hodnota v tabulce. Uložení nil je ekvivalentní smazání klíče z tabulky a přístup k libovolnému klíči, který nebyl nastaven, bude mít za následek hodnotu nil.
Všimněte si, že tabulky nejsou nikdy implicitně zkopírovány v Lua. Pokud je funkci předána jako argument tabulka a funkce manipuluje s klíči nebo hodnotami v tabulce, tyto změny budou viditelné ve volajícím.
Při převodu na řetězec je obvyklým výsledkem "tabulka", ale může být přepsána pomocí __tostring
metametody. Dokonce i prázdná tabulka je považována za pravdivou jako boolean.
funkce
Funkce v Lua jsou priritní hodnoty: Mohou být vytvořeny anonymně, předány jako argumenty, přiřazeny k proměnným a tak dále.
Funkce se vytvářejí pomocí klíčového slova function
a volají se pomocí závorek. Syntactic sugar je dostupný pro pojmenované funkce, lokální funkce a funkce, které fungují jako členské funkce tabulky. Podrobnosti viz Deklarace funkcí a Volání funkcí níže.
Funkce Lua jsou uzavřené, což znamená, že udržují odkaz na rozsah, ve kterém jsou deklarovány, a mohou přistupovat a manipulovat s proměnnými v tomto rozsahu.
Stejně jako tabulky, pokud je funkce přiřazena jiné proměnné nebo předána jako argument jiné funkci, je to stále stejný základní "funkční objekt", který bude volán.
Po převodu na řetězec je výsledkem "funkce".
Nepodporované typy
Typ userdata se používá k uchování neprůhledných hodnot pro rozšíření Lua napsaná v jiných jazycích. Například uživatelská data mohou být použita k udržení ukazatele C nebo struktury. Aby bylo možné používat Scribunto v hostitelských prostředích, kde není povolen vlastní kompilovaný kód, žádná taková rozšíření se nepoužívají.
Typ thread (vlákno) představuje úchyty pro rutiny, které nejsou dostupné v sandboxu Scribunto.
Upvalues (vyšší hodnoty)
Existuje přísný limit na max. 60 jedinečných hodnot zpřístupněných uvnitř funkce. Upvalue je hodnota deklarovaná mimo funkci a použitá v ní. Jak se hodnoty počítají:
- proměnné (tabulka s mnoha prvky se počítá jako jedna vyšší hodnota)
- funkce (pouze ty přímo volané z dané funkce, nikoli jejich závislosti)
Překročení limitu může být vyvoláno použitím takové proměnné nebo funkce, nikoli její pouhou přítomností nebo dostupností. Opakovaný přístup ke stejné hodnotě limit dále nevyčerpává.
Meta tabulky
Každá tabulka může mít přidruženou tabulku známou jako metatable. Pole v metatabulce používají některé operátory a funkce k určení odlišného nebo záložního chování pro tabulku. K metatabulce pro tabulku lze přistupovat pomocí funkce getmetatable() a nastavit ji pomocí funkce setmetatable().
Při přístupu k jejich meta funkcím se k polím metatabulek přistupuje jako s rawget().
Metatable pole, která ovlivňují samotnou tabulku, jsou:
- __index
- používá se, když by přístup k tabulce
t[key]
vrátil nulu. Pokud je hodnotou tohoto pole tabulka, přístup se bude v této tabulce opakovat, tj.__index[key]
(což může vyvolat __index metatabulky této tabulky). Pokud je hodnotou tohoto pole funkce, funkce bude volána jako__index( t, key )
. Funkce rawget() tuto metametodu obchází. - __newindex
- používá se při přiřazování klíče k tabulce
t[key] = value
, kderawget( t, key )
vrátí nulu. Pokud je hodnotou tohoto pole tabulka, přiřazení bude provedeno k této tabulce, tj.__newindex[key] = value
(což může vyvolat metatabulku této tabulky __newindex). Pokud je hodnotou tohoto pole funkce, funkce bude volána jako__newindex( t, key, value )
. Funkce rawset() tuto metametodu obchází. - __call
- používá se, pokud je v tabulce použita syntaxe volání funkce,
t( ··· )
. Hodnota musí být funkce, která se nazývá něco jako__call( t, ··· )
. - __mode
- používá se k vytvoření tabulek obsahujících slabé reference. Hodnota musí být řetězec. Ve výchozím nastavení nebude žádná hodnota, která je použita jako klíč nebo jako hodnota v tabulce, shromažďována. Pokud však toto metapole obsahuje písmeno 'k', mohou být klíče shromážděny nesmyslně, pokud neexistují žádné slabé odkazy, a pokud obsahuje hodnoty 'v', mohou být. V obou případech se z tabulky odstraní odpovídající klíč i hodnota. Všimněte si, že chování není definováno, pokud je toto pole změněno poté, co je tabulka použita jako metatabulka.
Mezi další metatabulková pole patří:
Poznámka: V Lua všechny řetězce také sdílejí jednu metatabulku, ve které __index
odkazuje na string
tabulku. Tato metatabulka není ve Scribuntu přístupná, stejně jako odkazovaná tabulka string
. Tabulka řetězců dostupná pro moduly je kopií.
Proměnné
Proměnné jsou místa, která uchovávají hodnoty. V Lua jsou tři druhy proměnných: globální proměnné, lokální proměnné a pole tabulky.
Jméno představuje globální nebo lokální proměnnou (nebo argument funkce, což je jen druh lokální proměnné). Předpokládá se, že proměnné jsou globální, pokud nejsou explicitně deklarovány jako lokální pomocí klíčového slova local
. Každá proměnná, které nebyla přiřazena žádná hodnota, je považována za nulovou.
Globální proměnné jsou uloženy ve standardní Lua tabulce zvané environment (prostředí). Tato tabulka je často dostupná jako globální proměnná _G
. Pro tuto tabulku globálních proměnných je možné nastavit metatabulku. Metametody __index a __newindex budou volány pro přístupy a přiřazení ke globálním proměnným stejně jako pro přístupy a přiřazení k polím v jakékoli jiné tabulce.
K prostředí pro funkci lze přistupovat pomocí funkce getfenv() a měnit pomocí funkce setfenv(). Ve Scribuntu jsou tyto funkce přísně omezeny, pokud jsou vůbec dostupné.
Lokální proměnné jsou lexikálně vymezeny. Podrobnosti naleznete na stránce Deklarace místních proměnných.
Výrazy
Výraz je něco, co má hodnoty: literály (čísla, řetězce, pravda, nepravda, nula), anonymní deklarace funkcí, konstruktory tabulek, odkazy na proměnné, volání funkcí, výraz vararg, zabalené výrazy v závorkách, unární operátory aplikované na výrazy a výrazy kombinované s binárními operátory.
Většina výrazů má jednu hodnotu. Volání funkcí a výraz vararg může mít libovolné číslo. Všimněte si, že zabalením volání funkce nebo výrazu vararg do závorek ztratíte všechny kromě první hodnoty.
Seznamy výrazů jsou seznamy výrazů oddělených čárkami. Všechny kromě posledního výrazu jsou nuceny na jednu hodnotu (vypuštění dalších hodnot nebo použití nuly, pokud výraz nemá žádné hodnoty). Všechny hodnoty z posledního výrazu jsou zahrnuty do hodnot seznamu výrazů.
Aritmetické operátory
Lua podporuje obvyklé aritmetické operátory: sčítání, odčítání, násobení, dělení, modul, umocňování a negace.
Když jsou všechny operandy čísla nebo řetězce, pro které tonumber() vrací nenulovou hodnotu, mají operace svůj obvyklý význam.
Pokud je některým z operandů tabulka s vhodnou metamethodou, bude zavolána metametoda.
Operátor | Funkce | Příklad | Metametoda | Poznámky |
---|---|---|---|---|
+ | Addition | a + b | __add | |
- | Subtraction | a - b | __sub | |
* | Multiplication | a * b | __mul | |
/ | Division | a / b | __div | dělení nulou není chyba; NaN nebo nekonečno bude vráceno |
% | Modulo | a % b | __mod | definované jako a % b == a - math.floor( a / b ) * b
|
^ | Exponentiation | a ^ b | __pow | jsou povoleny neceločíselné exponenty |
- | Negation | -a | __unm |
Relační operátory
Relační operátory v Lua jsou ==
, ~=
, <
, >
, <=
a >=
. Výsledkem relačního operátoru je vždy logická hodnota.
Rovnost (==
) nejprve porovná typy svých operandů. Pokud se liší, výsledek je nepravdivý. Poté porovná hodnoty: nula, boolean, číslo a řetězec jsou porovnány očekávaným způsobem. Funkce jsou stejné, pokud odkazují na přesně stejný funkční objekt. function() end == function() end
vrátí false, protože porovnává dvě různé anonymní funkce. Tabulky jsou standardně porovnávány stejným způsobem, ale to lze změnit pomocí __eq metametody.
Nerovnost (~=
) je přesnou negací rovnosti.
Pro operátory řazení platí, že pokud jsou oba čísla nebo oba řetězce, jsou porovnány přímo. Dále se zkontrolují metametody:
a < b
používá__lt
a <= b
používá__le
, pokud je k dispozici, nebo pokud je k dispozici__lt
, považuje se za ekvivalentní nanot ( b < a )
a > b
je považováno za ekvivalentníb < a
a >= b
je považováno za ekvivalentníb <= a
Pokud potřebné metametody nejsou k dispozici, dojde k chybě.
Logické operátory
Logické operátory jsou and
, or
a not
. Všechny používají standardní výklad, kde nula a nepravda jsou považovány za nepravdivé a cokoli jiného je považováno za pravdivé.
Pro and
, pokud je levý operand považován za nepravdivý, pak je vrácen a druhý operand není vyhodnocen. Jinak je vrácen druhý operand.
Pro or
, pokud je levý operand považován za pravdivý, pak je vrácen a druhý operand není vyhodnocen. Jinak je vrácen druhý operand.
Pro not
je výsledek vždy pravdivý nebo nepravdivý.
Všimněte si, že and
a or
zkratují. Například foo() or bar()
zavolá bar()
pouze v případě, že foo()
vrací false nebo nil jako svou první hodnotu.
Operátor zřetězení
Operátor zřetězení jsou dvě tečky, používané jako a .. b
. Pokud jsou oba operandy čísla nebo řetězce, jsou převedeny na řetězce a zřetězeny. Jinak, pokud je k dispozici __concat metamethod, použije se. V opačném případě se objeví chyba.
Všimněte si, že řetězce Lua jsou neměnné a Lua neposkytuje žádný druh "tvůrce řetězců", takže smyčka, která opakovaně dělá a = a .. b
, bude muset vytvořte nový řetězec pro každou iteraci a případně staré řetězce posbírat. Pokud mnoho řetězců potřebuje zřetězení, může být rychlejší použít string.format() nebo vložit všechny řetězce do sekvence a použít na konci table.concat().
Operátor délky
Operátor délky je #
, používá se jako #a
. Pokud je a
řetězec, vrátí délku v bajtech. Pokud a
je tabulka sekvence, vrátí délku sekvence.
Pokud a
je tabulka, která není sekvencí, může #a
vrátit 0 nebo jakoukoli hodnotu N, takže [N] není nula a [N+1] je nula, i když u vyšších indexů existují nenulové hodnoty. Například,
-- Toto není posloupnost, protože a[3] je nula a a[4] není.
a = { 1, 2, nil, 4 }
-- To může mít výstup 2 nebo 4.
-- A to se může změnit, i když se tabulka nezmění.
mw.log( #a )
Přednost operátora
Priorita operátora Lua nebo pořadí operací, od nejvyšší po nejnižší:
^
not
#
-
(negace)*
/
%
+
-
(odčítání)..
<
>
<=
>=
~=
==
and
or
V rámci úrovně priority je většina binárních operátorů asociativních vlevo, tj. a / b / c
je interpretováno jako (a / b) / c
. Umocňování a zřetězení jsou asociativní vpravo, tj. a ^ b ^ c
se interpretuje jako a ^ (b ^ c)
.
Volání funkcí
Volání funkcí Lua vypadá jako ve většině ostatních jazyků: Název následovaný seznamem argumentů v závorkách:
func( seznam-výrazů )
Jak je obvyklé u seznamů výrazů v Lua, poslední výraz v seznamu může poskytnout více hodnot argumentů.
Pokud je funkce volána s menším počtem hodnot v seznamu výrazů, než je argumentů v definici funkce, budou mít další argumenty nulovou hodnotu. Pokud seznam výrazů obsahuje více hodnot, než je argumentů, nadbytečné hodnoty se zahodí. Je také možné, aby funkce přijala proměnný počet argumentů. Podrobnosti naleznete na stránce Deklarace funkcí.
Lua také umožňuje přímé volání návratové hodnoty funkce, tj. func()()
. Pokud je k určení funkce, která má být volána, zapotřebí výraz složitější než proměnný přístup, lze místo proměnného přístupu použít výraz v závorkách.
Lua má syntaktický sugar pro dva běžné případy. První je, když je tabulka používána jako objekt a funkce má být volána jako metoda na objektu. Syntaxe
table:name( seznam-výrazů )
je přesně ekvivalentní
table.name( table, seznam-výrazů )
Druhým běžným případem je Luaova metoda implementace pojmenování argumentů předáním tabulky obsahující mapování jména na hodnotu jako jediného pozičního argumentu do funkce. V tomto případě mohou být závorky kolem seznamu argumentů vynechány. To také funguje, pokud má být funkci předán jeden doslovný řetězec. Například volání
func{ arg1 = exp, arg2 = exp } func"string"
jsou ekvivalentní s
func( { arg1 = exp, arg2 = exp } ) func( "string" )
Tyto mohou být kombinovány. Následující volání jsou ekvivalentní:
table:name{ arg1 = exp, arg2 = exp } table.name( table, { arg1 = exp, arg2 = exp } )
Deklarace funkcí
Syntaxe deklarace funkce vypadá takto:
function nameoptional ( var-listoptional )
blok
end
Všechny proměnné ve var-list (seznam proměnných) jsou pro funkci lokální, s hodnotami přiřazenými ze seznamu výrazů ve volání funkce. Uvnitř bloku mohou být deklarovány další lokální proměnné.
Když je funkce volána, příkazy v bloku jsou provedeny poté, co jsou vytvořeny lokální proměnné odpovídající var-listu a přiřazeny hodnoty. Pokud je dosaženo příkazu return, blok se opustí a hodnoty výrazu volání funkce jsou hodnoty dané příkazem return. Pokud provádění dosáhne konce bloku funkce, aniž by narazilo na příkaz return, bude mít výsledek výrazu volání funkce nulové hodnoty.
Funkce Lua jsou lexikální uzávěry. Běžným idiomem je deklarovat "soukromé statické" proměnné jako místní v rozsahu, kde je funkce deklarována. Například,
-- To vrátí funkci, která ke svému argumentu přidá číslo
function makeAdder( n )
return function( x )
-- Proměnná n z vnějšího rozsahu je zde k dispozici pro přidání k x
return x + n
end
end
local add5 = makeAdder( 5 )
mw.log( add5( 6 ) )
-- tiskne 11
Funkce může být deklarována tak, aby přijímala proměnný počet argumentů, zadáním ...
jako poslední položku ve var-listu:
V rámci bloku lze použít varargs výraz ...
, jehož výsledkem jsou všechny hodnoty navíc ve volání funkce. Například,
local join = function ( separator, ... )
-- získat další argumenty jako novou tabulku
local args = { ... }
-- získat počet argumentů navíc, správně
local n = select( '#', ... )
return table.concat( args, separator, 1, n )
end
join( ', ', 'foo', 'bar', 'baz' )
-- vrátí řetězec "foo, bar, baz"
Funkce select() je navržena pro práci s výrazem varargs. Konkrétně by měl být použit select( '#', ... )
namísto #{ ... }
, abyste spočítali počet hodnot ve výrazu varargs, protože { ... }
nemusí být [[#sequence|sekvence] ].
Lua poskytuje syntaktický sugar pro kombinaci deklarace funkce a přiřazení k proměnné. Podrobnosti najdete na stránce Prohlášení deklarace funkce.
Všimněte si, že to nebude fungovat:
local factorial = function ( n )
if n <= 2 then
return n
else
return n * factorial( n - 1 )
end
end
Protože deklarace funkce je zpracována před dokončením příkazu přiřazení lokální proměnné, "faktoriální" uvnitř těla funkce odkazuje na (pravděpodobně nedefinovanou) proměnnou tohoto jména ve vnějším rozsahu. Tomuto problému se lze vyhnout tak, že nejprve deklarujete lokální proměnnou a poté ji přiřadíte v následujícím příkazu, nebo použijete syntaxi deklarace funkce.
Výroky
Příkaz je základní jednotkou provádění: jedno přiřazení, řídicí struktura, volání funkce, deklarace proměnné atd.
Chunk (kus) je posloupnost příkazů, volitelně oddělená středníky. Blok je v podstatě považován za tělo anonymní funkce, takže může deklarovat lokální proměnné, přijímat argumenty a vracet hodnoty.
Blok je také posloupnost příkazů, stejně jako kus. Blok lze oddělit a vytvořit tak jeden příkaz: do block end
. Ty lze použít k omezení rozsahu lokálních proměnných nebo k přidání return
nebo break
uprostřed jiného bloku.
Zadání
seznam-proměnných = seznam-výrazů
variable-list je seznam proměnných oddělených čárkami. expression-list je čárkami oddělený seznam jednoho nebo více výrazů. Všechny výrazy jsou vyhodnoceny před provedením jakéhokoli přiřazení, takže a, b = b, a
zamění hodnoty a a b.
Deklarace lokálních proměnných
local seznam-proměnných
local seznam-proměnných = seznam-výrazů
Lokální proměnné mohou být deklarovány kdekoli v bloku nebo kusu. První formulář bez seznamu výrazů deklaruje proměnné, ale nepřiřazuje hodnotu, takže všechny proměnné mají hodnotu nula. Druhý formulář přiřazuje hodnoty lokálním proměnným, jak je popsáno v Úkolech výše.
Všimněte si, že viditelnost lokální proměnné začíná příkazem po deklaraci lokální proměnné. Takže deklarace jako local x = x
deklaruje lokální proměnnou x a přiřadí jí hodnotu x z vnějšího rozsahu. Lokální proměnná zůstává v rozsahu až do konce nejvnitřnějšího bloku obsahujícího deklaraci lokální proměnné.
Struktury kontroly
while výraz do blok end
Příkaz while opakuje blok, dokud je výraz vyhodnocen jako pravdivá hodnota.
repeat blok until výraz
Příkaz repeat opakuje blok, dokud se výraz nevyhodnotí jako pravdivá hodnota. Ve výrazu lze přistupovat k lokálním proměnným deklarovaným uvnitř bloku.
for name = exp1, exp2, exp3 do blok end
for name = exp1, exp2 do blok end
Tato první forma cyklu for deklaruje lokální proměnnou a opakuje blok pro hodnoty od exp1 do exp2 přidáním exp3 při každé iteraci. Všimněte si, že exp3 může být úplně vynecháno, v takovém případě se použije 1, ale nečíselné hodnoty jako nil
a false
jsou chybou. Všechny výrazy jsou vyhodnoceny jednou před spuštěním cyklu.
Tato forma cyklu for je zhruba ekvivalentní
do
local var, limit, step = tonumber( exp1 ), tonumber( exp2 ), tonumber( exp3 )
if not ( var and limit and step ) then
error()
end
while ( step > 0 and var <= limit ) or ( step <= 0 and var >= limit ) do
local name = var
block
var = var + step
end
end
kromě toho, že proměnné var, limit a step nejsou dostupné nikde jinde. Všimněte si, že proměnná name je pro daný blok lokální. Chcete-li použít hodnotu za smyčkou, musí být zkopírována do proměnné deklarované mimo smyčku.
for seznam-proměnných in seznam-výrazů do blok end
Druhá forma cyklu for pracuje s funkcemi iterátor. Stejně jako v prvním formuláři je seznam-výrazů vyhodnocen pouze jednou před začátkem cyklu.
Tato forma cyklu for je zhruba ekvivalentní
do
local func, static, var = expression-list
while true do
local var-list = func( static, var )
var = var1 -- ''var1'' je první proměnná v ''seznamu-proměnných''
if var == nil then
break
end
block
end
end
kromě toho, že opět proměnné func, static a var nejsou dostupné nikde jinde. Všimněte si, že proměnné v var-list jsou pro daný blok lokální; chcete-li je použít po cyklu, musí být zkopírovány do proměnných deklarovaných mimo cyklus.
Seznam výrazů je často volání jediné funkce, která vrací tři hodnoty. Pokud lze funkci iterátoru zapsat tak, že závisí pouze na parametrech, které jsou do ní předány, bylo by to nejúčinnější. Pokud ne, programování v Lua navrhuje, aby se upřednostňovalo uzavření před vrácením tabulky jako statické proměnné a aktualizací jejích členů při každé iteraci.
if exp1 then block1 elseif exp2 then block2 else block3 end
Provede block1, pokud exp1 vrátí true, jinak provede block2, pokud exp2 vrátí true, a block3 jinak. Část else block3
může být vynechána a část elseif exp2 then block2
může být podle potřeby opakována nebo vynechána.
return seznam-výrazů
Příkaz return se používá k vrácení hodnot z funkce nebo chunk (což je pouze funkce). Seznam-výrazů je čárkami oddělený seznam nula nebo více výrazů.
Lua implementuje volání tail: Pokud výraz-seznam obsahuje přesně jeden výraz, který je voláním funkce, bude pro volání této funkce znovu použit aktuální zásobníkový rámec. To má důsledky pro funkce, které se zabývají zásobníkem volání, jako je getfenv()
a debug.traceback()
.
Příkaz return musí být posledním příkazem v jeho bloku. Pokud je z nějakého důvodu potřeba návrat uprostřed bloku, lze použít explicitní blok do return end
.
break
Příkaz break se používá k ukončení provádění cyklu while, repeat nebo for, přičemž se přeskočí na další příkaz následující po cyklu.
Příkaz break musí být posledním příkazem v jeho bloku. Pokud je z nějakého důvodu potřeba přerušení uprostřed bloku, lze použít explicitní blok do break end
.
Na rozdíl od některých jiných jazyků nemá Lua pro cykly příkaz "continue" (tj. příkaz pro přechod na další iteraci bez úplného přerušení smyčky).
Je přímočaré dosáhnout stejného efektu vnořením bloku repeat ... until true
přímo do hlavní smyčky, která se bude opakovat pouze jednou pro každou iteraci hlavní smyčky (jelikož podmínka je vždy pravdivá).
Použití break
pouze ukončí vnitřní smyčku, což má praktický účinek, že hlavní smyčka bude pokračovat v další iteraci.
Pokud je nutné použít break
v hlavní smyčce, jednoduše deklarujte proměnnou, která je kontrolována pokaždé, když se vnitřní smyčka dokončí, a v případě potřeby ji nastavte.
Volání funkcí jako příkazů
Volání funkce lze použít jako příkaz. V tomto případě je funkce volána pouze pro jakékoli vedlejší účinky, které může mít (např. mw.log() protokoluje hodnoty) a všechny návratové hodnoty jsou zahozeny.
Příkazy deklarace funkce
Lua poskytuje syntaktický sugar, aby bylo deklarování funkce a její přiřazení k proměnné přirozenější. Následující dvojice deklarací jsou ekvivalentní
-- Základní prohlášení function func( var-list ) blok end func = function ( var-list ) blok end
-- Lokální funkce local function func( var-list ) blok end local func; func = function ( var-list ) blok end
-- Funkce jako pole v tabulce function table.func( var-list ) blok end table.func = function ( var-list ) blok end
-- Funkce jako metoda v tabulce function table:func( var-list ) blok end table.func = function ( self, var-list ) blok end
Všimněte si, že zápis dvojtečkou zde odpovídá zápisu dvojtečky pro volání funkcí a na začátek seznamu argumentů přidává implicitní argument s názvem self
.
Zpracování chyb
Chyby lze "vyvolat" pomocí funkcí error() a assert(). Chcete-li "zachytit" chyby, použijte pcall() nebo xpcall(). Všimněte si, že určité interní chyby Scriunto nelze zachytit v kódu Lua.
Garbage collection
Lua provádí automatickou správu paměti. To znamená, že se nemusíte starat ani o alokaci paměti pro nové objekty, ani o její uvolnění, když již objekty nejsou potřeba. Lua spravuje paměť automaticky tak, že čas od času spustí garbage collector, aby shromáždil všechny mrtvé objekty (tj. objekty, které již nejsou dostupné z Lua) a objekty, které jsou dosažitelné pouze prostřednictvím [[#weak tables|slabých referencí] ]. Veškerá paměť používaná Lua podléhá automatické správě: tabulky, funkce, řetězce atd.
Garbage collection (sběr odpadu) probíhá automaticky a nelze jej konfigurovat ze Scriunta.
Standardní knihovny
Standardní knihovny Lua poskytují Lua základní služby a funkce kritické pro výkon. Zde jsou zdokumentovány pouze ty části standardních knihoven, které jsou dostupné ve Scriuntu.
Základní funkce
_G
Tato proměnná obsahuje odkaz na aktuální tabulku globálních proměnných. Ke globální proměnné foo
lze také přistupovat jako _G.foo
. Všimněte si však, že na samotných _G není nic zvláštního. Může být znovu přiřazena stejným způsobem jako jakákoli jiná proměnná:
foo = 1
mw.log( foo ) -- logy "1"
_G.foo = 2
mw.log( foo ) -- logy "2"
_G = {} -- _G již neukazuje na tabulku globálních proměnných
_G.foo = 3
mw.log( foo ) -- přetrvávající logy "2"
Tabulku globálních proměnných lze použít stejně jako jakoukoli jinou tabulku. Například,
-- Volání funkce, jejíž název je uložen v proměnné
_G[var]()
-- Protokolujte názvy a zřetězené hodnoty všech globálních proměnných
for k, v in pairs( _G ) do
mw.log( k, v )
end
-- Zaznamenejte vytvoření nových globálních proměnných
setmetatable( _G, {
__newindex = function ( t, k, v )
mw.log( "Creation of new global variable '" .. k .. "'" )
rawset( t, k, v )
end
} )
_VERSION
Řetězec obsahující běžící verzi Lua, např. "Lua 5.1".
assert
assert( v, message, ... )
Pokud je v
nula nebo nepravda, vydá chybu. V tomto případě se jako text chyby použije message
: pokud je nula (nebo není zadáno), text je "tvrzení se nezdařilo!". Pokud je řetězec nebo číslo, text je tato hodnota. Jinak samo tvrzení vyvolá chybu.
Pokud je v
jakákoliv jiná hodnota, tvrzení vrátí všechny argumenty včetně v
a message
.
Poněkud běžný idiom v Lua je, že funkce v normálním provozu vrátí hodnotu "true" a při selhání vrátí nulu nebo nepravdu jako první hodnotu a chybovou zprávu jako druhou hodnotu. Snadnou kontrolu chyb lze poté implementovat zabalením hovoru do volání assert
:
-- Toto nekontroluje chyby
local result1, result2, etc = func( ... )
-- Funguje to stejně, ale kontroluje chyby
local result1, result2, etc = assert( func( ... ) )
error
error( message, level )
Vydá chybu s textem message
.
error
obvykle přidává nějaké informace o umístění chyby. Pokud level
je 1 nebo je vynechán, je tato informace místem samotného volání error
. 2 používá umístění volání funkce, která volala chybu. A tak dále. Předání 0 vynechá zahrnutí informací o poloze.
getfenv
getfenv( f )
Upozorňujeme, že tato funkce nemusí být dostupná v závislosti na allowEnvFuncs
v konfiguraci motoru.
Vrátí prostředí (globální tabulku proměnných), jak je specifikováno f
:
- Pokud je 1, nula nebo je vynecháno, vrátí prostředí funkce volající
getfenv
. Často to bude stejné jako _G. - Celá čísla 2–10 vrátí prostředí funkcí výše v zásobníku volání. Například 2 vrátí prostředí pro funkci, která volala aktuální funkci, 3 vrátí prostředí pro funkci volající tuto funkci a tak dále. Pokud je hodnota vyšší než počet volání funkcí v zásobníku nebo pokud se cílová úroveň zásobníku vrátí s voláním konce, dojde k chybě.
- Předání funkce vrátí prostředí, které bude použito při volání této funkce.
Prostředí používaná všemi standardními knihovními funkcemi a funkcemi knihovny Scriunto jsou chráněna. Pokus o přístup do těchto prostředí pomocí getfenv
vrátí nulu.
getmetatable
getmetatable( table )
Vrátí metatable tabulky. Jakýkoli jiný typ vrátí nulu.
Pokud má metatabulka pole __metatable
, bude vrácena tato hodnota namísto skutečné metatabulky.
ipairs
ipairs( t )
Vrátí tři hodnoty: funkci iterátoru, tabulku t
a 0. Toto je určeno pro použití ve tvaru iterator for
:
for i, v in ipairs( t ) do
-- process each index-value pair
end
Toto bude iterovat přes dvojice ( 1, t[1] ), ( 2, t[2] ) atd., přičemž se zastaví, když t[i] bude nulové.
Standardní chování může být potlačeno poskytnutím __ipairs
metametody. Pokud tato metametoda existuje, volání ipairs místo toho vrátí tři hodnoty vrácené __ipairs( t )
.
next
next( table, key )
To umožňuje iteraci přes klíče v tabulce. Pokud je key
nula nebo není specifikováno, vrátí "první" klíč v tabulce a jeho hodnotu; jinak vrátí klíč "další" a jeho hodnotu. Pokud nejsou k dispozici žádné další klíče, vrátí hodnotu nula. Zda je tabulka prázdná, je možné zkontrolovat pomocí výrazu next( t ) == nil
.
Všimněte si, že pořadí, ve kterém jsou klíče vráceny, není určeno, a to ani pro tabulky s číselnými indexy. Chcete-li procházet tabulkou v číselném pořadí, použijte numerical for nebo ipairs.
Chování je nedefinované, pokud je při použití next pro procházení přiřazena hodnota jakémukoli neexistujícímu klíči. Přiřazení nové hodnoty (včetně nuly) existujícímu poli je povoleno.
pairs
pairs( t )
Vrátí tři hodnoty: funkci iterátoru (next nebo podobnou práci), tabulku t
a nulu. Toto je určeno pro použití ve iterátorové formě for
:
for k, v in pairs( t ) do
-- zpracovat každý pár klíč–hodnota
end
To bude opakovat páry klíč-hodnota v t
stejně jako next. V dokumentaci k next naleznete omezení týkající se úprav tabulky během procházení.
Standardní chování může být potlačeno poskytnutím __pairs metametoda. Pokud tato metametoda existuje, volání párů místo toho vrátí tři hodnoty vrácené __pairs( t )
.
pcall
pcall( f, ... )
Volá funkci f
s danými argumenty v chráněném režimu. To znamená, že pokud se během volání na f
objeví chyba, pcall vrátí false a vyvolá se chybová zpráva. Pokud nedojde k žádné chybě, pcall vrátí true a všechny hodnoty vrácené voláním.
V pseudokódu může být pcall
definován nějak takto:
function pcall( f, ... )
try
return true, f( ... )
catch ( message )
return false, message
end
end
rawequal
rawequal( a, b )
To je ekvivalent a == b
kromě toho, že ignoruje jakoukoli __eq metametodu.
rawget
rawget( table, k )
To je ekvivalent table[k]
kromě toho, že ignoruje jakoukoli __index metametodu.
rawset
rawset( table, k, v )
To je ekvivalent table[k] = v
kromě toho, že ignoruje jakoukoli __newindex metametodU.
select
select( index, ... )
Pokud je index
číslo, vrátí všechny argumenty v ...
od tohoto indexu dále.
Pokud je index
řetězec "#"
, vrátí počet argumentů v ...
.
Poznámka: Na rozdíl od tabulek seznamy argumentů (včetně výrazu vararg ...
) považují nil
za odlišnou hodnotu (viz dokumentace k # a unpack pro problém s nil
v tabulkách). Například:
select(2, "foo", "bar")
vrátí"bar"
.select(2, "foo", nil, "bar", nil)
vrátínil, "bar", nil
.select("#", "foo", "bar")
vrátí2
.select("#", "foo", "bar", nil)
vrátí3
.
Jinými slovy, select
je zhruba jako následující (kromě toho, že také zpracovává všechny nil
argumenty po posledním nenulovém argumentu):
function select( index, ... )
local t = { ... }
local maxindex = table.maxn( t )
if index == "#" then
return maxindex
else
return unpack( t, index, maxindex )
end
end
setmetatable
setmetatable( table, metatable )
Nastavuje z tabulky metatabulku. metatable
může být nula, ale musí být výslovně uvedeno.
Pokud má aktuální metatabulka pole __metatable, setmetatable
vyvolá chybu.
tonumber
tonumber( value, base )
Pokusí se převést value
na číslo. Pokud se již jedná o číslo nebo řetězec převoditelný na číslo, pak tonumber
toto číslo vrátí; jinak vrátí nulu.
Volitelné base
(výchozí 10) určuje základ pro interpretaci čísla. Základem může být jakékoli celé číslo mezi 2 a 36 včetně. V základech nad 10 představuje písmeno "A" (buď velké nebo malé) 10, "B" představuje 11 a tak dále, přičemž "Z" představuje 35.
V základu 10 může mít hodnota desetinnou část, může být vyjádřena v E zápisu a může mít na začátku "0x" pro označení základu 16. V jiných základech jsou akceptována pouze celá čísla bez znaménka.
tostring
tostring( value )
Převede value
na řetězec. Podrobnosti o převodu jednotlivých typů viz Datové typy výše.
Standardní chování tabulek může být potlačeno poskytnutím __tostring metametody. Pokud tato metametoda existuje, volání tostring místo toho vrátí jedinou hodnotu vrácenou __tostring( value )
.
type
type( value )
Vrátí typ value
jako řetězec: "nil"
, "number"
, "string"
, "boolean"
, "table"
nebo "function"
.
unpack
unpack( table, i, j )
Vrátí hodnoty z dané tabulky, něco jako table[i], table[i+1], ···, table[j]
by udělalo, pokud by bylo zapsáno ručně. Pokud je nula nebo není zadáno, i
výchozí hodnota 1 a j
výchozí #table
.
Pokud tabulka nemá hodnotu pro konkrétní klíč, rozbalení vrátí pro tuto hodnotu nulu. Například unpack({"foo", [3] = "bar"}, 1, 4)
vrátí "foo", nil, "bar ", nul
.
Všimněte si, že výsledky nejsou deterministické, pokud tabulka
není sekvence a j
je nula nebo není specifikováno; podrobnosti viz Operátor délky.
xpcall
xpcall( f, errhandler )
Je to podobné jako pcall
, s tím rozdílem, že chybová zpráva je před jejím vrácením předána funkci errhandler
.
V pseudokódu může být xpcall
definován nějak takto:
function xpcall( f, errhandler )
try
return true, f()
catch ( message )
message = errhandler( message )
return false, message
end
end
Knihovna ladění
debug.traceback
debug.traceback( zpráva, úroveň)
Vrátí řetězec se zpětným sledováním zásobníku volání. Na začátek zpětného sledování je připojen volitelný řetězec zprávy. Volitelné číslo úrovně říká, na které úrovni zásobníku se má zahájit sledování.
Matematická knihovna
math.abs
math.abs( x )
Vrátí absolutní hodnotu x
.
math.acos
math.acos( x )
Vrátí arc cosinus x
(zadaný v radiánech).
math.asin
math.asin( x )
Vrátí úhlový sinus x
(zadaný v radiánech).
math.atan
math.atan( x )
Vrátí arkus tangens x
(zadaný v radiánech).
math.atan2
math.atan2( y, x )
Vrátí arkus tangens y/x
(zadaný v radiánech) pomocí znamének obou parametrů k nalezení kvadrantu výsledku.
math.ceil
math.ceil( x )
Vrátí nejmenší celé číslo větší nebo rovné x
.
math.cos
math.cos( x )
Vrátí kosinus x
(zadaný v radiánech).
math.cosh
math.cosh( x )
Vrátí hyperbolický kosinus x
.
math.deg
math.deg( x )
Vrátí úhel x
(zadaný v radiánech) ve stupních.
math.exp
math.exp( x )
Vrátí hodnotu .
math.floor
math.floor( x )
Vrátí největší celé číslo menší nebo rovné x
.
math.fmod
math.fmod( x, y )
Vrátí zbytek dělení x
ku y
, který zaokrouhlí podíl směrem k nule. Například math.fmod( 10, 3 )
vychází 1
.
math.frexp
math.frexp( x )
Vrátí dvě hodnoty m
a e
takové, že:
- Pokud je
x
konečný a nenulový: ,e
je celé číslo a absolutní hodnotam
je v rozsahu - Pokud je
x
nula:m
ae
jsou 0 - Pokud je
x
NaN (Not a Number ("nečíslo")) nebo nekonečno:m
jex
ae
není specifikováno
math.huge
Hodnota představující kladné nekonečno. Větší nebo rovno jakékoli jiné číselné hodnotě.
math.ldexp
math.ldexp( m, e )
Vrátí (e
by mělo být celé číslo).
math.log
math.log( x )
Vrátí přirozený logaritmus x
.
math.log10
math.log10( x )
Vrátí základní-10 logaritmus x
.
math.max
math.max( x, ... )
Vrátí maximální hodnotu mezi svými argumenty.
Chování s NaN není specifikováno. S aktuální implementací bude NaN vráceno, pokud x
je NaN, ale všechny ostatní NaN budou ignorovány.
math.min
math.min( x, ... )
Vrátí minimální hodnotu mezi svými argumenty.
Chování s NaN není specifikováno. S aktuální implementací bude NaN vráceno, pokud x
je NaN, ale všechny ostatní NaN budou ignorovány.
math.modf
math.modf( x )
Vrátí dvě čísla, integrální část x
a zlomkovou část x
. Například math.modf( 1.25 )
zobrazí 1, 0.25
.
math.pi
Hodnota .
math.pow
math.pow( x, y )
Ekvivalent x^y
.
math.rad
math.rad( x )
Vrátí úhel x
(zadaný ve stupních) v radiánech.
math.random
math.random( m, n )
Vrátí pseudonáhodné číslo.
Argumenty m
a n
mohou být vynechány, ale pokud jsou uvedeny, musí být převoditelné na celá čísla.
- Bez argumentů vrátí skutečné číslo v rozsahu
- S jedním argumentem vrátí celé číslo v rozsahu
- Se dvěma argumenty vrátí celé číslo v rozsahu
Všimněte si, že nesprávný výstup může vzniknout, pokud je m
nebo n
menší než −2147483648 nebo větší než 2147483647 nebo pokud je n - m
větší než 2147483646.
math.randomseed
math.randomseed( x )
Nastaví x
jako jádro pro pseudonáhodný generátor.
Všimněte si, že použití stejného semena způsobí, že math.random
vypíše stejnou sekvenci čísel.
math.randomseed( tonumber( mw.getContentLanguage():formatDate( "U" ) ) * 10000 + os.clock() * 10000 )
math.sin
math.sin( x )
Vrátí sinus x
(zadaný v radiánech).
math.sinh
math.sinh( x )
Vrátí hyperbolický sinus x
.
math.sqrt
math.sqrt( x )
Vrátí druhou odmocninu z x
. Ekvivalent x^0.5
.
math.tan
math.tan( x )
Vrátí tangens x
(zadaný v radiánech).
math.tanh
math.tanh( x )
Vrátí hyperbolický tangens x
.
Knihovna operačního systému
os.clock
os.clock()
Vrátí přibližnou hodnotu v sekundách času procesoru použitého programem.
os.date
os.date( format, time )
- Formát jazykové knihovny lze použít pro komplexnější formátování data
Vrátí řetězec nebo tabulku obsahující datum a čas ve formátu format
. Pokud je formát vynechán nebo je nulový, použije se "%c".
Pokud je zadáno time
, je to čas, který má být formátován (viz os.time()
). Jinak se použije aktuální čas.
Pokud format
začíná znakem '!', pak je datum formátováno v UTC, nikoli v místním čase serveru. Za tímto volitelným znakem, pokud je formátem řetězec "*t", pak datum vrátí tabulku s následujícími poli:
- year (rok) (full)
- month (měsíc) (1–12)
- day (den) (1–31)
- hour (hodina) (0–23)
- min (0–59)
- sec (0–60, umožní přestupné sekundy)
- wday (všední den, neděle je 1)
- yday (den v roce)
- isdst (příznak letního času, boolean; může chybět, pokud informace nejsou k dispozici)
Pokud formát není "*t", pak datum vrátí datum jako řetězec, naformátovaný podle stejných pravidel jako funkce C strftime.
os.difftime
os.difftime( t2, t1 )
Vrátí počet sekund od t1
do t2
.
os.time
os.time( table )
Vrátí číslo představující aktuální čas.
Při volání bez argumentů vrátí aktuální čas. Pokud projde tabulkou, bude analyzován čas zakódovaný v tabulce. Tabulka musí obsahovat pole "rok", "měsíc" a "den" a může také obsahovat "hodinu" (výchozí 12), "min" (výchozí 0), "sec" (výchozí 0) a "isdst".
Knihovna balíčků
require
require( modulename )
Načte zadaný modul.
Nejprve se podívá do package.loaded[modulename]
, aby zjistil, zda je modul již načten. Pokud ano, vrátí package.loaded[modulename]
.
Jinak volá každý zavaděč v sekvenci package.loaders
, aby se pokusil najít zavaděč pro modul. Pokud je nalezen zavaděč, zavolá se tento zavaděč. Hodnota vrácená zavaděčem se uloží do package.loaded[modulename]
a vrátí se.
Informace o dostupných zavaděčích naleznete v dokumentaci pro package.loaders
.
Pokud máte například modul "Module:Giving" obsahující následující:
local p = {}
p.someDataValue = 'Ahoj!'
return p
Můžete to načíst do jiného modulu s kódem, jako je tento:
local giving = require( "Module:Giving" )
local value = giving.someDataValue -- hodnota je nyní 'Ahoj!'
package.loaded
Tato tabulka obsahuje načtené moduly. Klíče jsou názvy modulů a hodnoty jsou hodnoty vrácené při načtení modulu.
package.loaders
Tato tabulka obsahuje posloupnost vyhledávacích funkcí, které se mají použít při načítání modulů. Každá vyhledávací funkce je volána s jediným argumentem, názvem modulu, který se má načíst. Pokud je modul nalezen, hledač musí vrátit funkci, která modul skutečně načte a vrátí hodnotu, kterou má vrátit požadavek. V opačném případě musí vrátit nulu.
Scriunto nabízí dva vyhledávače:
- V
package.preload[modulename]
vyhledejte funkci loader - Hledejte v modulech poskytovaných se Scriuntem název modulu, a pokud to selže, hledejte ve jmenném prostoru Module:. Musí být zadána předpona "Module:".
Všimněte si, že standardní zavaděče Lua nejsou součástí dodávky.
package.preload
Tato tabulka obsahuje funkce zavaděče, které používá první vyhledávač, který Scriunto obsahuje v package.loaders.
package.seeall
package.seeall( table )
Nastaví __index metamethod pro table
na _G.
Knihovna řetězců
Ve všech řetězcových funkcích je první znak na pozici 1, nikoli na pozici 0 jako v C, PHP a JavaScript. Indexy mohou být záporné, v takovém případě se počítají od konce řetězce: pozice -1 je poslední znak v řetězci, -2 je předposlední atd.
Upozornění: Knihovna řetězců předpokládá jednobajtové kódování znaků. Nedokáže zpracovat znaky Unicode. Chcete-li pracovat s řetězci Unicode, použijte odpovídající metody v knihovně Scribunto Ustring.
string.byte
string.byte( s, i, j )
Pokud je řetězec považován za pole bajtů, vrátí hodnoty bajtů pro s[i]
, s[i+1]
, ···, s[j]
.
Výchozí hodnota i
je 1;
výchozí hodnota pro j
je i
.
Stejné jako mw.ustring.byte().
string.char
string.char( ... )
Přijímá nulu nebo více celých čísel. Vrátí řetězec s délkou rovnou počtu argumentů, ve kterém má každý znak hodnotu bajtu rovnou jeho odpovídajícímu argumentu.
local value = string.char( 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x21 ) --hodnota je nyní 'Ahoj!'
Viz mw.ustring.char() pro podobnou funkci, která používá kódové body Unicode spíše než bajtové hodnoty.
string.find
string.find( s, pattern, init, plain )
Vyhledá první shodu pattern
v řetězci s
. Pokud najde shodu, pak find
vrátí offsety v s
, kde tento výskyt začíná a končí; jinak vrátí nulu. Pokud má vzor záchyty, pak jsou při úspěšné shodě zachycené hodnoty také vráceny po dvou indexech.
Třetí, volitelný číselný argument init
určuje, kde má začít hledání; jeho výchozí hodnota je 1 a může být záporná. Hodnota true jako čtvrtý, volitelný argument plain
vypne funkce porovnávání vzorů, takže funkce provede jednoduchou operaci „najít podřetězec“, přičemž v pattern
nejsou žádné znaky považovány za "kouzelné".
Všimněte si, že pokud je zadáno plain
, musí být zadáno také init
.
Viz mw.ustring.find(), kde najdete podobnou funkci rozšířenou, jak je popsáno v Ustring vzorech a kde offset init
je ve znacích, nikoli v bajtech.
string.format
string.format( formatstring, ... )
Vrátí formátovanou verzi svého proměnného počtu argumentů po popisu uvedeném v prvním argumentu (což musí být řetězec).
Formátovací řetězec používá omezenou podmnožinu printf
specifikátorů formátu:
- Rozpoznané příznaky jsou
'-', '+', ' ', '#',
a'0'
. - Jsou podporovány celočíselné šířky pole až 99.
'*'
není podporováno. - Podporovány jsou přesnosti celých čísel až 99.
'*'
není podporováno. - Modifikátory délky nejsou podporovány.
- Uznávané konverzní specifikátory jsou
'c', 'd', 'i', 'o', 'u', 'x', 'X', 'e', 'E', 'f', 'g', 'G', 's', '%',
a nestandardní'q'
. - Specifikátory polohy (např. "%2$s") nejsou podporovány.
Konverzní specifikátor q
je jako s
, ale formátuje řetězec ve formě vhodné k bezpečnému zpětnému přečtení překladačem Lua: Řetězec je zapsán mezi dvojité uvozovky a všechny dvojité uvozovky, nové řádky, vložené nuly a zpětná lomítka v řetězci jsou při zápisu správně uvozeny.
Konverze mezi řetězci a čísly se provádí tak, jak je uvedeno na stránce Datové typy. Ostatní typy nejsou automaticky převedeny na řetězce. Řetězce obsahující znaky NUL (hodnota bajtu 0) nejsou správně zpracovány.
Totožné s mw.ustring.format().
string.gmatch
string.gmatch( s, pattern )
Vrací funkci iterátoru, která při každém svém volání vrací další zachycení z vzor
přes řetězec s
. Pokud pattern
neurčuje žádné zachycení, pak se v každém volání vytvoří celá shoda.
Pro tuto funkci není '^
' na začátku vzoru magické, protože by to zabránilo opakování. Zachází se s ním jako s doslovným znakem.
Viz mw.ustring.gmatch() pro podobnou funkci, pro kterou je vzor rozšířen, jak je popsáno v Ustring vzorech.
string.gsub
string.gsub( s, pattern, repl, n )
Vrátí kopii s
, ve které mají všechny (nebo první n
, pokud je zadán) výskyty pattern
byl nahrazen náhradním řetězcem určeným repl
, což může být řetězec, tabulka nebo funkce. gsub
také vrací jako svou druhou hodnotu celkový počet shod, ke kterým došlo.
Pokud je repl
řetězec, jeho hodnota se použije k nahrazení. Znak %
> funguje jako znak escape: jakákoli sekvence v repl
ve tvaru %d
,
s d mezi 1 a 9 znamená hodnotu d-tého zachyceného podřetězce. Sekvence %0
představuje celou shodu a sekvence %%
představuje jeden %
.
Je-li repl
tabulka, pak je tabulka dotazována pro každou shodu s použitím prvního zachycení jako klíče; pokud vzor neurčuje žádné zachycení, pak se jako klíč použije celá shoda.
Je-li repl
funkce, pak je tato funkce volána pokaždé, když dojde ke shodě, se všemi zachycenými podřetězci předanými jako argumenty v pořadí. Pokud vzor neurčuje žádné zachycení, pak je celá shoda předána jako jediný argument.
Pokud je hodnota vrácená tabulkovým dotazem nebo voláním funkce řetězec nebo číslo, použije se jako náhradní řetězec. V opačném případě, je-li nepravda nebo nula, neexistuje žádná náhrada (tj. původní shoda je v řetězci zachována).
Viz mw.ustring.gsub() pro podobnou funkci, ve které je vzor rozšířen, jak je popsáno v Ustring vzory.
string.len
string.len( s )
Vrátí délku řetězce v bajtech. Není zmaten znaky ASCII NUL. Ekvivalent #s
.
Viz mw.ustring.len() pro podobnou funkci používající kódové body Unicode místo bajtů.
string.lower
string.lower( s )
Vrátí kopii tohoto řetězce se všemi velkými písmeny ASCII změněnými na malá. Všechny ostatní znaky jsou ponechány beze změny.
Viz mw.ustring.lower() pro podobnou funkci, ve které jsou převedeny všechny znaky s definicemi velkých písmen na malá v Unicode.
string.match
string.match( s, pattern, init )
Hledá první shodu vzor
v řetězci. Pokud nějaký najde, pak match
vrátí zachycení ze vzoru; jinak vrátí nulu. Pokud pattern
neurčuje žádné zachycení, vrátí se celá shoda.
Třetí, volitelný číselný argument init
určuje, kde má začít hledání; jeho výchozí hodnota je 1 a může být záporná.
Viz mw.ustring.match() pro podobnou funkci, ve které je vzor rozšířen, jak je popsáno v Ustring vzory a offset init
je v znaků spíše než bajtů.
string.rep
string.rep( s, n )
Vrátí řetězec, který je zřetězením n
kopií řetězce s
. Totožné s mw.ustring.rep().
string.reverse
string.reverse( s )
Vrátí řetězec, který je obrácený řetězec s
(bajtově).
string.sub
string.sub( s, i, j )
Vrátí podřetězec s
, který začíná na i
a pokračuje až do j
; i
a j
mohou být záporné. Pokud je j
nula nebo je vynecháno, bude pokračovat až do konce řetězce.
Konkrétně volání string.sub(s,1,j)
vrátí předponu s
s délkou j
a string.sub(s, -i)
vrátí příponu s
s délkou i
.
Viz mw.ustring.sub() pro podobnou funkci, ve které jsou offsety spíše znaky než bajty.
string.ulower
string.ulower( s )
Alias pro mw.ustring.lower().
string.upper
string.upper( s )
Vrátí kopii tohoto řetězce se všemi malými písmeny ASCII změněnými na velká. Všechny ostatní znaky jsou ponechány beze změny.
Viz mw.ustring.upper() pro podobnou funkci, ve které jsou převedeny všechny znaky s definicemi malých písmen na velká v Unicode.
string.uupper
string.uupper( s )
Alias pro mw.ustring.upper().
Vzory
Všimněte si, že vzory Lua jsou podobné regulární výrazy, ale nejsou totožné. Všimněte si zejména následujících rozdílů od regulárních výrazů a PCRE:
- Znak uvozovky je procento (
%
), nikoli zpětné lomítko (\
). - Tečka (
.
) vždy odpovídá všem znakům, včetně nových řádků. - Žádný režim bez rozlišení velkých a malých písmen.
- Žádná alternace (operátor
|
). - Kvantifikátory (
*
,+
,?
a-
) lze použít pouze na jednotlivé znaky nebo třídy znaků , nikoli k zachycení skupin. - Jediným nezištným kvantifikátorem je
-
, což je ekvivalentní kvantifikátoru PCRE*?
. - Žádný zobecněný konečný kvantifikátor (např. kvantifikátor
{n,m}
v PCRE). - Jediné výrazy s nulovou šířkou jsou
^
,$
a vzor "hraniční"%f[set]
. Tvrzení jako PCRE\b
nebo(?=···)
nejsou přítomna. - Vzory samy o sobě nerozpoznají escapes znaků, jako je
\ddd
. Protože jsou však vzory strings, lze tento druh escapes použít v řetězcových literálech používaných k vytvoření řetězce vzoru.
Všimněte si také, že vzor nemůže obsahovat vložených nula bajtů (ASCII NUL, "\0"
). Místo toho použijte %z
.
Viz také Ustring vzory pro podobné schéma porovnávání vzorů pomocí znaků Unicode.
Třída znaků
Třída znaků se používá k reprezentaci sady znaků. Při popisu třídy znaků jsou povoleny následující kombinace:
x
|
(kde x není jeden z magických znaků ^$()%.[]*+-? ) představuje samotný znak x .
|
---|---|
.
|
(tečka) Představuje všechny znaky. |
%a
|
Představuje všechna písmena ASCII. |
%c
|
Představuje všechny řídicí znaky ASCII. |
%d
|
Představuje všechny číslice. |
%l
|
Představuje všechna malá písmena ASCII. |
%p
|
Představuje všechny interpunkční znaky. |
%s
|
Představuje všechny mezery ASCII. |
%u
|
Představuje všechna velká písmena ASCII. |
%w
|
Představuje všechny alfanumerické znaky ASCII. |
%x
|
Představuje všechny hexadecimální číslice. |
%z
|
Představuje ASCII NUL, nulový bajt. |
%A
|
Všechny znaky nejsou v %a .
|
%C
|
Všechny znaky nejsou v %c .
|
%D
|
Všechny znaky nejsou v %d .
|
%L
|
Všechny znaky nejsou v %l .
|
%P
|
Všechny znaky nejsou v %p .
|
%S
|
Všechny znaky nejsou v %s .
|
%U
|
Všechny znaky nejsou v %u .
|
%W
|
Všechny znaky nejsou v %w .
|
%X
|
Všechny znaky nejsou v %x .
|
%Z
|
Všechny znaky nejsou v %z .
|
%y
|
(kde y je libovolný nealfanumerický znak) představuje znak y . Toto je standardní způsob, jak uniknout magickým postavám. Každému interpunkčnímu znaku (dokonce i nemagickému) může předcházet '% ', když se používá k reprezentaci sebe sama ve vzoru.
|
[set]
|
Představuje třídu, která je sjednocením všech znaků v set. Rozsah znaků lze určit oddělením koncových znaků rozsahu ' Interakce mezi rozsahy a třídami není definována. Proto vzory jako |
[^set]
|
Představuje doplněk set, kde set je interpretován jako výše. |
Vzorové položky
Položka vzoru může být
- třída jednoho znaku, která odpovídá libovolnému jednotlivému znaku ve třídě;
- třída jednoho znaku následovaná '
*
', která odpovídá 0 nebo více opakování znaků ve třídě. Tyto položky opakování budou vždy odpovídat nejdelší možné sekvenci; - třída jednoho znaku následovaná '
+
', která odpovídá 1 nebo více opakování znaků ve třídě. Tyto položky opakování budou vždy odpovídat nejdelší možné sekvenci; - třída jednoho znaku následovaná '
-
', která také odpovídá 0 nebo více opakování znaků ve třídě. Na rozdíl od '*
' budou tyto položky opakování vždy odpovídat nejkratší možné sekvenci; - třída jednoho znaku následovaná '
?
', která odpovídá 0 nebo 1 výskytu znaku ve třídě;
%n
, for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below);
%bxy
, kde x a y jsou dva odlišné znaky; taková položka odpovídá řetězcům, které začínají x, končí y a kde jsou x a y vyvážené. To znamená, že pokud čtete řetězec zleva doprava, počítáme-li +1 pro x a -1 pro y, koncovka y je první y, kde počet dosáhne 0. Například položka%b()
odpovídá výrazům s vyváženým závorky.
%f[set]
, a frontier pattern; such item matches an empty string at any position such that the next character belongs to set and the previous character does not belong to set. The set set is interpreted as previously described. The beginning and the end of the subject are handled as if they were the character '\0'.
Všimněte si, že hraniční vzory byly přítomné, ale nezdokumentované v Lua 5.1 a oficiálně přidány do Lua v 5.2. Implementace v Lua 5.2.1 se oproti 5.1.0 nezměnila.
Vzor
Vzor je posloupnost položek vzoru.
^
na začátku vzoru ukotví shodu na začátku řetězce předmětu. $
na konci vzoru ukotví shodu na konci řetězce předmětu. Na jiných pozicích nemají ^
a $
žádný zvláštní význam a představují samy sebe.
Zachycení
Vzor může obsahovat dílčí vzory uzavřené v závorkách. Popisují zachycení. Když je shoda úspěšná, podřetězce předmětu, které odpovídají zachyceným, jsou uloženy ("zachyceny") pro budoucí použití. Záběry jsou číslovány podle levých závorek. Například ve vzoru (a*(.)%w(%s*))
je část řetězce odpovídající a*(.)%w(%s*)
je uložen jako první zachycení (a má tedy číslo 1); znak odpovídající .
je zachycen číslem 2 a část odpovídající %s*
má číslo 3.
Odkazy na zachycení se mohou objevit v samotném řetězci vzoru a odkazovat zpět na text, který byl zachycen dříve ve shodě. Například ([a-z])%1
bude odpovídat libovolnému páru identických malých písmen, zatímco ([a-z])([a-z])([a-z])[a-z]%3%2%1
bude odpovídat libovolnému 7písmennému palindromu.
Jako zvláštní případ, prázdný capture ()
zachycuje aktuální pozici řetězce (číslo). Pokud například použijeme vzor "()aa()"
na řetězec "flaaap"
, dojde ke dvěma zachycením: 3 a 5.
Známá omezení: Na rozdíl od vzorů knihovny Ustring vzory knihovny řetězců nesmí obsahovat více než 32 zachycení. Pokud má vzor více, funkce String vyvolá chybu. Protože knihovna Ustring má vlastní maximum 10 000 bajtů pro vzory (na rozdíl od knihovny String), není možné použít vzor, který přesahuje oba limity, protože bude nekompatibilní s oběma knihovnami.
Knihovna tabulek
Většina funkcí v knihovně tabulek předpokládá, že tabulka představuje sekvenci.
Funkce table.foreach()
, table.foreachi()
a table.getn()
mohou být dostupné, ale jsou zastaralé; místo toho použijte cyklus for s pairs(), cyklus for s ipairs() a operátor délky. Funkce table.setn()
je však zcela zastaralá a při použití vyvolá chybu.
table.concat
table.concat( table, sep, i, j )
Zadané pole, kde všechny prvky jsou řetězce nebo čísla, vrátí table[i] .. sep .. table[i+1] ··· sep .. table[j]
.
Výchozí hodnota pro sep
je prázdný řetězec, výchozí hodnota pro i
je 1 a výchozí hodnota pro j
je délka tabulky. Pokud je i
větší než j
, vrátí prázdný řetězec.
table.insert
table.insert( table, value )
table.insert( table, pos, value )
Vloží prvek value
na pozici pos
v table
a v případě potřeby posune ostatní prvky nahoru do volného prostoru. Výchozí hodnota pro pos
je délka tabulky plus 1, takže volání table.insert(t, x)
vloží x
na konci tabulky t
.
Prvky až do #table
jsou posunuty. Viz Operátor délky pro upozornění, pokud tabulka není sekvence.
Poznámka: při použití parametru pos
by value
nemělo být nil
. Pokus o vložení explicitní hodnoty nil
doprostřed tabulky bude mít za následek nedefinované chování, které může nepředvídatelně odstranit prvky v tabulce.
table.maxn
table.maxn( table )
Vrátí největší kladný číselný index dané tabulky nebo nulu, pokud tabulka nemá žádné kladné číselné indexy.
K tomu iteruje přes celou tabulku. To je zhruba ekvivalentní
function table.maxn( table )
local maxn, k = 0, nil
repeat
k = next( table, k )
if type( k ) == 'number' and k > maxn then
maxn = k
end
until not k
return maxn
end
table.remove
table.remove( table, pos )
Odebere z table
prvek na pozici pos
, posunutím dalších prvků dolů, aby se prostor v případě potřeby uzavřel. Vrátí hodnotu odstraněného prvku. Výchozí hodnota pro pos
je délka tabulky, takže volání table.remove( t )
odstraní poslední prvek tabulky tabulka t
.
Prvky až do #table
jsou posunuty. Viz Operátor délky pro upozornění, pokud tabulka není sekvence.
table.sort
table.sort( table, comp )
Seřadí prvky tabulky v daném pořadí, na místě, od table[1]
do table[#table]
.
Je-li zadáno comp
, pak to musí být funkce, která přijímá dva prvky tabulky a vrací true
, když je první menší než druhý (takže not comp(a[i+1],a[i])
bude po třídění pravdivé).
Pokud není zadáno comp
, použije se místo něj standardní operátor Lua <
.
Algoritmus řazení není stabilní. To znamená, že prvky považované za stejné daným řádem mohou mít svou relativní polohu změněnou řazením.
Knihovny Scribunto
Všechny knihovny Scriunto jsou umístěny v tabulce mw
.
Základní funkce
mw.addWarning
mw.addWarning( text )
Přidá upozornění, které se zobrazí nad náhledem při náhledu úpravy. text
je analyzován jako wikitext.
mw.allToString
mw.allToString( ... )
Volá tostring() u všech argumentů a poté je zřetězí pomocí tabulátorů jako oddělovačů.
mw.clone
mw.clone( value )
Vytvoří hlubokou kopii hodnoty. Všechny tabulky (a jejich metatabulky) jsou od základu rekonstruovány. Funkce jsou však stále sdílené.
mw.getCurrentFrame
mw.getCurrentFrame()
Vrátí aktuální frame object, obvykle objekt frame z nejnovějšího #invoke
.
mw.incrementExpensiveFunctionCount
mw.incrementExpensiveFunctionCount()
Přidá jedničku k počtu "nákladné funkce analyzátoru" a vyvolá výjimku, pokud překročí limit (viz $wgExpensiveParserFunctionLimit
).
mw.isSubsting
mw.isSubsting()
Vrátí true, pokud je aktuální #invoke
substed, v opačném případě false
. Viz Vracející se text výše, kde najdete diskuzi o rozdílech mezi nahrazováním a nevracením.
mw.loadData
mw.loadData( module )
Někdy modul potřebuje velké tabulky dat. Například modul pro všeobecné použití pro převod měrných jednotek může potřebovat velkou tabulku rozpoznaných jednotek a jejich převodních faktorů. A někdy budou tyto moduly použity mnohokrát na jedné stránce. Analýza velké datové tabulky pro každý {{#invoke:}}
může zabrat značné množství času. Chcete-li se tomuto problému vyhnout, poskytujeme mw.loadData()
.
mw.loadData
funguje jako require()
s následujícími rozdíly:
- Načtený modul je vyhodnocen pouze jednou na stránku, nikoli jednou za volání
{{#invoke:}}
. - Načtený modul není zaznamenán v
package.loaded
. - Hodnota vrácená z načteného modulu musí být tabulka. Jiné datové typy nejsou podporovány.
- Vrácená tabulka (a všechny podtabulky) může obsahovat pouze logické hodnoty, čísla, řetězce a další tabulky. Jiné datové typy, zejména funkce, nejsou povoleny.
- Vrácená tabulka (a všechny podtabulky) nemusí mít metatable.
- Všechny klíče tabulky musí být booleovské, čísla nebo řetězce.
- Tabulka skutečně vrácená
mw.loadData()
má metametody, které poskytují přístup pouze pro čtení k tabulce vrácené modulem. Protože neobsahuje data přímo,pairs()
aipairs()
budou fungovat, ale jiné metody, včetně#value
,next()
a funkce v Knihovně tabulek nebudou fungovat správně.
Výše zmíněný hypotetický modul převodu jednotek by mohl ukládat svůj kód do "Module:Convert" a jeho data do "Module:Convert/data" a "Module:Convert" by používal local data = mw.loadData( 'Module:Convert/data' )
pro efektivní načítání dat.
mw.loadJsonData
mw.loadJsonData( page )
To je stejné jako mw.loadData()
výše, kromě toho, že načítá data ze stránek JSON, nikoli z tabulek Lua.
Obsah JSON musí být pole nebo objekt.
Více na stránce mw.text.jsonDecode()
.
mw.dumpObject
mw.dumpObject( object )
Serializuje object
na lidsky čitelnou reprezentaci a poté vrátí výsledný řetězec.
mw.log
mw.log( ... )
Předá argumenty mw.allToString() a poté připojí výsledný řetězec do vyrovnávací paměti protokolu.
V ladicí konzoli je funkce print()
aliasem této funkce.
mw.logObject
mw.logObject( object )
mw.logObject( object, prefix )
Zavolá mw.dumpObject() a připojí výsledný řetězec k vyrovnávací paměti protokolu. Pokud je zadán prefix
, bude přidán do vyrovnávací paměti protokolu následovaný znakem rovná se před připojením serializovaného řetězce (tj. protokolovaný text bude "prefix = object-string").
Objekt frame
Objekt frame je rozhraním pro parametry předávané {{#invoke:}}
a pro analyzátor.
Všimněte si, že neexistuje žádná knihovna frame a neexistuje žádná globální proměnná s názvem frame
. Objekt frame se obvykle získává předáním jako parametr funkci volané {{#invoke:}}
a lze jej také získat z mw.getCurrentFrame()
.
frame.args
Tabulka pro přístup k argumentům předávaným do frame. Například pokud je modul volán z wikitextu s
{{#invoke:module|function|arg1|arg2|name=arg3}}
potom frame.args[1]
vrátí "arg1"
, frame.args[2]
vrátí "arg2"
a frame.args['name']
(nebo frame.args.name
) vrátí "arg3"
. Je také možné opakovat argumenty pomocí pairs( frame.args )
nebo ipairs( frame.args )
.
Nicméně vzhledem k tomu, jak Lua implementuje iterátory tabulek, iterace přes argumenty je vrátí v nespecifikovaném pořadí a neexistuje způsob, jak zjistit původní pořadí, jak se objevují ve wikitextu.
Všimněte si, že hodnoty v této tabulce jsou vždy řetězce. tonumber()
lze v případě potřeby použít k jejich převodu na čísla. Klíče jsou však čísla, i když jsou ve vyvolání explicitně zadány: {{#invoke:module|function|1|2=2}}
udává řetězcové hodnoty "1"
a "2"
indexované pomocí číselných klíčů 1
a 2
.
Stejně jako při vyvolání šablon MediaWiki budou mít pojmenované argumenty před předáním Lua úvodní a koncové prázdné znaky odstraněné z názvu i hodnoty, zatímco u nepojmenovaných argumentů nebudou prázdné znaky odstraněny.
Z důvodů výkonu frame.args
používá metatabulku, nikoli přímo obsahující argumenty. Hodnoty argumentů jsou vyžadovány od MediaWiki na vyžádání. To znamená, že většina ostatních metod tabulky nebude fungovat správně, včetně #frame.args
, next ( frame.args )
a funkce v Knihovně tabulek.
Pokud je v argumentu #invoke
zahrnuta syntaxe preprocesoru, jako je vyvolání šablony a argumenty se třemi závorkami, nebudou po předání do Lua rozbaleny, dokud jejich hodnoty nebudou požadovány v Lua. Pokud jsou určité speciální značky napsané v notaci XML, jako například <pre>
, <nowiki>
, <gallery>
a <ref>
, zahrnuty jako argumenty #invoke
, pak budou tyto značky převedeny na "strip markers" — speciální řetězce které začínají znakem delete (ASCII 127), které mají být nahrazeny HTML poté, co jsou vráceny z #invoke.
frame:callParserFunction
frame:callParserFunction( name, args )
frame:callParserFunction( name, ... )
frame:callParserFunction{ name = string, args = table }
- Všimněte si použití pojmenovaných argumentů.
Zavolejte funkci analyzátoru a vrátíte příslušný řetězec. Toto je vhodnější než frame:preprocess
, ale kdykoli je to možné, měly by být před tímto rozhraním upřednostňovány nativní funkce Lua nebo funkce knihovny Scriunto.
Následující volání jsou přibližně ekvivalentní uvedenému wikitextu:
-- {{ns:0}}
frame:callParserFunction( 'ns', { 0 } )
frame:callParserFunction( 'ns', 0 )
frame:callParserFunction{ name = 'ns', args = { 0 } }
-- {{#tag:nowiki|some text}}
frame:callParserFunction( '#tag', { 'nowiki', 'some text' } )
frame:callParserFunction( '#tag', 'nowiki', 'some text' )
frame:callParserFunction( '#tag:nowiki', 'some text' )
frame:callParserFunction{ name = '#tag', args = { 'nowiki', 'some text' } }
-- {{#tag:ref|some text|name=foo|group=bar}}
frame:callParserFunction( '#tag', { 'ref',
'some text', name = 'foo', group = 'bar'
} )
Všimněte si, že stejně jako u frame:expandTemplate() nejsou název funkce a argumenty před předáním do funkce analyzátoru předzpracovány.
frame:expandTemplate
frame:expandTemplate{ title = title, args = table }
- Všimněte si použití pojmenovaných argumentů.
To je ekvivalentní volání frame:callParserFunction() s názvem funkce 'msg'
(viz Nápověda:Kouzelná slova#Modifikátory transkluze) a s title
předřazeným args
.
Toto je transkluze. Volání:
frame:expandTemplate{ title = 'template', args = { 'arg1', 'arg2', name = 'arg3' } }
dělá v Lua zhruba to samé, co {{template|arg1|arg2|name=arg3}}
dělá ve wikitextu. Stejně jako v transkluzi, pokud předaný název neobsahuje předponu jmenného prostoru, bude se předpokládat, že je ve jmenném prostoru Template:.
Všimněte si, že nadpis a argumenty nejsou před předáním do šablony předzpracovány:
-- To je zhruba ekvivalentní wikitextu jako {{template|{{!}}}}
frame:expandTemplate{ title = 'template', args = { '|' } }
frame:callParserFunction{ 'msg', { 'template', '|' } }
-- To je zhruba ekvivalentní wikitextu jako {{template|{{((}}!{{))}}}}
frame:expandTemplate{ title = 'template', args = { '{{!}}' } }
frame:callParserFunction{ 'msg', { 'template', '{{!}}' } }
frame:extensionTag
frame:extensionTag( name, content, args )
frame:extensionTag{ name = string, content = string, args = table_or_string }
To je ekvivalentní volání frame:callParserFunction() s názvem funkce '#tag'
(viz Help:Magic_words#Miscellaneous) a s name
a content
připojenými k args
.
-- Tyto jsou rovnocenné
frame:extensionTag( 'ref', 'some text', { name = 'foo', group = 'bar' } )
frame:extensionTag{ name = 'ref', content = 'some text', args = { name = 'foo', group = 'bar' } }
frame:callParserFunction( '#tag', { 'ref' ,
'some text', name = 'foo', group = 'bar'
} )
-- Tyto jsou rovnocenné
frame:extensionTag{ name = 'ref', content = 'some text', args = { 'some other text' } }
frame:callParserFunction( '#tag', { 'ref',
'some text', 'some other text'
} )
frame:getParent
frame:getParent()
Volaný v rámci vytvořeném {{#invoke:}}
vrátí rámec pro stránku, která volala {{#invoke:}}
. Volaný na tomto snímku vrací nulu.
Pokud například šablona {{Example}}
obsahuje kód {{#invoke:ModuleName|FunctionName|A|B}}
a stránka tuto šablonu převede kódem {{Example|C|D}}
, pak v Module:ModuleName volání frame.args[1]
a frame.args[2]
vrátí "A"
a "B"
a volání frame:getParent().args[1]
a frame:getParent().args[2]
vrátí "C"
a "D"
, přičemž frame
je první argument ve volání funkce.
frame:getTitle
frame:getTitle()
Vrátí název spojený s rámcem jako řetězec. Pro rámec vytvořený {{#invoke:}}
je to název vyvolaného modulu.
frame:newChild
frame:newChild{ title = title, args = table }
- Všimněte si použití pojmenovaných argumentů.
Vytvořte nový frame objekt, který je potomkem aktuálního frame, s volitelnými argumenty a názvem.
Toto je určeno hlavně pro použití v ladicí konzoli pro testování funkcí, které by normálně byly volány {{#invoke:}}
. Počet snímků, které mohou být vytvořeny najednou, je omezený.
frame:preprocess
frame:preprocess( string )
frame:preprocess{ text = string }
Tím se rozbalí wikitext v kontextu rámce, tj. rozbalí se šablony, funkce analyzátoru a parametry, jako je {{{1}}}
, a vrátí se rozbalený text. Některé speciální značky napsané ve stylu XML, jako například <pre>
, <nowiki>
, <gallery>
a <ref>
, budou nahrazeny "strip markers" — speciálními řetězci, které začínají znakem delete (ASCII 127), které mají být nahrazeny HTML poté, co budou vráceny z #invoke
.
Pokud rozšiřujete jednu šablonu, použijte frame:expandTemplate
místo toho, abyste se snažili vytvořit řetězec wikitextu pro předání této metodě. Je rychlejší a méně náchylné k chybám, pokud argumenty obsahují svislé znaky nebo jiné wikimarkupy.
Pokud rozšiřujete funkci jednoho analyzátoru, použijte ze stejných důvodů frame:callParserFunction
.
frame:getArgument
frame:getArgument( arg )
frame:getArgument{ name = arg }
Získá objekt pro zadaný argument nebo nulu, pokud argument není zadán.
Vrácený objekt má jednu metodu, object:expand()
, která vrací rozšířený wikitext pro argument.
frame:newParserValue
frame:newParserValue( text )
frame:newParserValue{ text = text }
Vrátí objekt jednou metodou, object:expand()
, která vrátí výsledek frame:preprocess( text )
.
frame:newTemplateParserValue
frame:newTemplateParserValue{ title = title, args = table }
- Všimněte si použití pojmenovaných argumentů.
Vrátí objekt s jednou metodou, object:expand()
, která vrátí výsledek frame:expandTemplate
volaného s danými argumenty.
frame:argumentPairs
frame:argumentPairs()
Stejně jako pairs( frame.args )
. Zahrnuto pro zpětnou kompatibilitu.
Knihovna hash
mw.hash.hashValue
mw.hash.hashValue( něco, hodnota )
Hašuje hodnotu řetězce se zadaným algoritmem. Platné algoritmy lze načíst pomocí mw.hash.listAlgorithms().
mw.hash.listAlgorithms
mw.hash.listAlgorithms()
Vrátí seznam podporovaných hashovacích algoritmů pro použití v mw.hash.hashValue().
Knihovna HTML
mw.html
je plynulé rozhraní pro vytváření komplexního HTML z Lua. Objekt mw.html lze vytvořit pomocí mw.html.create
.
Funkce dokumentované jako mw.html.name
jsou dostupné v globální tabulce mw.html
. Funkce dokumentované jako mw.html:name
a html:name
jsou metody objektu mw.html (viz mw.html.create
).
Základní příklad by mohl vypadat takto:
local div = mw.html.create( 'div' )
div
:attr( 'id', 'testdiv' )
:css( 'width', '100%' )
:wikitext( 'Some text' )
:tag( 'hr' )
return tostring( div )
-- Output: <div id="testdiv" style="width:100%;">Some text<hr /></div>
mw.html.create
mw.html.create( tagName, args )
Vytvoří nový objekt mw.html obsahující prvek html tagName
. Můžete také předat prázdný řetězec nebo nil jako tagName
, abyste vytvořili prázdný objekt mw.html.
args
může být tabulka s následujícími klíči:
args.selfClosing
: Vynutí automatické uzavření aktuální značky, i když ji mw.html jako samouzavírací nerozpoznáargs.parent
: Nadřazený prvek aktuální instance mw.html (určeno pro interní použití)
mw.html:node
html:node( builder )
Připojí podřízený uzel mw.html (builder
) k aktuální instanci mw.html. Pokud je předán nulový parametr, jedná se o neoperaci. Uzel (builder
) je řetězcová reprezentace prvku html.
mw.html:wikitext
html:wikitext( ... )
Připojí k objektu mw.html neurčený počet řetězců wikitextu.
Všimněte si, že toto končí u první položky nula (nil).
Basic wikitext will get parsed, like HTML, links, bold, lists or tables. However, templates and parser functions won't be evaluated if they are passed directly to this function, unless they came from template parameters. Those will be rendered in plain text instead. To evaluate them, they'll have to be passed through frame:preprocess.
mw.html:newline
html:newline()
Připojí nový řádek k objektu mw.html. Useful when used before and after mw.html:wikitext(), when the wikitext contains lists or tables, whose syntax only has a special meaning when present at the start of a line.
mw.html:tag
html:tag( tagName, args )
Připojí nový podřízený uzel s daným tagName
k staviteli a vrátí instanci mw.html představující tento nový uzel. Parametr args
je shodný s parametrem mw.html.create
Všimněte si, že na rozdíl od jiných metod, jako je html:node()
, tato metoda nevrací aktuální instanci mw.html, ale instanci mw.html nově vložené značky.
Ujistěte se, že používáte html:done()
pro přechod na nadřazenou instanci mw.html nebo html:allDone()
, pokud máte vnořené značky na několika úrovních.
mw.html:attr
html:attr( name, value )
html:attr( table )
Nastavte atribut HTML s daným name
a value
na uzlu. Alternativně lze předat tabulku obsahující páry atributů název->hodnota k nastavení. V prvním formuláři hodnota nil způsobí, že jakýkoli atribut s daným názvem nebude nastaven, pokud byl dříve nastaven.
mw.html:getAttr
html:getAttr( name )
Získejte hodnotu dříve nastaveného atributu html pomocí html:attr()
s daným name
.
mw.html:addClass
html:addClass( class )
Přidá název třídy do atributu class uzlu. Pokud je předán nulový parametr, nejedná se o operaci.
mw.html:css
html:css( name, value )
html:css( table )
Nastavte vlastnost CSS s daným name
a value
na uzlu. Alternativně lze předat tabulku obsahující páry vlastností název->hodnota k nastavení. V prvním formuláři hodnota nil způsobí, že jakákoli vlastnost s daným názvem nebude nastavena, pokud byla dříve nastavena.
mw.html:cssText
html:cssText( css )
Přidejte nějaké nezpracované css
do atributu stylu uzlu. Pokud je předán nulový parametr, nejedná se o operaci.
mw.html:done
html:done()
Vrátí nadřazený uzel, pod kterým byl vytvořen aktuální uzel. Stejně jako jQuery.end se jedná o pohodlnou funkci, která umožňuje zřetězení několika podřízených uzlů do jednoho příkazu.
mw.html:allDone
html:allDone()
Jako html:done()
, ale projde celou cestu ke kořenovému uzlu stromu a vrátí jej.
Jazyková knihovna
Kódy jazyků jsou popsány na kód jazyka. Mnoho jazykových kódů MediaWiki je podobných jazykovým značkám IETF, ale ne všechny kódy jazyků MediaWiki jsou platnými značkami IETF a naopak.
Funkce dokumentované jako mw.language.name
jsou dostupné v globální tabulce mw.language
. Funkce dokumentované jako mw.language:name
a lang:name
jsou metody jazykového objektu (viz mw.language.new
nebo mw.language.getContentLanguage
).
mw.language.fetchLanguageName
mw.language.fetchLanguageName( code, inLanguage )
Úplný název jazyka pro daný kód jazyka: Ve výchozím nastavení nativní název (autonomní jazyka), název přeložený do cílového jazyka, pokud je uvedena hodnota pro inLanguage.
mw.language.fetchLanguageNames
mw.language.fetchLanguageNames()
mw.language.fetchLanguageNames( inLanguage )
mw.language.fetchLanguageNames( inLanguage, include )
Načte seznam jazyků známých MediaWiki a vraťte tabulku mapující kód jazyka na název jazyka.
Ve výchozím nastavení je vrácen název autonomního jazyka. Předání kódu jazyka pro inLanguage vrátí všechna jména v tomto jazyce.
Ve výchozím nastavení jsou vráceny pouze názvy jazyků známé MediaWiki. Předání 'all'
pro include vrátí všechny dostupné jazyky (od Rozšíření:CLDR ), zatímco předání 'mwfile'
zahrne pouze jazyky s přizpůsobenými zprávami zahrnutými do jádra MediaWiki nebo povolených rozšíření. Chcete-li explicitně vybrat výchozí hodnotu, může být předáno 'mw'
.
mw.language.getContentLanguage
mw.language.getContentLanguage()
mw.getContentLanguage()
Vrátí nový jazykový objekt pro výchozí jazyk obsahu wiki.
mw.language.getFallbacksFor
mw.language.getFallbacksFor( code )
Vrátí seznam záložních jazykových kódů MediaWiki pro zadaný kód.
mw.language.isKnownLanguageTag
mw.language.isKnownLanguageTag( code )
Vrátí hodnotu true
, pokud MediaWiki zná kód jazyka.
Kód jazyka je "známý", pokud se jedná o "platný vestavěný kód" (tj. vrací hodnotu true
pro mw.language.isValidBuiltInCode
) a vrací neprázdný řetězec pro mw.language.fetchLanguageName
.
mw.language.isSupportedLanguage
mw.language.isSupportedLanguage( code )
Zkontroluje, zda je v MediaWiki pro daný kód jazyka k dispozici nějaká lokalizace.
Jazykový kód je "podporován", pokud je "platným" kódem (vrací hodnotu true
pro mw.language.isValidCode
), neobsahuje žádná velká písmena a má soubor zpráv v aktuálně spuštěné verzi MediaWiki.
Je možné, že kód jazyka bude "podporován", ale není „známý“ (tj. vrátí hodnotu true
pro mw.language.isKnownLanguageTag
). Všimněte si také, že některé kódy jsou "podporovány", přestože mw.language.isValidBuiltInCode
vrací false
.
mw.language.isValidBuiltInCode
mw.language.isValidBuiltInCode( code )
Vrátí hodnotu true, pokud má kód jazyka platnou formu pro účely interního přizpůsobení MediaWiki.
Kód nemusí ve skutečnosti odpovídat žádnému známému jazyku.
Kód jazyka je "platný vestavěný kód", pokud je "platným" kódem (tj. vrací hodnotu true pro mw.language.isValidCode
); sestává pouze z ASCII písmen, čísel a pomlček. A má alespoň dva znaky.
Všimněte si, že některé kódy jsou "podporovány" (tj. vrací true z mw.language.isSupportedLanguage
), i když tato funkce vrací false.
mw.language.isValidCode
mw.language.isValidCode( code )
Vrátí hodnotu true, pokud má řetězec kódu jazyka platnou formu, ať už existuje či nikoli. To zahrnuje kódy, které se používají výhradně pro přizpůsobení prostřednictvím jmenného prostoru MediaWiki.
Kód nemusí ve skutečnosti odpovídat žádnému známému jazyku.
Jazykový kód je platný, pokud neobsahuje určité nebezpečné znaky (dvojtečky, jednoduché nebo dvojité uvozovky, lomítka, zpětná lomítka, lomené závorky, ampersandy nebo ASCII NUL) a je jinak povolen v názvu stránky.
mw.language.new
mw.language.new( code )
mw.getLanguage( code )
Vytvoří nový jazykový objekt. Jazykové objekty nemají žádné veřejně přístupné vlastnosti, ale mají několik metod, které jsou zdokumentovány níže.
Počet odlišných jazykových kódů, které lze na stránce použít, je omezen. Překročení tohoto limitu bude mít za následek chyby.
mw.language:getCode
lang:getCode()
Vrátí kód jazyka pro tento jazykový objekt.
mw.language:toBcp47Code
lang:toBcp47Code()
Vrátí standardní BCP-47 kód jazyka pro tento objekt jazyka. Toto je kódový řetězec, který je vhodné použít v HTML, například jako hodnotu atributu lang
.
mw.language:getFallbackLanguages
lang:getFallbackLanguages()
Vrátí seznam záložních jazykových kódů MediaWiki pro tento jazykový objekt. Ekvivalent mw.language.getFallbacksFor( lang:getCode() )
.
mw.language:isRTL
lang:isRTL()
Vrátí true, pokud je jazyk psán zprava doleva, false, pokud je psán zleva doprava.
mw.language:lc
lang:lc( s )
Převede řetězec na malá písmena, respektuje všechna speciální pravidla pro daný jazyk.
Pokud je načtena knihovna Ustring, je funkce mw.ustring.lower() implementována jako volání mw.language.getContentLanguage():lc( s )
.
mw.language:lcfirst
lang:lcfirst( s )
Převede první znak řetězce na malá písmena, jako u lang:lc()
.
mw.language:uc
lang:uc( s )
Převede řetězec na velká písmena, respektuje všechna speciální pravidla pro daný jazyk.
Pokud je načtena knihovna Ustring, je funkce mw.ustring.upper()
implementována jako volání mw.language.getContentLanguage():uc( s )
.
mw.language:ucfirst
lang:ucfirst( s )
Převede první znak řetězce na velká písmena, jako u lang:uc().
mw.language:caseFold
lang:caseFold( s )
Převede řetězec na reprezentaci vhodnou pro porovnání bez ohledu na velikost písmen. Pamatujte, že výsledek nemusí při zobrazení dávat smysl.
mw.language:formatNum
lang:formatNum( n )
lang:formatNum( n, options )
Formátuje číslo se seskupením a oddělovači desetinných míst vhodnými pro daný jazyk. Vzhledem k 123456.78 může vytvořit "123,456,78", "123.456,78" nebo dokonce něco jako "١٢٣٬٤٥٦٫٧٨" v závislosti na jazyku a konfiguraci wiki.
options
je tabulka možností, které mohou být:
noCommafy
: Nastavením true vynecháte oddělovače seskupení a jako oddělovač desetinných míst použijete tečku (.
).
Stále může docházet k transformaci číslic, což může zahrnovat transformaci desetinného oddělovače.
mw.language:formatDate
lang:formatDate( format, timestamp, local )
Formátuje datum podle zadaného formátovacího řetězce. Pokud je timestamp
vynechán, výchozí je aktuální čas. Hodnota pro local
musí být booleovská nebo nulová; pokud je true, čas je formátován v místním čase wiki spíše než v UTC.
Formátovací řetězec a podporované hodnoty pro timestamp
jsou totožné s těmi pro #funkci analyzátoru času z Rozšíření:ParserFunctions .
Všimněte si však, že zpětná lomítka může být nutné zdvojnásobit v řetězcovém literálu Lua, protože Lua také používá zpětné lomítko jako znak escape, zatímco wikitext ne:
-- Tento řetězcový literál obsahuje nový řádek, nikoli dva znaky "\n", takže není ekvivalentní k {{#time:\n}}.
lang:formatDate( '\n' )
-- Toto je ekvivalentní {{#time:\n}}, nikoli {{#time:\\n}}.
lang:formatDate( '\\n' )
-- Toto je ekvivalent {{#time:\\n}}, nikoli {{#time:\\\\n}}.
lang:formatDate( '\\\\n' )
mw.language:formatDuration
lang:formatDuration( seconds )
lang:formatDuration( seconds, chosenIntervals )
Rozdělí dobu trvání v sekundách do více čitelných jednotek, např. 12345 na 3 hodiny, 25 minut a 45 sekund, výsledek se vrátí jako řetězec.
chosenIntervals
, pokud je zadán, je tabulka s hodnotami pojmenujícími jednotky intervalu, které se mají použít v odpovědi. Patří mezi ně 'millennia
' (tisíciletí), 'centuries
' (století), 'decades
' (dekády), 'years
' (roky), 'weeks
' (týdny), 'days
' (dny), 'hours
' (hodiny), 'minutes
' (minuty) a 'seconds
' (sekundy).
mw.language:parseFormattedNumber
lang:parseFormattedNumber( s )
To převezme číslo ve formátu lang:formatNum() a vrátí skutečné číslo. Jinými slovy, toto je v podstatě jazyková verze tonumber()
.
mw.language:convertPlural
lang:convertPlural( n, ... )
lang:convertPlural( n, forms )
lang:plural( n, ... )
lang:plural( n, forms )
Vybere vhodnou gramatickou formu z forms
(což musí být tabulka sequence) nebo ...
na základě čísla n
. Například v angličtině můžete použít n .. ' ' .. lang:plural( n, 'sock', 'socks' )
nebo n .. ' ' .. lang:plural( n, { 'ponožka', 'ponožky' } )
pro vygenerování gramaticky správného textu bez ohledu na to, zda je k dispozici pouze 1 ponožka nebo 200 ponožek.
Potřebné hodnoty pro sekvenci jsou závislé na jazyce, viz lokalizace kouzelných slov a Nejčastější dotazy na translatewiki na PLURAL, kde jsou některé podrobnosti.
mw.language:convertGrammar
lang:convertGrammar( word, case )
lang:grammar( case, word )
- Všimněte si rozdílného pořadí parametrů mezi dvěma aliasy.
convertGrammar
odpovídá pořadí stejnojmenné metody v objektu Language MediaWiki, zatímcogrammar
odpovídá pořadí stejnojmenné funkce analyzátoru, dokumentované na Nápověda:Magická slovíčka#Lokalizace.
Tím se vybere vhodná skloňovaná forma word
pro daný kód skloňování case
.
Možné hodnoty pro word
a case
jsou závislé na jazyce, viz Special:MyLanguage/Help:Magic words#Localisation a translatewiki:Grammar pro některé podrobnosti.
mw.language:gender
lang:gender( what, masculine, feminine, neutral )
lang:gender( what, { masculine, feminine, neutral } )
Vybere řetězec odpovídající pohlaví co
, což může být "muž", "žena" nebo registrované uživatelské jméno.
mw.language:getArrow
lang:getArrow( direction )
Vrátí znak šipky Unicode odpovídající směru
:
- vpřed: Buď "→" nebo "←" v závislosti na směrovosti jazyka.
- zpět: Buď "←" nebo "→" v závislosti na směrovosti jazyka.
- vlevo: "←"
- správně: "→"
- nahoru: "↑"
- dolů: "↓"
mw.language:getDir
lang:getDir()
Vrátí "ltr" nebo "rtl" v závislosti na směrovosti jazyka.
mw.language:getDirMark
lang:getDirMark( opposite )
Vrátí řetězec obsahující buď U+200E (značka zleva doprava) nebo U+200F (značka zprava doleva), v závislosti na směrovosti jazyka a na tom, zda je opačný
pravdivá nebo nepravdivá hodnota.
mw.language:getDirMarkEntity
lang:getDirMarkEntity( opposite )
Vrátí "‎" nebo "‏", v závislosti na směrovosti jazyka a na tom, zda je opačná
hodnota pravdivá nebo nepravdivá.
mw.language:getDurationIntervals
lang:getDurationIntervals( seconds )
lang:getDurationIntervals( seconds, chosenIntervals )
Rozdělí dobu trvání v sekundách do více čitelných jednotek, např. 12345 na 3 hodiny, 25 minut a 45 sekund, přičemž výsledek se vrátí jako tabulka mapující názvy jednotek na čísla.
chosenIntervals
, pokud je zadán, je tabulka s hodnotami pojmenujícími jednotky intervalu, které se mají použít v odpovědi. Patří mezi ně 'millennia
' (tisíciletí), 'centuries
' (století), 'decades
' (dekády), 'years
' (roky), 'weeks
' (týdny), 'days
' (dny), 'hours
' (hodiny), 'minutes
' (minuty) a 'seconds
' (sekundy).
Tato klíčová slova jednotek jsou také klíči používanými v tabulce odpovědí. V odpovědi jsou nastaveny pouze jednotky s nenulovou hodnotou, pokud by odpověď nebyla prázdná, v takovém případě je vrácena nejmenší jednotka s hodnotou 0.
Knihovna zpráv
Tato knihovna je rozhraním pro lokalizační zprávy a jmenný prostor MediaWiki:.
Funkce dokumentované jako mw.message.name
jsou dostupné v globální tabulce mw.message
; funkce dokumentované jako mw.message:name
a msg:name
jsou metody objektu zprávy (viz mw.message.new
).
mw.message.new
mw.message.new( key, ... )
Vytvoří nový objekt zprávy pro danou zprávu key
.
Zbývající parametry jsou předány metodě params()
nového objektu.
Objekt zprávy nemá žádné vlastnosti, ale má několik níže popsaných metod.
mw.message.newFallbackSequence
mw.message.newFallbackSequence( ... )
Vytvoří nový objekt zprávy pro dané zprávy (použije se první, který existuje).
Objekt zprávy nemá žádné vlastnosti, ale má několik níže popsaných metod.
mw.message.newRawMessage
mw.message.newRawMessage( msg, ... )
Vytvoří nový objekt zprávy, který použije přímo daný text, místo aby vyhledával internacionalizovanou zprávu. Zbývající parametry jsou předány metodě params()
nového objektu.
Objekt zprávy nemá žádné vlastnosti, ale má několik níže popsaných metod.
mw.message.rawParam
mw.message.rawParam( value )
Zabalí hodnotu tak, aby nebyla analyzována jako wikitext pomocí msg:parse()
.
mw.message.numParam
mw.message.numParam( value )
Zabalí hodnotu tak, aby byla automaticky naformátována jako lang:formatNum()
. Všimněte si, že to nezávisí na Language library skutečně dostupné.
mw.message.getDefaultLanguage
mw.message.getDefaultLanguage()
Vrátí jazykový objekt pro výchozí jazyk.
mw.message:params
msg:params( ... )
msg:params( params )
Přidá do zprávy parametry, které mohou být předány jako jednotlivé argumenty nebo jako sekvenční tabulka. Parametry musí být čísla, řetězce nebo speciální hodnoty vrácené funkcí mw.message.numParam() nebo mw.message.rawParam(). Pokud je použita sekvenční tabulka, parametry musí být přímo přítomny v tabulce. Odkazy používající __index metametodu nebudou fungovat.
Vrátí objekt msg
, aby bylo umožněno řetězení hovorů.
mw.message:rawParams
msg:rawParams( ... )
msg:rawParams( params )
Jako :params(), ale má za následek předání všech parametrů nejprve přes mw.message.rawParam().
Vrátí objekt msg
, aby bylo umožněno řetězení hovorů.
mw.message:numParams
msg:numParams( ... )
msg:numParams( params )
Jako :params(), ale má za následek předání všech parametrů nejprve přes mw.message.numParam().
Vrátí objekt msg
, aby bylo umožněno řetězení hovorů.
mw.message:inLanguage
msg:inLanguage( lang )
Určuje jazyk, který se má použít při zpracování zprávy. lang
může být řetězec nebo tabulka s metodou getCode()
(tj. Language objekt).
Výchozí jazyk je ten, který vrací mw.message.getDefaultLanguage()
.
Vrátí objekt msg
, aby bylo umožněno řetězení hovorů.
mw.message:useDatabase
msg:useDatabase( bool )
Určuje, zda se mají vyhledávat zprávy v MediaWiki: jmenný prostor (tj. hledat v databázi), nebo jen použít výchozí zprávy distribuované s MediaWiki.
Výchozí hodnota je true.
Vrátí objekt msg
, aby bylo umožněno řetězení hovorů.
mw.message:plain
msg:plain()
Nahradí parametry a vrátí zprávu wikitext tak, jak je. Volání šablony a funkce analyzátoru jsou nedotčeny.
mw.message:exists
msg:exists()
Vrátí boolean označující, zda klíč zprávy existuje.
mw.message:isBlank
msg:isBlank()
Vrací logickou hodnotu označující, zda má klíč zprávy obsah. Vrátí hodnotu true, pokud klíč zprávy neexistuje nebo je zpráva prázdný řetězec.
mw.message:isDisabled
msg:isDisabled()
Vrátí logickou hodnotu označující, zda je klíč zprávy zakázán. Vrátí hodnotu true, pokud klíč zprávy neexistuje nebo pokud je zpráva prázdný řetězec nebo řetězec "-".
Knihovna stránek
mw.site.currentVersion
Řetězec obsahující aktuální verzi MediaWiki.
mw.site.scriptPath
Hodnota $wgScriptPath
.
mw.site.server
Hodnota $wgServer
.
mw.site.siteName
Hodnota $wgSitename
.
mw.site.stylePath
Hodnota $wgStylePath
.
mw.site.namespaces
Tabulka obsahující data pro všechny jmenné prostory, indexovaná podle čísla.
Dostupné údaje jsou:
- id: * $1: Číslo jmenného prostoru.
- name: * $1: Místní název jmenného prostoru.
- canonicalName: Kanonický název jmenného prostoru.
- displayName: Nastaveno na jmenný prostor 0, název, který se má použít pro zobrazení (protože název je často prázdný řetězec).
- hasSubpages: Zda jsou pro jmenný prostor povoleny podstránky.
- hasGenderDistinction: Zda má jmenný prostor různé aliasy pro různá pohlaví.
- isCapitalized: Zda je první písmeno stránek ve jmenném prostoru velké.
- isContent: Zda se jedná o jmenný prostor obsahu.
- isIncludable: Whether pages in the namespace can be transcluded.
- isMovable: Whether pages in the namespace can be moved.
- isSubject: Whether this is a subject namespace.
- isTalk: Whether this is a talk namespace.
- defaultContentModel: The default content model for the namespace, as a string.
- aliases: List of aliases for the namespace.
- subject: Reference to the corresponding subject namespace's data.
- talk: Reference to the corresponding talk namespace's data.
- associated: Reference to the associated namespace's data.
A metatable is also set that allows for looking up namespaces by name (localized or canonical). For example, both mw.site.namespaces[4]
and mw.site.namespaces.Project
will return information about the Project namespace.
mw.site.contentNamespaces
Table holding just the content namespaces, indexed by number. See mw.site.namespaces for details.
mw.site.subjectNamespaces
Table holding just the subject namespaces, indexed by number. See mw.site.namespaces for details.
mw.site.talkNamespaces
Table holding just the talk namespaces, indexed by number. See mw.site.namespaces for details.
mw.site.stats
Table holding site statistics. Available statistics are:
- pages: Number of pages in the wiki.
- articles: Number of articles in the wiki.
- files: Number of files in the wiki.
- edits: Number of edits in the wiki.
- users: Number of users in the wiki.
- activeUsers: Number of active users in the wiki.
- admins: Number of users in group 'sysop' in the wiki.
mw.site.stats.pagesInCategory
mw.site.stats.pagesInCategory( category, which )
- This function is expensive
Gets statistics about the category. If which
has the special value "*
", the result is a table with the following properties:
- all: Total pages, files, and subcategories.
- subcats: Number of subcategories.
- files: Number of files.
- pages: Number of pages.
If which
is one of the above keys ("all", "subcats", "files", "pages"), the result is a number with the corresponding value.
Each new category queried will increment the expensive function count.
mw.site.stats.pagesInNamespace
mw.site.stats.pagesInNamespace( ns )
Returns the number of pages in the given namespace (specify by number).
mw.site.stats.usersInGroup
mw.site.stats.usersInGroup( group )
Returns the number of users in the given group.
mw.site.interwikiMap
mw.site.interwikiMap( filter )
Returns a table holding data about available interwiki prefixes. If filter
is the string "local", then only data for local interwiki prefixes is returned. If filter
is the string "!local", then only data for non-local prefixes is returned. If no filter is specified, data for all prefixes is returned. A "local" prefix in this context is one that is for the same project. For example, on the English Wikipedia, other-language Wikipedias are considered local, while Wiktionary and such are not.
Keys in the table returned by this function are interwiki prefixes, and the values are subtables with the following properties:
- prefix - the interwiki prefix.
- url - the URL that the interwiki points to. The page name is represented by the parameter $1.
- isProtocolRelative - a boolean showing whether the URL is protocol-relative.
- isLocal - whether the URL is for a site in the current project.
- isCurrentWiki - whether the URL is for the current wiki.
- isTranscludable - whether pages using this interwiki prefix are transcludable. This requires scary transclusion, which is disabled on Wikimedia wikis.
- isExtraLanguageLink - whether the interwiki is listed in
$wgExtraInterlanguageLinkPrefixes
.
- displayText - for links listed in $wgExtraInterlanguageLinkPrefixes, this is the display text shown for the interlanguage link. Nil if not specified.
- tooltip - for links listed in $wgExtraInterlanguageLinkPrefixes, this is the tooltip text shown when users hover over the interlanguage link. Nil if not specified.
Text library
The text library provides some common text processing functions missing from the String library and the Ustring library. These functions are safe for use with UTF-8 strings.
mw.text.decode
mw.text.decode( s )
mw.text.decode( s, decodeNamedEntities )
Replaces HTML entities in the string with the corresponding characters.
If boolean decodeNamedEntities
is omitted or false, the only named entities recognized are <
(<), >
(>), &
(&), "
(") and
(the non-breaking space, U+00A0).
Otherwise, the list of HTML5 named entities to recognize is loaded from PHP's get_html_translation_table
function.
Known bugs: Approximately 600 of around 2 200 named entities in the HTML5 standard do not get decoded, even when decodeNamedEntities
is used; this includes approximately 40 of around 250 entities which are also included in HTML4.
This occurs because PHP's get_html_translation_table
function returns only one mapping for each character, so for example
is not decoded since PHP returns only →
as the mapping for →
.
→
mw.text.encode
mw.text.encode( s )
mw.text.encode( s, charset )
Replaces characters in a string with HTML entities.
Five characters are replaced with the appropriate named entities: <
, >
, &
, "
and the non-breaking space (U+00A0).
All others are replaced with numeric entities.
If charset
is supplied, it should be a string as appropriate to go inside brackets in a Ustring pattern, i.e. the "set" in [set]
. The default charset contains six characters: <
, >
, &
, "
, '
and the non-breaking space (U+00A0).
mw.text.jsonDecode
mw.text.jsonDecode( s )
mw.text.jsonDecode( s, flags )
Decodes a JSON string. flags
is 0 or a combination (use +
) of the flags mw.text.JSON_PRESERVE_KEYS
and mw.text.JSON_TRY_FIXING
.
Normally JSON's zero-based arrays are renumbered to Lua one-based sequence tables; to prevent this, pass mw.text.JSON_PRESERVE_KEYS
.
To relax certain requirements in JSON, such as no terminal comma in arrays or objects, pass mw.text.JSON_TRY_FIXING
. This is not recommended.
Limitations:
- Decoded JSON arrays may not be Lua sequences if the array contains null values.
- JSON objects will drop keys having null values.
- It is not possible to directly tell whether the input was a JSON array or a JSON object with sequential integer keys.
- A JSON object having sequential integer keys beginning with 1 will decode to the same table structure as a JSON array with the same values, despite these not being at all equivalent, unless
mw.text.JSON_PRESERVE_KEYS
is used.
mw.text.jsonEncode
mw.text.jsonEncode( value )
mw.text.jsonEncode( value, flags )
Encode a JSON string. Errors are raised if the passed value cannot be encoded in JSON. flags
is 0 or a combination (use +
) of the flags mw.text.JSON_PRESERVE_KEYS
and mw.text.JSON_PRETTY
.
Normally Lua one-based sequence tables are encoded as JSON zero-based arrays; when mw.text.JSON_PRESERVE_KEYS
is set in flags
, zero-based sequence tables are encoded as JSON arrays.
Limitations:
- Empty tables are always encoded as empty arrays (
[]
), not empty objects ({}
). - Sequence tables cannot be encoded as JSON objects without adding a "dummy" element.
- To produce objects or arrays with nil values, a tricky implementation of the
__pairs
metamethod is required. - A Lua table having sequential integer keys beginning with 0 will encode as a JSON array, the same as a Lua table having integer keys beginning with 1, unless
mw.text.JSON_PRESERVE_KEYS
is used. - When both a number and the string representation of that number are used as keys in the same table, behavior is unspecified.
mw.text.killMarkers
mw.text.killMarkers( s )
Removes all MediaWiki strip markers from a string.
mw.text.listToText
mw.text.listToText( list )
mw.text.listToText( list, separator, conjunction )
Joins a list, prose-style. In other words, it's like table.concat()
but with a different separator before the final item.
The default separator is taken from MediaWiki:comma-separator in the wiki's content language, and the default conjunction is MediaWiki:and concatenated with MediaWiki:word-separator.
Examples, using the default values for the messages:
-- Returns the empty string
mw.text.listToText( {} )
-- Returns "1"
mw.text.listToText( { 1 } )
-- Returns "1 and 2"
mw.text.listToText( { 1, 2 } )
-- Returns "1, 2, 3, 4 and 5"
mw.text.listToText( { 1, 2, 3, 4, 5 } )
-- Returns "1; 2; 3; 4 or 5"
mw.text.listToText( { 1, 2, 3, 4, 5 }, '; ', ' or ' )
mw.text.nowiki
mw.text.nowiki( s )
Replaces various characters in the string with HTML entities to prevent their interpretation as wikitext. This includes:
- The following characters:
"
,&
,'
,<
,=
,>
,[
,]
,{
,|
,}
- The following characters at the start of the string or immediately after a newline:
#
,*
,:
,;
, space, tab (\t
) - Blank lines will have one of the associated newline or carriage return characters escaped
----
at the start of the string or immediately after a newline will have the first-
escaped__
will have one underscore escaped://
will have the colon escaped- A whitespace character following
ISBN
,RFC
, orPMID
will be escaped
mw.text.split
mw.text.split( s, pattern, plain )
Splits the string into substrings at boundaries matching the Ustring pattern pattern
. If plain
is specified and true, pattern
will be interpreted as a literal string rather than as a Lua pattern (just as with the parameter of the same name for mw.ustring.find()
). Returns a table containing the substrings.
For example, mw.text.split( 'a b\tc\nd', '%s' )
would return a table { 'a', 'b', 'c', 'd' }
.
If pattern
matches the empty string, s
will be split into individual characters.
Note that this function can be over 60 times slower than a reimplementation that is not Unicode-aware, such as the following:
function split(text, pattern, plain)
local ret = {}
local s, l = 1, string.len( text )
while s do
local e, n = string.find( text, pattern, s, plain )
if not e then
ret[#ret+1] = string.sub ( text, s )
s = nil
elseif n < e then
-- Empty separator!
ret[#ret+1] = string.sub ( text, s, e )
if e < l then
s = e + 1
else
s = nil
end
else
ret[#ret+1] = e > s and string.sub( text, s, e - 1 ) or ''
s = n + 1
end
end
return ret
end
mw.text.gsplit
mw.text.gsplit( s, pattern, plain )
Returns an iterator function that will iterate over the substrings that would be returned by the equivalent call to mw.text.split()
.
Note that this function can be over 60 times slower than a reimplementation that is not Unicode-aware, such as the following:
function gsplit( text, pattern, plain )
local s, l = 1, string.len( text )
return function ()
if s then
local e, n = string.find( text, pattern, s, plain )
local ret
if not e then
ret = string.sub( text, s )
s = nil
elseif n < e then
-- Empty separator!
ret = string.sub( text, s, e )
if e < l then
s = e + 1
else
s = nil
end
else
ret = e > s and string.sub( text, s, e - 1 ) or ''
s = n + 1
end
return ret
end
end, nil, nil
end
mw.text.tag
mw.text.tag( name, attrs, content )
mw.text.tag{ name = string, attrs = table, content = string|false }
- Note the use of named arguments.
Generates an HTML-style tag for name
.
If attrs
is given, it must be a table with string keys. String and number values are used as the value of the attribute; boolean true results in the key being output as an HTML5 valueless parameter; boolean false skips the key entirely; and anything else is an error.
If content
is not given (or is nil), only the opening tag is returned. If content
is boolean false, a self-closed tag is returned. Otherwise it must be a string or number, in which case that content is enclosed in the constructed opening and closing tag. Note the content is not automatically HTML-encoded; use mw.text.encode() if needed.
For properly returning extension tags such as <ref>
, use frame:extensionTag() instead.
mw.text.trim
mw.text.trim( s )
mw.text.trim( s, charset )
Remove whitespace or other characters from the beginning and end of a string.
If charset
is supplied, it should be a string as appropriate to go inside brackets in a Ustring pattern, i.e. the "set" in [set]
. The default charset is ASCII whitespace, %s
, which is equivalent to "\t\r\n\f\v "
.
mw.text.truncate
mw.text.truncate( text, length )
mw.text.truncate( text, length, ellipsis )
mw.text.truncate( text, length, ellipsis, adjustLength )
Truncates text
to the specified length in code points, adding ellipsis
if truncation was performed. If length is positive, the end of the string will be truncated; if negative, the beginning will be removed. If adjustLength
is given and true, the resulting string including ellipsis will not be longer than the specified length.
The default value for ellipsis
is taken from MediaWiki:ellipsis in the wiki's content language.
Examples, using the default "..." ellipsis:
-- Returns "foobarbaz"
mw.text.truncate( "foobarbaz", 9 )
-- Returns "fooba..."
mw.text.truncate( "foobarbaz", 5 )
-- Returns "...arbaz"
mw.text.truncate( "foobarbaz", -5 )
-- Returns "foo..."
mw.text.truncate( "foobarbaz", 6, nil, true )
-- Returns "foobarbaz", because that's shorter than "foobarba..."
mw.text.truncate( "foobarbaz", 8 )
mw.text.unstripNoWiki
mw.text.unstripNoWiki( s )
Replaces MediaWiki <nowiki> strip markers with the corresponding text. Other types of strip markers are not changed.
mw.text.unstrip
mw.text.unstrip( s )
Equivalent to mw.text.killMarkers( mw.text.unstripNoWiki( s ) )
.
This no longer reveals the HTML behind special page transclusion, <ref> tags, and so on as it did in earlier versions of Scribunto.
Title library
mw.title.equals
mw.title.equals( a, b )
Test for whether two titles are equal. Note that fragments are ignored in the comparison.
mw.title.compare
mw.title.compare( a, b )
Returns -1, 0, or 1 to indicate whether the title a
is less than, equal to, or greater than title b
.
This compares titles by interwiki prefix (if any) as strings, then by namespace number, then by the unprefixed title text as a string. These string comparisons use Lua's standard <
operator.
mw.title.getCurrentTitle
mw.title.getCurrentTitle()
Returns the title object for the current page.
mw.title.new
mw.title.new( text, namespace )
mw.title.new( id )
- This function is expensive when called with an ID
Creates a new title object.
If a number id
is given, an object is created for the title with that page_id. The title referenced will be counted as linked from the current page. If the page_id does not exist, returns nil. The expensive function count will be incremented if the title object created is not for a title that has already been loaded.
If a string text
is given instead, an object is created for that title (even if the page does not exist). If the text string does not specify a namespace, namespace
(which may be any key found in mw.site.namespaces
) will be used. If the text is not a valid title, nil is returned.
mw.title.makeTitle
mw.title.makeTitle( namespace, title, fragment, interwiki )
Creates a title object with title title
in namespace namespace
, optionally with the specified fragment
and interwiki
prefix. namespace
may be any key found in mw.site.namespaces
. If the resulting title is not valid, returns nil.
Note that, unlike mw.title.new()
, this method will always apply the specified namespace. For example, mw.title.makeTitle( 'Template', 'Module:Foo' )
will create an object for the page Template:Module:Foo, while mw.title.new( 'Module:Foo', 'Template' )
will create an object for the page Module:Foo.
Note also that functionality for interwiki titles is limited to interwiki
/ isExternal
/ isLocal
and URL-related methods; other methods might not behave as expected.
Title objects
A title object has a number of properties and methods. Most of the properties are read-only.
Note that fields ending with text
return titles as string values whereas the fields ending with title
return title objects.
- id: The page_id.
0
if the page does not exist.
This may be expensive.
- interwiki: The interwiki prefix, or the empty string if none.
- namespace: The namespace number.
- fragment: The fragment (aka section/anchor linking), or the empty string. May be assigned.
- nsText: The text of the namespace for the page.
- subjectNsText: The text of the subject namespace for the page.
- talkNsText: The text of the talk namespace for the page, or
nil
if this title cannot have a talk page. (added in MediaWiki 1.42.0-wmf.15, refs T180911)
- text: The title of the page, without the namespace or interwiki prefixes.
- prefixedText: The title of the page, with the namespace and interwiki prefixes.
- fullText: The title of the page, with the namespace and interwiki prefixes and the fragment. Interwiki is not returned if equal to the current.
- rootText: If this is a subpage, the title of the root page without prefixes. Otherwise, the same as
title.text
.
- baseText: If this is a subpage, the title of the page it is a subpage of without prefixes. Otherwise, the same as
title.text
.
- subpageText: If this is a subpage, just the subpage name. Otherwise, the same as
title.text
.
- canTalk: Whether the page for this title could have a talk page.
- exists: Whether the page exists. Alias for
file.exists
for Media-namespace titles. For File-namespace titles this checks the existence of the file description page, not the file itself. This may be expensive.
- file, fileExists: See #File metadata below.
- isContentPage: Whether this title is in a content namespace.
- isExternal: Whether this title has an interwiki prefix.
- isLocal: Whether this title is in this project. For example, on the English Wikipedia, any other Wikipedia is considered "local" while Wiktionary and such are not.
- isRedirect: Whether this is the title for a page that is a redirect. This may be expensive.
- isSpecialPage: Whether this is the title for a possible special page (i.e. a page in the Special: namespace).
- isSubpage: Whether this title is a subpage of some other title.
- isTalkPage: Whether this is a title for a talk page.
- isSubpageOf( title2 ): Whether this title is a subpage of the given title.
- inNamespace( ns ): Whether this title is in the given namespace. Namespaces may be specified by anything that is a key found in
mw.site.namespaces
.
- inNamespaces( ... ): Whether this title is in any of the given namespaces. Namespaces may be specified by anything that is a key found in
mw.site.namespaces
.
- hasSubjectNamespace( ns ): Whether this title's subject namespace is in the given namespace. Namespaces may be specified by anything that is a key found in
mw.site.namespaces
.
- contentModel: The content model for this title, as a string. This may be expensive.
- basePageTitle: The same as
mw.title.makeTitle( title.namespace, title.baseText )
.
- rootPageTitle: The same as
mw.title.makeTitle( title.namespace, title.rootText )
.
- talkPageTitle: The same as
mw.title.makeTitle( mw.site.namespaces[title.namespace].talk.id, title.text )
, ornil
if this title cannot have a talk page.
- subjectPageTitle: The same as
mw.title.makeTitle( mw.site.namespaces[title.namespace].subject.id, title.text )
.
- redirectTarget: Returns a title object of the target of the redirect page if the page is a redirect and the page exists, returns
false
otherwise.
- protectionLevels: The page's protection levels. This is a table with keys corresponding to each action (e.g.,
"edit"
and"move"
). The table values are arrays, the first item of which is a string containing the protection level. If the page is unprotected, either the table values or the array items will benil
. This is expensive.
- cascadingProtection: The cascading protections applicable to the page. This is a table with keys
"restrictions"
(itself a table with keys likeprotectionLevels
has) and"sources"
(an array listing titles where the protections cascade from). If no protections cascade to the page,"restrictions"
and"sources"
will be empty. This is expensive.
- categories: (since v1.43.0-wmf.18) The list of categories used on the page. This is expensive
- subPageTitle( text ): The same as
mw.title.makeTitle( title.namespace, title.text .. '/' .. text )
.
- partialUrl(): Returns
title.text
encoded as it would be in a URL.
- fullUrl( query, proto ): Returns the full URL (with optional query table/string) for this title. proto may be specified to control the scheme of the resulting url:
"http"
,"https"
,"relative"
(the default), or"canonical"
.
- localUrl( query ): Returns the local URL (with optional query table/string) for this title.
- canonicalUrl( query ): Returns the canonical URL (with optional query table/string) for this title.
- getContent(): Returns the (unparsed) content of the page, or
nil
if there is no page. The page will be recorded as a transclusion.
- pageLang: A language object for the title's page content language, which defaults to the wiki's content language. This is expensive.
Title objects may be compared using relational operators. tostring( title )
will return title.prefixedText
.
Note that accessing any expensive field on a title object records a "link" to the page (as shown on Special:WhatLinksHere, for example). Using the title object's getContent()
method or accessing the redirectTarget
field records it as a "vložení", and accessing the title object's file
or fileExists
fields records it as a "vložení souboru".
File metadata
Title objects representing a page in the File or Media namespace will have a property called file
. This is expensive. This is a table, structured as follows:
- exists: Whether the file exists. It will be recorded as an image usage. The
fileExists
property on a Title object exists for backwards compatibility reasons and is an alias for this property. If this isfalse
, all other file properties will benil
.
- width: The width of the file. If the file contains multiple pages, this is the width of the first page.
- height: The height of the file. If the file contains multiple pages, this is the height of the first page.
- pages: If the file format supports multiple pages, this is a table containing tables for each page of the file; otherwise, it is
nil
. The # operator can be used to get the number of pages in the file. Each individual page table contains a width and height property.
- size: The size of the file in bytes.
- mimeType: The MIME type of the file.
- length: The length (duration) of the media file in seconds. Zero for media types which do not support length.
Expensive properties
The properties id
, isRedirect
, exists
, and contentModel
require fetching data about the title from the database. For this reason, the expensive function count is incremented the first time one of them is accessed for a page other than the current page. Subsequent accesses of any of these properties for that page will not increment the expensive function count again.
Other properties marked as expensive will always increment the expensive function count the first time they are accessed for a page other than the current page.
URI library
mw.uri.encode
mw.uri.encode( s, enctype )
Percent-encodes the string. The default type, "QUERY"
, encodes spaces using '+' for use in query strings; "PATH"
encodes spaces as %20; and "WIKI"
encodes spaces as '_'.
Note that the "WIKI" format is not entirely reversible, as both spaces and underscores are encoded as '_'.
mw.uri.decode
mw.uri.decode( s, enctype )
Percent-decodes the string. The default type, "QUERY"
, decodes '+' to space; "PATH"
does not perform any extra decoding; and "WIKI"
decodes '_' to space.
mw.uri.anchorEncode
mw.uri.anchorEncode( s )
Encodes a string for use in a MediaWiki URI fragment.
mw.uri.buildQueryString
mw.uri.buildQueryString( table )
Encodes a table as a URI query string. Keys should be strings; values may be strings or numbers, sequence tables, or boolean false.
mw.uri.parseQueryString
mw.uri.parseQueryString( s, i, j )
Decodes the query string s
to a table. Keys in the string without values will have a value of false; keys repeated multiple times will have sequence tables as values; and others will have strings as values.
The optional numerical arguments i
and j
can be used to specify a substring of s
to be parsed, rather than the entire string. i
is the position of the first character of the substring, and defaults to 1. j
is the position of the last character of the substring, and defaults to the length of the string. Both i
and j
can be negative, as in string.sub.
mw.uri.canonicalUrl
mw.uri.canonicalUrl( page, query )
Returns a URI object for the canonical URL for a page, with optional query string/table.
mw.uri.fullUrl
mw.uri.fullUrl( page, query )
Returns a URI object for the full URL for a page, with optional query string/table.
mw.uri.localUrl
mw.uri.localUrl( page, query )
Returns a URI object for the local URL for a page, with optional query string/table.
mw.uri.new
mw.uri.new( s )
Constructs a new URI object for the passed string or table. See the description of URI objects for the possible fields for the table.
mw.uri.validate
mw.uri.validate( table )
Validates the passed table (or URI object). Returns a boolean indicating whether the table was valid, and on failure a string explaining what problems were found.
URI object
The URI object has the following fields, some or all of which may be nil:
- protocol: String protocol/scheme
- user: String user
- password: String password
- host: String host name
- port: Integer port
- path: String path
- query: A table, as from mw.uri.parseQueryString
- fragment: String fragment.
The following properties are also available:
- userInfo: String user and password
- hostPort: String host and port
- authority: String user, password, host, and port
- queryString: String version of the query table
- relativePath: String path, query string, and fragment
tostring()
will give the URI string.
Methods of the URI object are:
mw.uri:parse
uri:parse( s )
Parses a string into the current URI object. Any fields specified in the string will be replaced in the current object; fields not specified will keep their old values.
mw.uri:clone
uri:clone()
Makes a copy of the URI object.
mw.uri:extend
uri:extend( parameters )
Merges the parameters table into the object's query table.
Ustring library
The ustring library is intended to be a direct reimplementation of the standard String library, except that the methods operate on characters in UTF-8 encoded strings rather than bytes.
Most functions will raise an error if the string is not valid UTF-8; exceptions are noted.
mw.ustring.maxPatternLength
The maximum allowed length of a pattern, in bytes.
mw.ustring.maxStringLength
The maximum allowed length of a string, in bytes.
mw.ustring.byte
mw.ustring.byte( s, i, j )
Returns individual bytes; identical to string.byte().
mw.ustring.byteoffset
mw.ustring.byteoffset( s, l, i )
Returns the byte offset of a character in the string. The default for both l
and i
is 1. i
may be negative, in which case it counts from the end of the string.
The character at l
== 1 is the first character starting at or after byte i
; the character at l
== 0 is the first character starting at or before byte i
. Note this may be the same character. Greater or lesser values of l
are calculated relative to these.
mw.ustring.char
mw.ustring.char( ... )
Much like string.char(), except that the integers are Unicode codepoints rather than byte values.
local value = mw.ustring.char( 0x41f, 0x440, 0x438, 0x432, 0x435, 0x442, 0x21 ) -- value is now 'Привет!'
mw.ustring.codepoint
mw.ustring.codepoint( s, i, j )
Much like string.byte(), except that the return values are codepoints and the offsets are characters rather than bytes.
mw.ustring.find
mw.ustring.find( s, pattern, init, plain )
Much like string.find(), except that the pattern is extended as described in Ustring patterns and the init
offset is in characters rather than bytes.
mw.ustring.format
mw.ustring.format( format, ... )
Identical to string.format(). Widths and precisions for strings are expressed in bytes, not codepoints.
mw.ustring.gcodepoint
mw.ustring.gcodepoint( s, i, j )
Returns three values for iterating over the codepoints in the string. i
defaults to 1, and j
to -1. This is intended for use in the iterator form of for
:
for codepoint in mw.ustring.gcodepoint( s ) do
-- block
end
mw.ustring.gmatch
mw.ustring.gmatch( s, pattern )
Much like string.gmatch(), except that the pattern is extended as described in Ustring patterns.
Known bug: When used with a pattern which can match the empty string, the function will get stuck in an infinite loop. For example, the following loop never terminates:
for capture in mw.ustring.gmatch( "foo bar", ".*" ) do
-- block
end
mw.ustring.gsub
mw.ustring.gsub( s, pattern, repl, n )
Much like string.gsub(), except that the pattern is extended as described in Ustring patterns.
Known bugs: When repl
is a table, it is possible to use numbers as keys instead of strings (e.g. to replace instances of
in a string, the value at key "5"
or [5]
would be used); as such, the output is not predictable if they have different (non-nil) values.
["5"]
This is not an issue for string.gsub(), which ignores any numbers as keys.
mw.ustring.isutf8
mw.ustring.isutf8( s )
Returns true if the string is valid UTF-8, false if not.
mw.ustring.len
mw.ustring.len( s )
Returns the length of the string in codepoints, or nil if the string is not valid UTF-8.
See string.len() for a similar function that uses byte length rather than codepoints.
mw.ustring.lower
mw.ustring.lower( s )
Much like string.lower(), except that all characters with lowercase to uppercase definitions in Unicode are converted.
If the Language library is also loaded, this will instead call lc() on the default language object.
mw.ustring.match
mw.ustring.match( s, pattern, init )
Much like string.match(), except that the pattern is extended as described in Ustring patterns and the init
offset is in characters rather than bytes.
mw.ustring.rep
mw.ustring.rep( s, n )
Identical to string.rep().
mw.ustring.sub
mw.ustring.sub( s, i, j )
Much like string.sub(), except that the offsets are characters rather than bytes.
mw.ustring.toNFC
mw.ustring.toNFC( s )
Converts the string to Normalization Form C (also known as Normalization Form Canonical Composition). Returns nil if the string is not valid UTF-8.
mw.ustring.toNFD
mw.ustring.toNFD( s )
Converts the string to Normalization Form D (also known as Normalization Form Canonical Decomposition). Returns nil if the string is not valid UTF-8.
mw.ustring.toNFKC
mw.ustring.toNFKC( s )
Converts the string to Normalization Form KC (also known as Normalization Form Compatibility Composition). Returns nil if the string is not valid UTF-8.
mw.ustring.toNFKD
mw.ustring.toNFKD( s )
Converts the string to Normalization Form KD (also known as Normalization Form Compatibility Decomposition). Returns nil if the string is not valid UTF-8.
mw.ustring.upper
mw.ustring.upper( s )
Much like string.upper(), except that all characters with uppercase to lowercase definitions in Unicode are converted.
If the Language library is also loaded, this will instead call uc() on the default language object.
Ustring patterns
Patterns in the ustring functions use the same syntax as the String library patterns. The major difference is that the character classes are redefined in terms of Unicode character properties:
%a
: represents all characters with General Category "Letter".
%c
: represents all characters with General Category "Control".
%d
: represents all characters with General Category "Number, decimal digit".
%l
: represents all characters with General Category "Lowercase Letter".
%p
: represents all characters with General Category "Punctuation".
%s
: represents all characters with General Category "Separator", plus tab, linefeed, carriage return, vertical tab, and form feed.
%u
: represents all characters with General Category "Uppercase Letter".
%w
: represents all characters with General Category "Letter" or "Decimal Number".
%x
: adds fullwidth character versions of the hex digits.
Like in String library patterns, %A
, %C
, %D
, %L
, %P
, %S
, %U
, %W
a %X
here represent the complementary set ("all characters without given General Category").
In all cases, characters are interpreted as Unicode characters instead of bytes, so ranges such as [0-9]
, patterns such as %b«»
, and quantifiers applied to multibyte characters will work correctly. Empty captures will capture the position in code points rather than bytes.
Known limitations: Unlike String library patterns, Ustring library patterns have a maximum length of 10,000 bytes. If the pattern exceeds this length, then the Ustring function will throw an error. Because the String library has its own maximum of 32 captures (unlike the Ustring library), it is therefore impossible to use a pattern which exceeds both limits, as it will be incompatible with both libraries.
Note: 9 ASCII characters, $
, +
, <
, =
, >
, ^
, `
, |
, ~
, can be matched by %p
in the string library but not in the ustring library, as Unicode classifies them as Symbols rather than Punctuation.
Loadable libraries
These libraries are not included by default, but if needed may be loaded using require()
.
bit32
This emulation of the Lua 5.2 bit32
library may be loaded using:
bit32 = require( 'bit32' )
The bit32 library provides bitwise operations on unsigned 32-bit integers. Input numbers are truncated to integers (in an unspecified manner) and reduced modulo 232 so the value is in the range 0 to 232−1; return values are also in this range.
When bits are numbered (as in bit32.extract()), 0 is the least-significant bit (the one with value 20) and 31 is the most-significant (the one with value 231).
bit32.band
bit32.band( ... )
Returns the bitwise AND of its arguments: the result has a bit set only if that bit is set in all of the arguments.
If given zero arguments, the result has all bits set.
bit32.bnot
bit32.bnot( x )
Returns the bitwise complement of x
.
bit32.bor
bit32.bor( ... )
Returns the bitwise OR of its arguments: the result has a bit set if that bit is set in any of the arguments.
If given zero arguments, the result has all bits clear.
bit32.btest
bit32.btest( ... )
Equivalent to bit32.band( ... ) ~= 0
bit32.bxor
bit32.bxor( ... )
Returns the bitwise XOR of its arguments: the result has a bit set if that bit is set in an odd number of the arguments.
If given zero arguments, the result has all bits clear.
bit32.extract
bit32.extract( n, field, width )
Extracts width
bits from n
, starting with bit field
. Accessing bits outside of the range 0 to 31 is an error.
If not specified, the default for width
is 1.
bit32.replace
bit32.replace( n, v, field, width )
Replaces width
bits in n
, starting with bit field
, with the low width
bits from v
. Accessing bits outside of the range 0 to 31 is an error.
If not specified, the default for width
is 1.
bit32.lshift
bit32.lshift( n, disp )
Returns the number n
shifted disp
bits to the left. This is a logical shift: inserted bits are 0. This is generally equivalent to multiplying by 2disp
.
Note that a displacement over 31 will result in 0.
bit32.rshift
bit32.rshift( n, disp )
Returns the number n
shifted disp
bits to the right. This is a logical shift: inserted bits are 0. This is generally equivalent to dividing by 2disp
.
Note that a displacement over 31 will result in 0.
bit32.arshift
bit32.arshift( n, disp )
Returns the number n
shifted disp
bits to the right. This is an arithmetic shift: if disp
is positive, the inserted bits will be the same as bit 31 in the original number.
Note that a displacement over 31 will result in 0 or 4294967295.
bit32.lrotate
bit32.lrotate( n, disp )
Returns the number n
rotated disp
bits to the left.
Note that rotations are equivalent modulo 32: a rotation of 32 is the same as a rotation of 0, 33 is the same as 1, and so on.
bit32.rrotate
bit32.rrotate( n, disp )
Returns the number n
rotated disp
bits to the right.
Note that rotations are equivalent modulo 32: a rotation of 32 is the same as a rotation of 0, 33 is the same as 1, and so on.
libraryUtil
This library contains methods useful when implementing Scribunto libraries. It may be loaded using:
libraryUtil = require( 'libraryUtil' )
libraryUtil.checkType
libraryUtil.checkType( name, argIdx, arg, expectType, nilOk )
Raises an error if type( arg )
does not match expectType
. In addition, no error will be raised if arg
is nil and nilOk
is true.
name
is the name of the calling function, and argIdx
is the position of the argument in the argument list. These are used in formatting the error message.
libraryUtil.checkTypeMulti
libraryUtil.checkTypeMulti( name, argIdx, arg, expectTypes )
Raises an error if type( arg )
does not match any of the strings in the array expectTypes
.
This is for arguments that have more than one valid type.
libraryUtil.checkTypeForIndex
libraryUtil.checkTypeForIndex( index, value, expectType )
Raises an error if type( value )
does not match expectType
.
This is intended for use in implementing a __newindex
metamethod.
libraryUtil.checkTypeForNamedArg
libraryUtil.checkTypeForNamedArg( name, argName, arg, expectType, nilOk )
Raises an error if type( arg )
does not match expectType
. In addition, no error will be raised if arg
is nil and nilOk
is true.
This is intended to be used as an equivalent to libraryUtil.checkType()
in methods called using Lua's "named argument" syntax, func{ name = value }
.
libraryUtil.makeCheckSelfFunction
libraryUtil.makeCheckSelfFunction( libraryName, varName, selfObj, selfObjDesc )
This is intended for use in implementing "methods" on object tables that are intended to be called with the obj:method()
syntax. It returns a function that should be called at the top of these methods with the self
argument and the method name, which will raise an error if that self
object is not selfObj
.
This function will generally be used in a library's constructor function, something like this:
function myLibrary.new()
local obj = {}
local checkSelf = libraryUtil.makeCheckSelfFunction( 'myLibrary', 'obj', obj, 'myLibrary object' )
function obj:method()
checkSelf( self, 'method' )
end
function obj:method2()
checkSelf( self, 'method2' )
end
return obj
end
luabit
The luabit library modules "bit" and "hex" may be loaded using:
bit = require( 'luabit.bit' )
hex = require( 'luabit.hex' )
Note that the bit32 library contains the same operations as "luabit.bit", and the operations in "luabit.hex" may be performed using string.format()
and tonumber()
.
The luabit module "noki" is not available, as it is entirely useless in Scribunto. The luabit module "utf8" is also not available, as it was considered redundant to the Ustring library.
strict
The strict library is not a normal library; it causes an error to be raised whenever a new variable is used that is not explicitly scoped as a local variable (e.g., global variable assignment references). This functionality is typically enabled by loading at the top of a module using:
require( 'strict' )
On many Wikimedia wikis this was formerly implemented in Module:No globals
, which was replaced via phab:T209310. It is in part derived from strict.lua.
ustring
The pure-Lua backend to the Ustring library may be loaded using:
ustring = require( 'ustring' )
In all cases the Ustring library (mw.ustring
) should be used instead, as that replaces many of the slower and more memory-intensive operations with callbacks into PHP code.
Extension libraries
Some MediaWiki extensions provide additional Scribunto libraries. These are also located in the table mw
, usually in the table mw.ext
, however, they are only present when certain extensions are installed (in addition to the Scribunto extension itself).
Such extensions use Scribunto provided hooks:
Writing Scribunto libraries provides information on how such libraries can be developed to provide Lua interfaces for MediaWiki extensions.
mw.wikibase
Wikibase Client provides access to localizable structured data, most notably Wikidata. See docs_topics_lua.html and Rozšíření:Wikibase Client/Lua .
mw.wikibase.lexeme
WikibaseLexeme provides access to Wikibase Lexeme entities. This is supported by Wikidata:Lexicographical data. See md_docs_2topics_2lua.html and Extension:WikibaseLexeme/Lua .
mw.wikibase.mediainfo
WikibaseMediaInfo provides access to Wikibase MediaInfo entities. See WikibaseMediaInfo/Lua . This is supported by Structured Data on Commons. See Structured data/Lua.
mw.bcmath
BCmath provides arbitrary-precision arithmetic to Lua modules. See BCmath documentation via "LDoc" link at BCmath § Usage.
mw.smw
Semantic Scribunto provides native Scribunto support for the Semantic MediaWiki extension.
mw.ext.data
JsonConfig provides access to localizable tabular and map data. See JsonConfig/Tabular . Tabular Data and GeoJSON Map Data is supported in the "Data:" namespace at Commons.
mw.ext.data.get( pagename )
mw.ext.cargo
Cargo provides a means to query its data store from Lua. See Extension:Cargo/Other features#Lua support .
mw.ext.cattools
CategoryToolbox provides a means to check from Lua if a certain page belongs to a category. Is is experimental and not enabled on public WikiMedia wikis.
mw.ext.FlaggedRevs
FlaggedRevs provides a means to access the stability settings of a page from Lua.
mw.ext.TitleBlacklist
TitleBlacklist provides a means to test and obtain information about blacklisted page naming entries from Lua.
mw.ext.ParserFunctions
ParserFunctions provides a means from Lua to evaluate expressions in the same way as its PHP-based parser function #expr
.
mw.ext.proofreadPage
Proofread Page provides access to Index and Page namespaces. See Extension:Proofread Page/Lua reference . This is supported by Wikisource:ProofreadPage. See Help:Extension:ProofreadPage .
mw.ext.articlePlaceholder
ArticlePlaceholder provides a means to override default Wikibase renderings from Lua. See Extension:ArticlePlaceholder/Module:AboutTopic .
mw.ext.externalData
ExternalData provides a means to get structured data from Internet from Lua. See Extension:External Data/Lua .
mw.ext.UnlinkedWikibase
See UnlinkedWikibase
mw.ext.UnlinkedWikibase.getEntity( id )
mw.ext.UnlinkedWikibase.query( sparql )
mw.ext.seo
WikiSEO provides a means to set SEO Data for the current page. See Extension:WikiSEO#Usage in lua modules.
mw.slots
WSSlots provides a number of Lua functions for working with MCR slots:
mw.slots.slotContent(slotName, pageName)
mw.slots.slotTemplates(slotName, pageName)
(deprecated)mw.slots.slotContentModel(slotName, pageName)
mw.slots.slotData(slotName, pageName)
Differences from standard Lua
Changed functions
The following functions have been modified:
- setfenv()
- getfenv()
- May not be available, depending on the configuration. If available, attempts to access parent environments will fail.
- getmetatable()
- Works on tables only to prevent unauthorized access to parent environments.
- tostring()
- Pointer addresses of tables and functions are not provided. This is to make memory corruption vulnerabilities more difficult to exploit.
- pairs()
- ipairs()
- Support for the __pairs and __ipairs metamethods (added in Lua 5.2) has been added.
- pcall()
- xpcall()
- Certain internal errors cannot be intercepted.
- require()
- Can fetch certain built-in modules distributed with Scribunto, as well as modules present in the Module namespace of the wiki. To fetch wiki modules, use the full page name including the namespace. Cannot otherwise access the local filesystem.
Removed functions and packages
The following packages are mostly removed. Only those functions listed are available:
- package.*
- Filesystem and C library access has been removed. Available functions and tables are:
- package.loaded
- package.preload
- package.loaders
- Loaders which access the local filesystem or load C libraries are not present. A loader for Module-namespace pages is added.
- package.seeall()
- os.*
- There are some insecure functions in here, such as os.execute(), which can't be allowed. Available functions are:
- debug.*
- Most of the functions are insecure. Available functions are:
The following functions and packages are not available:
- collectgarbage()
- module()
- coroutine.*
- No application is known for us, so it has not been reviewed for security.
- dofile()
- loadfile()
- io.*, file.*
- Allows local filesystem access, which is insecure.
- load()
- loadstring()
- These were omitted to allow for static analysis of the Lua source code. Also, allowing these would allow Lua code to be added directly to article and template pages, which was not desired for usability reasons.
- print()
- This was discussed on wikitech-l and it was decided that it should be omitted in favour of return values, to improve code quality. If necessary, mw.log() may be used to output information to the debug console.
- string.dump()
- May expose private data from parent environments.
Additional caveats
- Referential data structures
- Circular data structures and data structures where the same node may be reached by more than one path cannot be correctly sent to PHP.
Attempting to do so will cause undefined behavior. This includes (but is not limited to) returning such data structures from the module called by {{#invoke:}}
and passing such data structures as parameters to Scribunto library functions that are implemented as callbacks into PHP.
Such data structures may be used freely within Lua, including as the return values of modules loaded with mw.loadData()
.
Writing Scribunto libraries
This information is useful to developers writing additional Scribunto libraries, whether for inclusion in Scribunto itself or for providing an interface for their own extensions.
A Scribunto library will generally consist of five parts:
- The PHP portion of the library.
- The Lua portion of the library.
- The PHP portion of the test cases.
- The Lua portion of the test cases.
- The documentation.
Existing libraries serve as a good example.
Library
The PHP portion of the library is a class that must extend Scribunto_LuaLibraryBase
. See the documentation for that class for implementation details. In the Scribunto extension, this file should be placed in engines/LuaCommon/NameLibrary.php
, and a mapping added to Scribunto_LuaEngine::$libraryClasses
. Other extensions should use the ScribuntoExternalLibraries hook. In either case, the key should match the Lua module name ("mw.name" for libraries in Scribunto, or "mw.ext.name" for extension libraries).
The Lua portion of the library sets up the table containing the functions that can be called from Lua modules. In the Scribunto extension, the file should be placed in engines/LuaCommon/lualib/mw.name.lua
. This file should generally include boilerplate something like this:
local object = {}
local php
function object.setupInterface( options )
-- Remove setup function
object.setupInterface = nil
-- Copy the PHP callbacks to a local variable, and remove the global
php = mw_interface
mw_interface = nil
-- Do any other setup here
-- Install into the mw global
mw = mw or {}
mw.ext = mw.ext or {}
mw.ext.NAME = object
-- Indicate that we're loaded
package.loaded['mw.ext.NAME'] = object
end
return object
The module in engines/LuaCommon/lualib/libraryUtil.lua
(load this with local util = require 'libraryUtil'
) contains some functions that may be helpful.
Be sure to run the Scribunto test cases with your library loaded, even if your library doesn't itself provide any test cases. The standard test cases include tests for things like libraries adding unexpected global variables. Also, if the library is loaded with PHP, any upvalues that its Lua functions have will not be reset between #invoke's. Care must be taken to ensure that modules can't abuse this to transfer information between #invoke's.
Test cases
The Scribunto extension includes a base class for test cases, Scribunto_LuaEngineTestBase
, which will run the tests against both the LuaSandbox and LuaStandalone engines.
The library's test case should extend this class, and should not override static function suite()
.
In the Scribunto extension, the test case should be in tests/engines/LuaCommon/NameLibraryTest.php
and added to the array in ScribuntoHooks::unitTestsList()
(in common/Hooks.php
); extensions should add the test case in their own UnitTestsList
hook function, probably conditional on whether $wgAutoloadClasses['Scribunto_LuaEngineTestBase']
is set.
Most of the time, all that is needed to make the test case is this:
class ClassNameTest extends Scribunto_LuaEngineTestBase { protected static $moduleName = 'ClassNameTest'; function getTestModules() { return parent::getTestModules() + array( 'ClassNameTest' => __DIR__ . '/ClassNameTests.lua'; ); } }
This will load the file ClassNameTests.lua
as if it were the page "Module:ClassNameTests", expecting it to return an object with the following properties:
- count: Integer, number of tests
- provide( n ): Function that returns three values:
n
, the name of testn
, and a string that is the expected output for testn
. - run( n ): Function that runs test
n
and returns one string.
If getTestModules()
is declared as shown, "Module:TestFramework" is available which provides many useful helper methods. If this is used, ClassNameTests.lua
would look something like this:
local testframework = require 'Module:TestFramework'
return testframework.getTestProvider( {
-- Tests go here
} )
Each test is itself a table, with the following properties:
- name: The name of the test.
- func: The function to execute.
- args: Optional table of arguments to pass to the function.
- expect: Results to expect.
- type: Optional "type" of the test, default is "Normal".
The type controls the format of expect
and how func
is called. Included types are:
- Normal:
expect
is a table of return values, or a string if the test should raise an error.func
is simply called. - Iterator:
expect
is a table of tables of return values.func
is called as with an iterated for loop, and each iteration's return values are accumulated. - ToString: Like "Normal", except each return value is passed through
tostring()
.
Test cases in another extension
There are (at least) two ways to run PHPUnit tests:
- Run phpunit against core, allowing the tests/phpunit/suites/ExtensionsTestSuite.php to find the extension's tests using the UnitTestsList hook.
If your extension's test class names all contain a unique component (e.g. the extension's name), the --filter
option may be used to run only your extension's tests.
- Run phpunit against the extension directory, where it will pick up any file ending in "Test.php".
Either of these will work fine if Scribunto is loaded in LocalSettings.php. And it is easy for method #1 to work if Scribunto is not loaded, as the UnitTestsList hook can easily be written to avoid returning the Scribunto test when $wgAutoloadClasses[ 'Scribunto_LuaEngineTestBase' ]
is not set.
But Jenkins uses method #2. For Jenkins to properly run the tests, you will need to add Scribunto as a dependency for your extension. See Gerrit change 56570 for an example of how this is done.
If for some reason you need the tests to be able to run using method #2 without Scribunto loaded, one workaround is to add this check to the top of your unit test file:
if ( !isset( $GLOBALS['wgAutoloadClasses']['Scribunto_LuaEngineTestBase'] ) ) {
return;
}
Documentation
Modules included in Scribunto should include documentation in the Scribunto libraries section above. Extension libraries should include documentation in a subpage of their own extension page, and link to that documentation from the Extension libraries subsection above.
See also
License
This manual is derived from the Lua 5.1 reference manual, which is available under the MIT license.
Copyright © 1994–2012 Lua.org, PUC-Rio. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
This derivative manual may also be copied under the terms of the same license.