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áva :

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

Redirects

Verze MediaWiki:

1.42 Gerrit change 574086

Since release 1.42, Scribunto recognizes one particular syntax for redirects (so they’re highlighted on special pages, appear on Special:WhatLinksHere, and so on), and also produces redirects when renaming/moving a module, similarly to how renaming of wikitext pages works (before that, module renames left no redirects behind, now extra rights are needed to suppress the redirect).

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.

Please note that other similarly valid Lua syntax variations (e.g. using quotation marks instead of square brackets, using parentheses around the require parameter, or even whitespace variations) are still not recognized by MediaWiki as redirects.

Jazyk Lua

Tokeny

Jméno (nazývané také identifikátor) v Lua může být libovolný řetězec písmen, číslic a podtržítek, který nezačíná číslicí. V názvech se rozlišují velká a malá písmena; "foo", "Foo" a "FOO" jsou různá jména.

Následující klíčová slova jsou vyhrazena a nelze je použít jako názvy:

• and
• break
• do
• else
• elseif
• end
• false
• for
• function
• if
• in
• local
• nil
• not
• or
• repeat
• return
• then
• true
• until
• while

Názvy začínající podtržítkem následovaným velkými písmeny jsou vyhrazeny pro interní globální proměnné Lua.

Další tokeny jsou:

• #
• %
• (
• )
• *
• +
• ,
• -
• --
• .
• ..
• ...
• /
• :
• ;
• <
• <=
• =
• ==
• >
• >=
• [
• ]
• ^
• {
• }
• ~=

Komentáře

Komentář začíná znakem -- kdekoli mimo řetězec. Pokud za -- bezprostředně následuje úvodní dlouhá závorka, komentář pokračuje do odpovídající uzavírací dlouhé závorky. Jinak komentář běží na konec aktuálního řádku.

-- Komentář v Lua začíná dvojitou pomlčkou a běží na konec řádku.
--[[ Víceřádkové řetězce a komentáře
      jsou ohraničeny dvojitými hranatými závorkami. ]]
--[=[ Komentáře jako tento mohou mít vnořené další ---[[komentáře]]. ]=]
--[==[ Komentáře jako tento mohou mít i jiné
      --[===[ dlouhé --[=[komentáře]=] --vnořené
        ]===] vícekrát, i když jsou všechny
      --[[ neohraničeny odpovídajícími dlouhými závorkami! ]===]
  ]==]

Datové typy

Lua je dynamicky typovaný jazyk, což znamená, že proměnné a argumenty funkcí nemají žádný typ, pouze hodnoty, které jsou jim přiřazeny. Všechny hodnoty nesou typ.

Lua má osm základních datových typů, avšak pouze šest je relevantních pro rozšíření Scribunto. Funkce type() vrátí typ hodnoty.

Funkce tostring() převede hodnotu na řetězec. Funkce tonumber() převede hodnotu na číslo, pokud je to možné, a jinak vrátí nulu. Neexistují žádné explicitní funkce pro převod hodnoty na jiné datové typy.

Čísla jsou automaticky převedena na řetězce při použití tam, kde se očekává řetězec, např. při použití s operátorem zřetězení. Řetězce rozpoznávané funkcí tonumber() jsou automaticky převedeny na čísla při použití s aritmetickými operátory. Když se očekává logická hodnota, všechny hodnoty kromě nula a false jsou považovány za pravdivé.

nil

"nil" je datový typ nil, který představuje absenci hodnoty.

Nil nelze použít jako klíč v tabulce a není žádný rozdíl mezi nepřiřazeným klíčem tabulky a klíčem, kterému je přiřazena nulová hodnota.

Při převodu na řetězec je výsledek "nil". Při převodu na booleovskou hodnotu je nil považováno za nepravdivé.

Poznámka: Lua v některých omezených situacích rozlišuje mezi nil a vůbec ničím. Například tostring(nil) vrátí "nil", ale tostring() vyvolá chybu, protože první parametr je povinný. Toto rozlišení je zvláště důležité pro funkci select().

boolean

Booleovské hodnoty jsou true a false.

Při převodu na řetězec je výsledek "true" nebo "false".

Na rozdíl od mnoha jiných jazyků nemusí být booleovské hodnoty přímo převedeny na čísla. A na rozdíl od mnoha jiných jazyků, pouze false a nul jsou považovány za false pro booleovskou konverzi. Číslo 0 a prázdný řetězec se považují za pravdivé.

řetězec

Lua řetězce jsou považovány za sérii 8bitových bajtů. Je na aplikaci, aby je interpretovala v jakémkoli konkrétním kódování.

Řetězcové literály mohou být odděleny buď jednoduchými nebo dvojitými uvozovkami (' nebo "). Jako JavaScript a na rozdíl od PHP mezi nimi není žádný rozdíl. Jsou rozpoznány následující sekvence escape:

• \a (zvonek, byte 7)
• \b (backspace, byte 8)
• \t (horizontální tab, byte 9)
• \n (nový řádek, byte 10)
• \v (vertikální tab, byte 11)
• \f (form feed, byte 12)
• \r (carriage return, byte 13)
• \" (double quote, byte 34)
• \' (single quote, byte 39)
• \\ (backslash, byte 92)

Doslovný nový řádek může být také zahrnut do řetězce tak, že jej předchází zpětné lomítko. Bajty lze také zadat pomocí escape sekvence '\ddd', kde ddd je desetinná hodnota bajtu v rozsahu 0–255. Chcete-li zahrnout znaky Unicode pomocí sekvencí escape, musí být specifikovány jednotlivé bajty pro kódování UTF-8. Obecně bude jednodušší zadávat znaky Unicode přímo.

Doslovné řetězce lze také definovat pomocí dlouhých závorek. Úvodní dlouhá závorka se skládá z otevírací hranaté závorky následované nulou nebo více stejnými znaménky, za nimiž následuje další otevírací hranatá závorka, např. [[, [=[ nebo [=====[. Otevírací dlouhá závorka musí odpovídat odpovídající zavírací dlouhé závorce, např. ]], ]=] nebo ]=====]. Ve speciálním případě, pokud je po úvodní dlouhé závorce bezprostředně následován nový řádek, nový řádek není zahrnut do řetězce, ale nový řádek těsně před uzavírací dlouhou závorkou je zachován. Řetězce oddělené dlouhými závorkami neinterpretují escape sekvence.

-- dlouhý řetězec
foo = [[
bar\tbaz
]]

-- je ekvivalentní tomuto řetězci oddělenému uvozovkami
foo = 'bar\\tbaz\n'

Všimněte si, že všechny řetězce jsou považovány za pravdivé, když jsou převedeny na booleovské. To je na rozdíl od většiny ostatních jazyků, kde je prázdný řetězec obvykle považován za nepravdivý.

číslo

Lua má pouze jeden číselný typ, který je obvykle interně reprezentován jako 64bitová hodnota s plovoucí desetinnou čárkou s dvojitou přesností. V tomto formátu mohou být celá čísla mezi -9007199254740991 (-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-10e-10, 1.23e-10e20 nebo 1.23e-10e5. 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"), které zřejmě nezpůsobují ani nejsou ovlivněny problém. Viz [1].

tabulka

Tabulky Lua jsou asociativní pole, podobně jako pole PHP a objekty JavaScriptu.

Tabulky se vytvářejí pomocí složených závorek. Prázdná tabulka je {}. Pro naplnění polí při vytváření může být do složených závorek zahrnut seznam specifikátorů polí oddělených čárkou nebo středníkem. Mohou mít několik podob:

• * [expression1] = expression2 používá (první) hodnotu expression1 jako klíč a (první) hodnotu expression2 jako hodnotu.
• * name = expression odpovídá ["name"] = expression
• * expression je zhruba ekvivalentní [i] = expression, kde i je celé číslo začínající na 1 a zvyšující se s každou specifikací pole tohoto formuláře. Pokud se jedná o poslední specifikátor pole a výraz má více hodnot, použijí se všechny hodnoty. Jinak zůstane zachováno pouze první.

K polím v tabulce se přistupuje pomocí zápisu v závorkách, např. table[key]. K řetězcovým klíčům, které jsou také platné names, lze také přistupovat pomocí tečkové notace, např. table.key odpovídá table['key']. Volání funkce, která je hodnotou v tabulce, může používat zápis dvojtečkou. Například table:func( ... ), což odpovídá table['func']( table, ... ) nebo table.func( table, ... ).

Pole (také nazývané sekvence nebo seznam) je tabulka s nenulovými hodnotami pro všechna kladná celá čísla od 1 do N a bez hodnoty (nula) pro všechna kladná celá čísla větší než N. Mnoho funkcí Lua pracuje pouze s poli a ignoruje klíče s kladnými celými čísly.

Na rozdíl od mnoha jiných jazyků, jako je PHP nebo JavaScript, lze jako klíč použít jakoukoli hodnotu kromě nil a NaN a neprovádí se žádná konverze typu. Všechny jsou platné a odlišné:

-- Vytvoření tabulky
t = {}
t["foo"] = "foo"
t.bar = "bar"
t[1] = "jedna"
t[2] = "dva"
t[3] = "tři"
t[12] = "číslo dvanáct"
t["12"] = "řetězec dvanáct"
t[true] = "true"
t[tonumber] = "ano, i funkce mohou být klíče tabulky"
t[t] = "ano, tabulka může být také klíčem k tabulce. Dokonce i sama o sobě."

-- Vznikne tak tabulka zhruba ekvivalentní výše uvedené
t2 = {
    foo = "foo",
    bar = "bar",
    "jedna",
    "dva",
    [12] = "číslo dvanáct"
    ["12"] = "řetězec dvanáct"
    "tři"
    [true] = "true",
    [tonumber] = "ano, i funkce mohou být klíče tabulky"
}
t2[t2] = "ano, tabulka může být také klíčem k tabulce. Dokonce i sama o sobě."

Podobně jakákoliv hodnota kromě nil může být uložena jako hodnota v tabulce. Uložení nil je ekvivalentní smazání klíče z tabulky a přístup k libovolnému klíči, který nebyl nastaven, bude mít za následek hodnotu nil.

Všimněte si, že tabulky nejsou nikdy implicitně zkopírovány v Lua. Pokud je funkci předána jako argument tabulka a funkce manipuluje s klíči nebo hodnotami v tabulce, tyto změny budou viditelné ve volajícím.

Při převodu na řetězec je obvyklým výsledkem "tabulka", ale může být přepsána pomocí __tostring metametody. Dokonce i prázdná tabulka je považována za pravdivou jako boolean.

funkce

Funkce v Lua jsou priritní hodnoty: Mohou být vytvořeny anonymně, předány jako argumenty, přiřazeny k proměnným a tak dále.

Funkce se vytvářejí pomocí klíčového slova function a volají se pomocí závorek. Syntactic sugar je dostupný pro pojmenované funkce, lokální funkce a funkce, které fungují jako členské funkce tabulky. Podrobnosti viz Deklarace funkcí a Volání funkcí níže.

Funkce Lua jsou uzavřené, což znamená, že udržují odkaz na rozsah, ve kterém jsou deklarovány, a mohou přistupovat a manipulovat s proměnnými v tomto rozsahu.

Stejně jako tabulky, pokud je funkce přiřazena jiné proměnné nebo předána jako argument jiné funkci, je to stále stejný základní "funkční objekt", který bude volán.

Po převodu na řetězec je výsledkem "funkce".

Nepodporované typy

Typ userdata se používá k uchování neprůhledných hodnot pro rozšíření Lua napsaná v jiných jazycích. Například uživatelská data mohou být použita k udržení ukazatele C nebo struktury. Aby bylo možné používat Scribunto v hostitelských prostředích, kde není povolen vlastní kompilovaný kód, žádná taková rozšíření se nepoužívají.

Typ thread (vlákno) představuje úchyty pro rutiny, které nejsou dostupné v sandboxu Scribunto.

Upvalues (vyšší hodnoty)

Existuje přísný limit na max. 60 jedinečných hodnot zpřístupněných uvnitř funkce. Upvalue je hodnota deklarovaná mimo funkci a použitá v ní. Jak se hodnoty počítají:

• proměnné (tabulka s mnoha prvky se počítá jako jedna vyšší hodnota)
• funkce (pouze ty přímo volané z dané funkce, nikoli jejich závislosti)

Překročení limitu může být vyvoláno použitím takové proměnné nebo funkce, nikoli její pouhou přítomností nebo dostupností. Opakovaný přístup ke stejné hodnotě limit dále nevyčerpává.

Meta tabulky

Každá tabulka může mít přidruženou tabulku známou jako metatable. Pole v metatabulce používají některé operátory a funkce k určení odlišného nebo záložního chování pro tabulku. K metatabulce pro tabulku lze přistupovat pomocí funkce getmetatable() a nastavit ji pomocí funkce setmetatable().

Při přístupu k jejich meta funkcím se k polím metatabulek přistupuje jako s rawget().

Metatable pole, která ovlivňují samotnou tabulku, jsou:

__index

používá se, když by přístup k tabulce t[key] vrátil nulu. Pokud je hodnotou tohoto pole tabulka, přístup se bude v této tabulce opakovat, tj. __index[key] (což může vyvolat __index metatabulky této tabulky). Pokud je hodnotou tohoto pole funkce, funkce bude volána jako __index( t, key ). Funkce rawget() tuto metametodu obchází.

__newindex

používá se při přiřazování klíče k tabulce $2, kde rawget( t, key ) vrátí nulu. Pokud je hodnotou tohoto pole tabulka, přiřazení bude provedeno k této tabulce, tj. $1 (což může vyvolat metatabulku této tabulky __newindex). Pokud je hodnotou tohoto pole funkce, funkce bude volána jako $1. Funkce rawset() tuto metametodu obchází.

__call

používá se, pokud je v tabulce použita syntaxe volání funkce, $1. 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 string. Tabulka řetězců dostupná pro moduly je kopií.

Proměnné

Proměnné jsou místa, která uchovávají hodnoty. V Lua jsou tři druhy proměnných: globální proměnné, lokální proměnné a pole tabulky.

Jméno představuje globální nebo lokální proměnnou (nebo argument funkce, což je jen druh lokální proměnné). Předpokládá se, že proměnné jsou globální, pokud nejsou explicitně deklarovány jako lokální pomocí klíčového slova local. Každá proměnná, které nebyla přiřazena žádná hodnota, je považována za nulovou.

Globální proměnné jsou uloženy ve standardní Lua tabulce zvané environment (prostředí). Tato tabulka je často dostupná jako globální proměnná _G. Pro tuto tabulku globálních proměnných je možné nastavit metatabulku. Metametody __index a __newindex budou volány pro přístupy a přiřazení ke globálním proměnným stejně jako pro přístupy a přiřazení k polím v jakékoli jiné tabulce.

K prostředí pro funkci lze přistupovat pomocí funkce getfenv() a měnit pomocí funkce setfenv(). Ve Scribuntu jsou tyto funkce přísně omezeny, pokud jsou vůbec dostupné.

Lokální proměnné jsou lexikálně vymezeny. Podrobnosti naleznete na stránce Deklarace místních proměnných.

Výrazy

Výraz je něco, co má hodnoty: literály (čísla, řetězce, pravda, nepravda, nula), anonymní deklarace funkcí, konstruktory tabulek, odkazy na proměnné, volání funkcí, výraz vararg, zabalené výrazy v závorkách, unární operátory aplikované na výrazy a výrazy kombinované s binárními operátory.

Většina výrazů má jednu hodnotu. Volání funkcí a výraz vararg může mít libovolné číslo. Všimněte si, že zabalením volání funkce nebo výrazu vararg do závorek ztratíte všechny kromě první hodnoty.

Seznamy výrazů jsou seznamy výrazů oddělených čárkami. Všechny kromě posledního výrazu jsou nuceny na jednu hodnotu (vypuštění dalších hodnot nebo použití nuly, pokud výraz nemá žádné hodnoty). Všechny hodnoty z posledního výrazu jsou zahrnuty do hodnot seznamu výrazů.

Aritmetické operátory

Lua podporuje obvyklé aritmetické operátory: sčítání, odčítání, násobení, dělení, modul, umocňování a negace.

Když jsou všechny operandy čísla nebo řetězce, pro které tonumber() vrací nenulovou hodnotu, mají operace svůj obvyklý význam.

Pokud je některým z operandů tabulka s vhodnou metamethodou, bude zavolána metametoda.

Operátor	Funkce	Příklad	Metametoda	Poznámky
+	Addition	a + b	__add
-	Subtraction	a - b	__sub
*	Multiplication	a * b	__mul
/	Division	a / b	__div	dělení nulou není chyba; NaN nebo nekonečno bude vráceno
%	Modulo	a % b	__mod	definované jako a % b == a - math.floor( a / b ) * b
^	Exponentiation	a ^ b	__pow	jsou povoleny neceločíselné exponenty
-	Negation	-a	__unm

Relační operátory

Relační operátory v Lua jsou ==, ~=, <, >, <= a >=. Výsledkem relačního operátoru je vždy logická hodnota.

Rovnost (==) nejprve porovná typy svých operandů. Pokud se liší, výsledek je nepravdivý. Poté porovná hodnoty: nula, boolean, číslo a řetězec jsou porovnány očekávaným způsobem. Funkce jsou stejné, pokud odkazují na přesně stejný funkční objekt. function() end == function() end vrátí false, protože porovnává dvě různé anonymní funkce. Tabulky jsou standardně porovnávány stejným způsobem, ale to lze změnit pomocí __eq metametody.

Nerovnost (~=) je přesnou negací rovnosti.

Pro operátory řazení platí, že pokud jsou oba čísla nebo oba řetězce, jsou porovnány přímo. Dále se zkontrolují metametody:

• a < b používá __lt
• a <= b používá __le, pokud je k dispozici, nebo pokud je k dispozici __lt, považuje se za ekvivalentní 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 a[N+1] je nula, i když u vyšších indexů existují nenulové hodnoty. Například,

-- Toto není posloupnost, protože aa[3] je nula a aa[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 ve 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: $1. Ty lze použít k omezení rozsahu lokálních proměnných nebo k přidání return nebo break uprostřed jiného bloku.

Zadání

seznam-proměnných = seznam-výrazů

variable-list je seznam proměnných oddělených čárkami. expression-list je čárkami oddělený seznam jednoho nebo více výrazů. Všechny výrazy jsou vyhodnoceny před provedením jakéhokoli přiřazení, takže a, b = b, a zamění hodnoty a a b.

Deklarace lokálních proměnných

local seznam-proměnných

local seznam-proměnných = seznam-výrazů

Lokální proměnné mohou být deklarovány kdekoli v bloku nebo kusu. První formulář bez seznamu výrazů deklaruje proměnné, ale nepřiřazuje hodnotu, takže všechny proměnné mají hodnotu nula. Druhý formulář přiřazuje hodnoty lokálním proměnným, jak je popsáno v Úkolech výše.

Všimněte si, že viditelnost lokální proměnné začíná příkazem po deklaraci lokální proměnné. Takže deklarace jako local x = x deklaruje lokální proměnnou x a přiřadí jí hodnotu x z vnějšího rozsahu. Lokální proměnná zůstává v rozsahu až do konce nejvnitřnějšího bloku obsahujícího deklaraci lokální proměnné.

Struktury kontroly

while výraz do blok end

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

repeat blok until výraz

Příkaz repeat opakuje blok, dokud se výraz nevyhodnotí jako pravdivá hodnota. Ve výrazu lze přistupovat k lokálním proměnným deklarovaným uvnitř bloku.

for name = exp1, exp2, exp3 do blok end
for name = exp1, exp2 do blok end

Tato první forma cyklu for deklaruje lokální proměnnou a opakuje blok pro hodnoty od exp1 do exp2 přidáním exp3 při každé iteraci. Všimněte si, že exp3 může být úplně vynecháno, v takovém případě se použije 1, ale nečíselné hodnoty jako nil a false jsou chybou. Všechny výrazy jsou vyhodnoceny jednou před spuštěním cyklu.

Tato forma cyklu for je zhruba ekvivalentní

do
    local var, limit, step = tonumber( exp1 ), tonumber( exp2 ), tonumber( exp3 )
    if not ( var and limit and step ) then
        error()
    end
    while ( step > 0 and var <= limit ) or ( step <= 0 and var >= limit ) do
        local name = var
        block
        var = var + step
    end
end

kromě toho, že proměnné var, limit a step nejsou dostupné nikde jinde. Všimněte si, že proměnná name je pro daný blok lokální. Chcete-li použít hodnotu za smyčkou, musí být zkopírována do proměnné deklarované mimo smyčku.

for seznam-proměnných in seznam-výrazů do blok end

Druhá forma cyklu for pracuje s funkcemi iterátor. Stejně jako v prvním formuláři je seznam-výrazů vyhodnocen pouze jednou před začátkem cyklu.

Tato forma cyklu for je zhruba ekvivalentní

do
    local func, static, var = expression-list
    while true do
        local var-list = func( static, var )
        var = var1  -- ''var1'' je první proměnná v ''seznamu-proměnných''
        if var == nil then
            break
        end
        block
    end
end

kromě toho, že opět proměnné func, static a var nejsou dostupné nikde jinde. Všimněte si, že proměnné v var-list jsou pro daný blok lokální; chcete-li je použít po cyklu, musí být zkopírovány do proměnných deklarovaných mimo cyklus.

Seznam výrazů je často volání jediné funkce, která vrací tři hodnoty. Pokud lze funkci iterátoru zapsat tak, že závisí pouze na parametrech, které jsou do ní předány, bylo by to nejúčinnější. Pokud ne, programování v Lua navrhuje, aby se upřednostňovalo uzavření před vrácením tabulky jako statické proměnné a aktualizací jejích členů při každé iteraci.

if exp1 then block1 elseif exp2 then block2 else block3 end

Provede block1, pokud exp1 vrátí true, jinak provede block2, pokud exp2 vrátí true, a block3 jinak. Část else block3 může být vynechána a část elseif exp2 then block2 může být podle potřeby opakována nebo vynechána.

return seznam-výrazů

Příkaz return se používá k vrácení hodnot z funkce nebo chunk (což je pouze funkce). Seznam-výrazů je čárkami oddělený seznam nula nebo více výrazů.

Lua implementuje volání tail: Pokud výraz-seznam obsahuje přesně jeden výraz, který je voláním funkce, bude pro volání této funkce znovu použit aktuální zásobníkový rámec. To má důsledky pro funkce, které se zabývají zásobníkem volání, jako je getfenv() a debug.traceback().

Příkaz return musí být posledním příkazem v jeho bloku. Pokud je z nějakého důvodu potřeba návrat uprostřed bloku, lze použít explicitní blok do return end.

break

Příkaz break se používá k ukončení provádění cyklu while, repeat nebo for, přičemž se přeskočí na další příkaz následující po cyklu.

Příkaz break musí být posledním příkazem v jeho bloku. Pokud je z nějakého důvodu potřeba přerušení uprostřed bloku, lze použít explicitní blok do break end.

Na rozdíl od některých jiných jazyků nemá Lua pro cykly příkaz "continue" (tj. příkaz pro přechod na další iteraci bez úplného přerušení smyčky). Je přímočaré dosáhnout stejného efektu vnořením bloku repeat ... until true přímo do hlavní smyčky, která se bude opakovat pouze jednou pro každou iteraci hlavní smyčky (jelikož podmínka je vždy pravdivá). Použití break pouze ukončí vnitřní smyčku, což má praktický účinek, že hlavní smyčka bude pokračovat v další iteraci. Pokud je nutné použít break v hlavní smyčce, jednoduše deklarujte proměnnou, která je kontrolována pokaždé, když se vnitřní smyčka dokončí, a v případě potřeby ji nastavte.

Volání funkcí jako příkazů

Volání funkce lze použít jako příkaz. V tomto případě je funkce volána pouze pro jakékoli vedlejší účinky, které může mít (např. mw.log() protokoluje hodnoty) a všechny návratové hodnoty jsou zahozeny.

Příkazy deklarace funkce

Lua poskytuje syntaktický sugar, aby bylo deklarování funkce a její přiřazení k proměnné přirozenější. Následující dvojice deklarací jsou ekvivalentní

-- Základní prohlášení
function func( var-list ) blok end
func = function ( var-list ) blok end

-- Lokální funkce
local function func( var-list ) blok end
local func; func = function ( var-list ) blok end

-- Funkce jako pole v tabulce
function table.func( var-list ) blok end
table.func = function ( var-list ) blok end

-- Funkce jako metoda v tabulce
function table:func( var-list ) blok end
table.func = function ( self, var-list ) blok end

Všimněte si, že zápis dvojtečkou zde odpovídá zápisu dvojtečky pro volání funkcí a na začátek seznamu argumentů přidává implicitní argument s názvem self.

Zpracování chyb

Chyby lze "vyvolat" pomocí funkcí error() a assert(). Chcete-li "zachytit" chyby, použijte pcall() nebo xpcall(). Všimněte si, že určité interní chyby Scriunto nelze zachytit v kódu Lua.

Garbage collection

Lua provádí automatickou správu paměti. To znamená, že se nemusíte starat ani o alokaci paměti pro nové objekty, ani o její uvolnění, když již objekty nejsou potřeba. Lua spravuje paměť automaticky tak, že čas od času spustí garbage collector, aby shromáždil všechny mrtvé objekty (tj. objekty, které již nejsou dostupné z Lua) a objekty, které jsou dosažitelné pouze prostřednictvím slabých referencí. Veškerá paměť používaná Lua podléhá automatické správě: tabulky, funkce, řetězce atd.

Garbage collection (sběr odpadu) probíhá automaticky a nelze jej konfigurovat ze Scriunta.

Standardní knihovny

Standardní knihovny Lua poskytují Lua základní služby a funkce kritické pro výkon. Zde jsou zdokumentovány pouze ty části standardních knihoven, které jsou dostupné ve Scriuntu.

Základní funkce

_G

Tato proměnná obsahuje odkaz na aktuální tabulku globálních proměnných. Ke globální proměnné foo lze také přistupovat jako _G.foo. Všimněte si však, že na samotných _G není nic zvláštního. Může být znovu přiřazena stejným způsobem jako jakákoli jiná proměnná:

foo = 1
mw.log( foo ) -- logy "1"
_G.foo = 2
mw.log( foo ) -- logy "2"
_G = {}       -- _G již neukazuje na tabulku globálních proměnných
_G.foo = 3
mw.log( foo ) -- přetrvávající logy "2"

Tabulku globálních proměnných lze použít stejně jako jakoukoli jinou tabulku. Například,

-- Volání funkce, jejíž název je uložen v proměnné
_G[var]()

-- Protokolujte názvy a zřetězené hodnoty všech globálních proměnných
for k, v in pairs( _G ) do
   mw.log( k, v )
end

-- Zaznamenejte vytvoření nových globálních proměnných
setmetatable( _G, {
    __newindex = function ( t, k, v )
         mw.log( "Creation of new global variable '" .. k .. "'" )
         rawset( t, k, v )
    end
} )

_VERSION

Řetězec obsahující běžící verzi Lua, např. "Lua 5.1".

assert

assert( v, message, ... )

Pokud je v nula nebo nepravda, vydá chybu. V tomto případě se jako text chyby použije message: pokud je nula (nebo není zadáno), text je "tvrzení se nezdařilo!". Pokud je řetězec nebo číslo, text je tato hodnota. Jinak samo tvrzení vyvolá chybu.

Pokud je v jakákoliv jiná hodnota, tvrzení vrátí všechny argumenty včetně v a message.

Poněkud běžný idiom v Lua je, že funkce v normálním provozu vrátí hodnotu "true" a při selhání vrátí nulu nebo nepravdu jako první hodnotu a chybovou zprávu jako druhou hodnotu. Snadnou kontrolu chyb lze poté implementovat zabalením hovoru do volání assert:

-- Toto nekontroluje chyby
local result1, result2, etc = func( ... )

-- Funguje to stejně, ale kontroluje chyby
local result1, result2, etc = assert( func( ... ) )

error

error( message, level )

Vydá chybu s textem message.

error obvykle přidává nějaké informace o umístění chyby. Pokud level je 1 nebo je vynechán, je tato informace místem samotného volání error. 2 používá umístění volání funkce, která volala chybu. A tak dále. Předání 0 vynechá zahrnutí informací o poloze.

getfenv

getfenv( f )

Upozorňujeme, že tato funkce nemusí být dostupná v závislosti na allowEnvFuncs v konfiguraci motoru.

Vrátí prostředí (globální tabulku proměnných), jak je specifikováno f:

• Pokud je 1, nula nebo je vynecháno, vrátí prostředí funkce volající getfenv. Často to bude stejné jako _G.
• Celá čísla 2–10 vrátí prostředí funkcí výše v zásobníku volání. Například 2 vrátí prostředí pro funkci, která volala aktuální funkci, 3 vrátí prostředí pro funkci volající tuto funkci a tak dále. Pokud je hodnota vyšší než počet volání funkcí v zásobníku nebo pokud se cílová úroveň zásobníku vrátí s voláním konce, dojde k chybě.
• Předání funkce vrátí prostředí, které bude použito při volání této funkce.

Prostředí používaná všemi standardními knihovními funkcemi a funkcemi knihovny Scriunto jsou chráněna. Pokus o přístup do těchto prostředí pomocí getfenv vrátí nulu.

getmetatable

getmetatable( table )

Vrátí metatable tabulky. Jakýkoli jiný typ vrátí nulu.

Pokud má metatabulka pole __metatable, bude vrácena tato hodnota namísto skutečné metatabulky.

ipairs

ipairs( t )

Vrátí tři hodnoty: funkci iterátoru, tabulku t a 0. Toto je určeno pro použití ve tvaru iterator for:

for i, v in ipairs( t ) do
    -- process each index-value pair
end

Toto bude iterovat přes dvojice ( 1, t[1] ), ( 2, t[2] ) atd., přičemž se zastaví, když t[i] bude nulové.

Standardní chování může být potlačeno poskytnutím __ipairs metametody. Pokud tato metametoda existuje, volání ipairs místo toho vrátí tři hodnoty vrácené __ipairs( t ).

next

next( table, key )

To umožňuje iteraci přes klíče v tabulce. Pokud je key nula nebo není specifikováno, vrátí "první" klíč v tabulce a jeho hodnotu; jinak vrátí klíč "další" a jeho hodnotu. Pokud nejsou k dispozici žádné další klíče, vrátí hodnotu nula. Zda je tabulka prázdná, je možné zkontrolovat pomocí výrazu next( t ) == nil.

Všimněte si, že pořadí, ve kterém jsou klíče vráceny, není určeno, a to ani pro tabulky s číselnými indexy. Chcete-li procházet tabulkou v číselném pořadí, použijte numerical for nebo ipairs.

Chování je nedefinované, pokud je při použití next pro procházení přiřazena hodnota jakémukoli neexistujícímu klíči. Přiřazení nové hodnoty (včetně nuly) existujícímu poli je povoleno.

pairs

pairs( t )

Vrátí tři hodnoty: funkci iterátoru (next nebo podobnou práci), tabulku t a nulu. Toto je určeno pro použití ve iterátorové formě for:

for k, v in pairs( t ) do
    -- zpracovat každý pár klíč–hodnota
end

To bude opakovat páry klíč-hodnota v t stejně jako next. V dokumentaci k next naleznete omezení týkající se úprav tabulky během procházení.

Standardní chování může být potlačeno poskytnutím __pairs metametoda. Pokud tato metametoda existuje, volání párů místo toho vrátí tři hodnoty vrácené __pairs( t ).

pcall

pcall( f, ... )

Volá funkci f s danými argumenty v chráněném režimu. To znamená, že pokud se během volání na f objeví chyba, pcall vrátí false a vyvolá se chybová zpráva. Pokud nedojde k žádné chybě, pcall vrátí true a všechny hodnoty vrácené voláním.

V pseudokódu může být pcall definován nějak takto:

function pcall( f, ... )
    try
        return true, f( ... )
    catch ( message )
        return false, message
    end
end

rawequal

rawequal( a, b )

To je ekvivalent a == b kromě toho, že ignoruje jakoukoli __eq metametodu.

rawget

rawget( table, k )

To je ekvivalent table[k] kromě toho, že ignoruje jakoukoli __index metametodu.

rawset

rawset( table, k, v )

To je ekvivalent table[k] = v kromě toho, že ignoruje jakoukoli __newindex metametodU.

select

select( index, ... )

Pokud je index číslo, vrátí všechny argumenty v ... od tohoto indexu dále. Pokud je index řetězec "#", vrátí počet argumentů v ....

Poznámka: Na rozdíl od tabulek seznamy argumentů (včetně výrazu vararg ...) považují nil za odlišnou hodnotu (viz dokumentace k # a unpack pro problém s nil v tabulkách). Například:

• select(2, "foo", "bar") vrátí "bar".
• select(2, "foo", nil, "bar", nil) vrátí nil, "bar", nil.
• select("#", "foo", "bar") vrátí 2.
• select("#", "foo", "bar", nil) vrátí 3.

Jinými slovy, select je zhruba jako následující (kromě toho, že také zpracovává všechny nil argumenty po posledním nenulovém argumentu):

function select( index, ... )
    local t = { ... }
    local maxindex = table.maxn( t )
    if index == "#" then
        return maxindex
    else
        return unpack( t, index, maxindex )
    end
end

setmetatable

setmetatable( table, metatable )

Nastavuje z tabulky metatabulku. metatable může být nula, ale musí být výslovně uvedeno.

Pokud má aktuální metatabulka pole __metatable, setmetatable vyvolá chybu.

tonumber

tonumber( value, base )

Pokusí se převést value na číslo. Pokud se již jedná o číslo nebo řetězec převoditelný na číslo, pak tonumber toto číslo vrátí; jinak vrátí nulu.

Volitelné base (výchozí 10) určuje základ pro interpretaci čísla. Základem může být jakékoli celé číslo mezi 2 a 36 včetně. V základech nad 10 představuje písmeno "A" (buď velké nebo malé) 10, "B" představuje 11 a tak dále, přičemž "Z" představuje 35.

V základu 10 může mít hodnota desetinnou část, může být vyjádřena v E zápisu a může mít na začátku "0x" pro označení základu 16. V jiných základech jsou akceptována pouze celá čísla bez znaménka.

tostring

tostring( value )

Převede value na řetězec. Podrobnosti o převodu jednotlivých typů viz Datové typy výše.

Standardní chování tabulek může být potlačeno poskytnutím __tostring metametody. Pokud tato metametoda existuje, volání tostring místo toho vrátí jedinou hodnotu vrácenou __tostring( value ).

type

type( value )

Vrátí typ value jako řetězec: "nil", "number", "string", "boolean", "table" nebo "function".

unpack

unpack( table, i, j )

Vrátí hodnoty z dané tabulky, něco jako table[i], table[i+1], ···, table[j] by udělalo, pokud by bylo zapsáno ručně. Pokud je nula nebo není zadáno, i výchozí hodnota 1 a j výchozí #table.

Pokud tabulka nemá hodnotu pro konkrétní klíč, rozbalení vrátí pro tuto hodnotu nulu. Například unpack({"foo", [3] = "bar"}, 1, 4) vrátí "foo", nil, "bar", nil.

Všimněte si, že výsledky nejsou deterministické, pokud table 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.randomseed( tonumber( mw.getContentLanguage():formatDate( "U" ) ) * 10000 + os.clock() * 10000 )

math.sin

math.sin( x )

Vrátí sinus x (zadaný v radiánech).

math.sinh

math.sinh( x )

Vrátí hyperbolický sinus x.

math.sqrt

math.sqrt( x )

Vrátí druhou odmocninu z x. Ekvivalent x^0.5.

math.tan

math.tan( x )

Vrátí tangens x (zadaný v radiánech).

math.tanh

math.tanh( x )

Vrátí hyperbolický tangens x.

Knihovna operačního systému

os.clock

os.clock()

Vrátí přibližnou hodnotu v sekundách času procesoru použitého programem.

os.date

os.date( format, time )

Formát jazykové knihovny lze použít pro komplexnější formátování data

Vrátí řetězec nebo tabulku obsahující datum a čas ve formátu format. Pokud je formát vynechán nebo je nulový, použije se "%c".

Pokud je zadáno time, je to čas, který má být formátován (viz os.time()). Jinak se použije aktuální čas.

Pokud format začíná znakem '!', pak je datum formátováno v UTC, nikoli v místním čase serveru. Za tímto volitelným znakem, pokud je formátem řetězec "*t", pak datum vrátí tabulku s následujícími poli:

• year (rok) (full)
• month (měsíc) (1–12)
• day (den) (1–31)
• hour (hodina) (0–23)
• min (0–59)
• sec (0–60, umožní přestupné sekundy)
• wday (všední den, neděle je 1)
• yday (den v roce)
• isdst (příznak letního času, boolean; může chybět, pokud informace nejsou k dispozici)

Pokud formát není "*t", pak datum vrátí datum jako řetězec, naformátovaný podle stejných pravidel jako funkce C strftime.

os.difftime

os.difftime( t2, t1 )

Vrátí počet sekund od t1 do t2.

os.time

os.time( table )

Vrátí číslo představující aktuální čas.

Při volání bez argumentů vrátí aktuální čas. Pokud projde tabulkou, bude analyzován čas zakódovaný v tabulce. Tabulka musí obsahovat pole "rok", "měsíc" a "den" a může také obsahovat "hodinu" (výchozí 12), "min" (výchozí 0), "sec" (výchozí 0) a "isdst".

Knihovna balíčků

require

require( modulename )

Načte zadaný modul.

Nejprve se podívá do package.loaded[modulename], aby zjistil, zda je modul již načten. Pokud ano, vrátí package.loaded[modulename].

Jinak volá každý zavaděč v sekvenci package.loaders, aby se pokusil najít zavaděč pro modul. Pokud je nalezen zavaděč, zavolá se tento zavaděč. Hodnota vrácená zavaděčem se uloží do package.loaded[modulename] a vrátí se.

Informace o dostupných zavaděčích naleznete v dokumentaci pro package.loaders.

Pokud máte například modul "Module:Giving" obsahující následující:

local p = {}

p.someDataValue = 'Ahoj!'

return p

Můžete to načíst do jiného modulu s kódem, jako je tento:

local giving = require( "Module:Giving" )

local value = giving.someDataValue -- hodnota je nyní 'Ahoj!'

package.loaded

Tato tabulka obsahuje načtené moduly. Klíče jsou názvy modulů a hodnoty jsou hodnoty vrácené při načtení modulu.

package.loaders

Tato tabulka obsahuje posloupnost vyhledávacích funkcí, které se mají použít při načítání modulů. Každá vyhledávací funkce je volána s jediným argumentem, názvem modulu, který se má načíst. Pokud je modul nalezen, hledač musí vrátit funkci, která modul skutečně načte a vrátí hodnotu, kterou má vrátit požadavek. V opačném případě musí vrátit nulu.

Scribunto nabízí dva vyhledávače:

1. V package.preload[modulename] vyhledejte funkci loader
2. Hledejte v modulech poskytovaných se Scribuntem 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 $3 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 init, kde najdete podobnou funkci rozšířenou, jak je popsáno ve vzorech Ustring 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 pattern 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 ve vzorech Ustring.

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 ve vzorech Ustring.

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 pattern 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. Všimněte si, že neobsahuje znak podtržítka (_), na rozdíl od obvyklé třídy \w v regulárních výrazech.
%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 znaků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ě;
• %n, pro n mezi 1 a 9. Taková položka odpovídá podřetězci rovnému n-tému 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.
• %f[set], hraniční vzor. 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 pairs() 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 Scribunto 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í objekt frame, obvykle objekt frame z nejnovějšího #invoke.

mw.incrementExpensiveFunctionCount

mw.incrementExpensiveFunctionCount()

Přidá jedničku k počtu "náročné 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ý objekt frame, který je potomkem aktuálního frame, s volitelnými argumenty a názvem.

Toto je určeno hlavně pro použití v modulech, které volají jiné moduly, jejichž jméno je definováno volajícím (např. {{#invoke:params|concat_and_invoke}}, nebo v ladicí konzoli pro testování funkcí, které by normálně volalo {{#invoke:}}. Počet frame, které mohou být vytvořeny v libovolném čas 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. Na mnoha wikinách Wikimedie to bylo dříve implementováno v Module:HtmlBuilder. 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).

Základní wikitext bude analyzován, jako je HTML, odkazy, tučné písmo, seznamy nebo tabulky. Šablony a funkce analyzátoru však nebudou vyhodnoceny, pokud jsou předány přímo této funkci, pokud nepocházejí z parametrů šablony. Ty budou místo toho vykresleny jako prostý text. Chcete-li je vyhodnotit, musíte je projít frame:preprocess.

mw.html:newline

html:newline()

Připojí nový řádek k objektu mw.html. Užitečné při použití před a po mw.html:wikitext(), když wikitext obsahuje seznamy nebo tabulky, jejichž syntaxe má zvláštní význam pouze tehdy, jsou-li uvedeny na začátku řádku.

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 pro 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í $1 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, { 'sock', 'socks' } ) 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 PLURALu, 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 stránceNá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 $3 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í what, což může být "muž", "žena" nebo registrované uživatelské jméno.

mw.language:getArrow

lang:getArrow( direction )

Vrátí znak šipky Unicode odpovídající směru:

• vpřed: Buď "→" nebo "←" v závislosti na směrovosti jazyka.
• zpět: Buď "←" nebo "→" v závislosti na směrovosti jazyka.
• vlevo: "←"
• správně: "→"
• nahoru: "↑"
• dolů: "↓"

mw.language:getDir

lang:getDir()

Vrátí "ltr" nebo "rtl" v závislosti na směrovosti jazyka.

mw.language:getDirMark

lang:getDirMark( opposite )

Vrátí řetězec obsahující buď U+200E (značka zleva doprava) nebo U+200F (značka zprava doleva), v závislosti na směrovosti jazyka a na tom, zda je opačný pravdivá nebo nepravdivá hodnota.

mw.language:getDirMarkEntity

lang:getDirMarkEntity( opposite )

Vrátí "‎" nebo "‏", v závislosti na směrovosti jazyka a na tom, zda je opačná hodnota pravdivá nebo nepravdivá.

mw.language:getDurationIntervals

lang:getDurationIntervals( seconds )
lang:getDurationIntervals( seconds, chosenIntervals )

Rozdělí dobu trvání v sekundách do více čitelných jednotek, např. 12345 na 3 hodiny, 25 minut a 45 sekund, přičemž výsledek se vrátí jako tabulka mapující názvy jednotek na čísla.

chosenIntervals, pokud je zadán, je tabulka s hodnotami pojmenujícími jednotky intervalu, které se mají použít v odpovědi. Patří mezi ně 'millennia' (tisíciletí), 'centuries' (století), 'decades' (dekády), 'years' (roky), 'weeks' (týdny), 'days' (dny), 'hours' (hodiny), 'minutes' (minuty) a 'seconds' (sekundy).

Tato klíčová slova jednotek jsou také klíči používanými v tabulce odpovědí. V odpovědi jsou nastaveny pouze jednotky s nenulovou hodnotou, pokud by odpověď nebyla prázdná, v takovém případě je vrácena nejmenší jednotka s hodnotou 0.

Knihovna zpráv

Tato knihovna je rozhraním pro lokalizační zprávy a jmenný prostor MediaWiki:.

Funkce dokumentované jako mw.message.name jsou dostupné v globální tabulce mw.message. Funkce dokumentované jako mw.message:name a msg:name jsou metody objektu zprávy (viz mw.message.new).

mw.message.new

mw.message.new( key, ... )

Vytvoří nový objekt zprávy pro danou zprávu key. Zbývající parametry jsou předány metodě params() nového objektu.

Objekt zprávy nemá žádné vlastnosti, ale má několik níže popsaných metod.

mw.message.newFallbackSequence

mw.message.newFallbackSequence( ... )

Vytvoří nový objekt zprávy pro dané zprávy (použije se první, který existuje).

Objekt zprávy nemá žádné vlastnosti, ale má několik níže popsaných metod.

mw.message.newRawMessage

mw.message.newRawMessage( msg, ... )

Vytvoří nový objekt zprávy, který použije přímo daný text, místo aby vyhledával internacionalizovanou zprávu. Zbývající parametry jsou předány metodě params() nového objektu.

Objekt zprávy nemá žádné vlastnosti, ale má několik níže popsaných metod.

mw.message.rawParam

mw.message.rawParam( value )

Zabalí hodnotu tak, aby nebyla analyzována jako wikitext pomocí msg:parse().

mw.message.numParam

mw.message.numParam( value )

Zabalí hodnotu tak, aby byla automaticky naformátována jako lang:formatNum(). Všimněte si, že to nezávisí na skutečně dostupné knihovně jazyků.

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 metamethod 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. Jazykový 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: Číslo jmenného prostoru.
• name: 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 v jmenném prostoru velké.
• isContent: Zda se jedná o jmenný prostor obsahu.
• isIncludable: Zda lze stránky v jmenném prostoru transkludovat.
• isMovable: Zda lze v jmenném prostoru přesouvat stránky.
• isSubject: Zda se jedná o předmětový jmenný prostor.
• isTalk: Ať už se jedná o jmenný prostor pro diskuse.
• defaultContentModel: Výchozí model obsahu pro jmenný prostor jako řetězec.
• aliases: Seznam aliasů pro jmenný prostor.
• subject: Odkaz na odpovídající data jmenného prostoru předmětu.
• talk: Odkaz na odpovídající data jmenného prostoru diskuse.
• associated: Odkaz na data souvisejícího jmenného prostoru.

Je také nastavena metatabulka, která umožňuje vyhledávat jmenné prostory podle názvu (lokalizovaného nebo kanonického). Například mw.site.namespaces[4] a mw.site.namespaces.Project vrátí informace o jmenném prostoru projektu.

mw.site.contentNamespaces

Tabulka obsahující pouze jmenné prostory obsahu, indexované podle čísla. Podrobnosti viz mw.site.namespaces.

mw.site.subjectNamespaces

Tabulka obsahující pouze obory názvů předmětů, indexované podle čísla. Podrobnosti viz mw.site.namespaces.

mw.site.talkNamespaces

Tabulka obsahující pouze jmenné prostory talk, indexované podle čísla. Podrobnosti viz mw.site.namespaces.

mw.site.stats

Tabulka statistiky webu. Dostupné statistiky jsou:

• pages: Počet stránek na wiki.
• articles: Počet článků na wiki.
• files: Počet souborů na wiki.
• edits: Počet úprav na wiki.
• users: Počet uživatelů na wiki.
• activeUsers: Počet aktivních uživatelů na wiki.
• admins: Počet uživatelů ve skupině 'sysop' na wiki.

mw.site.stats.pagesInCategory

mw.site.stats.pagesInCategory( kategorie, jaká )

Tato funkce je náročná

Získá statistiky o kategorii. Pokud má jaká speciální hodnotu "*", výsledkem je tabulka s následujícími vlastnostmi:

• all: Celkový počet stránek, souborů a podkategorií.
• subcats: Počet podkategorií.
• files: Počet souborů.
• pages: Počet stránek.

Pokud je jaká jedním z výše uvedených klíčů ("all", "subcats", "files", "pages"), výsledkem je číslo s odpovídající hodnotou.

Každá nová dotazovaná kategorie zvýší počet náročných funkcí.

mw.site.stats.pagesInNamespace

mw.site.stats.pagesInNamespace( jmenný prostor )

Vrátí počet stránek v daném jmenném prostoru (zadané číslem).

mw.site.stats.usersInGroup

mw.site.stats.usersInGroup( skupina )

Vrátí počet uživatelů v dané skupině.

mw.site.interwikiMap

mw.site.interwikiMap( filtr )

Vrátí tabulku obsahující data o dostupných interwiki prefixech. Pokud je filtr řetězec "local", vrátí se pouze data pro místní předpony interwiki. Pokud je filtr řetězec "!local", vrátí se pouze data pro nelokální předpony. Pokud není zadán žádný filtr, vrátí se data pro všechny předpony. Předpona "local" v tomto kontextu je ta, která je pro stejný projekt. Například na anglické Wikipedii jsou jiné jazykové Wikipedie považovány za místní, zatímco Wikislovník a podobně nikoli.

Klíče v tabulce vrácené touto funkcí jsou interwiki předpony a hodnoty jsou podtabulky s následujícími vlastnostmi:

• prefix - předpona interwiki.
• url - URL, na kterou interwiki odkazuje. Název stránky je reprezentován parametrem $1.
• isProtocolRelative - boolean ukazující, zda je adresa URL protokolově relativní.
• isLocal - zda je adresa URL pro web v aktuálním projektu.
• isCurrentWiki - zda je adresa URL pro aktuální wiki.
• isTranscludable - zda stránky používající tuto předponu interwiki jsou transcludable. To vyžaduje náročnou transkluzi, která je na wikinách Wikimedie zakázána.
• isExtraLanguageLink - zda je interwiki uvedena v $wgExtraInterlanguageLinkPrefixes .
• displayText - pro odkazy uvedené v $wgExtraInterlanguageLinkPrefixes je to zobrazovaný text zobrazený pro mezijazykový odkaz. Není-li uvedeno, nula.
• tooltip - pro odkazy uvedené v $wgExtraInterlanguageLinkPrefixes se jedná o text popisku, který se zobrazí, když uživatel najede na mezijazykový odkaz. Není-li uvedeno, nula.

Textová knihovna

Textová knihovna poskytuje některé běžné funkce pro zpracování textu, které chybí v knihovně řetězců a knihovně Ustring. Tyto funkce jsou bezpečné pro použití s ​​řetězci UTF-8.

mw.text.decode

mw.text.decode( řetězec )
mw.text.decode( řetězec, dekódované pojmenované entity )

Nahradí entity HTML v řetězci odpovídajícími znaky.

Pokud je logická hodnota dekódované pojmenované entity vynechána nebo je nepravdivá, jsou rozpoznány pouze pojmenované entity < (<), > (>), & (&), " (") a   (nerozdělitelná mezera, U+00A0). Jinak se seznam pojmenovaných entit HTML5 k rozpoznání načte z funkce get_html_translation_table PHP.

Známé chyby: Přibližně 600 z přibližně 2 200 pojmenovaných entit ve standardu HTML5 nelze dekódovat, i když jsou použity decodeNamedEntities. To zahrnuje přibližně 40 z přibližně 250 entit, které jsou také zahrnuty v HTML4. K tomu dochází, protože funkce get_html_translation_table PHP vrací pouze jedno mapování pro každý znak, takže například → není dekódováno, protože PHP vrací pouze → jako mapování pro →.

mw.text.encode

mw.text.encode( řetězec )
mw.text.encode( řetězec, znaková sada )

Nahradí znaky v řetězci HTML entity. Pět znaků je nahrazeno příslušnými pojmenovanými entitami: <, >, &, " a nerozdělitelná mezera (U+00A0). Všechny ostatní jsou nahrazeny číselnými entitami.

Je-li zadána znaková sada, měl by to být řetězec podle potřeby, který bude vložen do závorek ve vzorech Ustring, tj. "set" v [set]. Výchozí znaková sada obsahuje šest znaků: <, >, &, ", ' a pevnou mezeru (U+00A0).

mw.text.jsonDecode

mw.text.jsonDecode( řetězec )
mw.text.jsonDecode( řetězec, příznaky )

Dekóduje řetězec JSON. příznaky je 0 nebo kombinace (použijte +) příznaky mw.text.JSON_PRESERVE_KEYS a mw.text.JSON_TRY_FIXING.

Normálně jsou pole JSON založená na nule přečíslována na tabulky sekvencí založené na jedné Lua. Abyste tomu zabránili, předejte mw.text.JSON_PRESERVE_KEYS.

Chcete-li zmírnit určité požadavky v JSON, například žádné koncové čárky v polích nebo objektech, předejte mw.text.JSON_TRY_FIXING. To se nedoporučuje.

Omezení:

• Dekódovaná pole JSON nemusí být sekvencemi Lua, pokud pole obsahuje hodnoty null.
• Objekty JSON zahodí klíče s hodnotami null.
• Není možné přímo zjistit, zda vstupem bylo pole JSON nebo objekt JSON se sekvenčními celočíselnými klíči.
• Objekt JSON, který má sekvenční celočíselné klíče začínající 1, se dekóduje do stejné struktury tabulky jako pole JSON se stejnými hodnotami, přestože tyto nejsou vůbec ekvivalentní, pokud není použit mw.text.JSON_PRESERVE_KEYS.

mw.text.jsonEncode

mw.text.jsonEncode( hodnota )
mw.text.jsonEncode( hodnota, příznaky )

Zakódujte řetězec JSON. Pokud nelze předávanou hodnotu zakódovat do JSON, dojde k chybám. Příznaky jsou 0 nebo kombinace (použijte +) příznaků mw.text.JSON_PRESERVE_KEYS a mw.text.JSON_PRETTY.

Normálně jsou sekvenční tabulky založené na Lua jedné kódovány jako pole JSON založená na nule. Když je mw.text.JSON_PRESERVE_KEYS nastaveno v příznacích, nulové sekvenční tabulky jsou kódovány jako pole JSON.

Omezení:

• Prázdné tabulky jsou vždy kódovány jako prázdná pole ([]), nikoli prázdné objekty ({}).
• Sekvenční tabulky nelze kódovat jako objekty JSON bez přidání "fiktivního" prvku.
• Chcete-li vytvářet objekty nebo pole s nulovými hodnotami, je vyžadována složitá implementace metametody __pairs.
• Lua tabulka, která má sekvenční celočíselné klíče začínající 0, bude kódována jako pole JSON, stejně jako Lua tabulka s celočíselnými klíči začínajícími 1, pokud není použito mw.text.JSON_PRESERVE_KEYS.
• Když se jako klíče ve stejné tabulce použije číslo i řetězcová reprezentace tohoto čísla, chování není specifikováno.

mw.text.killMarkers

mw.text.killMarkers( řetězec )

Odebere všechny značky stripu MediaWiki z řetězce.

mw.text.listToText

mw.text.listToText( seznam )
mw.text.listToText( seznam, oddělovač, spojka )

Připojí se k seznamu ve stylu prózy. Jinými slovy, je to jako table.concat(), ale s jiným oddělovačem před poslední položkou.

Výchozí oddělovač je převzat z MediaWiki:comma-separator v jazyce obsahu wiki a výchozí spojka je MediaWiki:and zřetězená s MediaWiki:word-separator.

Příklady s použitím výchozích hodnot pro zprávy:

 -- Vrátí prázdný řetězec
 mw.text.listToText( {} )
 
 -- Vrátí "1"
 mw.text.listToText( { 1 } )
 
 -- Vrátí "1 a 2"
 mw.text.listToText( { 1, 2 } )
 
 -- Vrátí "1, 2, 3, 4 a 5"
 mw.text.listToText( { 1, 2, 3, 4, 5 } )
 
 -- Vrátí "1; 2; 3; 4 nebo 5"
 mw.text.listToText( { 1, 2, 3, 4, 5 }, '; ', ' or ' )

mw.text.nowiki

mw.text.nowiki( řetězec )

Nahradí různé znaky v řetězci HTML entity, aby se zabránilo jejich interpretaci jako wikitextu. To zahrnuje:

• Následující znaky: ", &, ', <, =, >, [, ], {, |, }
• Následující znaky na začátku řetězce nebo bezprostředně za novým řádkem: $2
• Prázdné řádky budou mít jeden z přidružených znaků nového řádku nebo konce řádku
• $3 na začátku řetězce nebo bezprostředně po novém řádku budou mít první $4 escapované
• $5 bude mít jedno podtržítko unikající
• $6 bude mít dvojtečku uniklou
• Mezera následující za $7 nebo $8 bude escapována

• 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( řetězec, vzor, ​​plain )

Rozdělí řetězec na podřetězce na hranicích odpovídajících vzoru Ustring. Pokud je zadán plain a true, bude vzor interpretován jako doslovný řetězec, nikoli jako vzor Lua (stejně jako u stejnojmenného parametru pro mw.ustring.find()). Vrátí tabulku obsahující podřetězce.

Například mw.text.split( 'a b\tc\nd', '%s' ) vrátí tabulku { 'a', 'b', 'c', 'd' }.

Pokud vzor odpovídá prázdnému řetězci, bude řetězec rozdělen na jednotlivé znaky.

Všimněte si, že tato funkce může být více než 60krát pomalejší než reimplementace, která nepodporuje Unicode, jako například následující:

function split(text, pattern, plain)
    local ret = {}
    local s, l = 1, string.len( text )
    while s do
    	local e, n = string.find( text, pattern, s, plain )
    	if not e then
    		ret[#ret+1] = string.sub ( text, s )
    		s = nil
    	elseif n < e then
    		-- Empty separator!
    		ret[#ret+1] = string.sub ( text, s, e )
    		if e < l then
    			s = e + 1
    		else
    			s = nil
    		end
    	else
    		ret[#ret+1] = e > s and string.sub( text, s, e - 1 ) or ''
    		s = n + 1
    	end
    end
    return ret
end

mw.text.gsplit

mw.text.gsplit( řetězec, vzor, ​​plain )

Vrací funkci iterátor, která bude iterovat podřetězce, které by vrátilo ekvivalentní volání mw.text.split().

Všimněte si, že tato funkce může být více než 60krát pomalejší než reimplementace, která nepodporuje Unicode, jako například následující:

function gsplit( text, pattern, plain )
	local s, l = 1, string.len( text )
	return function ()
		if s then
			local e, n = string.find( text, pattern, s, plain )
			local ret
			if not e then
				ret = string.sub( text, s )
				s = nil
			elseif n < e then
				-- Empty separator!
				ret = string.sub( text, s, e )
				if e < l then
					s = e + 1
				else
					s = nil
				end
			else
				ret = e > s and string.sub( text, s, e - 1 ) or ''
				s = n + 1
			end
			return ret
		end
	end, nil, nil
end

mw.text.tag

mw.text.tag( název, vlastnosti, obsah )
mw.text.tag{ název = řetězec, vlastnosti = tabulka, obsah = řetězec|false }

Všimněte si použití pojmenovaných argumentů.

Vygeneruje značku ve stylu HTML pro název.

Pokud je zadáno vlastnosti, musí to být tabulka s řetězcovými klíči. Řetězcové a číselné hodnoty se používají jako hodnota atributu. Boolean true má za následek výstup klíče jako parametr bez hodnoty HTML5. Boolean false klíč úplně přeskočí. A cokoli jiného je chyba.

Pokud není zadán obsah (nebo je nulový), vrátí se pouze úvodní značka. Pokud má obsah logickou hodnotu false, vrátí se značka s automatickým uzavřením. V opačném případě to musí být řetězec nebo číslo, v takovém případě je obsah uzavřen ve vytvořeném otevíracím a uzavíracím tagu. Všimněte si, že obsah není automaticky kódován HTML. V případě potřeby použijte mw.text.encode().

Chcete-li správně vracet značky rozšíření, jako je ‎<ref>, použijte místo toho frame:extensionTag().

mw.text.trim

mw.text.trim( řetězec )
mw.text.trim( řetězec, znaková sada )

Odstraňte mezery nebo jiné znaky ze začátku a konce řetězce.

Je-li zadán znaková sada, měl by to být řetězec, který se vejde do závorek ve vzoru Ustring, tj. "set" v [set]. Výchozí znaková sada je mezera ASCII, %s, což je ekvivalent "\t\r\n\f\v ".

mw.text.truncate

mw.text.truncate( text, délka )
mw.text.truncate( text, délka, vynechání )
mw.text.truncate( text, délka, vynechání, upravit délku )

Zkrátí text na zadanou délku v bodech kódu a přidá vynechání, pokud bylo provedeno zkrácení. Pokud je délka kladná, bude konec řetězce zkrácen. Je-li záporná, začátek bude odstraněn. Pokud je zadáno upravit délku a true, výsledný řetězec včetně vynechání nebude delší než zadaná délka.

Výchozí hodnota pro vynechání je převzata z MediaWiki:ellipsis v jazyce obsahu wiki.

Příklady s použitím výchozího vynechání "...":

-- Vrátí "foobarbaz"
mw.text.truncate( "foobarbaz", 9 )

-- Vrátí "fooba"...
mw.text.truncate( "foobarbaz", 5 )

-- Vrátí "...arbaz"
mw.text.truncate( "foobarbaz", -5 )

-- Vrátí "foo"...
mw.text.truncate( "foobarbaz", 6, nil, true )

-- Vrátí "foobarbaz", protože je to kratší než "foobarba... "
mw.text.truncate( "foobarbaz", 8 )

mw.text.unstripNoWiki

mw.text.unstripNoWiki( řetězec )

Nahrazuje MediaWiki <nowiki> označení pruhu s odpovídajícím textem. Ostatní typy proužkových značek se nemění.

mw.text.unstrip

mw.text.unstrip( řetězec )

Ekvivalent mw.text.killMarkers( mw.text.unstripNoWiki( řetězec ) ).

Toto již neodhaluje HTML za speciální transkluzí stránky, tagy <ref> a tak dále, jako tomu bylo v dřívějších verzích Scriunto.

Knihovna titulů

mw.title.equals

mw.title.equals( a, b )

Otestujte, zda jsou dva tituly stejné. Všimněte si, že fragmenty jsou při porovnávání ignorovány.

mw.title.compare

mw.title.compare( a, b )

Vrátí -1, 0 nebo 1 k označení, zda je titul a menší, rovný nebo větší než titul b.

To porovnává názvy podle předpony interwiki (pokud existuje) jako řetězců, poté podle čísla jmenného prostoru a poté podle textu názvu bez předpony jako řetězce. Tato porovnání řetězců používají standardní operátor Lua <.

mw.title.getCurrentTitle

mw.title.getCurrentTitle()

Vrátí objekt title pro aktuální stránku.

mw.title.new

mw.title.new( text, jmenný prostor )
mw.title.new( ID )

Tato funkce je náročná, pokud je volána s ID

Vytvoří nový objekt titulku.

Pokud je zadáno číslo ID, vytvoří se objekt pro nadpis s tímto page_id. Odkazovaný titul bude považován za odkazovaný z aktuální stránky. Pokud page_id neexistuje, vrátí nulu. Počet drahých funkcí se zvýší, pokud vytvořený objekt title není pro titul, který již byl načten.

Pokud je místo toho zadán řetězec text, vytvoří se pro tento nadpis objekt (i když stránka neexistuje). Pokud textový řetězec neurčuje jmenný prostor, použije se jmenný prostor (což může být jakýkoli klíč nalezený v mw.site.namespaces). Pokud text není platným názvem, vrátí se nula.

mw.title.makeTitle

mw.title.makeTitle( jmenný prostor, title, fragment, interwiki )

Vytvoří objekt title s title title ve jmenném prostoru jmenný prostor, volitelně se zadanou předponou fragment a interwiki. jmenný prostor může být jakýkoli klíč nalezený v mw.site.namespaces. Pokud výsledný název není platný, vrátí hodnotu nula.

Všimněte si, že na rozdíl od mw.title.new() tato metoda vždy použije zadaný jmenný prostor. Například mw.title.makeTitle( 'Template', 'Module:Foo' ) vytvoří objekt pro stránku Template:Module:Foo, zatímco mw.title.new( 'Module:Foo', 'Template' ) vytvoří objekt pro stránku Module:Foo.

Všimněte si také, že funkčnost pro titulky interwiki je omezena na interwiki / isExternal / isLocal a metody související s URL. Jiné metody se nemusí chovat podle očekávání.

Objekty titulků

Objekty titulků mají řadu vlastností a metod. Většina vlastností je pouze pro čtení.

Všimněte si, že pole končící na text vracejí názvy jako řetězcové hodnoty, zatímco pole končící na title vracejí názvy objektů.

• id: page_id. 0, pokud stránka neexistuje. Toto může být náročné.
• interwiki: Předpona interwiki nebo prázdný řetězec, pokud neexistuje.
• namespace: Číslo jmenného prostoru.
• fragment: Fragment (aka propojení sekce/kotvy) nebo prázdný řetězec. Může být přiděleno.
• nsText: Text jmenného prostoru stránky.
• subjectNsText: Text jmenného prostoru předmětu pro stránku.
• talkNsText: Text diskusního jmenného prostoru pro stránku, nebo nil, pokud tento titul nemůže mít diskusní stránku. (přidáno v MediaWiki 1.42.0-wmf.15, odkazy T180911)
• text: Název stránky, bez jmenného prostoru nebo interwiki předpon.
• prefixedText: Název stránky se jmenným prostorem a předponami interwiki.
• fullText: Název stránky se jmenným prostorem a předponami interwiki a fragmentem. Interwiki není vrácena, pokud je rovno aktuální.
• rootText: Pokud se jedná o podstránku, název kořenové stránky bez předpon. Jinak stejné jako title.text.
• baseText: Pokud se jedná o podstránku, název stránky je podstránkou bez prefixů. Jinak stejné jako title.text.
• subpageText: Pokud se jedná o podstránku, pouze název podstránky. Jinak stejné jako title.text.
• canTalk: Zda stránka pro tento titul může mít diskusní stránku.
• exists: Zda stránka existuje. Alias ​​pro file.exists pro názvy mediálního jmenného prostoru. U názvů oboru názvů souborů to kontroluje existenci stránky popisu souboru, nikoli samotného souboru. Toto může být drahé.
• file, fileExists: Viz #Metadata souboru níže.
• isContentPage: Zda je tento titul v jmenném prostoru obsahu.
• isExternal: Zda má tento název předponu interwiki.
• isLocal: Zda je tento titul součástí tohoto projektu. Například na anglické Wikipedii je jakákoli jiná Wikipedie považována za "místní", zatímco Wikislovník a podobně nikoli.
• isRedirect: Zda se jedná o název stránky, která je přesměrována. Toto může být náročné.
• isSpecialPage: Zda se jedná o název možné speciální stránky (tj. stránky ve jmenném prostoru Special:).
• isSubpage: Zda je tento titul podstránkou jiného titulu.
• isTalkPage: Zda se jedná o název diskusní stránky.
• isSubpageOf( title2 ): Zda je tento titul podstránkou daného titulu.
• inNamespace( ns ): Zda je tento název v daném jmenném prostoru. Jmenné prostory mohou být specifikovány čímkoli, co je klíčem nalezeným v mw.site.namespaces.
• inNamespaces( ... ): Zda je tento název v některém z daných jmenných prostorů. Jmenné prostory mohou být specifikovány čímkoli, co je klíčem nalezeným v mw.site.namespaces.
• hasSubjectNamespace( ns ): Zda je předmětný jmenný prostor tohoto titulu v daném jmenném prostoru. Jmenné prostory mohou být specifikovány čímkoli, co je klíčem nalezeným v mw.site.namespaces.
• contentModel: Model obsahu pro tento titul jako řetězec. Toto může být náročné.

• basePageTitle: Stejné jako mw.title.makeTitle( title.namespace, title.baseText ).

• rootPageTitle: Stejné jako mw.title.makeTitle( title.namespace, title.rootText ).
• talkPageTitle: Stejné jako mw.title.makeTitle( mw.site.namespaces[title.namespace].talk.id, title.text ) nebo nil, pokud tento titul nemůže mít diskusní stránku.
• subjectPageTitle: Stejné jako mw.title.makeTitle( mw.site.namespaces[title.namespace].subject.id, title.text ).
• redirectTarget: Vrátí objekt title cíle přesměrované stránky, pokud je stránka přesměrována a stránka existuje, jinak vrátí false.
• protectionLevels: Úrovně ochrany stránky. Toto je tabulka s klávesami odpovídajícími každé akci (např. "edit" a "move"). Hodnoty tabulky jsou pole, jejichž první položkou je řetězec obsahující úroveň ochrany. Pokud stránka není chráněna, budou buď hodnoty tabulky nebo položky pole nil. Toto je náročné.
• cascadingProtection: Kaskádové ochrany použitelné pro stránku. Toto je tabulka s klíči "restrictions" (sama tabulka s klíči jako má protectionLevels) a "sources" (pole s názvy, kde kaskáda ochran). Pokud se na stránku nehrnou žádná ochranná kaskáda, budou "restrictions" a "sources" prázdné. Toto je náročné.
• categories: (od v1.43.0-wmf.18) Seznam kategorií použitých na stránce. Toto je náročné
• subPageTitle( text ): Stejné jako mw.title.makeTitle( title.namespace, title.text .. '/' .. text ).
• partialUrl(): Vrací title.text zakódovaný tak, jako by byl v adrese URL.
• fullUrl( dotaz, proto ): Vrátí úplnou adresu URL (s volitelnou tabulkou dotazu/řetězcem) pro tento nadpis. proto lze zadat pro ovládání schématu výsledné adresy URL: "http", "https", "relativní" (výchozí) nebo "kanonické".
• localUrl( dotaz ): Vrátí místní adresu URL (s volitelnou tabulkou/řetězcem dotazu) pro tento nadpis.
• canonicalUrl( dotaz ): Vrátí kanonickou adresu URL (s volitelnou tabulkou/řetězcem dotazu) pro tento nadpis.
• content nebo getContent(): Vrátí (neanalyzovaný) obsah stránky nebo nil, pokud stránka neexistuje. Stránka bude zaznamenána jako transkluze.
• pageLang: jazykový objekt pro jazyk obsahu stránky, který je výchozím jazykem obsahu wiki. Toto je náročné.

Objekty titulků lze porovnávat pomocí relačních operátorů. tostring( title ) vrátí title.prefixedText.

Všimněte si, že přístup k jakémukoli náročnému poli na objektu title zaznamená "odkaz" na stránku (jak je ukázáno například na Special:WhatLinksHere). Pomocí metody getContent() objektu title nebo přístupu k poli redirectTarget jej zaznamenáte jako pole file nebo fileExists jej zaznamená jako "vložení souboru".

Metadata souboru

Objekty titulků představující stránku v oboru názvů Soubor nebo Média budou mít vlastnost nazvanou file. Toto je náročné. Toto je tabulka s následující strukturou:

• existuje: Zda soubor existuje. Bude zaznamenáno jako použití snímku. Vlastnost fileExists na objektu Title existuje z důvodů zpětné kompatibility a je aliasem této vlastnosti. Pokud je false, všechny ostatní vlastnosti souboru budou nil.
• width: Šířka souboru. Pokud soubor obsahuje více stránek, jedná se o šířku první stránky.
• height: Výška souboru. Pokud soubor obsahuje více stránek, jedná se o výšku první stránky.
• stránky: Pokud formát souboru podporuje více stránek, jedná se o tabulku obsahující tabulky pro každou stránku souboru; jinak je nil. Operátor # lze použít k získání počtu stránek v souboru. Každá jednotlivá tabulka stránek obsahuje vlastnost width a height.
• size: Velikost souboru v bajtech.
• mimeType: MIME typ souboru.
• length: Délka (trvání) mediálního souboru v sekundách. Nula pro typy médií, které nepodporují délku.

Vlastnosti expensive

Vlastnosti id, isRedirect, exists a contentModel vyžadují načtení dat o titulu z databáze. Z tohoto důvodu je počet expensive funkcí zvýšen při prvním přístupu k jedné z nich pro jinou než aktuální stránku. Následné přístupy k jakékoli z těchto vlastností pro danou stránku znovu nezvýší počet expensive funkcí.

Ostatní vlastnosti označené jako expensive budou vždy zvyšovat počet expensive funkcí při prvním přístupu na jinou než aktuální stránku.

Knihovna URI

mw.uri.encode

mw.uri.encode( řetěz, enctype )

Kóduje v procentech řetězec. Výchozí typ, "QUERY", kóduje mezery pomocí '+' pro použití v řetězcích dotazů. "PATH" kóduje mezery jako %20. A "WIKI" kóduje mezery jako '_'.

Všimněte si, že formát "WIKI" není zcela reverzibilní, protože mezery i podtržítka jsou kódovány jako '_'.

mw.uri.decode

mw.uri.decode( řetěz, enctype )

Procento-dekóduje řetězec. Výchozí typ, "QUERY", dekóduje '+' na mezeru. "PATH" neprovádí žádné další dekódování. A "WIKI" dekóduje '_' do prostoru.

mw.uri.anchorEncode

mw.uri.anchorEncode( řetězec )

Kóduje řetězec pro použití ve fragmentu URI MediaWiki.

mw.uri.buildQueryString

mw.uri.buildQueryString( tabulka )

Kóduje tabulku jako řetězec dotazu URI. Klíče by měly být řetězce. Hodnoty mohou být řetězce nebo čísla, sekvenční tabulky nebo logická nepravda.

mw.uri.parseQueryString

mw.uri.parseQueryString( s, i, j )

Dekóduje řetězec dotazu s do tabulky. Klíče v řetězci bez hodnot budou mít hodnotu false. Klíče opakované vícekrát budou mít jako hodnoty sekvenční tabulky. A další budou mít řetězce jako hodnoty.

Volitelné číselné argumenty i a j lze použít k určení podřetězce s, který má být analyzován, namísto celého řetězce. i je pozice prvního znaku podřetězce a výchozí hodnota je 1. j je pozice posledního znaku podřetězce a výchozí hodnota je délka řetězce. Jak i, tak j mohou být záporné, jako v string.sub.

mw.uri.canonicalUrl

mw.uri.canonicalUrl( stránka, dotaz )

Vrátí objekt URI pro kanonické URL stránky s volitelným řetězcem dotazu/tabulkou.

mw.uri.fullUrl

mw.uri.fullUrl( stránka, dotaz )

Vrátí objekt URI pro úplnou adresu URL stránky s volitelným řetězcem dotazu/tabulkou.

mw.uri.localUrl

mw.uri.localUrl( stránka, dotaz )

Vrátí objekt URI pro místní URL pro stránku s volitelným řetězcem dotazu/tabulkou.

mw.uri.new

mw.uri.new( řetězec )

Vytvoří nový objekt URI pro předaný řetězec nebo tabulku. Možná pole pro tabulku naleznete v popisu objektů URI.

mw.uri.validate

mw.uri.validate( tabulka )

Ověřuje předanou tabulku (nebo objekt URI). Vrátí logickou hodnotu označující, zda byla tabulka platná, a při selhání řetězec vysvětlující nalezené problémy.

Objekt URI

Objekt URI má následující pole, z nichž některá nebo všechna mohou být nulová:

• protocol: Řetězec protokolu/schématu
• user: Řetězec uživatele
• password: Řetězec hesla
• host: Řetězec názvu hostitle
• port: Celé číslo portu
• path: Řetězec cesyty
• query: Tabulka jako od mw.uri.parseQueryString
• fragment: Řetezec fragmentu.

K dispozici jsou také následující vlastnosti:

• userInfo: Řetězec uživatele a hesla
• hostPort: Řetězec hostitele a portu
• authority: Řetězec uživatele, hesla, hostitele a portu
• queryString: Řetězec verze tabulky dotazu
• relativePath: Řetězec cesty, řetězec dotazu a fragmentu

tostring() poskytne řetězec URI.

Metody objektu URI jsou:

mw.uri:parse

uri:parse( řetězec )

Analyzuje řetězec do aktuálního objektu URI. Jakákoli pole zadaná v řetězci budou v aktuálním objektu nahrazena. Pole, která nejsou specifikována, si zachovají své staré hodnoty.

mw.uri:clone

uri:clone()

Vytvoří kopii objektu URI.

mw.uri:extend

uri:extend( parametry )

Sloučí tabulku parametrů do tabulky dotazu objektu.

Knihovna Ustring

Knihovna Ustring je zamýšlena jako přímá reimplementace standardní String knihovny, kromě toho, že metody pracují se znaky v řetězcích kódovaných $1 spíše než s byty.

Většina funkcí vyvolá chybu, pokud řetězec není platný UTF-8. Jsou zaznamenány výjimky.

mw.ustring.maxPatternLength

Maximální povolená délka vzoru v bajtech.

mw.ustring.maxStringLength

Maximální povolená délka řetězce v bajtech.

mw.ustring.byte

mw.ustring.byte( s, i, j )

Vrátí jednotlivé bajty. Identické se string.byte().

mw.ustring.byteoffset

mw.ustring.byteoffset( s, l, i )

Vrátí bajtový posun znaku v řetězci. Výchozí hodnota pro l i i je 1. i může být záporná, v takovém případě se počítá od konce řetězce.

Znak na l == 1 je první znak začínající na nebo po bajtu i. Znak na l == 0 je první znak začínající na nebo před byte i. Všimněte si, že se může jednat o stejný znak. Větší nebo menší hodnoty l se vypočítávají vzhledem k těmto hodnotám.

mw.ustring.char

mw.ustring.char( ... )

Podobně jako string.char(), až na to, že celá čísla jsou kódové body Unicode, nikoli hodnoty bajtů.

local value = mw.ustring.char( 0x41f, 0x440, 0x438, 0x432, 0x435, 0x442, 0x21 ) -- hodnota je nyní 'Привет!'

mw.ustring.codepoint

mw.ustring.codepoint( s, i, j )

Podobně jako string.byte(), až na to, že návratové hodnoty jsou kódové body a offsety jsou znaky, nikoli bajty.

mw.ustring.find

mw.ustring.find( s, pattern, init, plain )

Podobně jako string.find(), až na to, že vzor je rozšířen tak, jak je popsáno ve vzorech Ustring a offset init je ve znacích, nikoli v bajtech.

mw.ustring.format

mw.ustring.format( formát, ... )

Identické se string.format(). Šířky a přesnosti řetězců jsou vyjádřeny v bajtech, nikoli v kódových bodech.

mw.ustring.gcodepoint

mw.ustring.gcodepoint( s, i, j )

Vrátí tři hodnoty pro iteraci přes kódové body v řetězci. Výchozí hodnota i je 1 a j je -1. Toto je určeno pro použití ve iterátoru ve formě for:

for codepoint in mw.ustring.gcodepoint( s ) do
     -- blok
end

mw.ustring.gmatch

mw.ustring.gmatch( s, pattern )

Podobně jako string.gmatch(), kromě toho, že vzor je rozšířen tak, jak je popsáno ve vzorech Ustring.

Known bug - Při použití se vzorem, který může odpovídat prázdnému řetězci, funkce uvízne v nekonečné smyčce. Například následující smyčka nikdy nekončí:

for capture in mw.ustring.gmatch( "foo bar", ".*" ) do
     -- block
end

mw.ustring.gsub

mw.ustring.gsub( s, pattern, repl, n )

Podobně jako string.gsub(), kromě toho, že vzor je rozšířen tak, jak je popsáno ve vzorech Ustring.

Známé chyby: Pokud je repl tabulka, je možné použít čísla jako klíče místo řetězců (např. pro nahrazení instancí "5" v řetězci by se použila hodnota v klíči [5] nebo ["5"]). Jako takový není výstup předvídatelný, pokud mají různé (nenulové) hodnoty. Toto není problém pro string.gsub(), který ignoruje jakákoli čísla jako klíče.

mw.ustring.isutf8

mw.ustring.isutf8( řetězec )

Vrátí true, pokud je řetězec platný UTF-8, a false, pokud platný není.

mw.ustring.len

mw.ustring.len( řetězec )

Vrátí délku řetězce v kódových bodech nebo nulu, pokud řetězec není platný UTF-8.

Viz string.len() pro podobnou funkci, která používá bajtovou délku spíše než kódové body.

mw.ustring.lower

mw.ustring.lower( řetězec )

Podobně jako string.lower(), kromě toho, že všechny znaky s definicemi malých písmen na velká v Unicode jsou převedeny.

Pokud je také načtena knihovna Language library, místo toho se zavolá lc() na výchozí jazykový objekt.

mw.ustring.match

mw.ustring.match( s, pattern, init )

Podobně jako string.match(), až na to, že vzor je rozšířen tak, jak je popsáno v Ustring vzory a offset init je ve znacích, nikoli v bajtech.

mw.ustring.rep

mw.ustring.rep( řetězec, n )

Totožné se string.rep().

mw.ustring.sub

mw.ustring.sub( s, i, j )

Podobně jako string.sub(), až na to, že offsety jsou spíše znaky než bajty.

mw.ustring.toNFC

mw.ustring.toNFC( řetězec )

Převede řetězec na Normalization Form C (také známý jako Normalization Form Canonical Composition (Normalizační forma kanonické skladby)). Vrátí nulu, pokud řetězec není platný 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.

Vzory Ustring

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.

Stejně jako ve vzorech knihovny String zde %A, %C, %D, %L, %P, %S, %U, %W a %X představuje komplementární sadu ("všechny znaky bez dané obecné kategorie").

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.

Známá omezení: Na rozdíl od vzorů knihovny String mají vzory knihovny Ustring maximální délku 10 000 bajtů. Pokud vzor překročí tuto délku, funkce Ustring vyvolá chybu. Protože knihovna String má své vlastní maximum 32 záchytů (na rozdíl od knihovny Ustring), není možné použít vzor, ​​který překračuje oba limity, protože bude nekompatibilní s oběma knihovnami.

Poznámka: 9 znaků ASCII, $', +, <, =, > ', ^, `, |, ~, mohou odpovídat %p v knihovně String, ale ne v knihovně Ustring, protože Unicode je spíše klasifikuje jako symboly než interpunkci.

Načítatelné knihovny

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.

Pokud jsou zadány nulové argumenty, výsledek má nastaveny všechny bity.

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.

Pokud jsou zadány nulové argumenty, výsledek má všechny bity čisté.

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.

Pokud jsou zadány nulové argumenty, výsledek má všechny bity čisté.

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

Tato knihovna obsahuje metody užitečné při implementaci knihoven Scriunto. Může být načtena pomocí:

 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.

Toto je pro argumenty, které mají více než jeden platný typ.

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.

Tato funkce bude obecně použita ve funkci konstruktoru knihovny, něco takového:

 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.

Knihovny rozšíření

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 (psaní knihoven Scribunto) poskytuje informace o tom, jak mohou být takové knihovny vyvinuty, aby poskytovaly rozhraní Lua pro rozšíření MediaWiki.

mw.wikibase

Wikibase Client poskytuje přístup k lokalizovatelným strukturovaným datům, zejména Wikidata. Viz docs_topics_lua.html a Rozšíření:Wikibase Client/Lua .

mw.wikibase.lexeme

WikibaseLexeme provides access to Wikibase Lexeme entities. This is supported by Wikidata:Lexicographical data. Viz md_docs_2topics_2lua.html a Extension:WikibaseLexeme/Lua .

mw.wikibase.mediainfo

WikibaseMediaInfo poskytuje přístup k entitám Wikibase MediaInfo. Podívejte se na stránku WikibaseMediaInfo/Lua . Toto je podporováno Structured Data on Commons. Viz Strukturovaná 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 poskytuje nativní podporu Scribunto pro rozšíření Semantic MediaWiki .

mw.ext.data

JsonConfig poskytuje přístup k lokalizovatelným tabulkovým a mapovým datům. Podívejte se na stránku JsonConfig/Tabular . Tabular Data a GeoJSON Map Data jsou podporovány ve jmenném prostoru "Data:" na Commons.

• mw.ext.data.get( pagename )

mw.ext.cargo

Cargo poskytuje prostředek k dotazování na úložiště dat z Lua. Viz Extension:Cargo/Other features#Lua support (Rozšíření:Náklad/Další funkce#Lua support).

mw.ext.cattools

CategoryToolbox poskytuje způsob, jak z Lua zkontrolovat, zda určitá stránka patří do kategorie. Je to experimentální a není povoleno na veřejných wikinách WikiMedia.

mw.ext.FlaggedRevs

FlaggedRevs poskytuje prostředek pro přístup k nastavení stability stránky z Lua.

mw.ext.TitleBlacklist

TitleBlacklist poskytuje prostředek k testování a získávání informací o položkách s názvy stránek na černé listině od Lua.

mw.ext.ParserFunctions

ParserFunctions poskytuje prostředek od Lua k vyhodnocení výrazů stejným způsobem jako jeho funkce analyzátoru založená na PHP #expr .

mw.ext.proofreadPage

Proofread Page poskytuje přístup k jmenným prostorům Index a Page. Podívejte se na stránku Extension:Proofread Page/Lua reference . This is supported by Wikisource:ProofreadPage. Podívejte se na stránku Help:Extension:ProofreadPage .

mw.ext.articlePlaceholder

ArticlePlaceholder poskytuje prostředek k přepsání výchozího vykreslování Wikibase z Lua. Podívejte se na stránku Extension:ArticlePlaceholder/Module:AboutTopic .

mw.ext.externalData

ExternalData poskytuje prostředek k získání strukturovaných dat z internetu od Lua. Podívejte se na stránku Extension:External Data/Lua .

mw.ext.UnlinkedWikibase

Podívejte se na 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)

Rozdíly od standardní Lua

Změněné funkce

Následující funkce byly upraveny:

setfenv()

getfenv()

V závislosti na konfiguraci nemusí být k dispozici. Pokud jsou k dispozici, pokusy o přístup k nadřazeným prostředím selžou.

getmetatable()

Funguje pouze na tabulkách, aby se zabránilo neoprávněnému přístupu k nadřazeným prostředím.

tostring()

Adresy ukazatelů tabulek a funkcí nejsou poskytovány. Důvodem je ztížení zneužití zranitelnosti poškození paměti.

pairs()

ipairs()

Support for the __pairs and __ipairs metamethods (added in Lua 5.2) has been added.

pcall()

xpcall()

Některé vnitřní chyby nelze zachytit.

require()

Může načíst určité vestavěné moduly distribuované se Scriunto, stejně jako moduly přítomné v jmenném prostoru modulu na wiki. Chcete-li načíst moduly wiki, použijte celý název stránky včetně jmenného prostoru. Nelze přistupovat jinak k místnímu souborovému systému.

Odebrané funkce a balíčky

Následující balíčky jsou většinou odstraněny. Dostupné jsou pouze tyto funkce:

package.*

Přístup do souborového systému a knihovny C byl odebrán. Dostupné funkce a tabulky jsou:

package.loaded

package.preload

package.loaders

Zavaděče, které přistupují k místnímu souborovému systému nebo načítají C knihovny, nejsou přítomny. 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.

{{mbox | type = notice | image = none | text =

Copyright © 1994–2012 Lua.org, PUC-Rio.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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