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

Ú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 nul a vůbec ničím. Například tostring(nil) vrátí "nil", ale tostring( ) vyvolá chybu, protože je vyžadován první parametr. 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 true.

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 (-2⁵³ + 1) a 9007199254740991 (2⁵³ - 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, 123.45e20 nebo 1.23E+5. 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, jako math.huge a -math.huge, nebo pomocí numerických operací jako 1/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ímco 1/-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í jako false (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 10¹⁴ 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")</ syntaxhighlight>, který problém nezpůsobuje ani jej neovlivňuje. Viz [https://lua-l.lua.narkive.com/k4kbwgKi/tostring-and-0]. <span id="table"></span> ==== 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 <code>{}</code>. 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: * <code style="white-space:nowrap">[''[[#Expressions|expression1]]''] = ''[[#Expressions|expression2]]''</code> používá (první) hodnotu z ''expression1'' jako klíč a (první) hodnota ''expression2'' jako hodnotu. * <code style="white-space:nowrap">''[[#name|name]]'' = ''[[#Expressions|expression]]''</code> je ekvivalentní <code style="white-space:nowrap">["''name''"] = ''expression''</code> * <code>''[[#Expressions|expression]]''</code> je zhruba ekvivalentní <code style="white-space:nowrap">[''i''] = ''expression''</code>, 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ř. <code>table[key]</code>. K řetězcovým klíčům, které jsou také platné [[#name|names]], lze také přistupovat pomocí tečkové notace, např. <code>table.key</code> odpovídá <code>table['key']</code>. Volání funkce, která je hodnotou v tabulce, může používat zápis dvojtečkou. Například <code style="white-space:nowrap">table:func( ... )</code>, což odpovídá <code style="white-space:nowrap">table['func']( table, ... )</code> nebo <code style="white-space:nowrap">table.func( table, ... )</code>. {{Anchor|sequence}} ''Sekvence'' je tabulka s nenulovými hodnotami pro všechna kladná celá čísla od 1 do N a žádnou hodnotou (nulovou) pro všechna kladná celá čísla větší než N. Mnoho funkcí Lua pracuje pouze se sekvencemi a ignoruje nekladné celočíselné klíče. 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é: <syntaxhighlight lang="lua"> -- 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í C ukazatele 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[klíč] = hodnota, kde rawget( t, key ) vrátí nulu. Pokud je hodnotou tohoto pole tabulka, přiřazení bude provedeno k této tabulce, tj. __newindex[key] = hodnota (což může vyvolat metatabulku této tabulky __newindex). Pokud je hodnotou tohoto pole funkce, funkce bude volána jako __newindex( t, klíč, hodnota ). 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ří:

• __add^†
• __sub^†
• __mul^†
• __div^†
• __mod^†
• __pow^†
• __unm
• __concat^†
• __eq^‡
• __lt^‡
• __le^‡
• __pairs
• __ipairs
• __metatable^*
• __tostring

^† U binárních operátorů se Lua nejprve podívá na metatabulku levého argumentu (pokud existuje), pak na pravou, když hledá metametodu k použití.

^‡ U relačních operátorů se metametoda používá pouze v případě, že je v metatabulkách obou argumentů zadána stejná funkce. Různé anonymní funkce, dokonce i se stejným tělem a uzávřením, nelze považovat za stejné.

^* __metatable ovlivňuje jak getmetatable(), tak setmetatable()

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 řetězec. 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í, modulo, 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í na not ( 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 a[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žší:

1. ^
2. not # - (negace)
3. * / %
4. + - (odčítání)
5. ..
6. < > <= >= ~= ==
7. and
8. 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 v var-listu:

function nameoptional ( var-list, ... )
    blok
end
-- or
function nameoptional ( ... )
    blok
end

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 exp do blok end

Příkaz while opakuje blok, dokud je výraz vyhodnocen jako pravdivá hodnota.

repeat blok until exp

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 nul 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 pak ' Část '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ě vararg výrazu ...) považují nil za odlišnou hodnotu (viz dokumentace k # a unpack pro problém s nul v tabulkách). Například:

• select(2, "foo", "bar") vrátí "bar".
• select(2, "foo", nil, "bar", nil) vrací 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 metatabuluku z tabulky. 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 $e^{x}$.

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ý: $x=m\times 2^{e}$, e je celé číslo a absolutní hodnota m je v rozsahu $[0.5,1)$
• Pokud je x nula: m a e jsou 0
• Pokud je x NaN (Not a Number ("nečíslo")) nebo nekonečno: m je x a e 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í $m\times 2^{e}$ (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 $\pi$.

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 $[0,1)$
• S jedním argumentem vrátí celé číslo v rozsahu $[1,m]$
• Se dvěma argumenty vrátí celé číslo v rozsahu $[m,n]$

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

1. V package.preload[modulename] vyhledejte funkci loader
2. 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 '-'. Všechny výše popsané třídy %y lze také použít jako komponenty v set. Všechny ostatní znaky v set představují samy sebe. Například [%w_] (nebo [_%w]) představuje všechny alfanumerické znaky plus podtržítko a [0-7] představuje osmičkové číslice. Chcete-li do sady zahrnout doslovný spojovník '-', použijte '%-', takže [0-7%l%-] představuje osmičkové číslice plus malá písmena plus znak '-'. Interakce mezi rozsahy a třídami není definována. Proto vzory jako [%a-z] nebo [a-%%] nemají žádný význam.
[^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ě;
• $ 1, za $ 2 mezi 1 a 9; taková položka odpovídá podřetězci rovnému n-th zachycenému řetězci (viz níže);
• %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.
• $ 1, hraniční vzor; taková položka odpovídá prázdnému řetězci na libovolné pozici tak, že další znak patří do set a předchozí znak nepatří do set. Sada set je interpretována tak, jak bylo popsáno dříve. Začátek a konec předmětu jsou zpracovány tak, jako by šlo o znak '\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() a ipairs() 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).

mw.html:newline

html:newline()

Připojí nový řádek k objektu mw.html.

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

Záložní řetězce

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ímco grammar 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í "&lrm;" nebo "&rlm;", 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, or PMID 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.

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().

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 ), or nil 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 be nil. This is expensive.

• cascadingProtection: The cascading protections applicable to the page. This is a table with keys "restrictions" (itself a table with keys like protectionLevels 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.

• 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 is false, all other file properties will be nil.

• 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 "5" 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.

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 [０-９], 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 2³² so the value is in the range 0 to 2³²−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 2⁰) and 31 is the most-significant (the one with value 2³¹).

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 2^disp.

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 2^disp.

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:

• ScribuntoExternalLibraries
• ScribuntoExternalLibraryPaths

Writing Scribunto libraries provides information on how such libraries can be developed to provide Lua interfaces for MediaWiki extensions.

mw.wikibase

Rozšíření: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

Rozšíření: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 Rozšíření:Semantic MediaWiki extension.

mw.ext.data

Rozšíření: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:

os.clock()

os.date()

os.difftime()

os.time()

debug.*

Most of the functions are insecure. Available functions are:

debug.traceback()

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 test n, and a string that is the expected output for test n.
• 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:

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

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

• Lua (programming language)

License

This manual is derived from the Lua 5.1 reference manual, which is available under the MIT license.

This derivative manual may also be copied under the terms of the same license.