Extension:Scribunto/Lua reference manual
Tato příručka je založena na rozšíření Lua . Některé části jsou odvozeny z Lua 5.1 referenčního manuálu, který je dostupný pod MIT licencí.
Tato stránka dokumentuje nejnovější verzi rozšíření Scribunto. Některé funkce ještě nemusí být nasazeny. |
Úvod
Začínáme
Na wiki MediaWiki s povoleným Scribunto vytvořte stránku s názvem začínajícím na Module:
, například "Module:Bananas".
Na tuto novou stránku zkopírujte následující text:
local p = {} --p znamená balíček
function p.hello( frame )
return "Hello, world!"
end
return p
Uložte to a poté na jinou (nemodulovou) stránku, jako na sandbox page, napište:
{{#invoke:Bananas|hello}}
Až na to, že byste měli nahradit "Bananas" jakkoli, co jste nazvali modul. To zavolá funkci "hello" exportovanou z tohoto modulu. {{#invoke:Bananas|hello}}
bude nahrazeno textem, který funkce vrátila, v tomto případě "Hello, world!"
Obecně je dobré vyvolat kód Lua z kontextu šablony. To znamená, že z pohledu volající stránky je syntaxe nezávislá na tom, zda je logika šablony implementována v Lua nebo ve wikitextu. Také se vyhne zavedení další složité syntaxe do jmenného prostoru obsahu wiki.
Struktura modulu
Samotný modul musí vrátit tabulku Lua obsahující funkce, které může {{#invoke:}}
volat.
Obecně, jak je uvedeno výše, je deklarována lokální proměnná obsahující tabulku, funkce jsou přidány do této tabulky a tabulka je vrácena na konec kódu modulu.
Jakékoli funkce, které nejsou přidány do této tabulky, ať už lokální nebo globální, nebudou přístupné pro {{#invoke:}}
, ale globální mohou být přístupné z jiných modulů načtených pomocí require()
.
Obecně je dobrým stylem modulu deklarovat všechny funkce a proměnné jako místní.
Přístup k parametrům z wikitextu
Funkce volané {{#invoke:}}
budou předány jediným parametrem, kterým je frame objekt. Pro přístup k parametrům předávaným do {{#invoke:}}
bude kód obvykle používat tabulku args
daného objektu frame. Je také možné přistupovat k parametrům předávaným do šablony obsahující {{#invoke:}}
pomocí frame:getParent()
a přístupu k args
daného frame.
Tento objekt frame se také používá pro přístup ke kontextově specifickým funkcím analyzátoru wikitextu, jako je volání funkcí analyzátoru, rozšiřující šablony a rozšiřování libovolných řetězců wikitextu .
Vracející se text
Funkce modulu by měla obvykle vracet jeden řetězec; jakékoli vrácené hodnoty budou předány přes tostring() a poté zřetězeny bez oddělovače. Tento řetězec je začleněn do wikitextu jako výsledek {{#invoke:}}
.
V tomto okamžiku analýzy stránky již byly šablony rozšířeny, funkce analyzátoru a značky rozšíření již byly zpracovány a pre-save transforms (tj. už se stalo). Modul proto nemůže tyto funkce použít ve svém výstupním textu. Pokud například modul vrátí "Hello, [[world]]! {{welcome}}"
, stránka bude číst "Hello, world! {{welcome}}".
Na druhou stranu subst je zpracováno v dřívější fázi zpracování, takže s {{subst:#invoke:}}
budou zpracovány pouze další pokusy o substituci. Protože neúspěšné nahrazení zůstane ve wikitextu, bude poté zpracováno při další úpravě. Tomu je třeba se obecně vyhnout.
Dokumentace modulu
Scribunto umožňuje dokumentaci modulů automatickým přidružením modulu k dokumentační stránce wikitextu. Ve výchozím nastavení se pro tento účel používá podstránka modulu "/doc" a je umístěna nad zdrojovým kódem modulu na stránce modulu. Například dokumentace pro "Module:Bananas" by byla na "Module:Bananas/doc".
To lze nakonfigurovat pomocí stránky Nápověda:Systémová zprá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.
Chcete-li ručně vytvořit přesměrování modulu, použijte následující syntaxi:
return require [[Module:Foo]]
Nahraďte Foo
názvem modulu, na který chcete přesměrovat.
Jazyk Lua
Tokeny
Jméno (nazývané také identifikátor) v Lua může být libovolný řetězec písmen, číslic a podtržítek, který nezačíná číslicí. V názvech se rozlišují velká a malá písmena; "foo", "Foo" a "FOO" jsou různá jména.
Následující klíčová slova jsou vyhrazena a nelze je použít jako názvy:
and
break
do
else
elseif
end
false
for
function
if
in
local
nil
not
or
repeat
return
then
true
until
while
Názvy začínající podtržítkem následovaným velkými písmeny jsou vyhrazeny pro interní globální proměnné Lua.
Další tokeny jsou:
#
%
(
)
*
+
,
-
--
.
..
...
/
:
;
<
<=
=
==
>
>=
[
]
^
{
}
~=
Komentáře
Komentář začíná znakem --
kdekoli mimo řetězec. Pokud za --
bezprostředně následuje úvodní dlouhá závorka, komentář pokračuje do odpovídající uzavírací dlouhé závorky. Jinak komentář běží na konec aktuálního řádku.
-- Komentář v Lua začíná dvojitou pomlčkou a běží na konec řádku.
--[[ Víceřádkové řetězce a komentáře
jsou ohraničeny dvojitými hranatými závorkami. ]]
--[=[ Komentáře jako tento mohou mít vnořené další ---[[komentáře]]. ]=]
--[==[ Komentáře jako tento mohou mít i jiné
--[===[ dlouhé --[=[komentáře]=] --vnořené
]===] vícekrát, i když jsou všechny
--[[ neohraničeny odpovídajícími dlouhými závorkami! ]===]
]==]
Datové typy
Lua je dynamicky typovaný jazyk, což znamená, že proměnné a argumenty funkcí nemají žádný typ, pouze hodnoty, které jsou jim přiřazeny. Všechny hodnoty nesou typ.
Lua má osm základních datových typů, avšak pouze šest je relevantních pro rozšíření Scribunto. Funkce type()
vrátí typ hodnoty.
Funkce tostring()
převede hodnotu na řetězec. Funkce tonumber()
převede hodnotu na číslo, pokud je to možné, a jinak vrátí nulu. Neexistují žádné explicitní funkce pro převod hodnoty na jiné datové typy.
Čísla jsou automaticky převedena na řetězce při použití tam, kde se očekává řetězec, např. při použití s operátorem zřetězení. Řetězce rozpoznávané funkcí tonumber()
jsou automaticky převedeny na čísla při použití s aritmetickými operátory. Když se očekává logická hodnota, všechny hodnoty kromě nula a false jsou považovány za pravdivé.
nil
"nil"
je datový typ nil
, který představuje absenci hodnoty.
Nil nelze použít jako klíč v tabulce a není žádný rozdíl mezi nepřiřazeným klíčem tabulky a klíčem, kterému je přiřazena nulová hodnota.
Při převodu na řetězec je výsledek "nil"
. Při převodu na booleovskou hodnotu je nil považováno za nepravdivé.
Poznámka: Lua v některých omezených situacích rozlišuje mezi nil
a vůbec ničím.
Například tostring(nil)
vrátí "nil"
, ale tostring()
vyvolá chybu, protože první parametr je povinný.
Toto rozlišení je zvláště důležité pro funkci select().
boolean
Booleovské hodnoty jsou true
a false
.
Při převodu na řetězec je výsledek "true"
nebo "false"
.
Na rozdíl od mnoha jiných jazyků nemusí být booleovské hodnoty přímo převedeny na čísla. A na rozdíl od mnoha jiných jazyků, pouze false
a nul jsou považovány za false pro booleovskou konverzi. Číslo 0 a prázdný řetězec se považují za pravdivé.
řetězec
Lua řetězce jsou považovány za sérii 8bitových bajtů. Je na aplikaci, aby je interpretovala v jakémkoli konkrétním kódování.
Řetězcové literály mohou být odděleny buď jednoduchými nebo dvojitými uvozovkami ('
nebo "
). Jako JavaScript a na rozdíl od PHP mezi nimi není žádný rozdíl. Jsou rozpoznány následující sekvence escape:
\a
(zvonek, byte 7)\b
(backspace, byte 8)\t
(horizontální tab, byte 9)\n
(nový řádek, byte 10)\v
(vertikální tab, byte 11)\f
(form feed, byte 12)\r
(carriage return, byte 13)\"
(double quote, byte 34)\'
(single quote, byte 39)\\
(backslash, byte 92)
Doslovný nový řádek může být také zahrnut do řetězce tak, že jej předchází zpětné lomítko. Bajty lze také zadat pomocí escape sekvence '\ddd', kde ddd je desetinná hodnota bajtu v rozsahu 0–255. Chcete-li zahrnout znaky Unicode pomocí sekvencí escape, musí být specifikovány jednotlivé bajty pro kódování UTF-8. Obecně bude jednodušší zadávat znaky Unicode přímo.
Doslovné řetězce lze také definovat pomocí dlouhých závorek.
Úvodní dlouhá závorka se skládá z otevírací hranaté závorky následované nulou nebo více stejnými znaménky, za nimiž následuje další otevírací hranatá závorka, např. [[
, [=[
nebo [=====[
.
Otevírací dlouhá závorka musí odpovídat odpovídající zavírací dlouhé závorce, např. ]]
, ]=]
nebo ]=====]
.
Ve speciálním případě, pokud je po úvodní dlouhé závorce bezprostředně následován nový řádek, nový řádek není zahrnut do řetězce, ale nový řádek těsně před uzavírací dlouhou závorkou je zachován.
Řetězce oddělené dlouhými závorkami neinterpretují escape sekvence.
-- dlouhý řetězec
foo = [[
bar\tbaz
]]
-- je ekvivalentní tomuto řetězci oddělenému uvozovkami
foo = 'bar\\tbaz\n'
Všimněte si, že všechny řetězce jsou považovány za pravdivé, když jsou převedeny na booleovské. To je na rozdíl od většiny ostatních jazyků, kde je prázdný řetězec obvykle považován za nepravdivý.
číslo
Lua má pouze jeden číselný typ, který je obvykle interně reprezentován jako 64bitová hodnota s plovoucí desetinnou čárkou s dvojitou přesností. V tomto formátu mohou být celá čísla mezi -9007199254740991
(-253 + 1) a 9007199254740991
(253 - 1) reprezentována přesně. Větší čísla a čísla se zlomkovou částí mohou trpět zaokrouhlovací chybou.
Číselné konstanty se zadávají pomocí tečky (.
) jako oddělovač desetinných míst a bez oddělovačů seskupení, např. 123456.78
.
Čísla mohou být také reprezentována pomocí E notace bez mezer, např. 1.23e-10
e-10, 1.23e-10
e20 nebo 1.23e-10
e5.
Celá čísla mohou být také specifikována v hexadecimálním zápisu pomocí předpony 0x
, např. 0x3A
.
S malým počtem číselných hodnot se zachází zvláštním způsobem:
- Kladné a záporné nekonečno, které jsou vyhodnoceny jako větší nebo menší než každé jiné číslo (kromě NaN - viz níže). Lze k nim přistupovat dvěma způsoby: prostřednictvím knihovny
math
, jakomath.huge
a-math.huge
, nebo pomocí numerických operací jako1/0
a-1/0
. - Lua občas rozlišuje
0
a-0
(více informací o nulách se znaménkem viz IEEE 754).0
a-0
jsou přísně ekvivalentní pro téměř všechny účely, ale chovají se odlišně v malém počtu numerických operací (např.1/0
vrátí nekonečno , zatímco1/-0
vrací záporné nekonečno). Rozdíl také ovlivňuje převody z čísla na řetězec (a naopak). - Pozitivní a negativní NaN (znamenající Not a Number). Žádná konstanta není poskytnuta pro žádnou z nich, ale
0/0
se vyhodnotí jako negativní NaN. Všimněte si, že obě NaN mají jedinečnou kvalitu, kterou jakékoli srovnání, které je zahrnuje, vyhodnotí jakofalse
(což znamená, že se ani nevyhodnotí jako sobě rovné). Jediný praktický rozdíl mezi těmito dvěma je převod typu do az řetězce (viz níže).
Všimněte si, že všechna čísla (včetně 0
, -0
, nekonečna a NaN) jsou při převodu na booleovské hodnoty považována za pravdivá. To je na rozdíl od většiny ostatních jazyků, kde se 0
obvykle považuje za nepravdu. Při převodu na řetězec jsou konečná čísla reprezentována v desítkové soustavě a zápisu E, pokud je 1014 nebo větší (např. "1e+14"
); nekonečna jsou "inf"
a "-inf"
; a NaN jsou "nan"
a "-nan"
.
Známá chyba: interpret Lua bude se všemi výskyty 0
a -0
zacházet jako s tím, který z nich narazí jako první když je skript zkompilován, což znamená, že návratové hodnoty tostring(0)
, 1/-0
(a tak dále) jsou ovlivněny tím, kde se v kódu vyskytují.
To může způsobit neočekávané výsledky, zejména pokud jsou všechny instance 0
při návratu převedeny na "-0"
.
V případě potřeby to lze obejít vygenerováním nulových hodnot pomocí tonumber("0")
a tonumber("-0")
, které zřejmě nezpůsobují ani nejsou ovlivněny problém. Viz [1].
tabulka
Tabulky Lua jsou asociativní pole, podobně jako pole PHP a objekty JavaScriptu.
Tabulky se vytvářejí pomocí složených závorek. Prázdná tabulka je {}
. Pro naplnění polí při vytváření může být do složených závorek zahrnut seznam specifikátorů polí oddělených čárkou nebo středníkem. Mohou mít několik podob:
[expression1] = expression2
používá (první) hodnotu expression1 jako klíč a (první) hodnotu[expression1] = expression2
jako hodnotu.- $4 odpovídá $5
- $6 je zhruba ekvivalentní $7, kde $8 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í.
name = expression
is equivalent to["name"] = expression
expression
is roughly equivalent to[i] = expression
, where i is an integer starting at 1 and incrementing with each field specification of this form. If this is the last field specifier and the expression has multiple values, all values are used; otherwise only the first is kept.
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ří:
Poznámka: V Lua všechny řetězce také sdílejí jednu metatabulku, ve které __index
odkazuje na string
tabulku. Tato metatabulka není ve Scribuntu přístupná, stejně jako odkazovaná tabulka string
. Tabulka řetězců dostupná pro moduly je kopií.
Proměnné
Proměnné jsou místa, která uchovávají hodnoty. V Lua jsou tři druhy proměnných: globální proměnné, lokální proměnné a pole tabulky.
Jméno představuje globální nebo lokální proměnnou (nebo argument funkce, což je jen druh lokální proměnné). Předpokládá se, že proměnné jsou globální, pokud nejsou explicitně deklarovány jako lokální pomocí klíčového slova local
. Každá proměnná, které nebyla přiřazena žádná hodnota, je považována za nulovou.
Globální proměnné jsou uloženy ve standardní Lua tabulce zvané environment (prostředí). Tato tabulka je často dostupná jako globální proměnná _G
. Pro tuto tabulku globálních proměnných je možné nastavit metatabulku. Metametody __index a __newindex budou volány pro přístupy a přiřazení ke globálním proměnným stejně jako pro přístupy a přiřazení k polím v jakékoli jiné tabulce.
K prostředí pro funkci lze přistupovat pomocí funkce getfenv() a měnit pomocí funkce setfenv(). Ve Scribuntu jsou tyto funkce přísně omezeny, pokud jsou vůbec dostupné.
Lokální proměnné jsou lexikálně vymezeny. Podrobnosti naleznete na stránce Deklarace místních proměnných.
Výrazy
Výraz je něco, co má hodnoty: literály (čísla, řetězce, pravda, nepravda, nula), anonymní deklarace funkcí, konstruktory tabulek, odkazy na proměnné, volání funkcí, výraz vararg, zabalené výrazy v závorkách, unární operátory aplikované na výrazy a výrazy kombinované s binárními operátory.
Většina výrazů má jednu hodnotu. Volání funkcí a výraz vararg může mít libovolné číslo. Všimněte si, že zabalením volání funkce nebo výrazu vararg do závorek ztratíte všechny kromě první hodnoty.
Seznamy výrazů jsou seznamy výrazů oddělených čárkami. Všechny kromě posledního výrazu jsou nuceny na jednu hodnotu (vypuštění dalších hodnot nebo použití nuly, pokud výraz nemá žádné hodnoty). Všechny hodnoty z posledního výrazu jsou zahrnuty do hodnot seznamu výrazů.
Aritmetické operátory
Lua podporuje obvyklé aritmetické operátory: sčítání, odčítání, násobení, dělení, modul, umocňování a negace.
Když jsou všechny operandy čísla nebo řetězce, pro které tonumber() vrací nenulovou hodnotu, mají operace svůj obvyklý význam.
Pokud je některým z operandů tabulka s vhodnou metamethodou, bude zavolána metametoda.
Operátor | Funkce | Příklad | Metametoda | Poznámky |
---|---|---|---|---|
+ | Addition | a + b | __add | |
- | Subtraction | a - b | __sub | |
* | Multiplication | a * b | __mul | |
/ | Division | a / b | __div | dělení nulou není chyba; NaN nebo nekonečno bude vráceno |
% | Modulo | a % b | __mod | definované jako a % b == a - math.floor( a / b ) * b
|
^ | Exponentiation | a ^ b | __pow | jsou povoleny neceločíselné exponenty |
- | Negation | -a | __unm |
Relační operátory
Relační operátory v Lua jsou ==
, ~=
, <
, >
, <=
a >=
. Výsledkem relačního operátoru je vždy logická hodnota.
Rovnost (==
) nejprve porovná typy svých operandů. Pokud se liší, výsledek je nepravdivý. Poté porovná hodnoty: nula, boolean, číslo a řetězec jsou porovnány očekávaným způsobem. Funkce jsou stejné, pokud odkazují na přesně stejný funkční objekt. function() end == function() end
vrátí false, protože porovnává dvě různé anonymní funkce. Tabulky jsou standardně porovnávány stejným způsobem, ale to lze změnit pomocí __eq metametody.
Nerovnost (~=
) je přesnou negací rovnosti.
Pro operátory řazení platí, že pokud jsou oba čísla nebo oba řetězce, jsou porovnány přímo. Dále se zkontrolují metametody:
a < b
používá__lt
a <= b
používá__le
, pokud je k dispozici, nebo pokud je k dispozici__lt
, považuje se za ekvivalentní nanot ( b < a )
a > b
je považováno za ekvivalentníb < a
a >= b
je považováno za ekvivalentníb <= a
Pokud potřebné metametody nejsou k dispozici, dojde k chybě.
Logické operátory
Logické operátory jsou and
, or
a not
. Všechny používají standardní výklad, kde nula a nepravda jsou považovány za nepravdivé a cokoli jiného je považováno za pravdivé.
Pro and
, pokud je levý operand považován za nepravdivý, pak je vrácen a druhý operand není vyhodnocen. Jinak je vrácen druhý operand.
Pro or
, pokud je levý operand považován za pravdivý, pak je vrácen a druhý operand není vyhodnocen. Jinak je vrácen druhý operand.
Pro not
je výsledek vždy pravdivý nebo nepravdivý.
Všimněte si, že and
a or
zkratují. Například foo() or bar()
zavolá bar()
pouze v případě, že foo()
vrací false nebo nil jako svou první hodnotu.
Operátor zřetězení
Operátor zřetězení jsou dvě tečky, používané jako a .. b
. Pokud jsou oba operandy čísla nebo řetězce, jsou převedeny na řetězce a zřetězeny. Jinak, pokud je k dispozici __concat metamethod, použije se. V opačném případě se objeví chyba.
Všimněte si, že řetězce Lua jsou neměnné a Lua neposkytuje žádný druh "tvůrce řetězců", takže smyčka, která opakovaně dělá a = a .. b
, bude muset vytvořte nový řetězec pro každou iteraci a případně staré řetězce posbírat. Pokud mnoho řetězců potřebuje zřetězení, může být rychlejší použít string.format() nebo vložit všechny řetězce do sekvence a použít na konci table.concat().
Operátor délky
Operátor délky je #
, používá se jako #a
. Pokud je a
řetězec, vrátí délku v bajtech. Pokud a
je tabulka sekvence, vrátí délku sekvence.
Pokud a
je tabulka, která není sekvencí, může #a
vrátit 0 nebo jakoukoli hodnotu N, takže [N] není nula a [N+1] je nula, i když u vyšších indexů existují nenulové hodnoty. Například,
-- Toto není posloupnost, protože a[3] je nula a a[4] není.
a = { 1, 2, nil, 4 }
-- To může mít výstup 2 nebo 4.
-- A to se může změnit, i když se tabulka nezmění.
mw.log( #a )
Přednost operátora
Priorita operátora Lua nebo pořadí operací, od nejvyšší po nejnižší:
^
not
#
-
(negace)*
/
%
+
-
(odčítání)..
<
>
<=
>=
~=
==
and
or
V rámci úrovně priority je většina binárních operátorů asociativních vlevo, tj. a / b / c
je interpretováno jako (a / b) / c
. Umocňování a zřetězení jsou asociativní vpravo, tj. a ^ b ^ c
se interpretuje jako a ^ (b ^ c)
.
Volání funkcí
Volání funkcí Lua vypadá jako ve většině ostatních jazyků: Název následovaný seznamem argumentů v závorkách:
func( seznam-výrazů )
Jak je obvyklé u seznamů výrazů v Lua, poslední výraz v seznamu může poskytnout více hodnot argumentů.
Pokud je funkce volána s menším počtem hodnot v seznamu výrazů, než je argumentů v definici funkce, budou mít další argumenty nulovou hodnotu. Pokud seznam výrazů obsahuje více hodnot, než je argumentů, nadbytečné hodnoty se zahodí. Je také možné, aby funkce přijala proměnný počet argumentů. Podrobnosti naleznete na stránce Deklarace funkcí.
Lua také umožňuje přímé volání návratové hodnoty funkce, tj. func()()
. Pokud je k určení funkce, která má být volána, zapotřebí výraz složitější než proměnný přístup, lze místo proměnného přístupu použít výraz v závorkách.
Lua má syntaktický sugar pro dva běžné případy. První je, když je tabulka používána jako objekt a funkce má být volána jako metoda na objektu. Syntaxe
table:name( seznam-výrazů )
je přesně ekvivalentní
table.name( table, seznam-výrazů )
Druhým běžným případem je Luaova metoda implementace pojmenování argumentů předáním tabulky obsahující mapování jména na hodnotu jako jediného pozičního argumentu do funkce. V tomto případě mohou být závorky kolem seznamu argumentů vynechány. To také funguje, pokud má být funkci předán jeden doslovný řetězec. Například volání
func{ arg1 = exp, arg2 = exp } func"string"
jsou ekvivalentní s
func( { arg1 = exp, arg2 = exp } ) func( "string" )
Tyto mohou být kombinovány. Následující volání jsou ekvivalentní:
table:name{ arg1 = exp, arg2 = exp } table.name( table, { arg1 = exp, arg2 = exp } )
Deklarace funkcí
Syntaxe deklarace funkce vypadá takto:
function nameoptional ( var-listoptional )
blok
end
Všechny proměnné ve var-list (seznam proměnných) jsou pro funkci lokální, s hodnotami přiřazenými ze seznamu výrazů ve volání funkce. Uvnitř bloku mohou být deklarovány další lokální proměnné.
Když je funkce volána, příkazy v bloku jsou provedeny poté, co jsou vytvořeny lokální proměnné odpovídající var-listu a přiřazeny hodnoty. Pokud je dosaženo příkazu return, blok se opustí a hodnoty výrazu volání funkce jsou hodnoty dané příkazem return. Pokud provádění dosáhne konce bloku funkce, aniž by narazilo na příkaz return, bude mít výsledek výrazu volání funkce nulové hodnoty.
Funkce Lua jsou lexikální uzávěry. Běžným idiomem je deklarovat "soukromé statické" proměnné jako místní v rozsahu, kde je funkce deklarována. Například,
-- To vrátí funkci, která ke svému argumentu přidá číslo
function makeAdder( n )
return function( x )
-- Proměnná n z vnějšího rozsahu je zde k dispozici pro přidání k x
return x + n
end
end
local add5 = makeAdder( 5 )
mw.log( add5( 6 ) )
-- tiskne 11
Funkce může být deklarována tak, aby přijímala proměnný počet argumentů, zadáním ...
jako poslední položku ve var-listu:
V rámci bloku lze použít varargs výraz ...
, jehož výsledkem jsou všechny hodnoty navíc ve volání funkce. Například,
local join = function ( separator, ... )
-- získat další argumenty jako novou tabulku
local args = { ... }
-- získat počet argumentů navíc, správně
local n = select( '#', ... )
return table.concat( args, separator, 1, n )
end
join( ', ', 'foo', 'bar', 'baz' )
-- vrátí řetězec "foo, bar, baz"
Funkce select() je navržena pro práci s výrazem varargs. Konkrétně by měl být použit select( '#', ... )
namísto #{ ... }
, abyste spočítali počet hodnot ve výrazu varargs, protože { ... }
nemusí být [[#sequence|sekvence] ].
Lua poskytuje syntaktický sugar pro kombinaci deklarace funkce a přiřazení k proměnné. Podrobnosti najdete na stránce Prohlášení deklarace funkce.
Všimněte si, že to nebude fungovat:
local factorial = function ( n )
if n <= 2 then
return n
else
return n * factorial( n - 1 )
end
end
Protože deklarace funkce je zpracována před dokončením příkazu přiřazení lokální proměnné, "faktoriální" uvnitř těla funkce odkazuje na (pravděpodobně nedefinovanou) proměnnou tohoto jména ve vnějším rozsahu. Tomuto problému se lze vyhnout tak, že nejprve deklarujete lokální proměnnou a poté ji přiřadíte v následujícím příkazu, nebo použijete syntaxi deklarace funkce.
Výroky
Příkaz je základní jednotkou provádění: jedno přiřazení, řídicí struktura, volání funkce, deklarace proměnné atd.
Chunk (kus) je posloupnost příkazů, volitelně oddělená středníky. Blok je v podstatě považován za tělo anonymní funkce, takže může deklarovat lokální proměnné, přijímat argumenty a vracet hodnoty.
Blok je také posloupnost příkazů, stejně jako kus. Blok lze oddělit a vytvořit tak jeden příkaz: do block end
. Ty lze použít k omezení rozsahu lokálních proměnných nebo k přidání return
nebo break
uprostřed jiného bloku.
Zadání
seznam-proměnných = seznam-výrazů
variable-list je seznam proměnných oddělených čárkami. expression-list je čárkami oddělený seznam jednoho nebo více výrazů. Všechny výrazy jsou vyhodnoceny před provedením jakéhokoli přiřazení, takže a, b = b, a
zamění hodnoty a a b.
Deklarace lokálních proměnných
local seznam-proměnných
local seznam-proměnných = seznam-výrazů
Lokální proměnné mohou být deklarovány kdekoli v bloku nebo kusu. První formulář bez seznamu výrazů deklaruje proměnné, ale nepřiřazuje hodnotu, takže všechny proměnné mají hodnotu nula. Druhý formulář přiřazuje hodnoty lokálním proměnným, jak je popsáno v Úkolech výše.
Všimněte si, že viditelnost lokální proměnné začíná příkazem po deklaraci lokální proměnné. Takže deklarace jako local x = x
deklaruje lokální proměnnou x a přiřadí jí hodnotu x z vnějšího rozsahu. Lokální proměnná zůstává v rozsahu až do konce nejvnitřnějšího bloku obsahujícího deklaraci lokální proměnné.
Struktury kontroly
while výraz do blok end
Příkaz while opakuje blok, dokud je výraz vyhodnocen jako pravdivá hodnota.
repeat blok until výraz
Příkaz repeat opakuje blok, dokud se výraz nevyhodnotí jako pravdivá hodnota. Ve výrazu lze přistupovat k lokálním proměnným deklarovaným uvnitř bloku.
for name = exp1, exp2, exp3 do blok end
for name = exp1, exp2 do blok end
Tato první forma cyklu for deklaruje lokální proměnnou a opakuje blok pro hodnoty od exp1 do exp2 přidáním exp3 při každé iteraci. Všimněte si, že exp3 může být úplně vynecháno, v takovém případě se použije 1, ale nečíselné hodnoty jako nil
a false
jsou chybou. Všechny výrazy jsou vyhodnoceny jednou před spuštěním cyklu.
Tato forma cyklu for je zhruba ekvivalentní
do
local var, limit, step = tonumber( exp1 ), tonumber( exp2 ), tonumber( exp3 )
if not ( var and limit and step ) then
error()
end
while ( step > 0 and var <= limit ) or ( step <= 0 and var >= limit ) do
local name = var
block
var = var + step
end
end
kromě toho, že proměnné var, limit a step nejsou dostupné nikde jinde. Všimněte si, že proměnná name je pro daný blok lokální. Chcete-li použít hodnotu za smyčkou, musí být zkopírována do proměnné deklarované mimo smyčku.
for seznam-proměnných in seznam-výrazů do blok end
Druhá forma cyklu for pracuje s funkcemi iterátor. Stejně jako v prvním formuláři je seznam-výrazů vyhodnocen pouze jednou před začátkem cyklu.
Tato forma cyklu for je zhruba ekvivalentní
do
local func, static, var = expression-list
while true do
local var-list = func( static, var )
var = var1 -- ''var1'' je první proměnná v ''seznamu-proměnných''
if var == nil then
break
end
block
end
end
kromě toho, že opět proměnné func, static a var nejsou dostupné nikde jinde. Všimněte si, že proměnné v var-list jsou pro daný blok lokální; chcete-li je použít po cyklu, musí být zkopírovány do proměnných deklarovaných mimo cyklus.
Seznam výrazů je často volání jediné funkce, která vrací tři hodnoty. Pokud lze funkci iterátoru zapsat tak, že závisí pouze na parametrech, které jsou do ní předány, bylo by to nejúčinnější. Pokud ne, programování v Lua navrhuje, aby se upřednostňovalo uzavření před vrácením tabulky jako statické proměnné a aktualizací jejích členů při každé iteraci.
if exp1 then block1 elseif exp2 then block2 else block3 end
Provede block1, pokud exp1 vrátí true, jinak provede block2, pokud exp2 vrátí true, a block3 jinak. Část else block3
může být vynechána a část elseif exp2 then block2
může být podle potřeby opakována nebo vynechána.
return seznam-výrazů
Příkaz return se používá k vrácení hodnot z funkce nebo chunk (což je pouze funkce). Seznam-výrazů je čárkami oddělený seznam nula nebo více výrazů.
Lua implementuje volání tail: Pokud výraz-seznam obsahuje přesně jeden výraz, který je voláním funkce, bude pro volání této funkce znovu použit aktuální zásobníkový rámec. To má důsledky pro funkce, které se zabývají zásobníkem volání, jako je getfenv()
a debug.traceback()
.
Příkaz return musí být posledním příkazem v jeho bloku. Pokud je z nějakého důvodu potřeba návrat uprostřed bloku, lze použít explicitní blok do return end
.
break
Příkaz break se používá k ukončení provádění cyklu while, repeat nebo for, přičemž se přeskočí na další příkaz následující po cyklu.
Příkaz break musí být posledním příkazem v jeho bloku. Pokud je z nějakého důvodu potřeba přerušení uprostřed bloku, lze použít explicitní blok do break end
.
Na rozdíl od některých jiných jazyků nemá Lua pro cykly příkaz "continue" (tj. příkaz pro přechod na další iteraci bez úplného přerušení smyčky).
Je přímočaré dosáhnout stejného efektu vnořením bloku repeat ... until true
přímo do hlavní smyčky, která se bude opakovat pouze jednou pro každou iteraci hlavní smyčky (jelikož podmínka je vždy pravdivá).
Použití break
pouze ukončí vnitřní smyčku, což má praktický účinek, že hlavní smyčka bude pokračovat v další iteraci.
Pokud je nutné použít break
v hlavní smyčce, jednoduše deklarujte proměnnou, která je kontrolována pokaždé, když se vnitřní smyčka dokončí, a v případě potřeby ji nastavte.
Volání funkcí jako příkazů
Volání funkce lze použít jako příkaz. V tomto případě je funkce volána pouze pro jakékoli vedlejší účinky, které může mít (např. mw.log() protokoluje hodnoty) a všechny návratové hodnoty jsou zahozeny.
Příkazy deklarace funkce
Lua poskytuje syntaktický sugar, aby bylo deklarování funkce a její přiřazení k proměnné přirozenější. Následující dvojice deklarací jsou ekvivalentní
-- Základní prohlášení function func( var-list ) blok end func = function ( var-list ) blok end
-- Lokální funkce local function func( var-list ) blok end local func; func = function ( var-list ) blok end
-- Funkce jako pole v tabulce function table.func( var-list ) blok end table.func = function ( var-list ) blok end
-- Funkce jako metoda v tabulce function table:func( var-list ) blok end table.func = function ( self, var-list ) blok end
Všimněte si, že zápis dvojtečkou zde odpovídá zápisu dvojtečky pro volání funkcí a na začátek seznamu argumentů přidává implicitní argument s názvem self
.
Zpracování chyb
Chyby lze "vyvolat" pomocí funkcí error() a assert(). Chcete-li "zachytit" chyby, použijte pcall() nebo xpcall(). Všimněte si, že určité interní chyby Scriunto nelze zachytit v kódu Lua.
Garbage collection
Lua provádí automatickou správu paměti. To znamená, že se nemusíte starat ani o alokaci paměti pro nové objekty, ani o její uvolnění, když již objekty nejsou potřeba. Lua spravuje paměť automaticky tak, že čas od času spustí garbage collector, aby shromáždil všechny mrtvé objekty (tj. objekty, které již nejsou dostupné z Lua) a objekty, které jsou dosažitelné pouze prostřednictvím 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 .
math.floor
math.floor( x )
Vrátí největší celé číslo menší nebo rovné x
.
math.fmod
math.fmod( x, y )
Vrátí zbytek dělení x
ku y
, který zaokrouhlí podíl směrem k nule. Například math.fmod( 10, 3 )
vychází 1
.
math.frexp
math.frexp( x )
Vrátí dvě hodnoty m
a e
takové, že:
- Pokud je
x
konečný a nenulový: ,e
je celé číslo a absolutní hodnotam
je v rozsahu - Pokud je
x
nula:m
ae
jsou 0 - Pokud je
x
NaN (Not a Number ("nečíslo")) nebo nekonečno:m
jex
ae
není specifikováno
math.huge
Hodnota představující kladné nekonečno. Větší nebo rovno jakékoli jiné číselné hodnotě.
math.ldexp
math.ldexp( m, e )
Vrátí (e
by mělo být celé číslo).
math.log
math.log( x )
Vrátí přirozený logaritmus x
.
math.log10
math.log10( x )
Vrátí základní-10 logaritmus x
.
math.max
math.max( x, ... )
Vrátí maximální hodnotu mezi svými argumenty.
Chování s NaN není specifikováno. S aktuální implementací bude NaN vráceno, pokud x
je NaN, ale všechny ostatní NaN budou ignorovány.
math.min
math.min( x, ... )
Vrátí minimální hodnotu mezi svými argumenty.
Chování s NaN není specifikováno. S aktuální implementací bude NaN vráceno, pokud x
je NaN, ale všechny ostatní NaN budou ignorovány.
math.modf
math.modf( x )
Vrátí dvě čísla, integrální část x
a zlomkovou část x
. Například math.modf( 1.25 )
zobrazí 1, 0.25
.
math.pi
Hodnota .
math.pow
math.pow( x, y )
Ekvivalent x^y
.
math.rad
math.rad( x )
Vrátí úhel x
(zadaný ve stupních) v radiánech.
math.random
math.random( m, n )
Vrátí pseudonáhodné číslo.
Argumenty m
a n
mohou být vynechány, ale pokud jsou uvedeny, musí být převoditelné na celá čísla.
- Bez argumentů vrátí skutečné číslo v rozsahu
- S jedním argumentem vrátí celé číslo v rozsahu
- Se dvěma argumenty vrátí celé číslo v rozsahu
Všimněte si, že nesprávný výstup může vzniknout, pokud je m
nebo n
menší než −2147483648 nebo větší než 2147483647 nebo pokud je n - m
větší než 2147483646.
math.randomseed
math.randomseed( x )
Nastaví x
jako jádro pro pseudonáhodný generátor.
Všimněte si, že použití stejného semena způsobí, že math.random
vypíše stejnou sekvenci čísel.
math.randomseed( tonumber( mw.getContentLanguage():formatDate( "U" ) ) * 10000 + os.clock() * 10000 )
math.sin
math.sin( x )
Vrátí sinus x
(zadaný v radiánech).
math.sinh
math.sinh( x )
Vrátí hyperbolický sinus x
.
math.sqrt
math.sqrt( x )
Vrátí druhou odmocninu z x
. Ekvivalent x^0.5
.
math.tan
math.tan( x )
Vrátí tangens x
(zadaný v radiánech).
math.tanh
math.tanh( x )
Vrátí hyperbolický tangens x
.
Knihovna operačního systému
os.clock
os.clock()
Vrátí přibližnou hodnotu v sekundách času procesoru použitého programem.
os.date
os.date( format, time )
- Formát jazykové knihovny lze použít pro komplexnější formátování data
Vrátí řetězec nebo tabulku obsahující datum a čas ve formátu format
. Pokud je formát vynechán nebo je nulový, použije se "%c".
Pokud je zadáno time
, je to čas, který má být formátován (viz os.time()
). Jinak se použije aktuální čas.
Pokud format
začíná znakem '!', pak je datum formátováno v UTC, nikoli v místním čase serveru. Za tímto volitelným znakem, pokud je formátem řetězec "*t", pak datum vrátí tabulku s následujícími poli:
- year (rok) (full)
- month (měsíc) (1–12)
- day (den) (1–31)
- hour (hodina) (0–23)
- min (0–59)
- sec (0–60, umožní přestupné sekundy)
- wday (všední den, neděle je 1)
- yday (den v roce)
- isdst (příznak letního času, boolean; může chybět, pokud informace nejsou k dispozici)
Pokud formát není "*t", pak datum vrátí datum jako řetězec, naformátovaný podle stejných pravidel jako funkce C strftime.
os.difftime
os.difftime( t2, t1 )
Vrátí počet sekund od t1
do t2
.
os.time
os.time( table )
Vrátí číslo představující aktuální čas.
Při volání bez argumentů vrátí aktuální čas. Pokud projde tabulkou, bude analyzován čas zakódovaný v tabulce. Tabulka musí obsahovat pole "rok", "měsíc" a "den" a může také obsahovat "hodinu" (výchozí 12), "min" (výchozí 0), "sec" (výchozí 0) a "isdst".
Knihovna balíčků
require
require( modulename )
Načte zadaný modul.
Nejprve se podívá do package.loaded[modulename]
, aby zjistil, zda je modul již načten. Pokud ano, vrátí package.loaded[modulename]
.
Jinak volá každý zavaděč v sekvenci package.loaders
, aby se pokusil najít zavaděč pro modul. Pokud je nalezen zavaděč, zavolá se tento zavaděč. Hodnota vrácená zavaděčem se uloží do package.loaded[modulename]
a vrátí se.
Informace o dostupných zavaděčích naleznete v dokumentaci pro package.loaders
.
Pokud máte například modul "Module:Giving" obsahující následující:
local p = {}
p.someDataValue = 'Ahoj!'
return p
Můžete to načíst do jiného modulu s kódem, jako je tento:
local giving = require( "Module:Giving" )
local value = giving.someDataValue -- hodnota je nyní 'Ahoj!'
package.loaded
Tato tabulka obsahuje načtené moduly. Klíče jsou názvy modulů a hodnoty jsou hodnoty vrácené při načtení modulu.
package.loaders
Tato tabulka obsahuje posloupnost vyhledávacích funkcí, které se mají použít při načítání modulů. Každá vyhledávací funkce je volána s jediným argumentem, názvem modulu, který se má načíst. Pokud je modul nalezen, hledač musí vrátit funkci, která modul skutečně načte a vrátí hodnotu, kterou má vrátit požadavek. V opačném případě musí vrátit nulu.
Scribunto nabízí dva vyhledávače:
- V
package.preload[modulename]
vyhledejte funkci loader - 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 metamethod pro table
na _G.
Knihovna řetězců
Ve všech řetězcových funkcích je první znak na pozici 1, nikoli na pozici 0 jako v C, PHP a JavaScript. Indexy mohou být záporné, v takovém případě se počítají od konce řetězce: pozice -1 je poslední znak v řetězci, -2 je předposlední atd.
Upozornění: Knihovna řetězců předpokládá jednobajtové kódování znaků. Nedokáže zpracovat znaky Unicode. Chcete-li pracovat s řetězci Unicode, použijte odpovídající metody v knihovně Scribunto Ustring.
string.byte
string.byte( s, i, j )
Pokud je řetězec považován za pole bajtů, vrátí hodnoty bajtů pro s[i]
, s[i+1]
, ···, s[j]
.
Výchozí hodnota i
je 1;
výchozí hodnota pro j
je i
.
Stejné jako mw.ustring.byte().
string.char
string.char( ... )
Přijímá nulu nebo více celých čísel. Vrátí řetězec s délkou rovnou počtu argumentů, ve kterém má každý znak hodnotu bajtu rovnou jeho odpovídajícímu argumentu.
local value = string.char( 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x21 ) --hodnota je nyní 'Ahoj!'
Viz mw.ustring.char() pro podobnou funkci, která používá kódové body Unicode spíše než bajtové hodnoty.
string.find
string.find( s, pattern, init, plain )
Vyhledá první shodu pattern
v řetězci s
. Pokud najde shodu, pak find
vrátí offsety v s
, kde tento výskyt začíná a končí. Jinak vrátí nulu. Pokud má vzor záchyty, pak jsou při úspěšné shodě zachycené hodnoty také vráceny po dvou indexech.
Třetí, volitelný číselný argument init
určuje, kde má začít hledání. Jeho výchozí hodnota je 1 a může být záporná. Hodnota true jako čtvrtý, volitelný argument plain
vypne funkce porovnávání vzorů, takže funkce provede jednoduchou operaci "najít podřetězec", přičemž v pattern
nejsou žádné znaky považovány za "kouzelné".
Všimněte si, že pokud je zadáno plain
, musí být zadáno také init
.
Viz 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 ' Interakce mezi rozsahy a třídami není definována. Proto vzory jako |
[^set]
|
Představuje doplněk set, kde set je interpretován jako výše. |
Vzorové položky
Položka vzoru může být
- třída jednoho znaku, která odpovídá libovolnému jednotlivému znaku ve třídě;
- třída jednoho znaku následovaná '
*
', která odpovídá 0 nebo více opakování znaků ve třídě. Tyto položky opakování budou vždy odpovídat nejdelší možné sekvenci; - třída jednoho znaku následovaná '
+
', která odpovídá 1 nebo více opakování znaků ve třídě. Tyto položky opakování budou vždy odpovídat nejdelší možné sekvenci; - třída jednoho znaku následovaná '
-
', která také odpovídá 0 nebo více opakování znaků ve třídě. Na rozdíl od '*
' budou tyto položky opakování vždy odpovídat nejkratší možné sekvenci; - třída jednoho znaku následovaná '
?
', která odpovídá 0 nebo 1 výskytu znaku ve třídě; %n
, 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 table.setn()
, cyklus for s ipairs() a operátor délky. Funkce table.setn()
je však zcela zastaralá a při použití vyvolá chybu.
table.concat
table.concat( table, sep, i, j )
Zadané pole, kde všechny prvky jsou řetězce nebo čísla, vrátí table[i] .. sep .. table[i+1] ··· sep .. table[j]
.
Výchozí hodnota pro sep
je prázdný řetězec, výchozí hodnota pro i
je 1 a výchozí hodnota pro j
je délka tabulky. Pokud je i
větší než j
, vrátí prázdný řetězec.
table.insert
table.insert( table, value )
table.insert( table, pos, value )
Vloží prvek value
na pozici pos
v table
a v případě potřeby posune ostatní prvky nahoru do volného prostoru. Výchozí hodnota pro pos
je délka tabulky plus 1, takže volání table.insert(t, x)
vloží x
na konci tabulky t
.
Prvky až do #table
jsou posunuty. Viz Operátor délky pro upozornění, pokud tabulka není sekvence.
Poznámka: při použití parametru pos
by value
nemělo být nil
. Pokus o vložení explicitní hodnoty nil
doprostřed tabulky bude mít za následek nedefinované chování, které může nepředvídatelně odstranit prvky v tabulce.
table.maxn
table.maxn( table )
Vrátí největší kladný číselný index dané tabulky nebo nulu, pokud tabulka nemá žádné kladné číselné indexy.
K tomu iteruje přes celou tabulku. To je zhruba ekvivalentní
function table.maxn( table )
local maxn, k = 0, nil
repeat
k = next( table, k )
if type( k ) == 'number' and k > maxn then
maxn = k
end
until not k
return maxn
end
table.remove
table.remove( table, pos )
Odebere z table
prvek na pozici pos
, posunutím dalších prvků dolů, aby se prostor v případě potřeby uzavřel. Vrátí hodnotu odstraněného prvku. Výchozí hodnota pro pos
je délka tabulky, takže volání table.remove( t )
odstraní poslední prvek tabulky tabulka t
.
Prvky až do #table
jsou posunuty. Viz Operátor délky pro upozornění, pokud tabulka není sekvence.
table.sort
table.sort( table, comp )
Seřadí prvky tabulky v daném pořadí, na místě, od table[1]
do table[#table]
.
Je-li zadáno comp
, pak to musí být funkce, která přijímá dva prvky tabulky a vrací true
, když je první menší než druhý (takže not comp(a[i+1],a[i])
bude po třídění pravdivé).
Pokud není zadáno comp
, použije se místo něj standardní operátor Lua <
.
Algoritmus řazení není stabilní. To znamená, že prvky považované za stejné daným řádem mohou mít svou relativní polohu změněnou řazením.
Knihovny Scribunto
Všechny knihovny 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()
aipairs()
budou fungovat, ale jiné metody, včetně#value
,next()
a funkce v Knihovně tabulek nebudou fungovat správně.
Výše zmíněný hypotetický modul převodu jednotek by mohl ukládat svůj kód do "Module:Convert" a jeho data do "Module:Convert/data" a "Module:Convert" by používal local data = mw.loadData( 'Module:Convert/data' )
pro efektivní načítání dat.
mw.loadJsonData
mw.loadJsonData( page )
To je stejné jako mw.loadData()
výše, kromě toho, že načítá data ze stránek JSON, nikoli z tabulek Lua.
Obsah JSON musí být pole nebo objekt.
Více na stránce mw.text.jsonDecode()
.
mw.dumpObject
mw.dumpObject( object )
Serializuje object
na lidsky čitelnou reprezentaci a poté vrátí výsledný řetězec.
mw.log
mw.log( ... )
Předá argumenty mw.allToString() a poté připojí výsledný řetězec do vyrovnávací paměti protokolu.
V ladicí konzoli je funkce print()
aliasem této funkce.
mw.logObject
mw.logObject( object )
mw.logObject( object, prefix )
Zavolá mw.dumpObject() a připojí výsledný řetězec k vyrovnávací paměti protokolu. Pokud je zadán prefix
, bude přidán do vyrovnávací paměti protokolu následovaný znakem rovná se před připojením serializovaného řetězce (tj. protokolovaný text bude "prefix = object-string").
Objekt frame
Objekt frame je rozhraním pro parametry předávané {{#invoke:}}
a pro analyzátor.
Všimněte si, že neexistuje žádná knihovna frame a neexistuje žádná globální proměnná s názvem frame
. Objekt frame se obvykle získává předáním jako parametr funkci volané {{#invoke:}}
a lze jej také získat z mw.getCurrentFrame()
.
frame.args
Tabulka pro přístup k argumentům předávaným do frame. Například pokud je modul volán z wikitextu s
{{#invoke:module|function|arg1|arg2|name=arg3}}
potom frame.args[1]
vrátí "arg1"
, frame.args[2]
vrátí "arg2"
a frame.args['name']
(nebo frame.args.name
) vrátí "arg3"
. Je také možné opakovat argumenty pomocí pairs( frame.args )
nebo ipairs( frame.args )
.
Nicméně vzhledem k tomu, jak Lua implementuje iterátory tabulek, iterace přes argumenty je vrátí v nespecifikovaném pořadí a neexistuje způsob, jak zjistit původní pořadí, jak se objevují ve wikitextu.
Všimněte si, že hodnoty v této tabulce jsou vždy řetězce. tonumber()
lze v případě potřeby použít k jejich převodu na čísla. Klíče jsou však čísla, i když jsou ve vyvolání explicitně zadány: {{#invoke:module|function|1|2=2}}
udává řetězcové hodnoty "1"
a "2"
indexované pomocí číselných klíčů 1
a 2
.
Stejně jako při vyvolání šablon MediaWiki budou mít pojmenované argumenty před předáním Lua úvodní a koncové prázdné znaky odstraněné z názvu i hodnoty, zatímco u nepojmenovaných argumentů nebudou prázdné znaky odstraněny.
Z důvodů výkonu frame.args
používá metatabulku, nikoli přímo obsahující argumenty. Hodnoty argumentů jsou vyžadovány od MediaWiki na vyžádání. To znamená, že většina ostatních metod tabulky nebude fungovat správně, včetně #frame.args
, next( frame.args )
a funkce v Knihovně tabulek.
Pokud je v argumentu #invoke
zahrnuta syntaxe preprocesoru, jako je vyvolání šablony a argumenty se třemi závorkami, nebudou po předání do Lua rozbaleny, dokud jejich hodnoty nebudou požadovány v Lua. Pokud jsou určité speciální značky napsané v notaci XML, jako například <pre>
, <nowiki>
, <gallery>
a <ref>
, zahrnuty jako argumenty #invoke
, pak budou tyto značky převedeny na "strip markers" — speciální řetězce které začínají znakem delete (ASCII 127), které mají být nahrazeny HTML poté, co jsou vráceny z #invoke.
frame:callParserFunction
frame:callParserFunction( name, args )
frame:callParserFunction( name, ... )
frame:callParserFunction{ name = string, args = table }
- Všimněte si použití pojmenovaných argumentů.
Zavolejte funkci analyzátoru a vrátíte příslušný řetězec. Toto je vhodnější než frame:preprocess
, ale kdykoli je to možné, měly by být před tímto rozhraním upřednostňovány nativní funkce Lua nebo funkce knihovny Scriunto.
Následující volání jsou přibližně ekvivalentní uvedenému wikitextu:
-- {{ns:0}}
frame:callParserFunction( 'ns', { 0 } )
frame:callParserFunction( 'ns', 0 )
frame:callParserFunction{ name = 'ns', args = { 0 } }
-- {{#tag:nowiki|some text}}
frame:callParserFunction( '#tag', { 'nowiki', 'some text' } )
frame:callParserFunction( '#tag', 'nowiki', 'some text' )
frame:callParserFunction( '#tag:nowiki', 'some text' )
frame:callParserFunction{ name = '#tag', args = { 'nowiki', 'some text' } }
-- {{#tag:ref|some text|name=foo|group=bar}}
frame:callParserFunction( '#tag', { 'ref',
'some text', name = 'foo', group = 'bar'
} )
Všimněte si, že stejně jako u frame:expandTemplate() nejsou název funkce a argumenty před předáním do funkce analyzátoru předzpracovány.
frame:expandTemplate
frame:expandTemplate{ title = title, args = table }
- Všimněte si použití pojmenovaných argumentů.
To je ekvivalentní volání frame:callParserFunction() s názvem funkce 'msg'
(viz Nápověda:Kouzelná slova#Modifikátory transkluze) a s title
předřazeným args
.
Toto je transkluze. Volání:
frame:expandTemplate{ title = 'template', args = { 'arg1', 'arg2', name = 'arg3' } }
dělá v Lua zhruba to samé, co {{template|arg1|arg2|name=arg3}}
dělá ve wikitextu. Stejně jako v transkluzi, pokud předaný název neobsahuje předponu jmenného prostoru, bude se předpokládat, že je ve jmenném prostoru Template:.
Všimněte si, že nadpis a argumenty nejsou před předáním do šablony předzpracovány:
-- To je zhruba ekvivalentní wikitextu jako {{template|{{!}}}}
frame:expandTemplate{ title = 'template', args = { '|' } }
frame:callParserFunction{ 'msg', { 'template', '|' } }
-- To je zhruba ekvivalentní wikitextu jako {{template|{{((}}!{{))}}}}
frame:expandTemplate{ title = 'template', args = { '{{!}}' } }
frame:callParserFunction{ 'msg', { 'template', '{{!}}' } }
frame:extensionTag
frame:extensionTag( name, content, args )
frame:extensionTag{ name = string, content = string, args = table_or_string }
To je ekvivalentní volání frame:callParserFunction() s názvem funkce '#tag'
(viz Help:Magic_words#Miscellaneous) a s name
a content
připojenými k args
.
-- Tyto jsou rovnocenné
frame:extensionTag( 'ref', 'some text', { name = 'foo', group = 'bar' } )
frame:extensionTag{ name = 'ref', content = 'some text', args = { name = 'foo', group = 'bar' } }
frame:callParserFunction( '#tag', { 'ref' ,
'some text', name = 'foo', group = 'bar'
} )
-- Tyto jsou rovnocenné
frame:extensionTag{ name = 'ref', content = 'some text', args = { 'some other text' } }
frame:callParserFunction( '#tag', { 'ref',
'some text', 'some other text'
} )
frame:getParent
frame:getParent()
Volaný v rámci vytvořeném {{#invoke:}}
vrátí rámec pro stránku, která volala {{#invoke:}}
. Volaný na tomto snímku vrací nulu.
Pokud například šablona {{Example}}
obsahuje kód {{#invoke:ModuleName|FunctionName|A|B}}
a stránka tuto šablonu převede kódem {{Example|C|D}}
, pak v Module:ModuleName volání frame.args[1]
a frame.args[2]
vrátí "A"
a "B"
a volání frame:getParent().args[1]
a frame:getParent().args[2]
vrátí "C"
a "D"
, přičemž frame
je první argument ve volání funkce.
frame:getTitle
frame:getTitle()
Vrátí název spojený s rámcem jako řetězec. Pro rámec vytvořený {{#invoke:}}
je to název vyvolaného modulu.
frame:newChild
frame:newChild{ title = title, args = table }
- Všimněte si použití pojmenovaných argumentů.
Vytvořte nový 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
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ímtrue
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ímcogrammar
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
, orPMID
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 )
nebonil
, 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 polenil
. 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 jefalse
, všechny ostatní vlastnosti souboru budounil
. - 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í
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.
["5"]
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 [0-9]
, patterns such as %b«»
, and quantifiers applied to multibyte characters will work correctly. Empty captures will capture the position in code points rather than bytes.
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 232 so the value is in the range 0 to 232−1; return values are also in this range.
When bits are numbered (as in bit32.extract()), 0 is the least-significant bit (the one with value 20) and 31 is the most-significant (the one with value 231).
bit32.band
bit32.band( ... )
Returns the bitwise AND of its arguments: the result has a bit set only if that bit is set in all of the arguments.
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 2disp
.
Note that a displacement over 31 will result in 0.
bit32.rshift
bit32.rshift( n, disp )
Returns the number n
shifted disp
bits to the right. This is a logical shift: inserted bits are 0. This is generally equivalent to dividing by 2disp
.
Note that a displacement over 31 will result in 0.
bit32.arshift
bit32.arshift( n, disp )
Returns the number n
shifted disp
bits to the right. This is an arithmetic shift: if disp
is positive, the inserted bits will be the same as bit 31 in the original number.
Note that a displacement over 31 will result in 0 or 4294967295.
bit32.lrotate
bit32.lrotate( n, disp )
Returns the number n
rotated disp
bits to the left.
Note that rotations are equivalent modulo 32: a rotation of 32 is the same as a rotation of 0, 33 is the same as 1, and so on.
bit32.rrotate
bit32.rrotate( n, disp )
Returns the number n
rotated disp
bits to the right.
Note that rotations are equivalent modulo 32: a rotation of 32 is the same as a rotation of 0, 33 is the same as 1, and so on.
libraryUtil
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:
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:
- debug.*
- Most of the functions are insecure. Available functions are:
The following functions and packages are not available:
- collectgarbage()
- module()
- coroutine.*
- No application is known for us, so it has not been reviewed for security.
- dofile()
- loadfile()
- io.*, file.*
- Allows local filesystem access, which is insecure.
- load()
- loadstring()
- These were omitted to allow for static analysis of the Lua source code. Also, allowing these would allow Lua code to be added directly to article and template pages, which was not desired for usability reasons.
- print()
- This was discussed on wikitech-l and it was decided that it should be omitted in favour of return values, to improve code quality. If necessary, mw.log() may be used to output information to the debug console.
- string.dump()
- May expose private data from parent environments.
Additional caveats
- Referential data structures
- Circular data structures and data structures where the same node may be reached by more than one path cannot be correctly sent to PHP.
Attempting to do so will cause undefined behavior. This includes (but is not limited to) returning such data structures from the module called by {{#invoke:}}
and passing such data structures as parameters to Scribunto library functions that are implemented as callbacks into PHP.
Such data structures may be used freely within Lua, including as the return values of modules loaded with mw.loadData()
.
Writing Scribunto libraries
This information is useful to developers writing additional Scribunto libraries, whether for inclusion in Scribunto itself or for providing an interface for their own extensions.
A Scribunto library will generally consist of five parts:
- The PHP portion of the library.
- The Lua portion of the library.
- The PHP portion of the test cases.
- The Lua portion of the test cases.
- The documentation.
Existing libraries serve as a good example.
Library
The PHP portion of the library is a class that must extend Scribunto_LuaLibraryBase
. See the documentation for that class for implementation details. In the Scribunto extension, this file should be placed in engines/LuaCommon/NameLibrary.php
, and a mapping added to Scribunto_LuaEngine::$libraryClasses
. Other extensions should use the ScribuntoExternalLibraries hook. In either case, the key should match the Lua module name ("mw.name" for libraries in Scribunto, or "mw.ext.name" for extension libraries).
The Lua portion of the library sets up the table containing the functions that can be called from Lua modules. In the Scribunto extension, the file should be placed in engines/LuaCommon/lualib/mw.name.lua
. This file should generally include boilerplate something like this:
local object = {}
local php
function object.setupInterface( options )
-- Remove setup function
object.setupInterface = nil
-- Copy the PHP callbacks to a local variable, and remove the global
php = mw_interface
mw_interface = nil
-- Do any other setup here
-- Install into the mw global
mw = mw or {}
mw.ext = mw.ext or {}
mw.ext.NAME = object
-- Indicate that we're loaded
package.loaded['mw.ext.NAME'] = object
end
return object
The module in engines/LuaCommon/lualib/libraryUtil.lua
(load this with local util = require 'libraryUtil'
) contains some functions that may be helpful.
Be sure to run the Scribunto test cases with your library loaded, even if your library doesn't itself provide any test cases. The standard test cases include tests for things like libraries adding unexpected global variables. Also, if the library is loaded with PHP, any upvalues that its Lua functions have will not be reset between #invoke's. Care must be taken to ensure that modules can't abuse this to transfer information between #invoke's.
Test cases
The Scribunto extension includes a base class for test cases, Scribunto_LuaEngineTestBase
, which will run the tests against both the LuaSandbox and LuaStandalone engines.
The library's test case should extend this class, and should not override static function suite()
.
In the Scribunto extension, the test case should be in tests/engines/LuaCommon/NameLibraryTest.php
and added to the array in ScribuntoHooks::unitTestsList()
(in common/Hooks.php
); extensions should add the test case in their own UnitTestsList
hook function, probably conditional on whether $wgAutoloadClasses['Scribunto_LuaEngineTestBase']
is set.
Most of the time, all that is needed to make the test case is this:
class ClassNameTest extends Scribunto_LuaEngineTestBase { protected static $moduleName = 'ClassNameTest'; function getTestModules() { return parent::getTestModules() + array( 'ClassNameTest' => __DIR__ . '/ClassNameTests.lua'; ); } }
This will load the file ClassNameTests.lua
as if it were the page "Module:ClassNameTests", expecting it to return an object with the following properties:
- count: Integer, number of tests
- provide( n ): Function that returns three values:
n
, the name of testn
, and a string that is the expected output for testn
. - run( n ): Function that runs test
n
and returns one string.
If getTestModules()
is declared as shown, "Module:TestFramework" is available which provides many useful helper methods. If this is used, ClassNameTests.lua
would look something like this:
local testframework = require 'Module:TestFramework'
return testframework.getTestProvider( {
-- Tests go here
} )
Each test is itself a table, with the following properties:
- name: The name of the test.
- func: The function to execute.
- args: Optional table of arguments to pass to the function.
- expect: Results to expect.
- type: Optional "type" of the test, default is "Normal".
The type controls the format of expect
and how func
is called. Included types are:
- Normal:
expect
is a table of return values, or a string if the test should raise an error.func
is simply called. - Iterator:
expect
is a table of tables of return values.func
is called as with an iterated for loop, and each iteration's return values are accumulated. - ToString: Like "Normal", except each return value is passed through
tostring()
.
Test cases in another extension
There are (at least) two ways to run PHPUnit tests:
- Run phpunit against core, allowing the tests/phpunit/suites/ExtensionsTestSuite.php to find the extension's tests using the UnitTestsList hook.
If your extension's test class names all contain a unique component (e.g. the extension's name), the --filter
option may be used to run only your extension's tests.
- Run phpunit against the extension directory, where it will pick up any file ending in "Test.php".
Either of these will work fine if Scribunto is loaded in LocalSettings.php. And it is easy for method #1 to work if Scribunto is not loaded, as the UnitTestsList hook can easily be written to avoid returning the Scribunto test when $wgAutoloadClasses[ 'Scribunto_LuaEngineTestBase' ]
is not set.
But Jenkins uses method #2. For Jenkins to properly run the tests, you will need to add Scribunto as a dependency for your extension. See Gerrit change 56570 for an example of how this is done.
If for some reason you need the tests to be able to run using method #2 without Scribunto loaded, one workaround is to add this check to the top of your unit test file:
if ( !isset( $GLOBALS['wgAutoloadClasses']['Scribunto_LuaEngineTestBase'] ) ) {
return;
}
Documentation
Modules included in Scribunto should include documentation in the Scribunto libraries section above. Extension libraries should include documentation in a subpage of their own extension page, and link to that documentation from the Extension libraries subsection above.
See also
License
This manual is derived from the Lua 5.1 reference manual, which is available under the MIT license.
Copyright © 1994–2012 Lua.org, PUC-Rio. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
This derivative manual may also be copied under the terms of the same license.