Extension:Scribunto/Lua reference manual
Niniejsza instrukcja przedstawia w jaki sposób jest używane Lua przez roszerzenie Scribunto . Pewne fragmenty pochodzą z Lua 5.1 reference manual, które są dostępne na licencji MIT.
Strona przedstawia najnowszą wersję rozszerzenia Scribunto. Niektóre funkcje mogą jeszcze nie być wdrożone. |
Wstęp
Pierwsze kroki
Utwórz stronę na wiki MediaWiki z włączonym Scribunto, o tytule rozpoczynającym się od „Module:”, na przykład „Module:Bananas”. Do nowej strony skopiuj następujący tekst:
local p = {} --p to skrót od pakietu
function p.hello( frame )
return "Hello, world!"
end
return p
Zapisz ją, a następnie na innej (nie modułowej) stronie wpisz:
{{#invoke:Bananas|hello}}
Wywoła to funkcję „hello” wyeksportowaną z tego modułu (jeśli zapisałeś go pod inną nazwą, podmień „Bananas” na tą nazwę). Wywołanie {{#invoke:Bananas|hello}}
zostanie zamienione przez tekst zwracany z funkcji, w tym przypadku „Hello, world!”.
Zalecanym stylem jest wywoływanie kodu Lua w kontekście szablonu. To oznacza, że z perspektywy wywołującej go strony składnia jest niezależna od tego czy logika szablonu jest zaimplementowana w Lua czy wikikodem. Ponadto unika się również z wprowadzania dodatkowej skomplikowanej składni w przestrzeni głównej wiki.
Struktura modułu
Moduł musi zwracać tablicę Lua zawierającą funkcje, które mogą być wywołane przez {{#invoke:}}
.
W ogólności, jak widać w przykładzie wyżej, deklaruje się lokalną zmienną przechowującą tablicę, funkcje dodaje się do tej tablicy, a sama tablica jest zwracana na końcu kodu modułu.
Wszelkie funkcje lokalne bądź globalne, które nie będą dodane do tej tablicy, będą niedostępne przez {{#invoke:}}
, jednak globalne mogą być dostępne z innych modułów załadowanych przez require()
.
Zalecanym dobrym stylem dla modułów jest deklarowanie wszystkich funkcji i zmiennych jako lokalnych.
Dostęp do parametrów od wikitekstu
Do funkcji wywołanych przez {{#invoke:}}
przekazywany jest jeden argument, tak zwany obiekt ramki. Aby uzyskać dostęp do parametrów przekazanych z wikitekstu do {{#invoke:}}
zwykle stosuje się tablicę args
z tego obiektu. Możliwy jest również dostęp do pól szablonu zawierającego {{#invoke:}}
przez użycie frame:getParent()
i odwołanie do tablicy args
tejże ramki.
Obiekt ramki jest również stosowany w celu użycia specyficznych cech parsera jak na przykład wywołanie funkcji parsera, rozwijania szablonu, i przetwarzania dowolnego ciągu wikitekstu.
Zwracanie tekstu
Funkcja modułu powinna zazwyczaj zwracać pojedynczy łańcuch tekstowy; wszelkie wartości, które będą zwracane będą przetworzone przez tostring() a następnie połączone w jeden łańcuch bez żadnego separatora. Łańcuch ten będzie następnie wstawiony do wikitekstu jako wynik {{#invoke:}}
.
Na tym etapie parsowania strony szablony już są rozwinięte, funkcje parsera i tagi rozszerzeń są przetworzone, a transformacje przed zapisem (np.: rozwinięcie tyld w podpis lub wikilink z pustym opisem po znaku |
tak zwany pipe trick) zrealizowane. Z tego powodu moduł nie może korzystać z tych możliwości w swoim wynikowym tekście. Jeśli moduł zwraca „Cześć [[world|świecie]]! {{witam}}”
, na stronie będzie można przeczytać „Cześć świecie! {{witam}}”.
Z drugiej strony, subst jest obsługiwany na wcześniejszym etapie przetwarzania, więc w przypadku {{subst:#invoke:}}
będą przetwarzane tylko inne próby podstawień. Ponieważ nieudane podstawienie pozostanie w wikitekście, zostanie one przetworzone przy następnej edycji. Zasadniczo należy tego unikać.
Dokumentacja modułu
Scribunto umożliwia dokumentowanie modułów przez automatyczne skojarzenie modułu ze stroną dokumentacji tworzonej w postaci wikitekstu; domyślnie jako dedykowanej podstrony o nazwie „/opis”, której zawartość jest transkludowana powyżej kodu źródłowego strony modułu. Na przykład dokumentacja dla „Moduł:Bananas” będzie umieszczona w „Moduł:Bananas/opis”.
Można to skonfigurować dzięki następującym komunikatom (MediaWiki-namespace messages):
scribunto-doc-page-name
— Ustala nazwę strony używanej jako dokumentacja. Nazwa modułu (bez prefiksu Moduł:) jest przekazana jako$1
. Jeśli są w przestrzeni modułów, strony określone tutaj będą interpretowane jako wikitekst zamiast skryptu Lua i nie mogą być używane przez{{#invoke:}}
. Wartością domyślną jest „Moduł:$1/opis”, np. podstona /opis modułu. Należy pamiętać, że w tym komunikacie nie można używać funkcji parsera i innych rozwinięć dostępnych przez podwójne nawiasy klamrowe.scribunto-doc-page-does-not-exist
— Komunikat wyświetlany w przypadku gdy odpowiednia strona z dokumentacją nie istnieje. Nazwa strony jest przekazywana jako$1
. Domyślnie nazwa jest pusta.scribunto-doc-page-show
— Komunikat wyświetlany w przypadku gdy odpowiednia strona z dokumentacją istnieje. Nazwa strony jest przekazywana jako$1
. Domyślnie transkluduje stronę dokumentacji.scribunto-doc-page-header
— Nagłówek wyświetlany podczas przeglądania samej strony dokumentacji. Nazwa dokumentowanego modułu (z prefiksem Moduł:) jest przekazana jako$1
. Domyślnie wyświetlane jest krótkie wyjaśnienie w kursywie.
Uwaga! Moduły nie mogą być kategoryzowane bezpośrednio ani nie mogą zawierać bezpośrednich linków interwiki.
Te kategorie i linki można umieszczać w kodzie dokumentacji ograniczając je tagami <includeonly>...</includeonly>
, które je zaaplikują do modułu kiedy strona z dokumentacją jest transkludowana w stronę modułu.
Renaming or moving modules
To rename or move a module, use the Move Page link in the Tools sidebar. You will want to move both the module itself, as well as the subpage containing its documentation.
To manually create a module redirect, use the following syntax:
return require [[Module:Foo]]
Replace Foo
with the name of the module you'd like to redirect to.
Język Lua
Tokeny
Nazwą (albo identyfikatorem) w Lua może być dowolny ciąg liter, cyfr lub podkreśleń, który nie zaczyna się cyfrą. Odróżniane są wielkie litery od małych; czyli w zbiorze nazw „foo”, „Foo” i „FOO” wszystkie one są różne.
Następujące słowa kluczowe są zarezerwowane i nie mogą być użyte jako nazwy:
and
break
do
else
elseif
end
false
for
function
if
in
local
nil
not
or
repeat
return
then
true
until
while
Nazwy zaczynające się podkreśleniem i następującymi po nim wielkimi literami są zarezerwowane na wewnętrzne zmienne globalne Lua.
Pozostałymi tokenami są:
#
%
(
)
*
+
,
-
--
.
..
...
/
:
;
<
<=
=
==
>
>=
[
]
^
{
}
~=
Komentarze
Komentarz zaczyna się od --
w dowolnym miejscu poza łańcuchem znaków. Jeśli bezpośrednio po --
następuje długi nawias otwierający to komentarz kończy się dopiero po napotkaniu odpowiedniego długiego nawiasu zamykającego; w przeciwnym razie komentarz kończy się na końcu bieżącej linii.
-- Komentarz w Lua zaczyna się od podwójnego myślnika, a kończy na końcu linii.
--[[ Wieloliniowe łańcuchy i komentarze
są wystrojone w podwójne nawiasy kwadratowe. ]]
--[=[ Komentarze takie jak ten mogą mieć inne --[[komentarze]] zagnieżdżone. ]=]
--[==[ Komentarze takie jak ten mogą mieć inne
--[===[ długie --[=[komentarze]=] --zagnieżdżone
]===] wiele razy, nawet jeśli nie wszystkie z nich
--[[ są rozdzielone odpowiednio pasującymi długimi nawiasami! ]===]
]==]
Typy danych
Lua to język z typowaniem dynamicznym, co oznacza, że zmienne i argumenty funkcji nie mają typów, jedynie wartości do nich przypisane. Wszystkie wartości niosą informację o typie.
Lua ma osiem podstawowych typów danych, aczkolwiek tylko sześć ma znaczenie w rozszerzeniu Scribunto. Funkcja type()
zwraca typ wartości.
Funkcja tostring()
zamienia wartość na łańcuch znaków. Funkcja tonumber()
zamienia wartość na liczbę jeśli to możliwe, w przeciwnym wypadku zwraca nil. Nie ma żadnych innych bezpośrednich funkcji do zamiany wartości na inne typy danych.
Liczby są automatycznie zamieniane na łańcuchy znaków jeśli są użyte w kontekście, w którym oczekiwany jest łańcuch znaków, na przykład z operatorem łączenia łańcuchów znaków. Łańcuchy znaków rozpoznawalne przez tonumber()
są automatycznie zamieniane na liczby jeśli są użyte wraz z operatorami arytmetycznymi. Jeśli oczekiwana jest wartość logiczna to wszystkie wartości oprócz nil i false są traktowane jak wartość true.
nil
„nil” jest typem danych wartości nil
, który istnieje w celu wskazania braku wartości.
Nil nie może być użyty jako klucz w tablicy, w dodatku nie ma różnicy pomiędzy nieprzypisanym kluczem w tablicy, a kluczem przypisanym wartością nil.
Zamiana na string daje wynik „nil”. Zamiana na wartość logiczną jest tożsama z fałszem.
Note: Lua does make a distinction between nil
and nothing at all in some limited situations.
For example, tostring(nil)
returns "nil"
, but tostring()
throws an error, as the first parameter is required.
This distinction is particularly relevant to the select() function.
boolean
Wartości logiczne to true
i false
.
Zamiana na łańcuch tekstowy daje wynik „true” lub „false”.
Inaczej niż w wielu innych językach, wartości logiczne nie mogą być bezpośrednio zamieniane na liczby. Podobnie inaczej niż wielu innych językach, tylko false i nil są uznawane za fałsz w przeliczeniach logicznych; liczba 0 i pusty łańcuch tekstowy są tożsame z prawdą.
string
Łańcuch tekstowe w Lua są traktowane jako ciągi 8-bitowych bajtów; od aplikacji zależy ich interpretacja w dowolnym wybranym kodowaniu.
Literały łańcuchów tekstowych są ograniczane przez pojedyncze lub podwójne cudzysłowy ('
lub "
); podobnie jak w JavaScript i inaczej niż w PHP, nie ma między oboma zapisami różnicy. Rozpoznawane są następujące sekwencje specjalne:
\a
(bell, dzwonek, bajt 7)\b
(backspace, powrót o 1 pozycję, bajt 8)\t
(horizontal tab, tabulacja pozioma, bajt 9)\n
(newline, przesunięcie o 1 wiersz, bajt 10)\v
(vertical tab, tabulacja pionowa, bajt 11)\f
(form feed, przesunięcie o 1 stronę, bajt 12)\r
(carriage return, powrót karetki, bajt 13)\"
(double quote, cudzysłów, bajt 34)\'
(single quote, apostrof, bajt 39)\\
(backslash, ukośnik wsteczny, ukośnik lewy, bajt 92)
Znak nowej linii można umieścić w łańcuchu tekstowym poprzedzając go wstecznym ukośnikiem. Bajty można również wprowadzać za pomocą sekwencji specjalnej '\ddd', gdzie ddd jest dziesiętną wartością bajtu z zakresu 0–255. Aby umieścić znaki Unikodu za pomocą sekwencji specjalnych należy podać odpowiednie bajty przy zachowaniu kodowania UTF-8; w ogólności znacznie łatwiej wpisać znaki Unikodu wprost.
Literały łańcuchów tekstowych można również definiować stosując długie nawiasy.
Długi nawias otwierający składa się z otwierającego nawiasu kwadratowego, następnie z zera lub więcej znaków równości i zakończenia w postaci ponownie otwierającego nawiasu kwadratowego na przykład [[
, [=[
lub [=====[
.
Długiemu nawiasowi otwierającemu musi odpowiadać odpowiedni długi nawias zamykający na przykład ]]
, ]=]
lub ]=====]
..
Specjalnym przypadkiem jest długi nawias otwierający na samym końcu linii, w którym znak nowej linii nie wlicza się do definiowanego łańcucha tekstowego, jednak znak nowej linii tuż przed długim nawiasem zamykającym jest wliczany.
Łańcuchy tekstowe ograniczane przez długie nawiasy nie obsługują sekwencji specjalnych.
-- Ten długi łańcuch tekstowy
foo = [[
bar\tbaz
]]
-- jest równoważny temu ograniczonemu apostrofami
foo = 'bar\\tbaz\n'
Należy pamiętać, że każdy łańcuch tekstowy w wyrażeniach logicznych jest tożsamy z prawdą. Jest to nietypowa cecha, gdyż zazwyczaj pusty tekst w innych językach oznacza fałsz.
number
Lua ma tylko jeden typ liczbowy, który wewnętrznie jest reprezentowany jako wartości zmiennoprzecinkowe podwójnej precyzji. W tym formacie liczby całkowite pomiędzy -9007199254740992 a 9007199254740992 mają dokładną reprezentację, natomiast liczby o większym module lub z częścią ułamkową mogą podlegać błędom zaokrągleń.
Stałe liczbowe są określane z pomocą kropki (.
) jako separatora cyfr dziesiętnych, i bez możliwości grupowania cyfr na przykład 123456.78
. Liczby można również przedstawiać w zapisie naukowym bez odstępów, np. 1.23e-10
, 123.45e20
, lub 1.23E5
. Liczby całkowite można również zapisać w systemie szesnastkowym poprzedzając je przedrostkiem 0x
na przykład 0x3A
.
Numbers may also be represented using E notation without spaces, e.g. 1.23e-10
, 123.45e20
, or 1.23E+5
.
Integers may also be specified in hexadecimal notation using a 0x
prefix, e.g. 0x3A
.
Mimo iż NaN oraz dodania i ujemna nieskończoność są poprawnie przechowywane i obsługiwane, Lua nie dostarcza odpowiadającym im literałów. Stała math.huge
to dodania nieskończoność, jak również wynik dzielenia 1/0
, a dzielenie takie jak 0/0
można wykorzystać do uzyskania NaN.
Należy pamiętać, że wszystkie liczby są uznawane za prawdę w wyrażeniach logicznych. Jest to nietypowa cecha odróżniająca od innych języków, w których zwykle liczba 0 bywa uznawana za fałsz. W przypadku zamiany na tekst, skończone liczby dziesiętne są prezentowane w systemie dziesiętnym, możliwa jest notacja naukowa; NaN to "nan"
lub "-nan"
; a nieskończoności to "inf"
lub "-inf"
.
Known bug: the Lua interpreter will treat all instances of 0
and -0
as whichever of the two is encountered first when the script is compiled, which means that the return values of tostring(0)
, 1/-0
(and so on) are affected by where they occur in the code.
This can cause unexpected results, particularly if all instances of 0
are converted to "-0"
on return.
If necessary, this can be circumvented by generating zero values using tonumber("0")
and tonumber("-0")
, which doesn't seem to cause or be affected by the issue. See [1].
table
Tablice w Lua są tablicami asocjacyjnymi, podobnie jak tablice w PHP lub obiekty w JavaScript.
Tablice są tworzone za pomocą nawiasów klamrowych. Pusta tablica to {}
. Aby utworzyć tablicę od razu wypełnioną polami należy umieścić listę definicji pól wewnątrz nawiasów klamrowych oddzielając je przecinkami i/lub średnikami. Każda z definicji pola może przyjąć jedną z następujących form:
[wyrażenie1] = wyrażenie2
używa (pierwszą) wartość z wyrażenie1 jako klucza i (pierwszą) wartość z wyrażenie2 jako wartość.nazwa = wyrażenie
jest równoważne do["nazwa"] = wyrażenie
wyrażenie
to mniej więcej to samo co[i] = wyrażenie
, gdzie i jest liczbą całkowitą na początku równą 1 i zwiększaną wraz z kolejnymi definicjami w tej formie. Jeśli jest to ostatnia definicja, a wyrażenie zwraca wiele wartości, to wszystkie zostaną użyte; w przeciwnym wypadku zachowana zostanie jedynie pierwsza wartość.
Pola tablicy są dostępne dzięki notacji z nawiasami kwadratowymi np. table[key]
. Klucze w postaci łańcuchów tekstowych, które są również poprawnymi nazwami mogą być dostępne dzięki zapisowi z kropką np. table.key
jest równoważne z table['key']
. Wywoływanie funkcji, która jest wartością w tabeli, można dokonać za pomocą zapisu z dwukropkiem; na przykład table:func( ... )
jest równoważne z table['func']( table, ... )
lub table.func( table, ... )
.
Sekwencja jest tablicą z wartościami różnymi od nil dla wszystkich dodatnich liczb całkowitych od 1 do N, i bez żadnych wartości (tj. z nil) dla wszystkich dodatnich liczb większych niż N. Wiele funkcji Lua działa tylko na sekwencjach i ignoruje niedodatnie klucze.
Inaczej niż w wielu językach jak PHP lub JavaScript, dowolna wartość oprócz nil i NaN może być używana jako klucz i nie jest przy tym dokonywana żadna konwersja. Wszystkie z nich są poprawne i różne:
-- Twórz tablicę
t = {}
t["foo"] = "foo"
t.bar = "bar"
t[1] = "jeden"
t[2] = "dwa"
t[3] = "trzy"
t[12] = "liczba dwanaście"
t["12"] = "tekstowa dwunastka"
t[true] = "true"
t[tonumber] = "tak, nawet funkcje mogą być kluczami tabeli"
t[t] = "tak, tabela może być również kluczem tabeli. Nawet sama dla siebie."
-- To tworzy tablicę mniej więcej taką samą jak powyżej
t2 = {
foo = "foo",
bar = "bar",
"jeden",
"dwa",
[12] = "liczba dwanaście",
["12"] = "tekstowa dwunastka",
"trzy",
[true] = "true",
[tonumber] = "tak, nawet funkcje mogą być kluczami tabeli",
}
t2[t2] = "tak, tabela może być również kluczem tabeli. Nawet sama dla siebie."
Podobnie dowolna wartość oprócz nil może być przechowywana w tablicy. Umieszczenie nil jest równoważne usunięciu klucza z tablicy, a próba dostępu do dowolnego klucza, który nie został zdefiniowany zwraca wartość nil.
Należy pamiętać, że tablice nie są nigdy domyślnie kopiowane w Lua; jeśli tabela jest przekazana jako argument do funkcji, a funkcja operuje na kluczach lub wartościach w tablicy, to zmiany te będą widoczne w kodzie wywołującym funkcje.
Jeśli tablica jest zamieniana na tekst to zazwyczaj wynikiem jest tekst „table”, jednak można to zmienić stosując metametodę __tostring
. Nawet pusta tablica jest uznawana za prawdę w wyrażeniach logicznych.
function
Funkcje w Lua są wartościami pierwszoklasowymi: mogą być tworzone anonimowo, przekazywane jako argumenty, przypisywane do zmiennych i tym podobne.
Funkcje są tworzone dzięki słowu kluczowemu function
, a wywoływane z pomocą nawiasów. Dla funkcji nazwanych, lokalnych i funkcji działających jako metody w tablicach istnieje lukier składniowy. Zobacz szczegóły w deklaracjach funkcji i wywołaniach funkcji poniżej.
Funkcje w Lua są domknięciami, czyli utrzymują referencję do zakresu w którym zostały zadeklarowane i mogą mieć dostęp i manipulować zmiennymi w tym zakresie.
Podobnie do tablic, jeśli funkcja jest przypisana do różnych zmiennych lub przekazana jako argument do innej funkcji, to jest to wciąż pod spodem ten sam „obiekt funkcji”, która będzie wywołana.
Zamiana funkcji na łańcuch tekstowy daje w wyniku „function”.
Nieobsługiwane typy
The userdata type is used to hold opaque values for extensions to Lua written in other languages; for example, a userdata might be used to hold a C pointer or struct. To allow for use of Scribunto in hosting environments where custom-compiled code is not allowed, no such extensions are used.
The thread type represents the handles for coroutines, which are not available in Scribunto's sandbox.
Upvalues
There is a strict limit of max 60 unique upvalues acessed inside a function. An upvalue is a value declared outside of a function and used inside it. As upvalues do count:
- variables (a table with many elements counts as one upvalue)
- functions (only those directly called from function in question, not their dependencies)
A violation of the limit can be triggered by a use of such a variable or function, not by its mere presence or availability. Repeated access to same upvalue does not exhaust the limit further.
Metatablice
Każda tablica może mieć stowarzyszoną tablicę znaną jako „metatablica”. Pola w metatablicy są używane przez niektóre operatory i funkcje aby określić inne lub zastępcze zachowanie tablicy. Metatablicę tablicy można odczytać funkcją getmetatable(), a ustawić funkcją setmetatable().
Kiedy potrzebny jest dostęp do metafunkcji, metapola są odczytywane w taki sposób jaki robi to rawget().
Pola metatablicy, które mają wpływ na samą tablicę:
- __index
- To pole jest używane gdy zwykły dostęp przez
t[klucz]
zwróciłby nil. Jeśli wartością pola jest tabela, dostęp będzie powtórzony na tej tabeli, np.__index[klucz]
(co może spowodować dalsze odwołania do __index, gdyby metatablica miała własną metatablicę). Jeśli wartością pola jest funkcja, to będzie ona wywołana jako__index( t, klucz)
. Funkcja rawget() omija tę metametodę. - __newindex
- To pole jest używane gdy przypisywany jest klucz do tablicy
t[klucz] = wartość
, gdzierawget( t, key )
zwróciłoby nil. Jeśli wartością pola jest tablica, przypisanie będzie powtórzone w tej tablicy, np.__newindex[klucz] = wartość
(co może spowodować dalsze odwołania do __newindex, gdyby metatablica miała własną metatablicę). Jeśli wartością pola jest funkcja, to będzie ona wywołana jako__newindex( t, klucz, wartość )
. Funkcja rawset() omija tę metametodę. - __call
- To pole jest używane gdy stosowana jest składnia wywołania funkcji na tablicy,
t( ··· )
. Wartość pola musi być funkcją, której wywołanie będzie będzie podobne do__call( t, ··· )
. - __mode
- To pole ma zastosowanie w tablicach przechowujących słabe referencje. Wartością pola musi być łańcuch tekstowy. Domyślnie żadna wartość, która jest kluczem albo wartością w tablicy nie będzie usuwana podczas procesu odśmiecania pamięci. Jednak jeśli to metapole zawiera literę 'k' lub 'v' to klucze bądź wartości mogą być usuwane w procesie odśmiecania jeśli nie mają nie-słabych referencji. W dowolnym przypadku odpowiedni klucz i wartość są usuwane z tablicy. Należy pamiętać, że to zachowanie jest niezdefiniowane jeśli pole jest ustawione później niż tablica została użyta jako metatablica.
Inne pola metatablicy to:
Uwaga: W Lua wszystkie łańcuchy tekstowe współdzielą jedną metatablicę, w której __index
odwołuje się do tablicy string
. Ta metatablica jest niedostępna w Scribunto, podobnie nie jest dostępna oryginalna tablica string
; tablica string dostępna dla modułów jest jej kopią.
Zmienne
Zmienne to miejsca, w których przechowywane są wartości. W Lua istnieją trzy rodzaje zmiennych: globalne, lokalne i pola w tablicach.
Nazwa przedstawia globalną lub lokalną zmienną (lub argument funkcji, który jest rodzajem zmiennej lokalnej). Zakłada się, że zmienne są globalne, chyba że zostały zadeklarowane jako lokalne za pomocą słowa kluczowego local
. Uznaje się, że dowolna zmienna, do której nie została przypisana wartość ma wartość nil.
Zmienne globalne są przechowywane z standardowej tablicy Lua nazywanej „środowiskiem”; ta tablica jest często dostępna w zmiennej globalnej _G
. Do tej zmiennej globalnej można przypisać metatablicę; metametody __index i __newindex będą wywoływane w przypadku dostępu lub przypisywania zmiennych globalnych tak jak to ma miejsce w dostępie i zapisie pól dowolnej innej tablicy.
Środowisko funkcji można uzyskać przez funkcję getfenv(), a zmienić przez funkcję setfenv(); w Scribunto te funkcje są poważnie ograniczone jeśli w ogóle dostępne.
Local variables are lexically scoped; see Local variable declarations for details.
Wyrażenia
Wyrażenie to coś co ma wartość: literały (liczby, łańcuchy tekstowe, true, false, nil), deklaracje funkcji anonimowych, konstruktory tablic, odwołanie do zmiennych, wywołania funkcji, wyrażenia o zmiennej liczbie argumentów, wyrażenia w nawiasach, operatory jednoargumentowe przypisane do wyrażenia i wyrażenia połączone operatorem dwuargumentowym.
Większość wyrażeń ma jedną wartość; wywołania funkcji i wyrażenia o zmiennej liczbie argumentów mogą mieć dowolną liczbę wartości. Należy pamiętać, że umieszczenie wywołania funkcji lub wyrażenia o zmiennej liczbie argumentów w nawiasie powoduje utratę wszystkich wartości oprócz pierwszej.
Listy wyrażeń tworzy się oddzielając wyrażenia przecinkami. Wszystkie wyrażenia z wyjątkiem ostatniego są redukowane do jednej wartości (przez odrzucenie dodatkowych wartości lub użycie nil, gdy wyrażenie nie zwraca żadnej wartości); wszystkie wartości z ostatniego wyrażenia są umieszczane na liście wyrażeń.
Operatory arytmetyczne
Lua wspiera typowe operatory arytmetyczne: dodawanie, odejmowanie, mnożenie, dzielenie, modulo, potęgowanie i negację.
Jeśli wszystkie argumenty są liczbami lub łańcuchami tekstowymi, dla których tonumber() nie zwraca nil, działanie ma zwyczajowe znaczenie.
Jeśli dowolny argument jest tablicą z odpowiednią metametodą, to ta metametoda będzie wywołana.
Operator | Funkcja | Przykład | Metametoda | Uwagi |
---|---|---|---|---|
+ | Dodawanie | a + b | __add | |
- | Odejmowanie | a - b | __sub | |
* | Mnożenie | a * b | __mul | |
/ | Dzielenie | a / b | __div | dzielenie przez zero nie jest błędem; zwraca NaN lub nieskończoność |
% | Modulo | a % b | __mod | zdefiniowane jako a % b == a - math.floor( a / b ) * b
|
^ | Potęgowanie | a ^ b | __pow | dopuszczalne są argumenty niecałkowite |
- | Negacja | -a | __unm |
Operatory relacji
Operatorami relacyjnymi w Lua są ==
, ~=
, <
, >
, <=
i >=
. Wynikiem z tych operacji jest zawsze wartość logiczna.
Równość (==
) najpierw porównuje typy argumentów; jeśli są różne wynikiem jest fałsz. Następnie porównywane są wartości: nil, wartości logiczne, liczby i łańcuchy znakowe są porównywane w oczekiwany sposób. Funkcje są równe jeśli wskazują na dokładnie ten sam obiekt funkcyjny; function() end == function() end
zwróci fałsz, gdyż porównywane są dwie różne funkcje anonimowe. Tablice są porównywane domyślnie w ten sam sposób, jednak w ich przypadku można to zmienić stosując metametodę __eq.
Nierówność (~=
) jest dokładnym zaprzeczeniem równości.
Dla porządku operatorów, jeśli oba argumenty są liczbami lub łańcuchami tekstowymi, są one porównywane bezpośrednio. W następnej kolejności są sprawdzane metametody:
a < b
używa__lt
a <= b
używa__le
jeśli dostępne, lub jeśli__lt
jest dostępne to uznaje się zamiennikiem jestnot ( b < a )
a > b
uznawane jest za równoważne zb < a
a >= b
uznawane jest za równoważne zb <= a
Jeśli niezbędne metametody są niedostępne zgłaszany jest błąd.
Operatory logiczne
Operatorami logicznymi są and
(i), or
(lub) i not
(nie). Wszystkie stosują typową interpretację, w której nil i false jest uznawane za fałsz, a wszystko inne za prawdę.
W operatorze and
, jeśli lewy argument jest uznawany za fałsz, to jest on zwracany, a drugi (prawy) argument nie jest obliczany; w przeciwnym razie zwracany jest wynik drugiego argumentu.
W operatorze or
, jeśli lewy argument jest uznawany za prawdę, to jest on zwracany, a drugi (prawy) argument nie jest obliczany; w przeciwnym razie zwracany jest wynik drugiego argumentu.
Wynikiem operatora not
jest zawsze true lub false.
Należy wspomnieć o zwarciach dla and
i or
. Na przykład foo() or bar()
wywoła bar()
jeśli foo()
zwróci false lub nil jako swoją pierwszą wartość.
Operator połączenia
Operator połączenia to dwie kropki, używany jako a .. b
. Jeśli oba argumenty są liczbami lub łańcuchami tekstowymi, są one zamieniane na łańcuchy tekstowe i połączone. W przeciwnym razie jeśli jest dostępna metametoda __concat, to będzie ona użyta. W ostatecznym razie zgłaszany jest błąd.
Należy pamiętać, że łańcuchy tekstowe są obiektami niezmiennymi, a Lua nie dostarcza czegoś w rodzaju „string builder”, więc pętla, która powtarza a = a .. b
będzie tworzyła nowy łańcuch tekstowy w każdej iteracji, proces odśmiecania pamięci ewentualnie pousuwa stare łańcuch tekstowe. Jeśli wiele łańcuchów tekstowych wymaga połączenia, szybszą metodą może być zastosowanie string.format() lub umieszczenie wszystkich łańcuchów tekstowych w sekwencji i wywołaniu na samym końcu table.concat().
Operator długości
Operatorem długości jest #
, używany jako #a
. Jeśli a
jest łańcuchem tekstowym, to zwraca on długość w bajtach. Jeśli a
jest tablicą z sekwencją, to wynikiem jest długość sekwencji.
Jeśli a
jest tablicą, lecz nie sekwencją, #a
może zwrócić 0 lub dowolną wartość N >= 1, taką, że a[N] nie jest nil, a a[N+1] jest nil, nawet jeśli w tablicy znajdują się wartości różne od nil na wyższych indeksach. Na przykład,
-- To nie jest sekwencja, ponieważ a[3] to nil, a a[4] nie.
a = { 1, 2, nil, 4 }
-- To może podać 2 lub 4.
-- A nawet może się zmieniać mimo, że tablica nie jest modyfikowana.
mw.log( #a )
Kolejność wykonywania działań
Posortowana kolejność wykonywania działań w Lua od pierwszego do ostatniego:
^
not
#
-
(negacja)*
/
%
+
-
(odejmowanie)..
<
>
<=
>=
~=
==
and
or
Wśród jednego poziomu kolejności większość operatorów dwuargumentowych jest lewostronnie łączna, np. a / b / c
jest interpretowane jako (a / b) / c
. Potęgowanie i połączenie są prawostronnie łączne, np. a ^ b ^ c
jest interpretowane jako a ^ (b ^ c)
.
Wywołania funkcji
Wywołanie funkcji w Lua wygląda podobnie jak w większości innych języków: nazwa, po której jest lista argumentów w nawiasach:
func( lista-wyrażeń )
Tak jak zazwyczaj w listach wyrażeń w Lua ostatnie wyrażenie może dostarczyć wiele wartości.
Jeśli funkcja jest wywołana z mniejszą liczbą wartości na liście wyrażeń niż liczba argumentów, która znajduje się w definicji funkcji, to dodatkowe argumenty przyjmą wartość nil. Jeśli lista wyrażeń zawiera więcej wartości niż na liście argumentów funkcji, ponadmiarowe wartości są usuwane. Jest możliwe przekazanie do funkcji zmiennej liczby argumentów; więcej szczegółów w Deklaracje funkcji.
Lua także zezwala na bezpośrednie wywołanie funkcji będącej wynikiem np. func()()
. Jeśli wymagane jest bardziej złożone wyrażenie niż dostęp do zmiennej aby określić funkcję do wywołania to można stosować wyrażenia w nawiasach w miejscu zmiennej.
Lua ma lukier składniowy do dwóch typowych przypadków. Pierwszy to tablica używana jak obiekt, w którym funkcja jest wywoływana jak metoda obiektu. Składnia
table:name( lista-wyrażeń )
jest dokładnym zamiennikiem dla
table.name( table, lista-wyrażeń )
Drugi typowy przypadek to implementacja w Lua nazwanych argumentów jako przekazywanie tablicy zawierającej słownik nazwa-wartość jako jedynego pozycyjnego argumentu funkcji. W tym przypadku nawiasy dookoła listy argumentów mogą zostać pominięte. Ten sposób działa nawet jeśli do funkcji przekazywany jest pojedynczy literał łańcucha tekstowego. Na przykład wywołania
func{ arg1 = exp, arg2 = exp } func"string"
są równoważne z
func( { arg1 = exp, arg2 = exp } ) func( "string" )
Mogą one być łączone; następujące wywołania są równoważne:
table:name{ arg1 = exp, arg2 = exp } table.name( table, { arg1 = exp, arg2 = exp } )
Deklaracje funkcji
Składnia deklaracji funkcji wygląda następująco:
function nameoptional ( var-listoptional )
block
end
Wszystkie zmienne w var-list są lokalne w tej funkcji, z wartościami przypisanymi z listy wyrażeń w wywołaniu funkcji. Dodatkowe zmienne lokalne mogą być zadeklarowane wewnątrz bloku funkcji.
Kiedy funkcja jest wywołana, instrukcje w block są wykonywane po utworzeniu i przypisaniu odpowiednich zmiennych z var-list. Po osiągnięciu instrukcji powrotu blok jest opuszczany, a wartościom wyrażenia wywołania funkcji są przypisywane te, które zostały podane przez instrukcję powrotu. Jeśli wykonywanie instrukcji osiągnie koniec bloku funkcji bez napotkania instrukcji powrotu, wynik wyrażenia wywołania funkcji zawiera zero wartości.
Funkcje w Lua są domknięciami. Wspólnym idiomem jest deklaracja „prywatnych statycznych” zmiennych jako lokalnych w zakresie gdzie jest zadeklarowana funkcja. Na przykład,
-- To zwraca funkcję, która dodaje liczbę do jej argumentu
function makeAdder( n )
return function( x )
-- The variable n from the outer scope is available here to be added to x
return x + n
end
end
local add5 = makeAdder( 5 )
mw.log( add5( 6 ) )
-- drukuje 11
Można zadeklarować funkcję, która akceptuje zmienną liczbę argumentów przez użycie ...
na samym końcu var-list:
Wewnątrz bloku można użyć zmiennoargumentowego wyrażenia ...
, którego wynikiem są wszystkie dodatkowe wartości wywołania funkcji. Na przykład,
local join = function ( separator, ... )
-- get the extra arguments as a new table
local args = { ... }
-- get the count of extra arguments, correctly
local n = select( '#', ... )
return table.concat( args, separator, 1, n )
end
join( ', ', 'foo', 'bar', 'baz' )
-- zwraca łańcuch tekstowy „foo, bar, baz”
Funkcja select() jest przeznaczona do pracy z wyrażeniem zmiennoargumentowym; w szczególności należy używać select( '#', ... )
zamiast #{ ... }
aby wyznaczyć liczbę wartości w wyrażeniu zmiennoargumentowym ponieważ { ... }
może nie być sekwencją.
Lua dostarcza lukier składniowy do łączenia deklaracji funkcji z przypisaniem do zmiennej; zobacz szczegóły w instrukcji deklaracji funkcji.
Uwaga, taka konstrukcja nie działa:
local factorial = function ( n )
if n <= 2 then
return n
else
return n * factorial( n - 1 )
end
end
Z uwagi na to, że deklaracja funkcji jest przetwarzana zanim dokona się przypisanie do zmiennej lokalnej, „factorial” wewnątrz ciała funkcji odwołuje się do (prawdopodobnie niezdefiniowanej) zmiennej o tej nazwie z zewnętrznego zakresu. Tego problemu można uniknąć deklarując zmienną najpierw, a następnie przypisując ją w następnej instrukcji, lub stosując składnię instrukcji deklaracji funkcji.
Instrukcje
Instrukcja to podstawowa jednostka wykonywanego programu: jedno przypisanie, struktura kontrolne, wywołanie funkcji, deklaracja zmiennej, itp.
Fragment to sekwencja instrukcji opcjonalnie oddzielonych średnikami. Fragment jest w zasadzie uważany za ciało anonimowej funkcji, dzięki czemu może ona deklarować zmienne lokalne, przyjmować argumenty i zwracać wartości.
Blok jest również sekwencją instrukcji jak fragment. Blok może być ograniczony aby utworzyć pojedynczą instrukcję: do block end
. Ta forma może być stosowana aby ograniczyć zakres zmiennych lokalnych lub dodać return
bądź break
w środku innego bloku.
Przypisania
lista-zmiennych = lista-wyrażeń
lista-zmiennych to lista zmiennych oddzielonych przecinkami; lista-wyrażeń to lista z co najmniej jednym wyrażeniem, również oddzielanych przecinkami. Wszystkie wyrażenia są wyznaczane, zanim zostanie wykonane jakiekolwiek przypisanie, więc a, b = b, a
spowoduje, że zmienne a i b wymienią się na wzajem swoimi wartościami.
Deklaracje zmiennych lokalnych
local lista-zmiennych
local lista-zmiennych = lista-wyrażeń
Zmienne lokalne można deklarować gdziekolwiek wewnątrz bloku lub fragmentu. Pierwsza forma, bez listy wyrażeń, deklaruje zmienne lecz nie przypisuje do nich wartości, więc zmienne mają wartość nil. Druga forma przypisuje wartości do zmiennych lokalnych tak jak to opisano w przypisaniach powyżej.
Należy pamiętać, że widoczność zmiennej zaczyna się w instrukcji po deklaracji zmiennej. Stąd deklaracja taka jak local x = x
deklaruje zmienną lokalną x i przypisuje do niej wartość x z zewnętrznego zakresu. Zmienna lokalna pozostaje w zakresie, aż do końca najgłębszego bloku zawierającego deklarację tej zmiennej lokalnej.
Struktury kontrolne
while exp do blok end
Instrukcja while
powtarza blok tak długo jak długo prawdziwe jest wyrażenie exp.
repeat blok until exp
Instrukcja repeat
powtarza blok do momentu gdy wyrażenie exp stanie się prawdziwe. Zmienne lokalne zadeklarowane wewnątrz bloku mogą być używane przez wyrażenie exp.
for name = exp1, exp2, exp3 do blok end
for name = exp1, exp2 do blok end
Pierwsza forma pętli for
zadeklaruje zmienną lokalną i powtórzy blok dla wartości od exp1 do exp2 dodając exp3 po każdej iteracji. Uwaga, wyrażenie exp3 można całkowicie pominąć, w takim przypadku zostanie domyślnie użyte 1, lecz użycie wartości pozaliczbowych takich jak nil
i false
jest błędem. Wszystkie wyrażenia są obliczane raz przed uruchomieniem pętli.
Forma pętli for
jest mniej więcej równoważna do
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
z wyjątkiem, że zmienne var, limit i step są niedostępne nigdzie indziej. Należy zauważyć, że zmienna name jest lokalna wewnątrz bloku; aby móc z niej skorzystać po wyjściu z pętli musi ona być skopiowana do zmiennej zadeklarowanej na zewnątrz pętli.
for lista-zmiennych in lista-wyrażeń do blok end
Druga forma pętli for
pracuje z funkcjami „iteratora”. Tak jak w pierwszej formie lista-wyrażeń jest rozwijana tylko raz przed uruchomieniem pętli.
Ta forma pętli for
jest mniej więcej równoważna do
do
local func, static, var = expression-list
while true do
local var-list = func( static, var )
var = var1 -- ''var1'' is the first variable in ''var-list''
if var == nil then
break
end
block
end
end
z ponownym wyjątkiem, że zmienne func, static i var nie są dostępne nigdzie indziej. Należy pamiętać, że zmienne w lista-zmiennych są lokalne dla bloku; aby je użyć po wyjściu z pętli muszą one być skopiowane do zmiennych zadeklarowanych na zewnątrz pętli.
Często lista-wyrażeń jest pojedynczym wywołaniem funkcji, która zwraca trzy wartości. Jeśli funkcja iteratora może być napisana tak, że zależy jedynie od parametrów do niej przekazanych, to jest najbardziej optymalne rozwiązanie. Jeśli nie, Podręcznik Lua sugeruje, żeby domknięcie zwracało tablicę jako statyczną zmienną i aktualizowało jej zawartość po każdej iteracji.
if exp1 then blok1 elseif exp2 then blok2 else blok3 end
Wykona blok1 jeśli wyrażenie exp1 jest prawdziwe, w przeciwnym razie wykona blok2 jeśli wyrażenie exp2 jest prawdziwe, ostatecznie wykona blok3. Część else blok3
można pominąć lub część elseif exp2 then blok2
powtórzyć lub pominąć jeśli to konieczne.
return lista-wyrażeń
Instrukcja return
służy do zwracania wartości z funkcji lub fragmentu (który jest właściwie funkcją). Natomiast lista-wyrażeń to nawet pusta lista wyrażeń oddzielanych przecinkiem.
Lua implementuje rekurencję ogonową: jeśli lista-wyrażeń składa się z dokładnie jednego wyrażenia, które jest wywołaniem funkcji, bieżąca ramka stosu będzie ponownie wykorzystana na wykonanie wywołania tejże funkcji. To ma wpływ na funkcje, które operują na wywołaniach na stosie takie jakgetfenv()
i debug.traceback()
.
Instrukcja powrotu musi być ostatnią instrukcją w bloku. Jeśli z jakiegoś powodu wymagany jest powrót w środku bloku można użyć formalnego bloku do return end
.
break
Instrukcja przerwania jest używana do zakończenia wykonywania pętli while
, repeat
lub for
, pomijając wszystkie instrukcje aż do pierwszej instrukcji poza pętlą.
Instrukcja przerwania musi być ostatnią instrukcją w swoim bloku. Jeśli z jakiegoś powodu jest potrzeba przerwania gdzieś w środku bloku można użyć formalnego bloku do break end
.
Unlike some other languages, Lua does not have a "continue" statement for loops (i.e. a statement to move onto the next iteration without breaking the loop altogether).
It is straightforward to achieve the same effect by nesting a repeat ... until true
block immediately inside the main loop, which will only ever iterate once for each iteration of the main loop (as its condition is always true).
Using break
will only end the inner loop, which has the practical effect of causing the main loop to continue onto the next iteration.
If it is necessary to use break
on the main loop, simply declare a variable which is checked each time the inner loop completes, and set it when necessary.
Wywołanie funkcji jako instrukcji
Funkcje można wywołać jak instrukcję; w takim przypadku funkcja jest wywołana tylko na potrzeby wszelkich efektów ubocznych jakie dostarcza (np. mw.log() loguje wartości) a jakiekolwiek zwracane wyniki są odrzucane.
Instrukcja deklaracji funkcji
Lua dostarcza lukier składniowy na bardziej naturalne deklarowanie funkcji i przypisywanie jej do zmiennej. Następujące pary deklaracji są równoważne
-- Basic declaration function func( var-list ) block end func = function ( var-list ) block end
-- Local function local function func( var-list ) block end local func; func = function ( var-list ) block end
-- Function as a field in a table function table.func( var-list ) block end table.func = function ( var-list ) block end
-- Function as a method in a table function table:func( var-list ) block end table.func = function ( self, var-list ) block end
Note the colon notation here parallels the colon notation for function calls, adding an implicit argument named self
at the beginning of the arguments list.
Obsługa błędów
Błędy można „rzucać” stosując funkcje error() i assert(). Do „złapania” błędów można użyć pcall() lub xpcall(). Należy pamiętać, że pewne wewnętrzne błędy Scribunto są nieprzechwytywalne w kodzie Lua.
Odśmiecanie pamięci
Lua prowadzi automatyczne zarządzanie pamięcią. To oznacza, że nie trzeba się martwić ani alokowaniem pamięci na nowe obiekty, ani jej zwalnianiem, kiedy obiekty stają się niepotrzebne. Lua zarządza pamięcią dzięki uruchamianiu od czasu do czasu „procesu odśmiecania pamięci” aby zebrać wszystkie martwe obiekty (to jest takie, które są już niedostępne z Lua) i obiekty, które są osiągalne już tylko przez słabe referencje. Cała pamięć używana w Lua podlega automatycznemu zarządzaniu: tablice, funkcje, łańcuchy tekstowe, itd.
Odśmiecanie pamięci zdarza się automatycznie i nie ma możliwości jego konfiguracji w Scribunto.
Biblioteki standardowe
Standardowe biblioteki Lua zapewniają niezbędne usługi i krytyczne wydajnościowo funkcje dla Lua. Tutaj jest udokumentowana tylko ta część, która jest dostępna w Scribunto.
Podstawowe funkcje
_G
Ta zmienna przechowuje referencję do głównej tablicy zmiennych globalnych; zmienna globalna foo
może być również osiągalna jako _G.foo
. Jednak należy pamiętać, że w _G nie ma nic specjalnego, i można tę zmienną nadpisać jak każdą inną.
foo = 1
mw.log( foo ) -- logs "1"
_G.foo = 2
mw.log( foo ) -- logs "2"
_G = {} -- _G no longer points to the global variable table
_G.foo = 3
mw.log( foo ) -- still logs "2"
Tablica zmiennych globalnych może być używana jak każda inna tablica. Na przykład
-- Call a function whose name is stored in a variable
_G[var]()
-- Log the names and stringified values of all global variables
for k, v in pairs( _G ) do
mw.log( k, v )
end
-- Log the creation of new global variables
setmetatable( _G, {
__newindex = function ( t, k, v )
mw.log( "Creation of new global variable '" .. k .. "'" )
rawset( t, k, v )
end
} )
_VERSION
Łańcuch tekstowy zawierający uruchomioną wersję Lua, np. „Lua 5.1”.
assert
assert( v, message, ... )
Jeśli v
to nil lub false
, to zgłasza błąd. W takim przypadku message
jest używany jako treść błędu: dla nil (lub braku) domyślny tekst to „assertion failed!”; dla łańcucha tekstowego lub liczby treść jest tą wartością; inne wartości powodują, że funkcja assert zgłosi błąd.
Jeśli v
jest dowolną inną wartością, assert zwraca wszystkie argumenty włączając w to v
i message
.
Pewnym typowym idiomem dla funkcji w Lua jest to, że zwraca wartość „true” w normalnym działaniu, a w przypadku błędu wynikiem jest nil lub „false” jako pierwsza wartość i komunikat błędu jako druga wartość. To umożliwia łatwe sprawdzanie błędów przez opakowanie wywołania w funkcję assert
.
-- This doesn't check for errors
local result1, result2, etc = func( ... )
-- This works the same, but does check for errors
local result1, result2, etc = assert( func( ... ) )
error
error( message, level )
Zgłasza błąd o treści message
.
error
zwykle dodaje pewne informacje o miejscu błędu. Jeśli level
to 1 lub jest pominięty, dodawana informacja jest o miejscu wywołania funkcji error
; 2 używa miejsca wywołania funkcji, która zgłosiła błąd; i tak dalej. Przekazanie 0 wyłącza wstawianie informacji o miejscu.
getfenv
getfenv( f )
Uwaga! Ta funkcja może być niedostępna. To zależy od nastawy allowEnvFuncs
w konfiguracji silnika.
Zwraca środowisko (tablica zmiennych globalnych) tak jak to określa f
:
- Jeśli 1, nil lub pominięte to zwraca środowisko funkcji wywołującej
getfenv
. Często będzie to to samo co _G. - Liczby całkowite 2–10 zwracają środowisko funkcji wyżej na stosie wywołań. Na przykład 2 zwraca środowisko dla funkcji, która wywołała bieżącą funkcję, 3 zwraca środowisko dla funkcji, która wywołała tamtą funkcję i tak dalej. Jeśli wartość jest większa niż liczba funkcji na stosie wywołań lub zostanie osiągnięty poziom z rekurencją ogonową to zgłoszony będzie błąd.
- Przekazanie funkcji zwraca środowisko, które będzie użyte, kiedy ta funkcja będzie wywołana.
Środowiska używane przez funkcje biblioteki standardowej i funkcje biblioteki Scribunto są chronione. Próba dostępu do tych środowisk przez getfenv
zwraca nil zamiast środowiska.
getmetatable
getmetatable( table )
Zwraca metatablicę z tablicy. Dla każdego innego typu zwraca nil.
Jeśli metatablica ma pole __metatable
, to jego wartość będzie zwrócona zamiast rzeczywistej metatablicy.
ipairs
ipairs( t )
Zwraca trzy wartości: funkcję iteratora, tablicę t
i 0. To ma na celu używanie w iterowanej postaci pętli for
:
for i, v in ipairs( t ) do
-- process each index-value pair
end
To będzie iterowało po parach ( 1, t[1] ), ( 2, t[2] ), itd., zatrzymując się kiedy t[i] będzie nil.
Standardowe zachowanie może być zmienione przez dostarczenie metametody __ipairs
. Jeśli ta metametoda istnieje to wywołanie ipairs zwróci trzy wartości uzyskane przez __ipairs( t )
zamiast domyślnych.
next
next( table, key )
To pozwala na iterowanie po kluczach w tablicy. Jeśli key
to nil lub nie jest podane to funkcja zwraca „pierwszy” klucz w tabeli i jego wartość; w przeciwnym razie zwraca „następny” klucz i jego wartość. Kiedy nie ma już więcej kluczy, funkcja zwraca nil. Do sprawdzenia czy tablica jest pusta można zastosować kod next( t ) == nil
.
Należy pamiętać, że kolejność, w której są zwracane klucze, nie jest określona, nawet dla tablic z liczbowym indeksem. Aby przejrzeć tablicę w kolejności numerycznej trzeba użyć pętli numerycznej lub ipairs.
Behavior is undefined if, when using next for traversal, any non-existing key is assigned a value. Assigning a new value (including nil) to an existing field is allowed.
pairs
pairs( t )
Zwraca trzy wartośći: funkcję iteratora (next lub działającą podobnie), tablicę t
i nil. To ma na celu używanie w iterowanej postaci pętli for
:
for k, v in pairs( t ) do
-- process each key-value pair
end
To iteruje po parach klucz-wartość w t
tak podobnie do next; zobacz dokumentację do next w celu poznania ograniczeń na temat modyfikacji tablicy podczas iterowania.
Standardowe zachowanie może być zmienione przez dostarczenie metametody __pairs. Jeśli ta metametoda istnieje to wywołanie funkcji pairs zwróci trzy wartości uzyskane przez __pairs( t )
zamiast domyślnych.
pcall
pcall( f, ... )
Wywołuje funkcję f
z podanymi argumentami w trybie chronionym. To oznacza, że jeśli zostanie zgłoszony błąd podczas wywołania f
, funkcja pcall zwróci false
i komunikat zgłoszonego błędu. Jeśli błąd się nie pojawi, funkcja pcall zwróci true
i wszystkie wartości zwracane przez wywołaną funkcję.
W pseudokodzie, pcall
może być zdefiniowane podobnie do:
function pcall( f, ... )
try
return true, f( ... )
catch ( message )
return false, message
end
end
rawequal
rawequal( a, b )
To jest równoważne do a == b
z takim wyjątkiem, że ignoruje dowolną metametodę __eq.
rawget
rawget( table, k )
To jest równoważne do tablica[k]
z takim wyjątkiem, że ignoruje dowolną metametodę __index.
rawset
rawset( table, k, v )
To jest równoważne do table[k] = v
z takim wyjątkiem, że ignoruje dowolną metametodę __newindex.
select
select( index, ... )
Jeśli indeks
jest liczbą, to zwraca wszystkie argumenty w ...
po tym indeksie. Jeśli indeks
jest łańcuchem tekstowym '#', to zwraca liczbę argumentów w ...
.
If index
is the string "#"
, returns the number of arguments in ...
.
Note: unlike tables, lists of arguments (including the vararg expression ...
) treat nil
as a distinct value (see documentation for # and unpack for the problem with nil
in tables). For example:
select(2, "foo", "bar")
returns"bar"
.select(2, "foo", nil, "bar", nil)
returnsnil, "bar", nil
.select("#", "foo", "bar")
returns2
.select("#", "foo", "bar", nil)
returns3
.
Innymi słowy select
to coś mniej więcej poniżej z takim wyjątkiem, że działa prawidłowo nawet jeśli ...
zawiera wartości nil (zobacz dokumentację dla # i unpack wskazującą na takie problemy).
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 )
Ustawia metatablicę w tablicy. metatablica
może być nil, lecz musi być jawnie dostarczona.
If the current metatable has a __metatable field, setmetatable
will throw an error.
tonumber
tonumber( value, base )
Próbuje zamienić wartość
na liczbę. Jeśli to już jest liczba lub łańcuch tekstowy zamienialny na liczbę, to tonumber
zwraca tę liczbę; w przeciwnym razie zwraca nil.
Opcjonalna podstawa
(domyślnie 10) określa podstawę systemu pozycyjnego do interpretacji liczby. Podstawa może przyjąć wartości całkowite od 2 do 36 włącznie. Dla podstaw większych od 10, litera 'A' (wielka lub mała) oznacza 10, 'B' oznacza 11, itd. aż do 'Z' oznaczającego 35.
Dla podstawy 10, wartość może mieć ułamek dziesiętny, być wyrażona w notacji naukowej, i mieć przedrostek „0x” aby wskazać podstawę 16. Dla innych podstaw akceptowane są tylko liczby całkowite bez znaku.
tostring
tostring( value )
Zamienia value
na łańcuch tekstowy. Zobacz Typy danych powyżej, aby zobaczyć szczegóły jak poszczególne typy są zamieniane.
Standardowe zachowanie dla tablic może być zmienione przez dostarczenie metametody __tostring. Jeśli taka metametoda istnieje to wywołanie funkcji tostring zwróci pojedynczą wartość uzyskaną przez __tostring( value )
zamiast domyślnej.
type
type( value )
Zwraca typ wartości value
jako łańcuch tekstowy: "nil"
, "number"
, "string"
, "boolean"
, "table"
lub "function"
.
unpack
unpack( table, i, j )
Zwraca wartości z podanej tablicy, coś jak table[i], table[i+1], ···, table[j]
gdyby to zapisać ręcznie. Domyślną wartością dla i
jest 1, a dla j
to #table
, które są również przyjmowane gdy przekazane zostanie nil.
If the table does not have a value for a particular key, unpack will return nil for that value. For example, unpack({"foo", [3] = "bar"}, 1, 4)
returns "foo", nil, "bar", nil
.
Należy pamiętać, że wyniki nie są deterministyczne jeśli table
nie jest sekwencją, a j
jest nil lub niepodane; zobacz szczegóły w sekcji Operator długości.
xpcall
xpcall( f, errhandler )
Prawie to samo co pcall
z takim wyjątkiem, że komunikat błędu jest przekazany do funkcji errhandler
przed powrotem.
W pseudokodzie xpcall
może być zdefiniowane podobnie do:
function xpcall( f, errhandler )
try
return true, f()
catch ( message )
message = errhandler( message )
return false, message
end
end
Biblioteka diagnostyczna
debug.traceback
debug.traceback( komunikat, poziom )
Zwraca łańcuch tekstowy z raportem ze ścieżką wywołań na stosie. Opcjonalny łańcuch tekstowy z komunikatem jest umieszczany na początku raportu. Opcjonalny numer poziomu określa od którego poziomu wywołań stosu rozpocząć tworzenie raportu.
Biblioteka matematyczna
math.abs
math.abs( x )
Zwraca moduł liczby x
.
math.acos
math.acos( x )
Zwraca arcus cosinus z x
(w radianach)
math.asin
math.asin( x )
Zwraca arcus sinus z x
(w radianach)
math.atan
math.atan( x )
Zwraca arcus tangens z x
(w radianach)
math.atan2
math.atan2( y, x )
Zwraca arcus tangens z y/x
(w radianach), używając znaków z obu argumentów aby ustalić właściwą ćwiartkę wyniku.
math.ceil
math.ceil( x )
Zwraca najmniejszą liczbę całkowitą większą lub równą x
.
math.cos
math.cos( x )
Zwraca cosinus z x
(w radianach)
math.cosh
math.cosh( x )
Zwraca cosinus hiperboliczny z x
.
math.deg
math.deg( x )
Zamienia kąt x
z radianów na stopnie.
math.exp
math.exp( x )
Zwraca wartość .
math.floor
math.floor( x )
Zwraca największą liczbę całkowitą mniejszą lub równą x
.
math.fmod
math.fmod( x, y )
Zwraca resztę z dzielenia x
przez y
zaokrąglając iloraz w kierunku zera. Na przykład math.fmod( 10, 3 )
dają 1
.
math.frexp
math.frexp( x )
Zwraca dwie wartości m
i e
takie, że:
- Jeśli
x
jest skończone i różne od zera: , gdziee
jest liczbą całkowitą, a modułm
mieści się w przedziale - Jeśli
x
jest zerem:m
ie
są równe 0 - Jeśli
x
to NaN lub nieskończoność:m
równa sięx
, ae
jest nieokreślone
math.huge
Wartość oznaczająca dodatnią nieskończoność; większa lub równa od dowolnej innej wartości liczbowej.
math.ldexp
math.ldexp( m, e )
zwraca (e
powinien być liczbą całkowitą).
math.log
math.log( x )
Zwraca logarytm naturalny z x
.
math.log10
math.log10( x )
Zwraca logarytm dziesiętny z x
.
math.max
math.max( x, ... )
Zwraca największą wartość z podanych argumentów.
Zachowanie z argumentami NaN jest nieokreślone. W bieżącej implementacji zwrócone będzie NaN jeśli x
jest równe NaN, lecz wszystkie pozostałe wartości NaN będą zignorowane.
math.min
math.min( x, ... )
Zwraca najmniejszą wartość z podanych argumentów.
Zachowanie z argumentami NaN jest nieokreślone. W bieżącej implementacji zwrócone będzie NaN jeśli x
jest równe NaN, lecz wszystkie pozostałe wartości NaN będą zignorowane.
math.modf
math.modf( x )
Zwraca dwie liczby, część całkowitą z x
i część ułamkową z x
. Na przykład math.modf( 1.25 )
dają 1, 0.25
.
math.pi
Zwraca wartość .
math.pow
math.pow( x, y )
Równoważne z x^y
.
math.rad
math.rad( x )
Zamienia wartość kąta x
ze stopni na radiany.
math.random
math.random( m, n )
Zwraca liczbę pseudolosową.
Argumenty m
i n
można pominąć, lecz jeśli są podane to muszą być zamienialne na liczby całkowite.
- Bez argumentów zwraca liczbę rzeczywistą z przedziału
- Z jednym argumentem zwraca liczbę całkowitą z przedziału
- Z dwoma argumentami zwraca liczbę całkowitą z przedziału
Note that incorrect output may be produced if m
or n
are less than −2147483648 or greater than 2147483647, or if n - m
is greater than 2147483646.
math.randomseed
math.randomseed( x )
Ustawia x
jako ziarno dla generatora liczb pseudolosowych.
Należy pamiętać, że używanie tego samego ziarna spowoduje, że math.random
będzie generowało takie same sekwencje liczb.
math.randomseed( tonumber( mw.getContentLanguage():formatDate( "U" ) ) * 10000 + os.clock() * 10000 )
math.sin
math.sin( x )
Zwraca sinus z x
(w radianach)
math.sinh
math.sinh( x )
Zwraca sinus hiperboliczny z x
.
math.sqrt
math.sqrt( x )
Zwraca pierwiastek kwadratowy z x
. Równoważne z x^0.5
.
math.tan
math.tan( x )
Zwraca tangens z x
(w radianach).
math.tanh
math.tanh( x )
Zwraca tangens hiperboliczny z x
.
Biblioteka systemu operacyjnego
os.clock
os.clock()
Zwraca przybliżony czas w sekundach używania procesora przez program.
os.date
os.date( format, time )
- Dla bardziej wszechstronnego formatowania daty można skorzystać z
formatDate
z biblioteki językowej
Zwraca łańcuch tekstowy lub tablicę zawierającą datę i czas sformatowane zgodnie z formate w format
. Jeśli format jest pominięty lub nil to będzie użyty „%c”.
Jeśli podano time
, to będzie on sformatowany (zobacz os.time()
). W przeciwnym razie zostanie użyty czas bieżący.
Jeśli format
zaczyna się na '!' to data będzie sformatowana jako UTC zamiast lokalnego czasu serwera. Jeśli po tym opcjonalnym znaku znajduje się łańcuch „*t” to funkcja zwraca tablicę z następującymi polami:
- year (pełny rok)
- month (miesiąc: 1–12)
- day (dzień: 1–31)
- hour (godzina: 0–23)
- min (minuta: 0–59)
- sec (sekunda: 0–60) (dopuszcza sekundę przestępną)
- wday (dzień tygodnia: niedziela to 1)
- yday (numer dnia w roku)
- isdst (flaga czasu letniego, zmienna logiczna; pole może nie istnieć jeśli taka informacja nie jest dostępna)
Jeśli format jest różny od „*t” to funkcja zwraca datę jako łańcuch tekstowy sformatowany zgodnie z regułami takimi jak w funkcji C strftime.
os.difftime
os.difftime( t2, t1 )
Zwraca liczbę sekund między t1
a t2
.
os.time
os.time( table )
Zwraca liczbę reprezentującą bieżący czas.
Funkcja wywołana bez argumentów zwraca bieżący czas. Jeśli przekazana zostanie tablica to czas zakodowany w tablicy będzie sparsowany. Tablica musi mieć pola „year”, „month” i „day” oraz może zawierać pola „hour” (domyślnie 12), „min” (domyślnie 0), „sec” (domyślnie 0) i „isdst”.
Biblioteka pakietów
require
require( modulename )
Ładuje określony moduł.
Najpierw zagląda do package.loaded[nazwamodułu]
żeby sprawdzić czy moduł już jest załadowany. Jeśli tak to zwraca package.loaded[nazwamodułu]
.
W przeciwnym razie wywołuje każdą ładowarkę z sekwencji package.loaders
aby spróbować znaleźć ładowarkę modułu. Jeśli ładowarka jest znaleziona to jest ona wywołana. Wartość uzyskana z ładowarki jest umieszczana w package.loaded[nazwamodułu]
i zwracana.
Zobacz dokumentację dla package.loaders
na temat dostępnych ładowarek.
Na przykład jeśli masz moduł „Module:Giving” zawierający co następuje:
local p = {}
p.someDataValue = 'Hello!'
return p
Możesz go załadować w innym module w następujący sposób:
local giving = require( "Module:Giving" )
local value = giving.someDataValue -- value is now 'Hello!'
package.loaded
Ta tablica przetrzymuje załadowane moduły. Klucze są nazwami modułów, a wartości to wyniki zwracane kiedy moduł był załadowany.
package.loaders
Ta tablica przetrzymuje sekwencję funkcji wyszukujących, które są używane kiedy moduły są ładowane. Każda funkcja wyszukująca jest wywoływana z jednym argumentem, nazwą modułu do załadowania. Jeśli moduł jest znaleziony to wyszukiwarka musi zwrócić funkcję, która dokona właściwego załadowania modułu i zwróci wartość, która będzie wynikiem dla require. W przeciwnym razie musi zwracać nil.
Scribuno dostarcza dwie wyszukiwarki:
- Wyszukiwanie w
package.preload[nazwamodułu]
żeby znaleźć funkcję ładowarki - Wyszukiwanie w modułach dostarczanych przez Scribunto aby znaleźć nazwę modułu, a jeśli to zawiedzie to wyszukiwanie w przestrzeni nazw Moduł:. Przedrostek „Moduł:” (albo „Module:”) jest obowiązkowy.
Należy pamiętać, że standardowe ładowarki Lia nie są dostępne.
package.preload
This table holds loader functions, used by the first searcher Scribunto includes in package.loaders.
package.seeall
package.seeall( table )
Ustawia metametodę __index na _G.
Biblioteka łańcuchów tekstowych
We wszystkich łańcuchach tekstowych pierwszy znak jest na pozycji 1, nie 0 jak w C, PHP czy JavaScript. Indeksy mogą być ujemne, w takim przypadku są odliczane od końca łańcucha tekstowego; -1 to ostatni znak w łańcuchu tekstowym, -2 to przedostatni znak, itd.
Uwaga: Biblioteka łańcuchów tekstowych zakłada, że kodowanie znaków jest jednobajtowe. Nie radzi sobie ze znakami w Unikodzie. Aby pracować z Unikodowymi łańcuchami tekstowymi należy skorzystać z odpowiednich metod w biblioteki Scribunto Ustring.
string.byte
string.byte( s, i, j )
Jeśli łańcuch tekstowy jest rozważany jako tablica bajtów to funkcja zwraca bajtowe wartości dla s[i]
, s[i+1]
, ···, s[j]
.
Domyślna wartość dla i
to 1;
domyślna wartość dla j
to i
.
Identycznie z mw.ustring.byte().
string.char
string.char( ... )
Przyjmuje zero lub więcej liczb całkowitych. Zwraca łańcuch tekstowy o długości równej liczbie argumentów, w którym każdy znak ma wartość bajtu równą z odpowiednim przekazanym argumentem.
local value = string.char( 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x21 ) --value is now 'Hello!'
Zobacz mw.ustring.char(), która jest podobną funkcją jednak operującą na znakach kodowanych w Unikodzie zamiast na bajtach.
string.find
string.find( s, pattern, init, plain )
Szuka pierwszego wystąpienia wartości pattern
w łańcuchu tekstowym s
. Jeśli znajdzie wystąpienie to find
zwraca pozycje w s
, gdzie to wystąpienie się zaczyna i kończy; w przeciwnym razie zwraca nil. Jeśli wzór ma grupy przechwytywania, to pomyślne odszukanie zwraca również te grupy po dwóch indeksach.
Trzeci opcjonalny liczbowy argument początek
określa gdzie rozpocząć wyszukiwanie; domyślną wartością jest 1, a może być ujemne. Wartość true
jako czwarty argument zwykły
wyłącza wsparcie wyrażeń regularnych, czyli funkcja pracuje w trybie zwykłego „wyszukiwania podłańcucha tekstowego”, bez uznawania znaków w argumencie wzór
jako „magicznych”.
Należy pamiętać, że jeśli argument zwykły
jest podany, to musi być również podany argument początek
.
Zobacz mw.ustring.find(), która jest podobną funkcją rozszerzającą możliwości tak jak to opisano we Wzory Ustring, oraz gdzie indeks początek
jest obliczany według pozycji znaków a nie bajtów.
string.format
string.format( formatstring, ... )
Zwraca sformatowaną wersję z podanej dynamicznej liczby argumentów następującej po podanym w pierwszym argumencie przepisie, który musi być łańcuchem tekstowym.
Tekstowy łańcuch formatujący używa ograniczonego podzbioru specyfikatorów z funkcji printf
:
- Rozpoznawane flagi to '-', '+', ' ', '#', i '0'.
- Wspierane są szerokości pól jako liczby całkowite aż do 99. '*' nie jest wspierana.
- Wspierane są wartości precyzji jako liczby całkowite aż do 99. '*' nie jest wspierana.
- Modyfikatory długości nie są wspierane.
- Rozpoznawane znaczniki konwersji to 'c', 'd', 'i', 'o', 'u', 'x', 'X', 'e', 'E', 'f', 'g', 'G', 's', '%', i niestandardowy 'q'.
- Wskaźniki pozycji (np. „%2$s”) nie są wspierane.
Znacznik konwersji 'q' jest jak 's', lecz formatuje łańcuch tekstowy w postaci odpowiedniej do bezpiecznego powtórnego odczytania przez interpreter Lua: łańcuch tekstowy jest zapisany miedzy podwójnymi cudzysłowami, a wszystkie podwójne cudzysłowy, nowe linie, bajty zerowe, ukośniki są prawidłowo zamienione na sekwencje specjalne podczas zapisywania wyniku.
Zamiana między łańcuchami tekstowymi a liczbami jest przeprowadzana tak jak to zostało wyspecyfikowane w sekcji Typy danych; inne typy nie są automatycznie zamieniane na łańcuchy tekstowe. Łańcuchy tekstowe zawierające znak NUL (bajtowa wartość 0) nie są obsługiwane prawidłowo.
Identyczne z mw.ustring.format().
string.gmatch
string.gmatch( s, pattern )
Zwraca funkcję iteratora, która w każdym wywołaniu zwraca następne znalezione grupy zdefiniowane przez wzrór
podczas przeszukiwania s
. Jeśli wzór
nie definiuje żadnej grupy, to zwracany jest pełny znaleziony podłańcuch tekstowy w każdym wywołaniu.
Dla tej funkcji '^
' na początku wzoru nie jest magiczny, gdyż w przeciwnym razie to by uniemożliwiło iterację. Jest on traktowany jak dosłowny znak.
Zobacz podobną funkcję mw.ustring.gmatch(), w której wzór jest rozszerzony jak opisano w sekcji Wzory Ustring.
string.gsub
string.gsub( s, pattern, repl, n )
Zwraca kopię s
, w którym wszystkie (lub pierwsze n
, jeśli podano) wystąpienia podtekstu określonego przez wzór
są zamienione przez łańcuch tekstowy określony przez zam
, który może być łańcuchem tekstowym, tablicą lub funkcją. Funkcja gsub
zwraca również drugą wartość, całkowitą liczbę znalezionych wystąpień podanego wzoru.
Jeśli zam
jest łańcuchem tekstowym, to jego wartość jest używana jako zamiennik. Znak %
rozpoczyna sekwencję specjalną: każdy ciąg w zam
w postaci %n
,
z n pomiędzy 1 i 9, oznaczającą wartość n-tej znalezionej grupy. Ciąg %0
oznacza pełne znalezione wyrażenie, a %%
oznacza pojedynczy %
.
Jeśli zam
jest tablicą, to tablica jest zapytywana dla każdego odnalezionego wyrażenia, używając pierwszej grupy jako klucza; jeśli wzór nie określa żadnej grupy, to pełne wyrażenie jest używane jako klucz.
Jeśli zam
jest funkcją, to ta funkcja jest wywoływana za każdym razem jak znalezione jest wyrażenie, wraz ze znalezionymi grupami jako argumentami w tej samej kolejności; jeśli wzór nie określa żadnych grup, to pełne znalezione wyrażenie jest przekazane jako pojedynczy argument.
Jeśli wartość otrzymana z odczytu tablicy lub wywołania funkcji jest łańcuchem tekstowym lub liczbą, to jest ona używana jako zamiennik; w przeciwnym razie jeśli jest fałszem lub nil, to zamiana nie jest dokonywana (to znaczy, że oryginalny tekst pozostanie w miejscu znalezionego wyrażenia).
Zobacz podobną funkcję mw.ustring.gsub(), w której wzór jest rozszerzony jak opisano w Wzory Ustring.
string.len
string.len( s )
Zwraca długość łańcucha tekstowego w bajtach. Nie zaburzają jej znaki ASCII NUL. Równoważna z #
.
Zobacz podobną funkcję mw.ustring.len(), która używa znaków Unikod, zamiast bajtów.
string.lower
string.lower( s )
Zwraca kopię łańcucha tekstowego, w którym wszystkie wielkie litery ASCII są zamienione na małe. Wszystkie inne znaki są pozostawione bez zmian.
Zobacz podobną funkcję mw.ustring.lower(), w której dokonywana jest taka sama zamiana lecz używająca reguł z Unikodu.
string.match
string.match( s, pattern, init )
Szuka pierwszego wystąpienia wyrażenia określonego przez wzór
w łańcuchu tekstowym. Jeśli znajdzie jedno, to funcja match
zwraca znalezione grupy ze wzoru; w przeciwnym razie zwraca nil. Jeśli wzór
nie określa grup, to zwracane jest pełne znalezione wyrażenie.
Trzeci opcjonalny argument liczbowy początek
określa gdzie rozpocząć wyszukiwanie; domyślna wartość to 1, a może być ujemna.
Zobacz podobną funkcję mw.ustring.match(), w której wzór jest rozszerzony jak opisano w sekcji Wzory Ustring, a początek
jest liczony w znakach zamiast bajtach.
string.rep
string.rep( s, n )
Zwraca łańcuch tekstowy będący połączeniem n
kopii łańcucha tekstowego s
. Identyczne z mw.ustring.rep().
string.reverse
string.reverse( s )
Zwraca łańcuch tekstowy, który jest zapisem s
od tyłu (w bajtach).
string.sub
string.sub( s, i, j )
Zwraca podłańcuch tekstowy z s
, który rozpoczyna się w i
a kończy w j
; i
i j
mogą być ujemne. Jeśli j
jest nil lub pominięte to zostanie użyte -1, będzie trwać do końca ciągu.
W szególności wywołanie string.sub(s,1,j)
zwraca początek s
o długości j
, a string.sub(s, -i)
zwraca koniec z s
o długości i
.
Zobacz podobną funkcję mw.ustring.sub(), w której zakresy są liczone w znakach zamiast bajtach.
string.ulower
string.ulower( s )
An alias for mw.ustring.lower().
string.upper
string.upper( s )
Zwraca kopię łańcucha tekstowego, w którym wszystkie małe litery ASCII są zamieniane na wielkie. Wszystkie pozostałe znaki są pozostawione bez zmian.
Zobacz podobną funkcję mw.ustring.upper(), w której dokonywana jest taka sama zamiana lecz używająca reguł z Unikodu.
string.uupper
string.uupper( s )
Alias dla mw.ustring.upper()
Wzory
Należy zauważyć, że wzory Lua są podobne do wyrażeń regularnych, lecz nie są takie same. W szczególności mają miejsce następujące różnice względem PCRE:
- Znak cytujący to procent (
%
), a nie odwrotny (wsteczny) ukośnik (\
).
- Kropka (
.
) zawsze wyszukuje dowolny znak, włączając do tego nowe linie.
- Brak trybu nieodróżniającego wielkości liter.
- Brak alternatywy (operatora
|
).
- Kwantyfikatory (
*
,+
,?
, and-
) mogą być zastosowane do pojedynczych znaków lub klas znaków, a nie do znalezionych grup.
- Jedyny nieżarłoczny kwantyfikator to
-
, który odpowiada w PCRE kwantyfikatorowi*?
.
- Brak uogólnionych skończonych kwantyfikatorów (na przykład
{n,m}
w PCRE).
- Jedyne twierdzenia o zerowej szerokości to
^
,$
, i%f[set]
wzór „graniczny”; twierdzenia takie jak w PCRE\b
lub(?=···)
są nieobecne.
- Patterns themselves do not recognize character escapes such as
\ddd
. However, since patterns are strings these sort of escapes may be used in the string literals used to create the pattern-string.
Also note that a pattern cannot contain embedded zero bytes (ASCII NUL, "\0"
). Use %z
instead.
Also see Ustring patterns for a similar pattern-matching scheme using Unicode characters.
Klasa znaku
Klasa znaku jest używana do reprezentowania zbioru znaków. Następujące kombinacje są dopuszczalne w opisywaniu klasy znaku:
x
|
(gdzie x nie jest żadnym z magicznych znaków ^$()%.[]*+-? ) reprezentuje znak x .
|
---|---|
.
|
(kropka) reprezentuje dowolny znak. |
%a
|
reprezentuje wszystkie litery ASCII. |
%c
|
reprezentuje wszystkie znaki sterujące ASCII. |
%d
|
reprezentuje wszystkie cyfry. |
%l
|
reprezentuje wszystkie małe litery ASCII. |
%p
|
reprezentuje wszystkie znaki interpunkcyjne. |
%s
|
reprezentuje wszystkie odstępy w ASCII. |
%u
|
reprezentuje wszystkie wielkie litery ASCII. |
%w
|
reprezentuje wszystkie znaki alfanumeryczne w ASCII. |
%x
|
reprezentuje wszystkie cyfry szesnastkowe. |
%z
|
reprezentuje znak ASCII NUL, bajt o wartości zero. |
%A
|
Wszystkie znaki nie są w %a .
|
%C
|
Wszystkie znaki nie są w %c .
|
%D
|
Wszystkie znaki nie są w %d .
|
%L
|
Wszystkie znaki nie są w %l .
|
%P
|
Wszystkie znaki nie są w %p .
|
%S
|
Wszystkie znaki nie są w %s .
|
%U
|
Wszystkie znaki nie są w %u .
|
%W
|
Wszystkie znaki nie są w %w .
|
%X
|
Wszystkie znaki nie są w %x .
|
%Z
|
Wszystkie znaki nie są w %z .
|
%y
|
(gdzie $x jest dowolnym niealfanumerycznym znakiem) reprezentuje znak $x. To jest standardowa metoda zapisu w postaci sekwencji specjalnej pozwalającej na anulowanie magicznego znaczenia. Dowolny znak interpunkcyjny (nawet niemagiczny) może być poprzedzony przez '% ' kiedy ma oznaczać samego siebie we wzorze.
|
[set]
|
Represents the class which is the union of all characters in set. A range of characters can be specified by separating the end characters of the range with a ' The interaction between ranges and classes is not defined. Therefore, patterns like |
[^set]
|
Represents the complement of set, where set is interpreted as above. |
Elementy wzoru
Elementem wzoru może być
- pojedyncza klasa znaku, która odnajduje dowolny znak z wybranej klasy;
- pojedynczy znak z następującym po nim '
*
', który odnajduje 0 lub więcej powtórzeń znaków z wybranej klasy. Te elementy zawsze wyszukują najdłuższą możliwą sekwencję znaków; - pojedynczy znak z następującym po nim '
+
', który odnajduje 1 lub więcej powtórzeń znaków z wybranej klasy. Te elementy zawsze wyszukują najdłuższą możliwą sekwencję znaków; - pojedynczy znak z następującym po nim '
-
', który także odnajduje 0 lub więcej powtórzeń znaków z wybranej klasy. Jednak inaczej niż '*
', te elementy zawsze wyszukują najkrótszą możliwą sekwencję znaków; - pojedynczy znak z następującym po nim '
?
', który odnajduje 0 lub 1 wystąpienie znaku z wybranej klasy; %n
, dla n między 1 a 9; taki element wyszukuje podłańcuch tekstowy identyczny jak n-ta wyszukana grupa (zobacz niżej);%bxy
, gdzie x i y to dwa różne znaki; ten element wyszukuje łańcuchy tekstowe, które zaczynają się na x, kończą na y, w których x i y są zrównoważone. To oznacza, że czytając od lewej do prawej, odlicza się +1 na x a -1 na y, kończący y to pierwszy y, w którym licznik osiągnął 0. Na przykład element%b()
wyszukuje wyrażenia w odpowiednio sparowanych nawiasach.%f[zbiór]
, wzór graniczny; ten element wyszukuje pusty łańcuch tekstowy w dowolnym miejscu taki, że następny znak należy do zbioru, a poprzedzający go znak do tego zbioru nie należy. Podany zbiór zbiór jest rozumiany tak jak zostało to uprzednio opisane. Początek i koniec przeszukiwanego łańcucha są obsługiwane tak jakby były tam znaki '\0'.
Należy pamiętać, że wzory graniczne były obecne lecz nieudokumentowane w Lua 5.1, a oficjalnie dodane w Lua in 5.2. Implementacja w Lua 5.2.1 się nie zmieniła od tej z wersji 5.1.0.
- a single character class followed by '
*
', which matches 0 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence;
- a single character class followed by '
+
', which matches 1 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence;
- a single character class followed by '
-
', which also matches 0 or more repetitions of characters in the class. Unlike '*
', these repetition items will always match the shortest possible sequence;
- a single character class followed by '
?
', which matches 0 or 1 occurrence of a character in the class;
%n
, for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below);
%bxy
, where x and y are two distinct characters; such item matches strings that start with x, end with y, and where the x and y are balanced. This means that, if one reads the string from left to right, counting +1 for an x and -1 for a y, the ending y is the first y where the count reaches 0. For instance, the item%b()
matches expressions with balanced parentheses.
%f[set]
, a frontier pattern; such item matches an empty string at any position such that the next character belongs to set and the previous character does not belong to set. The set set is interpreted as previously described. The beginning and the end of the subject are handled as if they were the character '\0'.
Note that frontier patterns were present but undocumented in Lua 5.1, and officially added to Lua in 5.2. The implementation in Lua 5.2.1 is unchanged from that in 5.1.0.
Wzór
Wzór to sekwencja elementów wzoru.
Znak '^
' na początku wzoru zakotwicza wyszukiwanie na początku przeszukiwanego łańcucha tekstowego . Znak '$
' na końcu wzoru zakotwicza wyszukiwanie na końcu przeszukiwanego łańcucha tekstowego. Na innych pozycjach '^
' i '$
' nie mają żadnego specjalnego znaczenia i przedstawiają samych siebie.
A $
at the end of a pattern anchors the match at the end of the subject string. At other positions, ^
and $
have no special meaning and represent themselves.
Grupy
Wzór może zawierać podwzory umieszczone w nawiasach; one opisują grupy. Kiedy wyszukiwanie się powiedzie, podłańcuchy przeszukiwanego tekstu, które pasują do grup są zapamiętywane (grupowane) do przyszłego użycia. Grupy są ponumerowane zgodnie z kolejnością nawiasów otwierających. Na przykład we wzorze (a*(.)%w(%s*))
część łańcucha pasująca do a*(.)%w(%s*)
jest zapamiętana jako pierwsza grupa (i w konsekwencji ma numer 1); znak wyszukany przez .
jest zgrupowany pod numerem 2, a część wyszukana przez %s*
ma numer 3.
Odwołania do grup mogą się pojawić we wzorze i przywołują tekst, który został wcześniej wyszukany i zgrupowany. Na przykład ([a-z])%1
będzie wyszukiwał par identycznych małych liter, podczas gdy ([a-z])([a-z])([a-z])[a-z]%3%2%1
będzie szukał dowolnego siedmioliterowego palindromu.
Przypadkiem specjalnym jest pusta grupa ()
, która zapamiętuje bieżącą pozycję (liczbę) w łańcuchu tekstowym. Na przykład jeśli zastosowany zostanie wzór "()aa()"
na łańcuchu tekstowym "flaaap"
, to wynikiem będą dwie grupy: 3 i 5.
Known limitations: Unlike Ustring library patterns, String library patterns may not contain more than 32 captures. If the pattern has more, then the String function will throw an error. Because the Ustring library has its own maximum of 10,000 bytes for patterns (unlike the String library), it is therefore impossible to use a pattern which exceeds both limits, as it will be incompatible with both libraries.
Biblioteka tablicowa
Większość funkcji w bibliotece tablicowej zakłada, że tablica przedstawia sekwencję.
Funkcje table.foreach()
, table.foreachi()
i table.getn()
mogą być dostępne, lecz są przestarzałe. Zamiast nich należy używać pętli for
z pairs() lub z ipairs() i operatora długości.
table.concat
table.concat( table, sep, i, j )
Jeśli przekazana zostanie tablica zawierająca łańcuchy tekstowe lub liczby wynikiem będzie tablica[i] .. sep .. tablica[i+1] ··· sep .. tablica[j]
.
Domyślną wartością dla sep
jest pusty łańcuch tekstowy, domyślną dla i
jest 1, a domyślną dla j
jest długość tablicy. Jeśli i
jest większe niż j
to wynikiem będzie pusty łańcuch tekstowy.
table.insert
table.insert( table, value )
table.insert( table, pos, value )
Wstawia element wartość
na pozycji poz
w tablicy tablica
, przesuwając w górę inne elementy aby utworzyć wolne miejsce jeśli to konieczne. Domyślną wartością dla pos
jest długość tablicy plus 1, tak więc wywołanie table.insert(t, x)
wstawia x
na koniec tablicy t
.
Elementy aż do#tablica
są przesuwane; zobacz sekcję Operator długości aby poznać zastrzeżenia jeśli tablica nie jest sekwencją.
Note: when using the pos
parameter, value
should not be nil
. Attempting to insert an explicit nil
value into the middle of a table will result in undefined behaviour, which may delete elements in the table unpredictably.
table.maxn
table.maxn( table )
Zwraca największy dodatni liczbowy indeks w podanej tablicy lub zero jeśli tablica nie zawiera dodatnich liczbowych indeksów.
Aby to uzyskać iteruje po całej tablicy. Algorytm wygląda mniej więcej tak
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 )
Usuwa z tablicy tablica
element na pozycji poz
, przesuwając w dół inne elementy aby uzupełnić zwolnione miejsce jeśli potrzeba. Zwraca wartość usuniętego elementu. Domyślną wartością dla pos
jest długość tablicy, tak więc wywołanie table.remove( t )
usuwa ostatni element z tablicy t
.
Elementy aż do#tablica
są przesuwane; zobacz sekcję Operator długości aby poznać zastrzeżenia jeśli tablica nie jest sekwencją.
table.sort
table.sort( table, comp )
Sortuje elementy tablicy w zadanym porządku, w miejscu, od tablica[1]
do tablica[#tablica]
. Jeśli por
jest podany, to musi to być funkcja, która otrzymuje dwa elementy tablicy i zwraca true
kiedy pierwszy element jest mniejszy niż drugi (tak więc not por(a[i+1],a[i])
będzie zachodziło po sortowaniu). Jeśli por
nie jest podana, to w zamian używany jest standardowy operator Lua <
.
If comp
is given, then it must be a function that receives two table elements, and returns true
when the first is less than the second (so that not comp(a[i+1],a[i])
will be true after the sort).
If comp
is not given, then the standard Lua operator <
is used instead.
Algorytm sortowanie nie jest stabilny; to znaczy, że elementy uznawane za takie same w danym porządku mogą zmienić swoje względne pozycje przez sortowanie.
Biblioteki Scribunto
Wszystkie biblioteki Scribunto są umieszczone w tablicy mw
.
Podstawowe funkcje
mw.addWarning
mw.addWarning( text )
Dodaje ostrzeżenie, które jest wyświetlane na podglądzie edycji. text
jest interpretowany jak wikitekst.
mw.allToString
mw.allToString( ... )
Wywołuje tostring() na wszystkich argumentach, które następnie łączy używając znaki tabulacji jako separatorów.
mw.clone
mw.clone( value )
Tworzy głęboką kopię wartości. Wszystkie tablice (i ich metatablice) są utworzone od zera. Jednak funkcje są w dalszym ciągu wspólne.
mw.getCurrentFrame
mw.getCurrentFrame()
Zwraca bieżący obiekt ramki, zazwyczaj jest to obiekt ramki z ostatniego wywołania #invoke
.
mw.incrementExpensiveFunctionCount
mw.incrementExpensiveFunctionCount()
Dodaje jeden do licznika „złożonych obliczeniowo funkcji parsera” i zgłasza wyjątek jeśli limit zostaje przekroczony (zobacz $wgExpensiveParserFunctionLimit
).
mw.isSubsting
mw.isSubsting()
Zwraca true
jeśli bieżące wywołanie #invoke
jest wywołany w trybie subst:, w przeciwnym razie false
. Zobacz sekcję Zwracanie tekstu powyżej aby zapoznać z opisem różnic w działaniu.
mw.loadData
mw.loadData( module )
Czasami moduł potrzebuje dużej tablic z danymi, na przykład, moduł ogólnego przeznaczenia do konwersji jednostek miar może potrzebować tablicy rozpoznawalnych jednostek wraz z ich współczynnikami konwersji. A czasami te moduły mogą być wielokrotnie używane na jednej stronie. Parsowanie dużych tablic przy każdym {{#invoke:}}
może zająć zauważalnie dużo czasu. Funkcja mw.loadData()
została wprowadzona w celu uniknięcia tych problemów.
mw.loadData
działa jak require()
z następującymi różnicami:
- Ładowany moduł jest ładowany tylko raz na stronę, zamiast raz na każde wywołanie
{{#invoke:}}
.
- Ładowany moduł nie jest umieszczany w tablicy
package.loaded
. - Wartość zwracana z ładowanego modułu musi być tablicą. Inne typy danych nie są wspierane.
- Zwracana tablica (i wszystkie podtablice) może zawierać tylko wartości typu logicznego, liczbowego, tekstowego lub tablicowego. Pozostałe typy, a zwłaszcza funkcje, są niedozwolone.
- Zwracana tablica (i wszystkie podtablice) nie mogą mieć metatablicy.
- Wszystkie klucze muszą być logiczne, liczbowe lub tekstowe.
- W rzeczywistości tablica zwracana przez
mw.loadData()
ma metametody, które dostarczają dostęp tylko do odczytu do tablicy uzyskanej z modułu. Z uwagi, że nie zawiera ona danych bezpośrednio, funkcjepairs()
iipairs()
będą działać, lecz inne metody, w tym#wartość
,next()
i funckje opisane w sekcji Biblioteka tablicowa, nie będą działały prawidłowo.
Potencjalny moduł konwersji jednostek wspomniany wyżej składać się z kodu w module „Moduł:Konwerter” i danych w module „Moduł:Konwerter/dane”, a „Moduł:Konwerter” mógłby używać local data = mw.loadData( 'Moduł:Konwerter/dane' )
aby wydajnie ładować dane.
mw.loadJsonData
mw.loadJsonData( page )
This is the same as mw.loadData()
above, except it loads data from JSON pages rather than Lua tables.
The JSON content must be an array or object.
See also mw.text.jsonDecode()
.
mw.dumpObject
mw.dumpObject( object )
Serializes object
to a human-readable representation, then returns the resulting string.
mw.log
mw.log( ... )
Przekazuje argumenty do mw.allToString(), a następnie dołącza wynikowy tekst do bufora logu.
Funkcja print()
jest jej aliasem w konsoli debugowania.
mw.logObject
mw.logObject( object )
mw.logObject( object, prefix )
Calls mw.dumpObject() and appends the resulting string to the log buffer. If prefix
is given, it will be added to the log buffer followed by an equals sign before the serialized string is appended (i.e. the logged text will be "prefix = object-string").
Frame object
Obiekt ramki to interfejs do parametrów przekazanych do {{#invoke:}}
i parsera.
Note that there is no frame library, and there is no global variable named frame
. A frame object is typically obtained by being passed as a parameter to the function called by {{#invoke:}}
, and can also be obtained from mw.getCurrentFrame()
.
frame.args
Tablica udostępniająca argumenty przekazane do ramki. Na przykład jeśli moduł jest wywołany z wikitekstu przez
{{#invoke:module|function|arg1|arg2|name=arg3}}
to frame.args[1]
zwróci "arg1"
, frame.args[2]
zwróci "arg2"
, a frame.args['name']
(lub frame.args.name
) zwróci "arg3"
. Możliwe jest również iterowanie po argumentach używając pairs( frame.args )
lub ipairs( frame.args )
.
However, due to how Lua implements table iterators, iterating over arguments will return them in an unspecified order, and there's no way to know the original order as they appear in wikitext.
Należy pamiętać, że wartości w tej tablicy są zawsze łańcuchami tekstowymi; jeśli zachodzi potrzeba ich zamiany na liczby to można użyć funkcji tonumber()
. Jednak klucze są liczbami nawet jeśli są jawnie podane w wywołaniu: {{#invoke:module|function|1|2=2}}
otrzymuje wartości łańcuchów tekstowych "1"
i "2"
indeksowane liczbowymi kluczami 1
i 2
.
Podobnie jak w wywołaniu szablonów MediaWiki, nazwane argumenty są pozbawiane wiodących i kończących znaków odstępu zarówno z nazwy jak i wartości przed przekazaniem ich do Lua, podczas gdy argumenty nienazwane takie odstępy mają nietknięte.
Z powodów wydajnościowych frame.args
używa metatablicy, zamiast zawierać bezpośrednio argumenty. Wartości argumentów są uzyskiwane od MediaWiki na żądanie. To oznacza, że większość pozostałych metod tablicowych nie działa prawidłowo, włączając w to #frame.args
, next( frame.args )
i funkcje opisane w sekcji Biblioteka tablicowa.
Jeśli składnia preprocesora, taka jak wywołania szablonów i argumenty z potrójnymi nawiasami klamrowymi, jest zawarta w argumencie #invoke1, nie zostaną one rozwinięte po przekazaniu do Lua, dopóki ich wartości nie zostaną zażądane w Lua. Jeśli argument do #invoke2 zawiera pewne specjalne tagi w zapisie XML takie jak <pre>
, <nowiki>
, <gallery>
lub <ref>
, to są one zamieniane na specjalne znaczniki (strip marker) — łańcuchy tekstowe, które zaczynają się znakiem kasowania (ASCII 127), i będą one wymienione na HTML dopiero po powrocie z #invoke.
frame:callParserFunction
frame:callParserFunction( name, args )
frame:callParserFunction( name, ... )
frame:callParserFunction{ name = string, args = table }
- Należy pamiętać o używaniu nazwanych argumentów.
Wywołuje funkcję parsera zwracając odpowiedni łańcuch tekstowy. Jest to lepsze niż frame:preprocess
, ale jeśli tylko to możliwe, należy skorzystać z natywnych funkcji Lua lub biblioteki Scribunto zamiast tego interfejsu.
Następujące wywołania są w przybliżeniu równoważne z podanym wikikodem:
-- {{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'
} )
Należy pamiętać, że stosując frame:expandTemplate(), nazwa funkcji i argumenty nie są już przetwarzane przed przekazaniem ich do funkcji parsera.
frame:expandTemplate
frame:expandTemplate{ title = title, args = table }
- Należy pamiętać o używaniu nazwanych argumentów.
This is equivalent to a call to frame:callParserFunction() with function name 'msg'
(see Help:Magic words#Transclusion modifiers) and with title
prepended to args
.
To jest transkluzja. Wywołanie:
frame:expandTemplate{ title = 'template', args = { 'arg1', 'arg2', name = 'arg3' } }
w Lua robi mniej więcej to samo co {{template|arg1|arg2|name=arg3}}
w wikikodzie. Podobnie jak w transkluzji, jeśli przekazany tytuł nie zawiera przedrostka z nazwą przestrzeni, to domyślnie przyjęta będzie nazwa przestrzeni Szablon:.
Należy pamiętać, że tytuł i argumenty nie są już przetwarzane przed przekazaniem ich do szalonu:
-- To jest mniej więcej równoważne z wikikodem jak {{template|{{!}}}}
frame:expandTemplate{ title = 'template', args = { '|' } }
frame:callParserFunction{ 'msg', { 'template', '|' } }
-- To jest mniej więcej równoważne z wikikodem jak {{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 jest równoważne wywołaniu frame:callParserFunction() z nazwą funkcji '#tag:' .. nazwa
, a następnie podaną treścią z zawartość
i argumentami z argumenty
.
-- Te wywołania są równoważne
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'
} )
-- Te wywołania są równoważne
frame:extensionTag{ name = 'ref', content = 'some text', args = { 'some other text' } }
frame:callParserFunction( '#tag', { 'ref',
'some text', 'some other text'
} )
frame:getParent
frame:getParent()
Wywołane na ramce utworzonej przez {{#invoke:}}
zwraca ramkę dla strony, która wywołała {{#invoke:}}
. Wywołane dla tamtej ramki zwraca nil.
Na przykład jeśli szablon {{Przykład}}
zawiera kod {{#invoke:NazwaModułu}}
i strona transkluduje ten szablon wraz z polami ({{Przykład|arg1|arg2}}
), wywołując mw.getCurrentFrame():getParent().args[1], mw.getCurrentFrame():getParent().args[2]
w module „Moduł:NazwaModułu” otrzymuje się "arg1", "arg2"
.
frame:getTitle
frame:getTitle()
Zwraca tytuł stowarzyszony z ramką jako łańcuch tekstowy. Dla ramki utworzonej przez {{#invoke:}}
jest to tytuł wywołanego modułu.
frame:newChild
frame:newChild{ title = title, args = table }
- Należy pamiętać o używaniu nazwanych argumentów.
Tworzy nową ramkę obiektu, która jest potomna względem bieżącej ramki, z opcjonalnymi argumentami i tytułem.
To jest głównie przeznaczone do używania w konsoli debugowania do testowania funkcji, które normalnie byłyby wywoływane przez {{#invoke:}}
. Liczba ramek, która może być utworzona w danym momencie jest ograniczona.
frame:preprocess
frame:preprocess( string )
frame:preprocess{ text = string }
Rozwija wikikod w kontekście ramki, np. szablony, funkcje parser i parametry takie jak {{{1}}}
są rozwijane. Niektóre specjalne tagi zapisane w postaci XML, takie jak <pre>
, <nowiki>
, <gallery>
i <ref>
, będą zamienione na specjalne znaczniki („strip markers”) — łańcuchy tekstowe, które zaczynają się znakiem kasowania (ASCII 127), i będą one wymienione na HTML dopiero po powrocie z #invoke.
Jeśli rozwija się pojedynczy szablon, lepiej użyć frame:expandTemplate
zamiast tworzyć łańcuch tekstowy z wikikodem w celu przekazania do tej metody. To jest szybsze i mniej podatne na błędy jeśli argumenty zawierają znak '|
' lub inne wikiznaczniki.
If you are expanding a single parser function, use frame:callParserFunction
for the same reasons.
frame:getArgument
frame:getArgument( arg )
frame:getArgument{ name = arg }
Zwraca obiekt dla określonego argumentu, lub nil jeśli argument nie jest dostarczony.
Zwrócony obiekt ma jedną metodę obiekt:expand()
, która zwraca rozwinięty wikikod argumentu.
frame:newParserValue
frame:newParserValue( text )
frame:newParserValue{ text = text }
Zwraca obiekt z jedną metodą obiekt:expand()
, która zwraca wynik frame:preprocess( tekst )
.
frame:newTemplateParserValue
frame:newTemplateParserValue{ title = title, args = table }
- Należy pamiętać o używaniu nazwanych argumentów.
Zwraca obiekt z jedną metodą obiekt:expand()
, która zwraca wynik frame:expandTemplate
wywołanego z podanymi argumentami.
frame:argumentPairs
frame:argumentPairs()
To samo co pairs( frame.args )
. Dostępne ze względu na wsteczną kompatybilność.
Biblioteka haszująca
mw.hash.hashValue
mw.hash.hashValue( algorytm, wartość )
Oblicza funkcję skrótu z podanego łańcucha tekstowego używając wskazanego algorytmu. Listę prawidłowych algorytmów można uzyskać przez mw.hash.listAlgorithms().
mw.hash.listAlgorithms
mw.hash.listAlgorithms()
Zwraca listę wspieranych algorytmów funkcji skrótu do użycia w funkcji mw.hash.hashValue().
Biblioteka HTML
mw.html
to fluent interface do tworzenia skomplikowanego kodu HTML z Lua. Objekt mw.html można utworzyć stosując mw.html.create
.
Funkcje udokumentowane jako mw.html.name
są dostępne globalnie w tablicy mw.html
; funkcje udokumentowane jako mw.html:name
są metodami obiektu mw.html (zobacz mw.html.create
).
Podstawowy przykład mógłby wyglądać tak:
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 )
Tworzy nowy obiekt mw.html zawierający element HTML nazwaTagu
. Można podać pusty łańcuch tekstowy lub jako nazwaTagu
aby utworzyć pusty obiekt mw.html.
argumenty
może być tablicą z następującymi kluczami:
argumenty.selfClosing
: Wymuszenie utworzenia bieżącego taga jako samozamykającego, nawet jeśli mw.html nie rozpoznaje go jako samozamykającegoargumenty.parent
: Rodzic dla bieżącej instancji mw.html (przeznaczony do użytku wewnętrznego)
mw.html:node
html:node( builder )
Appends a child mw.html (builder
) node to the current mw.html instance. If a nil parameter is passed, this is a no-op. A (builder
) node is a string representation of an html element.
mw.html:wikitext
html:wikitext( ... )
Appends an undetermined number of wikitext strings to the mw.html object.
Należy pamiętać, że operacja dołączania jest zatrzymywana na pierwszym napotkanym elemencie o wartości „nil”.
Basic wikitext will get parsed, like HTML, links, bold, lists or tables. However, templates and parser functions won't be evaluated if they are passed directly to this function, unless they came from template parameters.
Those will be rendered in plain text instead.
To evaluate them, they'll have to be passed through frame:preprocess.
mw.html:newline
html:newline()
Dołącza znak nowej linii do obiektu mw.html.
Useful when used before and after mw.html:wikitext(), when the wikitext contains lists or tables, whose syntax only has a special meaning when present at the start of a line.
mw.html:tag
html:tag( tagName, args )
Appends a new child node with the given tagName
to the builder, and returns a mw.html instance representing that new node. The args
parameter is identical to that of mw.html.create
Note that contrarily to other methods such as html:node()
, this method doesn't return the current mw.html instance, but the mw.html instance of the newly inserted tag.
Make sure to use html:done()
to go up to the parent mw.html instance, or html:allDone()
if you have nested tags on several levels.
mw.html:attr
html:attr( name, value )
html:attr( table )
Set an HTML attribute with the given name
and value
on the node. Alternatively a table holding name->value pairs of attributes to set can be passed. In the first form, a value of nil causes any attribute with the given name to be unset if it was previously set.
mw.html:getAttr
html:getAttr( name )
Get the value of a html attribute previously set using html:attr()
with the given name
.
mw.html:addClass
html:addClass( class )
Adds a class name to the node's class attribute. If a nil parameter is passed, this is a no-op.
mw.html:css
html:css( name, value )
html:css( table )
Set a CSS property with the given name
and value
on the node. Alternatively a table holding name->value pairs of properties to set can be passed. In the first form, a value of nil causes any property with the given name to be unset if it was previously set.
mw.html:cssText
html:cssText( css )
Add some raw css
to the node's style attribute. If a nil parameter is passed, this is a no-op.
mw.html:done
html:done()
Returns the parent node under which the current node was created. Like jQuery.end, this is a convenience function to allow the construction of several child nodes to be chained together into a single statement.
mw.html:allDone
html:allDone()
Like html:done()
, but traverses all the way to the root node of the tree and returns it.
Biblioteka językowa
Kody języków są opisane w podręczniku jezyków. Wiele kodów języków MediaWiki jest podobnych do kodów języka IETF, lecz nie wszystkie kody języków MediaWiki są poprawne w IETF i odwrotnie.
Funkcje udokumentowane jak mw.language.nazwa
są dostępne w globalnej tablicy mw.language
; funkcje udokumentowane jak mw.language:nazwa
są metodami obiektu językowego (zobacz mw.language.new
).
mw.language.fetchLanguageName
mw.language.fetchLanguageName( code, inLanguage )
Pełna nazwa języka o podanym kodzie: domyślnie w tym w swoim języku, lub przetłumaczona na inny język jeśli podany jest argument inLanguage
z językiem docelowym.
mw.language.fetchLanguageNames
mw.language.fetchLanguageNames()
mw.language.fetchLanguageNames( inLanguage )
mw.language.fetchLanguageNames( inLanguage, include )
Pobiera listę języków znanych w MediaWiki, zwracając tablicę mapującą kody języków na ich nazwy.
Domyślnie zwrócone nazwy są w języku, który przedstawiają; przekazując kod języka w inLanguage
w wyniku będą umieszczone wszystkie nazwy w tym języku.
Domyślnie zwracane są jedynie nazwy języków znanych w MediaWiki; przekazując 'all'
w include
zwrócone będą wszystkie dostępne języki (np. z Extension:CLDR ), natomiast gdy przekazane zostanie 'mwfile'
to w wyniku zostaną umieszczone tylko języki, które mają dostosowane komunikaty zawarte w rdzennym oprogramowaniu MediaWiki lub włączonych rozszerzeniach. Aby jawnie wskazać, że wymagane jest zachowanie domyślne można przekazać 'mw'
.
mw.language.getContentLanguage
mw.language.getContentLanguage()
mw.getContentLanguage()
Zwraca nowy obiekt językowy dla domyślnego języka zawartości wiki.
mw.language.getFallbacksFor
mw.language.getFallbacksFor( code )
Zwraca listę alternatywnych kodów języka (awaryjnych zamienników) dla określonego kodu języka.
mw.language.isKnownLanguageTag
mw.language.isKnownLanguageTag( code )
Zwraca true
jeśli kod języka jest znany przez MediaWiki.
Kod języka jest „znany” jeśli jest „poprawnym kodem wbudowanym” (np. mw.language.isValidBuiltInCode
zwraca true
) i zwraca niepusty łańcuch tekstowy w wywołaniu mw.language.fetchLanguageName
.
mw.language.isSupportedLanguage
mw.language.isSupportedLanguage( code )
Sprawdza czy istnieje jakiekolwiek tłumaczenie w tym języku w MediaWiki.
Kod języka jest „wspierany” jeśli jest „poprawny” (wywołanie mw.language.isValidCode
zwraca true
), nie zawiera dużych liter i ma plik komunikatów w aktualnie uruchomionej wersji MediaWiki.
Istnieje taka możliwość, że kod języka jest „wspierany” ale nie jest „znany” (np. zwracając true
z mw.language.isKnownLanguageTag
). Należy również pamiętać, że niektóre kody są „wspierane” chociaż mw.language.isValidBuiltInCode
zwraca false
.
mw.language.isValidBuiltInCode
mw.language.isValidBuiltInCode( code )
Zwraca true
jeśli kod języka jest w poprawnej postaci do celów wewnętrznego dostosowywania MediaWiki.
Kod nie musi właściwie odpowiadać żadnemu znanemu językowi.
Kod języka jest „poprawnym kodem wbudowanym” jeśli jest „poprawnym” kodem (np. wywołanie mw.language.isValidCode
zwraca true
); składa się tylko z liter ASCII, cyfr i myślników; oraz jego minimalna długość to dwa znaki.
Należy pamiętać, że pewne kody są „wspierane” (np. zwracające true
z mw.language.isSupportedLanguage
) nawet jeśli ta funkcja zwraca false
.
mw.language.isValidCode
mw.language.isValidCode( code )
Zwraca true
jeśli łańcuch z kodem języka ma prawidłową postać, niezależnie od tego czy istnieje czy nie. Obejmuje to kody, które są używane wyłącznie do dostosowywania za pomocą przestrzeni nazw MediaWiki.
Kod właściwie nie musi odpowiadać żadnemu znanemu językowi.
Kod języka jest poprawny jeśli nie zawiera pewnych niebezpiecznych znaków (dwukropek, apostrof, cudzysłów, ukośnik, również wsteczny, nawiasy trójkątne, ampersand lub ASCII NUL) i ponadto jest dopuszczalny jako tytuł strony.
mw.language.new
mw.language.new( code )
mw.getLanguage( code )
Tworzy nowy obiekt językowy. Obiekty językowe nie mają żadnych publicznie dostępnych cech, lecz mają metody, które są udokumentowane poniżej.
Istnieje granica w liczbie różnych języków dostępnych, których można razem używać na stronie. Przekroczenie tego limitu powoduje błędy.
mw.language:getCode
lang:getCode()
Zwraca kod języka dla tego obiektu językowego.
mw.language:toBcp47Code
lang:toBcp47Code()
Returns the standard BCP-47 language code for this language object. This is the code string which is appropriate to use in HTML, for example as the value of a lang
attribute.
mw.language:getFallbackLanguages
lang:getFallbackLanguages()
Zwraca listę alternatywnych kodów języka (awaryjnych zamienników) dla tego obiektu językowego. Równoważne wywołaniu mw.language.getFallbacksFor( lang:getCode() )
.
mw.language:isRTL
lang:isRTL()
Zwraca true
jeśli język jest zapisywane od prawej do lewej, lub false
jeśli jest zapisywany od lewej do prawej.
mw.language:lc
lang:lc( s )
Zamienia łańcuch tekstowy na zapis z małymi literami, uwzględniając każde specjalne reguły dla danego języka.
Jeśli załadowana jest biblioteka Ustring, funkcja mw.ustring.lower() jest zaimplementowana jako wywołanie mw.language.getContentLanguage():lc( s )
.
mw.language:lcfirst
lang:lcfirst( s )
Zamienia pierwszy znak w łańcuchu tekstowym na małą literę, tak jak lang:lc().
mw.language:uc
lang:uc( s )
Zamienia łańcuch tekstowy na zapis dużymi literami, uwzględniając wszelkie specjalne reguły dla danego języka.
Jeśli załadowana jest biblioteka Ustring, funkcja mw.ustring.upper() jest zaimplementowana jako wywołanie mw.language.getContentLanguage():uc( s )
.
mw.language:ucfirst
lang:ucfirst( s )
Zamienia pierwszy znak z łańcucha tekstowego na wielką literę, tak jak lang:uc().
mw.language:caseFold
lang:caseFold( s )
Zamienia łańcuch tekstowy na postać dogodną do porównywania bez odróżniania wielkości liter. Należy pamiętać, że wynik może nie mieć żadnego sensu gdyby go wyświetlać.
mw.language:formatNum
lang:formatNum( n )
lang:formatNum( n, options )
Przedstawia liczbę w postaci stosownej w danym języku, używając właściwego symbolu na oddzielanie cyfr po przecinku jak również ich grupowania. Na przykład podając 123456.78
można otrzymać "123,456.78"
, "123.456,78"
a nawet coś takiego jak "١٢٣٬٤٥٦٫٧٨"
w zależności od języka i konfiguracji wiki.
Argument options
jest tablicą opcji, w których może być:
noCommafy
: Ustawione natrue
pomija grupowanie i użyj kropki (.
) jako separatora dziesiętnego.
Digit transformation may still occur, which may include transforming the decimal separator.
mw.language:formatDate
lang:formatDate( format, timestamp, local )
Przedstawia datę zgodnie z podanym wzorem. Jeśli timestamp
jest pominięty to użyty zostanie czas bieżący. Wartość local
musi być logiczna lub nil; jeśli jest to true
to czas jest przedstawiany w lokalnej strefie czasowej wiki zamiast w UTC.
Wzór i wspierane wartości dla timestamp
są identyczne jak te w funkcji parser #time z Extension:ParserFunctions .
Należy jednak pamiętać, że wsteczne ukośniki mogą wymagać podwojenia w literałach łańcuchów tekstowych w Lua, ponieważ są one również używane do oznaczania specjalnych sekwencji do podawania niektórych znaków, podczas gdy w wikikodzie nie ma takiej potrzeby.
-- Literał łańcucha tekstowego zawiera znak nowej lini, a nie dwa znaki „\n”, więc nie jest to równoważne z {{#time:\n}}.
lang:formatDate( '\n' )
-- To jest równoważne z {{#time:\n}}, a nie z {{#time:\\n}}.
lang:formatDate( '\\n' )
-- To jest równoważne z {{#time:\\n}}, a nie z {{#time:\\\\n}}.
lang:formatDate( '\\\\n' )
mw.language:formatDuration
lang:formatDuration( seconds )
lang:formatDuration( seconds, chosenIntervals )
Zamienia czas trwania w sekundach na jednostki bardziej czytelne dla człowieka, np. 12345 na 3 godziny, 25 minut i 45 sekund, zwracając wynik w postaci łańcucha tekstowego.
Jeśli przekazuje się chosenIntervals
, to jest to tablica z wartościami określającymi, które jednostki mają być używane do przedstawienia wyniku. Może ona zawierać następujące nazwy: 'millennia
', 'centuries
', 'decades
', 'years
', 'weeks
', 'days
', 'hours
', 'minutes
', and 'seconds
'.
mw.language:parseFormattedNumber
lang:parseFormattedNumber( s )
Przyjmuje liczbę zapisaną tak jak wyniki z lang:formatNum() i zwraca właściwą liczbę. Innymi słowy, jest to językowa-świadoma wersja funkcji tonumber()
.
mw.language:convertPlural
lang:convertPlural( n, ... )
lang:convertPlural( n, forms )
lang:plural( n, ... )
lang:plural( n, forms )
Wybiera właściwą formę gramatyczną z forms
(która musi być tablicą sekwencyjną) lub z ...
, na podstawie liczby n
. Na przykład w języku polskim można użyć n .. ' ' .. lang:plural( n, 'skarpetka', 'skarpetki', 'skarpetek' )
lub n .. ' ' .. lang:plural( n, { 'skarpetka', 'skarpetki', 'skarpetek' } )
aby uzyskać gramatycznie poprawną treść zarówno dla 1 skarpetki jak i 2 lub 200 skarpetek.
Niezbędne wartości dla sekwencji są zależne od języka, zobacz więcej szczegółów w sekcji Lokalizacja w Help:Magiczne słowa i FAQ on PLURAL na translatewiki.
mw.language:convertGrammar
lang:convertGrammar( word, case )
lang:grammar( case, word )
- Note the different parameter order between the two aliases.
convertGrammar
matches the order of the method of the same name on MediaWiki's Language object, whilegrammar
matches the order of the parser function of the same name, documented at Help:Magic words#Localisation.
This chooses the appropriate inflected form of word
for the given inflection code case
.
The possible values for word
and case
are language-dependent, see Special:MyLanguage/Help:Magic words#Localisation and translatewiki:Grammar for some details.
mw.language:gender
lang:gender( what, masculine, feminine, neutral )
lang:gender( what, { masculine, feminine, neutral } )
Wybiera łańcuch testowy odpowiadający rodzajowi w what
, który może być wartością „male”, „female” lub zarejestrowaną nazwą użytkownika.
mw.language:getArrow
lang:getArrow( direction )
Zwraca znak strzałki w Unikodzie odpowiadający wartości direction
:
- forwards: Albo "→" albo "←", w zależności od kierunku zapisu języka.
- backwards: Albo "←" albo "→", w zależności od kierunku zapisu języka.
- left: "←"
- right: "→"
- up: "↑"
- down: "↓"
mw.language:getDir
lang:getDir()
Zwraca "ltr" lub "rtl", w zależności od kierunku zapisu języka.
mw.language:getDirMark
lang:getDirMark( opposite )
Zwraca łańcuch tekstowy zawierający albo U+200E (znacznik z-lewej-do-prawej) albo U+200F (znacznik z-prawej-do-lewej), w zależności od kierunku zapisu języka i logicznego argumentu odwrotnie
czy jest włączony (true
), czy nie (false
).
mw.language:getDirMarkEntity
lang:getDirMarkEntity( opposite )
Zwraca "‎" lub "‏" w zależności od kierunku zapisu języka i flagi odwrotnie
czy jest włączona (true
) czy nie (false
).
mw.language:getDurationIntervals
lang:getDurationIntervals( seconds )
lang:getDurationIntervals( seconds, chosenIntervals )
Dzieli przedział czasu w sekundach na części w jednostkach bardziej czytelnych dla człowieka, np. 12345 na 3 godziny, 25 minut i 45 sekund, zwracając tablicę mapującą nazwy jednostek na liczby.
Jeśli przekazuje się chosenIntervals
, to jest to tablica z wartościami określającymi, które jednostki mają być używane do przedstawienia wyniku. Może ona zawierać następujące nazwy: 'millennia
', 'centuries
', 'decades
', 'years
', 'weeks
', 'days
', 'hours
', 'minutes
', and 'seconds
'.
Those unit keywords are also the keys used in the response table. Only units with a non-zero value are set in the response, unless the response would be empty in which case the smallest unit is returned with a value of 0.
Message library
This library is an interface to the localisation messages and the MediaWiki: namespace.
Functions documented as mw.message.name
are available on the global mw.message
table; functions documented as mw.message:name
and msg:name
are methods of a message object (see mw.message.new
).
mw.message.new
mw.message.new( key, ... )
Creates a new message object for the given message key
.
The remaining parameters are passed to the new object's params()
method.
The message object has no properties, but has several methods documented below.
mw.message.newFallbackSequence
mw.message.newFallbackSequence( ... )
Creates a new message object for the given messages (the first one that exists will be used).
The message object has no properties, but has several methods documented below.
mw.message.newRawMessage
mw.message.newRawMessage( msg, ... )
Creates a new message object, using the given text directly rather than looking up an internationalized message. The remaining parameters are passed to the new object's params()
method.
The message object has no properties, but has several methods documented below.
mw.message.rawParam
mw.message.rawParam( value )
Wraps the value so that it will not be parsed as wikitext by msg:parse()
.
mw.message.numParam
mw.message.numParam( value )
Wraps the value so that it will automatically be formatted as by lang:formatNum()
. Note this does not depend on the Language library actually being available.
mw.message.getDefaultLanguage
mw.message.getDefaultLanguage()
Returns a Language object for the default language.
mw.message:params
msg:params( ... )
msg:params( params )
Add parameters to the message, which may be passed as individual arguments or as a sequence table. Parameters must be numbers, strings, or the special values returned by mw.message.numParam() or mw.message.rawParam(). If a sequence table is used, parameters must be directly present in the table; references using the __index metamethod will not work.
Returns the msg
object, to allow for call chaining.
mw.message:rawParams
msg:rawParams( ... )
msg:rawParams( params )
Like :params(), but has the effect of passing all the parameters through mw.message.rawParam() first.
Returns the msg
object, to allow for call chaining.
mw.message:numParams
msg:numParams( ... )
msg:numParams( params )
Like :params(), but has the effect of passing all the parameters through mw.message.numParam() first.
Returns the msg
object, to allow for call chaining.
mw.message:inLanguage
msg:inLanguage( lang )
Specifies the language to use when processing the message. lang
may be a string or a table with a getCode()
method (i.e. a Language object).
The default language is the one returned by mw.message.getDefaultLanguage()
.
Returns the msg
object, to allow for call chaining.
mw.message:useDatabase
msg:useDatabase( bool )
Specifies whether to look up messages in the MediaWiki: namespace (i.e. look in the database), or just use the default messages distributed with MediaWiki.
The default is true.
Returns the msg
object, to allow for call chaining.
mw.message:plain
msg:plain()
Substitutes the parameters and returns the message wikitext as-is. Template calls and parser functions are intact.
mw.message:exists
msg:exists()
Returns a boolean indicating whether the message key exists.
mw.message:isBlank
msg:isBlank()
Returns a boolean indicating whether the message key has content. Returns true if the message key does not exist or the message is the empty string.
mw.message:isDisabled
msg:isDisabled()
Returns a boolean indicating whether the message key is disabled. Returns true if the message key does not exist or if the message is the empty string or the string "-".
Site library
mw.site.currentVersion
A string holding the current version of MediaWiki.
mw.site.scriptPath
The value of $wgScriptPath
.
mw.site.server
The value of $wgServer
.
mw.site.siteName
The value of $wgSitename
.
mw.site.stylePath
The value of $wgStylePath
.
mw.site.namespaces
Table holding data for all namespaces, indexed by number.
The data available is:
- id: Namespace number.
- name: Local namespace name.
- canonicalName: Canonical namespace name.
- displayName: Set on namespace 0, the name to be used for display (since the name is often the empty string).
- hasSubpages: Whether subpages are enabled for the namespace.
- hasGenderDistinction: Whether the namespace has different aliases for different genders.
- isCapitalized: Whether the first letter of pages in the namespace is capitalized.
- isContent: Whether this is a content namespace.
- isIncludable: Whether pages in the namespace can be transcluded.
- isMovable: Whether pages in the namespace can be moved.
- isSubject: Whether this is a subject namespace.
- isTalk: Whether this is a talk namespace.
- defaultContentModel: The default content model for the namespace, as a string.
- aliases: List of aliases for the namespace.
- subject: Reference to the corresponding subject namespace's data.
- talk: Reference to the corresponding talk namespace's data.
- associated: Reference to the associated namespace's data.
A metatable is also set that allows for looking up namespaces by name (localized or canonical). For example, both mw.site.namespaces[4]
and mw.site.namespaces.Project
will return information about the Project namespace.
mw.site.contentNamespaces
Table holding just the content namespaces, indexed by number. See mw.site.namespaces for details.
mw.site.subjectNamespaces
Table holding just the subject namespaces, indexed by number. See mw.site.namespaces for details.
mw.site.talkNamespaces
Table holding just the talk namespaces, indexed by number. See mw.site.namespaces for details.
mw.site.stats
Table holding site statistics. Available statistics are:
- pages: Number of pages in the wiki.
- articles: Number of articles in the wiki.
- files: Number of files in the wiki.
- edits: Number of edits in the wiki.
- users: Number of users in the wiki.
- activeUsers: Number of active users in the wiki.
- admins: Number of users in group 'sysop' in the wiki.
mw.site.stats.pagesInCategory
mw.site.stats.pagesInCategory( category, which )
- This function is expensive
Gets statistics about the category. If which
has the special value "*
", the result is a table with the following properties:
- all: Total pages, files, and subcategories.
- subcats: Number of subcategories.
- files: Number of files.
- pages: Number of pages.
If which
is one of the above keys ("all", "subcats", "files", "pages"), the result is a number with the corresponding value.
Each new category queried will increment the expensive function count.
mw.site.stats.pagesInNamespace
mw.site.stats.pagesInNamespace( ns )
Returns the number of pages in the given namespace (specify by number).
mw.site.stats.usersInGroup
mw.site.stats.usersInGroup( group )
Returns the number of users in the given group.
mw.site.interwikiMap
mw.site.interwikiMap( filter )
Returns a table holding data about available interwiki prefixes. If filter
is the string "local", then only data for local interwiki prefixes is returned. If filter
is the string "!local", then only data for non-local prefixes is returned. If no filter is specified, data for all prefixes is returned. A "local" prefix in this context is one that is for the same project. For example, on the English Wikipedia, other-language Wikipedias are considered local, while Wiktionary and such are not.
Keys in the table returned by this function are interwiki prefixes, and the values are subtables with the following properties:
- prefix - the interwiki prefix.
- url - the URL that the interwiki points to. The page name is represented by the parameter $1.
- isProtocolRelative - a boolean showing whether the URL is protocol-relative.
- isLocal - whether the URL is for a site in the current project.
- isCurrentWiki - whether the URL is for the current wiki.
- isTranscludable - whether pages using this interwiki prefix are transcludable. This requires scary transclusion, which is disabled on Wikimedia wikis.
- isExtraLanguageLink - whether the interwiki is listed in
$wgExtraInterlanguageLinkPrefixes
.
- displayText - for links listed in $wgExtraInterlanguageLinkPrefixes, this is the display text shown for the interlanguage link. Nil if not specified.
- tooltip - for links listed in $wgExtraInterlanguageLinkPrefixes, this is the tooltip text shown when users hover over the interlanguage link. Nil if not specified.
Biblioteka tekstowa
Biblioteka tekstowa dostarcza pewne wspólne funkcje przetwarzające tekst, których zabrakło w bibliotece łańcuchów tekstowych i bibliotece Ustring. Funkcje te zachowują się bezpieczne gdy są używane z łańcuchami tekstowymi zakodowanymi systemem UTF-8.
mw.text.decode
mw.text.decode( s )
mw.text.decode( s, decodeNamedEntities )
Zamienia encje HTML w łańcuchu tekstowym na odpowiednie znaki.
Jeśli decodeNamedEntities
jest pominięte lub ma wartość false
, to jedynymi rozpoznawanymi encjami są '<', '>', '&', '"', i ' '. W przeciwnym razie list rozpoznawalnych nazwanych encji HTML5 jest ładowana funkcją PHP [$url get_html_translation_table
].
Otherwise, the list of HTML5 named entities to recognize is loaded from PHP's get_html_translation_table
function.
Known bugs: Approximately 600 of around 2200 named entities in the HTML5 standard do not get decoded, even when decodeNamedEntities
is used; this includes approximately 40 of around 250 entities which are also included in HTML4.
This occurs because PHP's get_html_translation_table
function returns only one mapping for each character, so for example
is not decoded since PHP returns only →
as the mapping for →
.
→
mw.text.encode
mw.text.encode( s )
mw.text.encode( s, charset )
Zamienia znaki w łańcuchu tekstowym na encje HTML. Znaki '<', '>', '&', '"' i spacja niełamiąca są zamieniane na właściwe nazwane encje; wszystkie pozostałe są zamieniane na encje numeryczne.
Five characters are replaced with the appropriate named entities: <
, >
, &
, "
and the non-breaking space (U+00A0).
All others are replaced with numeric entities.
Jeśli jest podany zbiór znaków charset
, to powinien to być odpowiedni łańcuch tekstowy, który można wstawić w nawiasy kwadratowe we wzorze Ustring, na przykład „zbiór” w [zbiór]
. Domyślnym zbiorem znaków jest '<>&"\' '
(spacja na końcu to spacja niełamiąca, U+00A0).
mw.text.jsonDecode
mw.text.jsonDecode( s )
mw.text.jsonDecode( s, flags )
Dekoduje łańcuch tekstowy z danymi w formacie JSON. Flagi flags
to 0 lub kombinacja (za pomocą +
) flag mw.text.JSON_PRESERVE_KEYS
i mw.text.JSON_TRY_FIXING
.
Tablice w JSON są indeksowane od zera lecz podczas przepisywania do Lua ich indeksy zaczynają się standardowo od jedności; aby temu zapobiec należy przekazać flagę mw.text.JSON_PRESERVE_KEYS
.
Aby zluzować pewne wymagania składni JSON, takie jak brak przecinka po ostatnim elemencie w tablicy lub ostatnim polu w obiekcie, należy przekazać flagę mw.text.JSON_TRY_FIXING
. Nie jest to zalecane.
Ograniczenia:
- Odkodowane tablice JSON mogą nie być sekwencjami w Lua jeśli tablica zawiera wartości null.
- Obiekty JSON stracą klucze w wartościach null.
- Nie można bezpośrednio stwierdzić czy na wejściu była tablica JSON, czy obiekt JSON z sekwencją kluczy będących liczbami całkowitymi.
- Obiekt JSON mający sekwencję kluczy będących liczbami całkowitymi zaczynającymi się od 1 będzie odkodowany do tablicy o takiej samej strukturze jak tablica JSON z takimi samymi wartościami, pomimo że są to zupełnie nierównoważne konstrukcje, chyba że zostanie użyta flaga
mw.text.JSON_PRESERVE_KEYS
.
mw.text.jsonEncode
mw.text.jsonEncode( value )
mw.text.jsonEncode( value, flags )
Koduje dane na łańcuch tekstowy w formacie JSON. Jeśli wartość nie może zakodowana w formacie JSON to zgłaszane są błędy. Flagi flags
to 0 lub kombinacja (za pomocą +
) flag mw.text.JSON_PRESERVE_KEYS
i mw.text.JSON_TRY_FIXING
.
Tablice w Lua są indeksowane od jednego lecz podczas przekształcania ich w JSON ich indeksy standardowo zaczynają się od zera; użycie flagi mw.text.JSON_PRESERVE_KEYS
w argumencie flags
spowoduje, że sekwencje zaczynające się od zera będą kodowane jako tablice w formacie JSON.
Ograniczenia:
- Puste tablice są zawsze zakodowane jako puste tablice (
[]
), a nie jak puste obiekty ({}
). - Tablice z sekwencją nie mogą być zakodowane jako obiekty JSON bes dodawania „sztucznego” elementu.
- Aby tworzyć obiekty lub tablice z wartościami nil wymagana jest zawiło-zręczna implementacja metametody
__pairs
. - Tablice Lua mające sekwencję kluczy będących liczbami całkowitymi i zaczynających się od zera zostaną zakodowane w JSON jako tablice, tak samo jak tablice Lua, których klucze zaczynają się od 1, chyba że zostanie użyta flaga
mw.text.JSON_PRESERVE_KEYS
. - Jeśli jakaś liczba i jej zapis w postaci łańcucha tekstowego będą razem użyte jako klucze w tej samej tablicy to zachowanie jest nieokreślone.
mw.text.killMarkers
mw.text.killMarkers( s )
Usuwa wszystkie specjalne znaczniki MediaWiki („strip marker”) z łańcucha tekstowego.
mw.text.listToText
mw.text.listToText( list )
mw.text.listToText( list, separator, conjunction )
Łączy listę w opisowym stylu. Innymi słowy działa podobnie jak table.concat()
lecz z innym separatorem przed ostatnim elementem.
Domyślny separator jest brany z MediaWiki:comma-separator w języku w jakim tworzona jest treść wiki, a domyślny ostatni łącznik to MediaWiki:and połączony z MediaWiki:word-separator.
Przykłady używające domyślne wartości w komunikatach:
-- Zwraca pusty łańcuch tekstowy
mw.text.listToText( {} )
-- Zwraca "1"
mw.text.listToText( { 1 } )
-- Zwraca "1 oraz 2"
mw.text.listToText( { 1, 2 } )
-- Zwraca "1, 2, 3, 4 oraz 5"
mw.text.listToText( { 1, 2, 3, 4, 5 } )
-- Returns "1; 2; 3; 4 or 5"
mw.text.listToText( { 1, 2, 3, 4, 5 }, '; ', ' or ' )
mw.text.nowiki
mw.text.nowiki( s )
Zamienia różne znaki w łańcuchu tekstowym na encje HTML aby zapobiec ich interpretacji jako wikikod. To obejmuje:
- Następujące znaki:
"
,&
,'
,<
,=
,>
,[
,]
,{
,|
,}
- Następujące znaki na początku łańcucha tekstowego lub bezpośrednio po znaku nowej linii:
#
,*
,:
,;
, spacja, tabulacja (\t
) - Puste linie będą miały jeden ze stowarzyszonych znaków nowej linii albo powrotu karetki zastąpiony sekwencją specjalną
----
na początku łańcucha tekstowego lub bezpośrednio po znaku nowej linii będzie miał pierwszy '-' zamieniony sekwencją specjalną__
będzie miał jedno podkreślenie zamienione sekwencją specjalną://
będzie miał dwukropek zamieniony sekwencją specjalną- Znak odstępu po
ISBN
,RFC
lubPMID
będzie zastąpiony sekwencją specjalną
mw.text.split
mw.text.split( s, pattern, plain )
Dzieli łańcuch tekstowy na podłańcuchy, w których granice dzielenia wyznacza wzrór Ustring pattern
. Jeśli wartość plain
jest ustawiona na true
, to pattern
będzie interpretowany jako literalny łańcuch tekstowy zamiast wzoru wyrażenia regularnego Lua (tak jak odpowiedni argument mw.ustring.find()
). Funkcja zwraca tablicę zawierającą podłańcuchy tekstowe.
Na przykład mw.text.split( 'a b\tc\nd', '%s' )
zwróci tablicę { 'a', 'b', 'c', 'd' }
.
Jeśli wzór pattern
wyszukuje pusty tekst, to s
będzie podzielony na pojedyncze znaki.
mw.text.gsplit
mw.text.gsplit( s, pattern, plain )
Zwraca funkcję iteratora, która będzie kolejno zwracała podłańcuchy; ostateczny wynik powinien być równoważny z wywołaniem mw.text.split()
.
mw.text.tag
mw.text.tag( name, attrs, content )
mw.text.tag{ name = string, attrs = table, content = string|false }
- Należy pamiętać o używaniu nazwanych argumentów.
Tworzy znacznik w stylu HTML o nazwie name
.
Jeśli jest podany argument attrs
, to musi on być tablicą z kluczami będącymi łańcuchami tekstowymi. Wartości tekstowe i liczbowe są używane jako wartości atrybutów; logiczna wartość true
powoduje, że klucz będzie wyemitowany jako parametr bezwartościowy, wartość false
pomija klucz całkowicie; inne wartości są błędami.
Jeśli argument content
nie jest podany (lub jest nil), to zwracany jest tylko znacznik otwierający. Jeśli content
to wartość logiczna false
, to zwracany jest znacznik samozamykający. W przeciwnym razie zawartość musi być łańcuchem tekstowym lub liczbą, która to jest zawierana między znacznikami otwierającym i zamykającym. Należy pamiętać, że treść nie jest automatycznie kodowana w HTML; w razie potrzeby należy użyć mw.text.encode().
Aby uzyskać prawidłowo działające znaczniki rozszerzające takie jak <ref>
należy stosować frame:extensionTag().
mw.text.trim
mw.text.trim( s )
mw.text.trim( s, charset )
Usuwa odstępy i inne znaki na początku i końcu łańcucha tekstowego.
Jeśli jest podany zbiór znaków charset
, to powinien to być odpowiedni łańcuch tekstowy, który można wstawić w nawiasy kwadratowe we wzorze Ustring, na przykład „zbiór” w [zbiór]
. Domyślnym zbiorem znaków jest odstęp w ASCII, "\t\r\n\f "
.
mw.text.truncate
mw.text.truncate( text, length )
mw.text.truncate( text, length, ellipsis )
mw.text.truncate( text, length, ellipsis, adjustLength )
Obcina test
do określonej długości, dodając wielokropek (ellipsis
) jeśli obcięcie zostało wykonane. Jeśli długość (length
) jest dodatnia, to koniec tekstu będzie obcięty; jeśli ujemna, to obcięty będzie początek. Jeśli jest podany argument adjustLength
i ma on wartość true
, to wynikowy łańcuch tekstowy wraz z wielokropkiem nie będzie dłuższy niż określona długość.
Domyślna wartość dla wielokropka (ellipsis
) jest brana z MediaWiki:ellipsis w języku, w którym tworzona jest zawartość wiki.
Przykłady używające domyślnego wielokropka „...”:
-- Returns "foobarbaz"
mw.text.truncate( "foobarbaz", 9 )
-- Returns "fooba..."
mw.text.truncate( "foobarbaz", 5 )
-- Returns "...arbaz"
mw.text.truncate( "foobarbaz", -5 )
-- Returns "foo..."
mw.text.truncate( "foobarbaz", 6, nil, true )
-- Returns "foobarbaz", because that's shorter than "foobarba..."
mw.text.truncate( "foobarbaz", 8 )
mw.text.unstripNoWiki
mw.text.unstripNoWiki( s )
Zamienia specjalne znaczniki MediaWiki (strip marker) pochodzące od <nowiki> przez odpowiadający im tekst. Znaczniki utworzone z innych powodów pozostają nietknięte.
mw.text.unstrip
mw.text.unstrip( s )
Równoważne wywołaniu mw.text.killMarkers( mw.text.unstripNoWiki( s ) )
.
Ta funkcja już nie ujawnia kodu HTML utworzonego przez transkluzję stron specjalnych, znaczników <ref> i innych, co było możliwe we wcześniejszych wersjach Scribunto.
Biblioteka tytułowa
mw.title.equals
mw.title.equals( a, b )
Sprawdza czy dwa tytuły są równe. Należy pamiętać, że fragmenty są ignorowane w porównywaniu.
mw.title.compare
mw.title.compare( a, b )
Zwraca -1, 0 lub 1 aby wskazać czy tytuł a
jest mniejszy, równy lub większy niż tytuł b
.
Operacja zaczyna się od porównania przedrostków interwiki (jeśli istnieją) jako łańcuchów tekstowych, następnie po numerze przestrzeni, a na końcu po tytule strony jako łańcucha tekstowego pozbawionego przedrostka nazwy przestrzeni. Porównywanie łańcuchów tekstowych używa standardowego operatora Lua <
.
mw.title.getCurrentTitle
mw.title.getCurrentTitle()
Zwraca obiekt tytułu dla bieżącej strony.
mw.title.new
mw.title.new( text, namespace )
mw.title.new( id )
- Ta funkcja wywołana z
id
jest skomplikowana obliczeniowo
Tworzy nowy obiekt tytułu.
Jeśli podano numer id
, tworzony jest obiekt z tytułem strony o takim numerze identyfikatora strony. Przywołany tytuł będzie figurował jako linkujący z bieżącej strony. Jeśli identyfikator strony nie istnieje to wynikiem będzie nil. Licznik funkcji skomplikowanych obliczeniowo będzie zwiększony jeśli tworzony obiekt tytułu dotyczy innego tytułu niż już załadowanego.
Natomiast jeśli podano łańcuch tekstowy text
, to obiekt jest tworzony dla podanego tytułu (nawet jeśli ta strona nie istnieje). Jeśli łańcuch tekstowy nie określa przestrzeni nazw, to będzie użyta wartość namespace
(która może być dowolnym kluczem znalezionym w mw.site.namespaces
). Jeśli wartość text
nie jest prawidłową nazwą tytułu, to wynikiem będzie nil.
mw.title.makeTitle
mw.title.makeTitle( namespace, title, fragment, interwiki )
Tworzy obiekt tytułu z tytułem title
w przestrzeni nazw namespace
, opcjonalnie z określonym fragmentem fragment
i przedrostkiem interwiki
. Wartość namespace
może być dowolnym kluczem znalezionym w mw.site.namespaces
. Jeśli wynik byłby nieprawidłowy zwracany jest nil.
Należy pamiętać, że inaczej niż w funkcji mw.title.new()
, ta metoda zawsze zastosuje określoną nazwę przestrzeni. Na przykład mw.title.makeTitle( 'Szablon', 'Moduł:Foo' )
utworzy obiekt dla strony Szablon:Moduł:Foo, natomiast mw.title.new( 'Moduł:Foo', 'Szablon' )
utworzy obiekt dla strony Moduł:Foo.
Note also that functionality for interwiki titles is limited to interwiki
/ isExternal
/ isLocal
and URL-related methods; other methods might not behave as expected.
Obiekty tytułów
Obiekty tytułu ma liczne cechy i metody. Większość cech jest tylko do odczytu.
Należy pamiętać, że pola kończące się na text
zwracają tytuły jako wartości będące łańcuchami tekstowymi, natomiast pola kończące się na title
zwracają obiekty tytułów.
- id: Identyfikator strony.
0
jeśli strona nie istnieje. To może być skomplikowane obliczeniowo. - interwiki: Przedrostek interwiki lub pusty łańcuch tekstowy jeśli brak.
- namespace: Numer przestrzeni nazw.
- fragment: The fragment (aka section/anchor linking), or the empty string. May be assigned.
- nsText: Nazwa przestrzeni nazw dla tej strony.
- subjectNsText: Nazwa przedmiotowej przestrzeni nazw dla tej strony.
- talkNsText: The text of the talk namespace for the page, or
nil
if this title cannot have a talk page. (added in MediaWiki 1.42.0-wmf.15, refs T180911)
- text: Tytuł strony bez nazwy przestrzeni i bez przedrostka interwiki.
- prefixedText: Tytuł strony razem z nazwą przestrzeni i przedrostkiem interwiki.
- fullText: Tytuł strony z nazwą przestrzeni, przedrostkiem interwiki i fragmentem.
- rootText: Jeśli jest to podstrona, to tytuł strony głównej bez przedrostków. W przeciwnym razie to samo co
title.text
. - baseText: Jeśli jest to podstrona, to tytuł strony, której jest ona podstroną, bez przedrostków. W przeciwnym razie to samo co
title.text
. - subpageText: Jeśli jest to podstrona, to ostatni człon jej nazwy. W przeciwnym razie to samo co
title.text
. - canTalk: Wskazuje czy strona o tym tytule może mieć stronę dyskusji.
- exists: Whether the page exists. Alias for
file.exists
for Media-namespace titles. For File-namespace titles this checks the existence of the file description page, not the file itself. This may be expensive.
- file, fileExists: See #File metadata below.
- isContentPage: Whether this title is in a content namespace.
- isExternal: Whether this title has an interwiki prefix.
- isLocal: Whether this title is in this project. For example, on the English Wikipedia, any other Wikipedia is considered "local" while Wiktionary and such are not.
- isRedirect: Whether this is the title for a page that is a redirect. This may be expensive.
- isSpecialPage: Whether this is the title for a possible special page (i.e. a page in the Special: namespace).
- isSubpage: Whether this title is a subpage of some other title.
- isTalkPage: Whether this is a title for a talk page.
- isSubpageOf( title2 ): Whether this title is a subpage of the given title.
- inNamespace( ns ): Whether this title is in the given namespace. Namespaces may be specified by anything that is a key found in
mw.site.namespaces
.
- inNamespaces( ... ): Whether this title is in any of the given namespaces. Namespaces may be specified by anything that is a key found in
mw.site.namespaces
.
- hasSubjectNamespace( ns ): Whether this title's subject namespace is in the given namespace. Namespaces may be specified by anything that is a key found in
mw.site.namespaces
.
- contentModel: The content model for this title, as a string. This may be expensive.
- basePageTitle: The same as
mw.title.makeTitle( title.namespace, title.baseText )
.
- rootPageTitle: The same as
mw.title.makeTitle( title.namespace, title.rootText )
.
- talkPageTitle: The same as
mw.title.makeTitle( mw.site.namespaces[title.namespace].talk.id, title.text )
, ornil
if this title cannot have a talk page.
- subjectPageTitle: The same as
mw.title.makeTitle( mw.site.namespaces[title.namespace].subject.id, title.text )
.
- redirectTarget: Returns a title object of the target of the redirect page if the page is a redirect and the page exists, returns
false
otherwise.
- protectionLevels: The page's protection levels. This is a table with keys corresponding to each action (e.g.,
"edit"
and"move"
). The table values are arrays, the first item of which is a string containing the protection level. If the page is unprotected, either the table values or the array items will benil
. This is expensive.
- cascadingProtection: The cascading protections applicable to the page. This is a table with keys
"restrictions"
(itself a table with keys likeprotectionLevels
has) and"sources"
(an array listing titles where the protections cascade from). If no protections cascade to the page,"restrictions"
and"sources"
will be empty. This is expensive.
- categories: (since v1.43.0-wmf.18) The list of categories used on the page. This is expensive
- subPageTitle( text ): The same as
mw.title.makeTitle( title.namespace, title.text .. '/' .. text )
.
- partialUrl(): Returns
title.text
encoded as it would be in a URL.
- fullUrl( query, proto ): Returns the full URL (with optional query table/string) for this title. proto may be specified to control the scheme of the resulting url:
"http"
,"https"
,"relative"
(the default), or"canonical"
.
- localUrl( query ): Returns the local URL (with optional query table/string) for this title.
- canonicalUrl( query ): Returns the canonical URL (with optional query table/string) for this title.
- getContent(): Returns the (unparsed) content of the page, or
nil
if there is no page. The page will be recorded as a transclusion.
- pageLang: A language object for the title's page content language, which defaults to the wiki's content language. This is expensive.
Obiekty tytułów mogą być porównywane za pomocą operatorów relacji. Funkcja tostring( title )
zwróci title.prefixedText
.
Note that accessing any expensive field on a title object records a "link" to the page (as shown on Special:WhatLinksHere, for example). Using the title object's getContent()
method or accessing the redirectTarget
field records it as a "dołączony szablon", and accessing the title object's file
or fileExists
fields records it as a "link do pliku".
Metadane pliku
Obiekty tytułów przedstawiające strony z przestrzeni nazw Plik lub Media będą miały cechę zwaną file
. To jest skomplikowane obliczeniowo. Jest to tablica o następującej budowie:
- exists: Wskazuje czy plik istnieje. Użycie będzie zarejestrowane jako wykorzystanie obrazu/pliku. Cecha
fileExists
w obiekcie tytułu istnieje z powodu wstecznej kompatybilności i jest aliasem dla tej cechy. Jeśli ma ona wartośćfalse
, to wszystkie pozostałe cechy dotyczące plików będą miały wartośćnil
. - width: Szerokość obrazu w pliku. Jeśli plik zawiera wiele stron, to jest to szerokość obrazu pierwszej strony.
- height: Wysokość obrazu w pliku. Jeśli plik zawiera wiele stron, to jest to wysokość obrazu pierwszej strony.
- pages: If the file format supports multiple pages, this is a table containing tables for each page of the file; otherwise, it is
nil
. The # operator can be used to get the number of pages in the file. Each individual page table contains a width and height property.
- size: The size of the file in bytes.
- mimeType: The MIME type of the file.
- length: The length (duration) of the media file in seconds. Zero for media types which do not support length.
Cechy skomplikowane obliczeniowo
Cechy id
, isRedirect
, exists
i contentModel
wymagają pobrania danych o tytule z bazy danych. Z tego powodu zwiększany jest licznik funkcji skomplikowanych obliczeniowo gdy po raz pierwszy jedna z nich jest użyta dla strony innej niż bieżąca. Powtórne użycie dowolnej z tych cech dla tamtej strony już nie zwiększa licznika funkcji skomplikowanych obliczeniowo.
Pozostałe cechy oznaczone jako skomplikowane obliczeniowo zawsze zwiększają licznik funkcji skomplikowanych obliczeniowo, gdy są po raz pierwszy wywołane dla strony innej niż bieżąca.
Biblioteka URI
mw.uri.encode
mw.uri.encode( s, enctype )
Koduje procentowo łańcuch tekstowy. Domyślny typ, "QUERY"
koduje spacje używając '+' do stosowania w zapytaniach; "PATH"
koduje spacje jako %20, a "WIKI"
koduje spacje jako '_'.
Należy pamiętać, że format "WIKI"
nie jest w pełni odwracalny, ponieważ zarówno spacje jak i znaki podkreślenia są kodowane przez '_'.
mw.uri.decode
mw.uri.decode( s, enctype )
Dekoduje procentowo zakodowany łańcuch tekstowy. Domyślny typ, "QUERY"
, zamienia '+' na spacje, "PATH"
nie wykonuje żadnych dodatkowych zmian, a "WIKI"
zamienia '_' na spacje.
mw.uri.anchorEncode
mw.uri.anchorEncode( s )
Koduje łańcuch tekstowy do wykorzystania jako fragment w URI MediaWiki.
mw.uri.buildQueryString
mw.uri.buildQueryString( table )
Koduje tablicę jako łańcuch tekstowy z zapytaniem dla URI. Klucze powinny być łańcuchami tekstowymi; wartości mogą być łańcuchami tekstowymi, wielkościami liczbowymi, tablicami sekwencyjnymi lub wartościami logicznymi false
.
mw.uri.parseQueryString
mw.uri.parseQueryString( s, i, j )
Zamienia łańcuch tekstowy, który jest zapytaniem z URI, na tablicę. Klucze z zapytania bez wartości będą miały przypisaną wartość false
; klucze powtórzone wielokrotnie będą miały przypisaną tablicę sekwencyjną z wartościami; pozostałe klucze będą miały przypisane łańcuchy tekstowe jako wartości.
Opcjonalne liczbowe argumenty i
i j
można użyć aby wskazać podłańcuch tekstowy to analizy, zamiast całego łańcucha tekstowego. Argument i
określa pozycję pierwszego znaku w łańcuchu tekstowym i domyślnie przyjmuje się 1. Argument j
jest pozycją ostatniego znaku w łańcuchu tekstowym i domyślnie przyjmuje się długość łańcucha tekstowego. Zarówno i
jak i j
mogą być ujemne tak jak w string.sub.
mw.uri.canonicalUrl
mw.uri.canonicalUrl( page, query )
Returns a URI object for the canonical URL for a page, with optional query string/table.
mw.uri.fullUrl
mw.uri.fullUrl( page, query )
Returns a URI object for the full URL for a page, with optional query string/table.
mw.uri.localUrl
mw.uri.localUrl( page, query )
Returns a URI object for the local URL for a page, with optional query string/table.
mw.uri.new
mw.uri.new( s )
Tworzy nowy obiekt URI z podanego łańcucha tekstowego lub tablicy. Zobacz opis obiektów URI aby poznać dopuszczalne pola w tablicy.
mw.uri.validate
mw.uri.validate( table )
Sprawdza poprawność przekazanej tablicy (lub obiektu URI). Zwraca wartość logiczną wskazującą czy tablica jest poprawna, a w przypadku błędów łańcuch tekstowy wyjaśniający jakie problemy zostały znalezione.
Obiekt URI
Obiekt URI ma następujące pola, z których część lub wszystkie mogą być nil:
- protocol: Łańcuch tekstowy z protokołem/schematem
- user: Łańcuch tekstowy z nazwą użytkownika
- password: Łańcuch tekstowy z hasłem
- host: Łańcuch tekstowy z nazwą serwera
- port: Numer portu, który jest liczbą całkowitą
- path: Łańcuch tekstowy ze ścieżką
- query: Tablica taka jak z funkcji mw.uri.parseQueryString
- fragment: Łańcuch tekstowy z fragmentem.
Dostępne są również następujące cechy:
- userInfo: Łańcuch tekstowy z nazwą użytkownika i hasłem
- hostPort: Łańcuch tekstowy z nazwą serwera i numerem portu
- authority: Łańcuch tekstowy z nazwą użytkownika, hasłem, nazwą serwera i numerem portu
- queryString: Tablica z zapytaniem w postaci łańcucha tekstowego
- relativePath: Łańcuch tekstowy ze ścieżką, zapytaniem i fragmentem
Funkcja tostring()
zwraca łańcuch tekstowy z URI.
Metodami obiektu URI są:
mw.uri:parse
uri:parse( s )
Analizuje podany łańcuch tekstowy i umieszcza wyniki do bieżącego obiektu URI. Dowolne pola określone w łańcuchu tekstowym będą zamienione w bieżącym obiekcie, pola niewskazane zachowają swoje pierwotne wartości.
mw.uri:clone
uri:clone()
Tworzy kopię obiektu URI.
mw.uri:extend
uri:extend( parameters )
Scala zawartość tablicy parameters
z tablicą zapytania w obiekcie (query
).
Biblioteka Ustring
Bezpośrednim celem biblioteki ustring jest zaimplementowanie standardowej biblioteki łańcuchów tekstowych, z tą różnicą, że jej metody operują na znakach łańcuchów tekstowych zakodowanych w UTF-8 zamiast bajtów.
Większość funkcji zgłasza błąd jeśli łańcuch nie jest prawidłowo zakodowany w UTF-8; wyjątki są wykazane.
mw.ustring.maxPatternLength
Największa dopuszczalna długość wzoru w bajtach.
mw.ustring.maxStringLength
Największa dopuszczalna długość łańcucha tekstowego w bajtach.
mw.ustring.byte
mw.ustring.byte( s, i, j )
Zwraca pojedyncze bajty; identycznie jak string.byte().
mw.ustring.byteoffset
mw.ustring.byteoffset( s, l, i )
Zwraca bajtową pozycję znaku w łańcuchu tekstowym. Domyślnie dla obu wartości l
i i
przyjmowane jest 1. Wartość i
może być ujemna, i w takim przypadku odliczanie będzie prowadzone od końca łańcucha tekstowego.
Dla l
== 1 pierwszy znak zaczyna się na pozycji bajtowej i
lub po niej. Dla l
== 0 pierwszy znak zaczyna się na pozycji bajtowej i
lub przed nią. Należy zauważyć, że może to być ten sam znak. Większe lub mniejsze wartości l
są obliczane względem tych.
mw.ustring.char
mw.ustring.char( ... )
Podobnie jak string.char(), z tą różnicą, że liczby całkowite określają wartości kodów znaków Unikodzie zamiast bajtów.
local value = mw.ustring.char( 0x41f, 0x440, 0x438, 0x432, 0x435, 0x442, 0x21 ) -- value is now 'Привет!'
mw.ustring.codepoint
mw.ustring.codepoint( s, i, j )
Podobnie jak string.byte(), z tą różnicą, że zwracane wartości to kody znaków Unikode, a indeksy wskazują numer znaku a nie bajtu.
mw.ustring.find
mw.ustring.find( s, pattern, init, plain )
Podobnie jak string.find(), z tą różnicą, że wzór pattern
jest poszerzony tak jak to opisano w sekcji wzory Ustring oraz indeks init
wskazuje numer znaku, a nie bajtu.
mw.ustring.format
mw.ustring.format( format, ... )
Identycznie do string.format(). Szerokość i precyzja dla łańcuchów tekstowych są wyrażone w bajtach, a nie kodach Unikodu.
mw.ustring.gcodepoint
mw.ustring.gcodepoint( s, i, j )
Zwraca trzy wartości do iterowania po znakach Unikode w łańcuchu tekstowym. Domyślna wartość dla i
to 1, a dla j
to -1. Funkcja jest przeznaczona do użycia przez iterowaną postać pętli for
:
for codepoint in mw.ustring.gcodepoint( s ) do
-- blok
end
mw.ustring.gmatch
mw.ustring.gmatch( s, pattern )
Podobnie jak string.gmatch(), z tą różnicą, że wzór pattern
jest poszerzony tak jak jest to opisane w sekcji wzory Ustring.
Known bug: When used with a pattern which can match the empty string, the function will get stuck in an infinite loop. For example, the following loop never terminates:
for capture in mw.ustring.gmatch( "foo bar", ".*" ) do
-- block
end
mw.ustring.gsub
mw.ustring.gsub( s, pattern, repl, n )
Podobnie jak string.gsub(), z tą różnicą, że wzór pattern
jest poszerzony tak jak to opisano w sekcji wzory Ustring.
Known bugs: When repl
is a table, it is possible to use numbers as keys instead of strings (e.g. to replace instances of
in a string, the value at key "5"
or [5]
would be used); as such, the output is not predictable if they have different (non-nil) values.
["5"]
This is not an issue for string.gsub(), which ignores any numbers as keys.
mw.ustring.isutf8
mw.ustring.isutf8( s )
Zwraca true
jeśli łańcuch tekstowy jest prawidłowy w kodowaniu UTF-8, w przeciwnym razie wynikiem jest false
.
mw.ustring.len
mw.ustring.len( s )
Zwraca długość łańcucha tekstowego z znakach Unikodu, lub nil jeśli łańcuch nie jest prawidłowy w kodowaniu UTF-8.
Zobacz opis podobnej funkcji string.len(), która oblicza długość w bajtach zamiast w znakach Unikodu.
mw.ustring.lower
mw.ustring.lower( s )
Podobnie jak string.lower(), z tą różnicą, że zamieniane są wszystkie znaki, które mają odpowiednie definicje w Unikodzie.
Jeśli jest załadowana biblioteka językowa, to wtedy wywołanie zastąpione będzie przez lc() domyślnego obiektu językowego.
mw.ustring.match
mw.ustring.match( s, pattern, init )
Podobnie jak string.match(), z tą różnicą, że wzór pattern
jest poszerzony tak jak to opisano w sekcji wzory Ustring, oraz indeks init
wskazuje numer znaku, a nie bajtu.
mw.ustring.rep
mw.ustring.rep( s, n )
Identycznie do string.rep().
mw.ustring.sub
mw.ustring.sub( s, i, j )
Podobnie jak string.sub(), z tą różnicą, że indeksy wskazują numer znaku, a nie bajtu.
mw.ustring.toNFC
mw.ustring.toNFC( s )
Zamienia łańcuch tekstowy na Znormalizowaną Postać C. Zwraca nil jeśli łańcuch tekstowy nie jest poprawny w UTF-8.
mw.ustring.toNFD
mw.ustring.toNFD( s )
Zamienia łańcuch tekstowy na Znormalizowaną Postać D. Zwraca nil jeśli łańcuch tekstowy nie jest poprawny w 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 )
Podobnie jak string.upper(), z tą różnicą, że zamieniane są wszystkie znaki, które mają odpowiednie definicje w Unikodzie.
Jeśli jest załadowana biblioteka językowa, to wtedy wywołanie zastąpione będzie przez uc() domyślnego obiektu językowego.
Wzory Ustring
Wzory w funkcjach z ustring używają tej samej składni jak wzory w bibliotece łańcuchów tekstowych. Główną różnicą jest to, że klasy znaków są przedefiniowane pod kątem cech znaków Unikodu.
%a
: reprezentuje wszystkie znaki z kategorii ogólnej „Litera”.%c
: reprezentuje wszystkie znaki z kategorii ogólnej „Znak sterujący”.%d
: reprezentuje wszystkie znaki z kategorii ogólnej „Cyfra dziesiętna”.%l
: reprezentuje wszystkie znaki z kategorii ogólnej „Mała litera”.%p
: reprezentuje wszystkie znaki z kategorii ogólnej „Interpunkcja”.%s
: reprezentuje wszystkie znaki z kategorii ogólnej „Separator”, oraz dodatkowo tabulacja (tab), nowa linia (linefeed), powrót karetki (carriage return), tabulacja pionowa (vertical tab), i nowa strona (form feed).%u
: reprezentuje wszystkie znaki z kategorii ogólnej „Wielka litera”.%w
: reprezentuje wszystkie znaki z kategorii ogólnej „Litera” lub „Cyfra dziesiętna”.%x
: dodaje warianty znaków cyfr szesnastkowych o pełnej szerokości.
%c
: represents all characters with General Category "Control".
%d
: represents all characters with General Category "Number, decimal digit".
%l
: represents all characters with General Category "Lowercase Letter".
%p
: represents all characters with General Category "Punctuation".
%s
: represents all characters with General Category "Separator", plus tab, linefeed, carriage return, vertical tab, and form feed.
%u
: represents all characters with General Category "Uppercase Letter".
%w
: represents all characters with General Category "Letter" or "Decimal Number".
%x
: adds fullwidth character versions of the hex digits.
Like in String library patterns, %A
, %C
, %D
, %L
, %P
, %S
, %U
, %W
oraz %X
here represent the complementary set ("all characters without given General Category").
We wszystkich przypadkach znaki są interpretowane jako znaki Unikodu, a nie bajty, tak więc zakresy jak [0-9]
, wzory jak %b«»
i kwantyfikatory dołączone do wielobajtowych znaków działają prawidłowo. Puste grupy rejestrują pozycję w numerze znaku Unikodu zamiast w bajtach.
Known limitations: Unlike String library patterns, Ustring library patterns have a maximum length of 10,000 bytes. If the pattern exceeds this length, then the Ustring function will throw an error. Because the String library has its own maximum of 32 captures (unlike the Ustring library), it is therefore impossible to use a pattern which exceeds both limits, as it will be incompatible with both libraries.
Note: 9 ASCII characters, $
, +
, <
, =
, >
, ^
, `
, |
, ~
, can be matched by %p
in the string library but not in the ustring library, as Unicode classifies them as Symbols rather than Punctuation.
Ładowalne biblioteki
Te biblioteki nie są ładowane domyślnie, lecz jeśli zajdzie taka potrzeba mogą być załadowane przez użycie require()
.
bit32
Ta emulacja biblioteki bit32
z Lua 5.2 może być załadowana przez:
bit32 = require( 'bit32' )
Biblioteka bit32 dostarcza operatory bitowe dla nieujemnych liczb całkowitych. Wejściowe liczby są obcinane do wartości całkowitych (w bliżej nieokreślony sposób) i zredukowane do reszty z dzielenia przez 232, tak aby ich wartość mieściła się w zakresie od 0 do 232-1; zwracane wyniki są również z tego przedziału.
Kiedy bity są numerowane (tak jak w bit32.extract()), 0 to najmniej znaczący bit (ten o wartości 20), a 31 to najbardziej znaczący (ten o wartości 231).
bit32.band
bit32.band( ... )
Zwraca koniunkcję binarną argumentów: wynik ma ustawiony bit tylko wtedy jeśli jest on ustawiony we wszystkich argumentach.
Jeśli nie podano żadnych argumentów, wynik ma ustawione wszystkie bity.
bit32.bnot
bit32.bnot( x )
Zwraca bitowe dopełnienie z x
.
bit32.bor
bit32.bor( ... )
Zwraca argumentów: wynik ma ustawiony bit jeśli taki bit jest ustawiony w dowolnym argumencie.
Jeśli nie podano żadnych argumentów, wynik ma wszystkie bity wyzerowane.
bit32.btest
bit32.btest( ... )
Równoważne z bit32.band( ... ) ~= 0
bit32.bxor
bit32.bxor( ... )
Zwraca alternatywę rozłączną argumentów: wynik ma ustawiony bit jeśli liczba argumentów, która ma taki bit ustawiony, jest nieparzysta.
Jeśli nie podano żadnych argumentów, wynik ma wszystkie bity wyzerowane.
bit32.extract
bit32.extract( n, field, width )
Wycina fragment bitowy o szerokości width
, zaczynający się od bitu o numerze field
. Próba odczytu bitów o numerach spoza zakresu od 0 do 31 jest błędem.
Wartością domyślną dla width
jest 1, jeśli jej nie podano.
bit32.replace
bit32.replace( n, v, field, width )
Zamienia fragment bitowy o szerokości width
w liczbie n
, zaczynający się od bitu o numerze field
przez fragment o szerokości width
z najmłodszy bitów wartości v
. Próba odczytu bitów o numerach spoza zakresu od 0 do 31 jest błędem.
Wartością domyślną dla width
jest 1, jeśli jej nie podano.
bit32.lshift
bit32.lshift( n, disp )
Zwraca liczbę n
przesuniętą o disp
bitów w lewo. Jest to przesunięcie logiczne: wstawiane bity mają wartość 0. W ogólności jest to równoważne mnożeniu przez 2disp
.
Należy pamiętać, że wynikiem przesunięcia o ponad 31 bitów jest 0.
bit32.rshift
bit32.rshift( n, disp )
Zwraca liczbę n
przesuniętą o disp
bitów w prawo. Jest to przesunięcie logiczne: wstawiane bity mają wartość 0. W ogólności jest to równoważne dzieleniu przez 2disp
.
Należy pamiętać, że wynikiem przesunięcia o ponad 31 bitów jest 0.
bit32.arshift
bit32.arshift( n, disp )
Zwraca liczbę n
przesuniętą o disp
bitów w prawo. Jest to przesunięcie arytmetyczne: jeśli disp
jest dodatnie, to wstawiane bity są takie same jak 31. bit w oryginalnej liczbie.
Należy pamiętać, że wynikiem przesunięcie o ponad 31 bitów jest 0 lub 4294967295.
bit32.lrotate
bit32.lrotate( n, disp )
Zwraca liczbę n
obróconą o disp
bitów w lewo.
Należy pamiętać, że obroty są równoważne co 32: obrót o 32 jest taki sam jak obrót o 0, obrót o 33 taki sam jak o 1, itd.
bit32.rrotate
bit32.rrotate( n, disp )
Zwraca liczbę n
obróconą o disp
bitów w prawo.
Należy pamiętać, że obroty są równoważne co 32: obrót o 32 jest taki sam jak obrót o 0, obrót o 33 taki sam jak o 1, itd.
libraryUtil
Ta biblioteka zawiera metody przydatne kiedy implementuje się biblioteki Scribunto. Można ją załadować przez:
libraryUtil = require( 'libraryUtil' )
libraryUtil.checkType
libraryUtil.checkType( name, argIdx, arg, expectType, nilOk )
Zgłasza błąd jeśli type( arg )
nie pasuje do oczekiwanego typu w expectType
. Ponadto błąd nie będzie zgłoszony jeśli arg
będzie nil, a nilOk
będzie miało wartość true
.
Argument name
to nazwa wywołującej funkcji, a argIdx
jest pozycją argumentu na liście argumentów. Są one używane przy formatowaniu komunikatów błędów.
libraryUtil.checkTypeMulti
libraryUtil.checkTypeMulti( name, argIdx, arg, expectTypes )
Zgłasza błąd jeśli type( arg )
nie pasuje do żadnego łańcucha tekstowego w tablicy expectTypes
.
Ta funkcja jest przeznaczona dla argumentów, które mogą mieć więcej niż jeden poprawny typ.
libraryUtil.checkTypeForIndex
libraryUtil.checkTypeForIndex( index, value, expectType )
Zgłasza błąd jeśli type( value )
nie pasuje do wartości w expectType
.
Głównym przeznaczeniem tej funkcji jest jej użycie podczas implementowania metametody __newindex
.
libraryUtil.checkTypeForNamedArg
libraryUtil.checkTypeForNamedArg( name, argName, arg, expectType, nilOk )
Zgłasza błąd jeśli type( arg )
nie pasuje do wartości w expectType
. Ponadto błąd nie będzie zgłoszony jeśli wartość arg
będzie nil, a wartość nilOk
będzie ustawiona na true
.
Główne zastosowanie tej funkcji jest takie samo jak libraryUtil.checkType()
lecz dla metod, które stosują składnię „nazwanych argumentów” w Lua, func{ name = value }
.
libraryUtil.makeCheckSelfFunction
libraryUtil.makeCheckSelfFunction( libraryName, varName, selfObj, selfObjDesc )
Przeznaczeniem tej funkcji jest implementowanie „metod” w obiektach tablicowych, które mają być wywoływane zgodnie ze składnią obj:metoda()
. Wynikiem jest funkcja, która powinna być wywołana na początku tych metod z argumentem self
i nazwą metody, i ta funkcja zgłasza błąd jeśli obiekt self
jest inny niż selfObj
.
Ta funkcja ma ogólnie zastosowanie w funkcji bibliotecznej będącej konstruktorem obiektu, czegoś podobnego do:
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
Moduły „bit” i „hex” z biblioteki luabit można załadować przez:
bit = require( 'luabit.bit' )
hex = require( 'luabit.hex' )
Należy pamiętać, że biblioteka bit32 zawiera kod wykonujący te same operacje jak „luabit.bit”, a operacje wykonywane przez „luabit.hex” można zastąpić przez użycie string.format()
i tonumber()
.
Moduł „noki” z luabit jest niedostępny ponieważ jest zupełnie bezużyteczny w Scribunto. Moduł „utf8” z luabit jest również niedostępny ponieważ został uznany za nadmiarowy w stosunku do biblioteki Ustring.
strict
The strict library is not a normal library; it causes an error to be raised whenever a new variable is used that is not explicitly scoped as a local variable (e.g., global variable assignment references). This functionality is typically enabled by loading at the top of a module using:
require( 'strict' )
On many Wikimedia wikis this was formerly implemented in Module:No globals
, which was replaced via phab:T209310. It is in part derived from strict.lua.
ustring
The pure-Lua backend to the Ustring library may be loaded using:
ustring = require( 'ustring' )
In all cases the Ustring library (mw.ustring
) should be used instead, as that replaces many of the slower and more memory-intensive operations with callbacks into PHP code.
Extension libraries
Some MediaWiki extensions provide additional Scribunto libraries. These are also located in the table mw
, usually in the table mw.ext
, however, they are only present when certain extensions are installed (in addition to the Scribunto extension itself).
Such extensions use Scribunto provided hooks:
Writing Scribunto libraries provides information on how such libraries can be developed to provide Lua interfaces for MediaWiki extensions.
mw.wikibase
Wikibase Client provides access to localizable structured data, most notably Wikidata. See docs_topics_lua.html and Extension:Wikibase Client/Lua .
mw.wikibase.lexeme
WikibaseLexeme provides access to Wikibase Lexeme entities. This is supported by Wikidata:Lexicographical data. See md_docs_2topics_2lua.html and Extension:WikibaseLexeme/Lua .
mw.wikibase.mediainfo
WikibaseMediaInfo provides access to Wikibase MediaInfo entities. Zobacz WikibaseMediaInfo/Lua . This is supported by Structured Data on Commons. See Structured data/Lua.
mw.bcmath
BCmath provides arbitrary-precision arithmetic to Lua modules. See BCmath documentation via "LDoc" link at BCmath § Usage.
mw.smw
Semantic Scribunto provides native Scribunto support for the Semantic MediaWiki extension.
mw.ext.data
JsonConfig provides access to localizable tabular and map data. Zobacz $1. Dane tabelaryczne and GeoJSON Map Data is supported in the "Data:" namespace at Commons.
mw.ext.data.get( pagename )
mw.ext.cargo
Cargo provides a means to query its data store from Lua. See Extension:Cargo/Other features#Lua support .
mw.ext.cattools
CategoryToolbox provides a means to check from Lua if a certain page belongs to a category. Is is experimental and not enabled on public WikiMedia wikis.
mw.ext.FlaggedRevs
FlaggedRevs provides a means to access the stability settings of a page from Lua.
mw.ext.TitleBlacklist
TitleBlacklist provides a means to test and obtain information about blacklisted page naming entries from Lua.
mw.ext.ParserFunctions
ParserFunctions provides a means from Lua to evaluate expressions in the same way as its PHP-based parser function #expr
.
mw.ext.proofreadPage
Proofread Page provides access to Index and Page namespaces. See Extension:Proofread Page/Lua reference . This is supported by Wikisource:ProofreadPage. See Help:Extension:ProofreadPage .
mw.ext.articlePlaceholder
ArticlePlaceholder provides a means to override default Wikibase renderings from Lua. See Extension:ArticlePlaceholder/Module:AboutTopic .
mw.ext.externalData
ExternalData provides a means to get structured data from Internet from Lua. See Extension:External Data/Lua .
mw.ext.UnlinkedWikibase
See UnlinkedWikibase
mw.ext.UnlinkedWikibase.getEntity( id )
mw.ext.UnlinkedWikibase.query( sparql )
mw.ext.seo
WikiSEO provides a means to set SEO Data for the current page. See Extension:WikiSEO#Usage in lua modules.
mw.slots
WSSlots provides a number of Lua functions for working with MCR slots:
mw.slots.slotContent(slotName, pageName)
mw.slots.slotTemplates(slotName, pageName)
(deprecated)mw.slots.slotContentModel(slotName, pageName)
mw.slots.slotData(slotName, pageName)
Differences from standard Lua
Changed functions
The following functions have been modified:
- setfenv()
- getfenv()
- May not be available, depending on the configuration. If available, attempts to access parent environments will fail.
- getmetatable()
- Works on tables only to prevent unauthorized access to parent environments.
- tostring()
- Pointer addresses of tables and functions are not provided. This is to make memory corruption vulnerabilities more difficult to exploit.
- pairs()
- ipairs()
- Support for the __pairs and __ipairs metamethods (added in Lua 5.2) has been added.
- pcall()
- xpcall()
- Certain internal errors cannot be intercepted.
- require()
- Can fetch certain built-in modules distributed with Scribunto, as well as modules present in the Module namespace of the wiki. To fetch wiki modules, use the full page name including the namespace. Cannot otherwise access the local filesystem.
Removed functions and packages
The following packages are mostly removed. Only those functions listed are available:
- package.*
- Filesystem and C library access has been removed. Available functions and tables are:
- package.loaded
- package.preload
- package.loaders
- Loaders which access the local filesystem or load C libraries are not present. A loader for Module-namespace pages is added.
- package.seeall()
- os.*
- There are some insecure functions in here, such as os.execute(), which can't be allowed. Available functions are:
- debug.*
- Most of the functions are insecure. Available functions are:
The following functions and packages are not available:
- collectgarbage()
- module()
- coroutine.*
- No application is known for us, so it has not been reviewed for security.
- dofile()
- loadfile()
- io.*, file.*
- Allows local filesystem access, which is insecure.
- load()
- loadstring()
- These were omitted to allow for static analysis of the Lua source code. Also, allowing these would allow Lua code to be added directly to article and template pages, which was not desired for usability reasons.
- print()
- This was discussed on wikitech-l and it was decided that it should be omitted in favour of return values, to improve code quality. If necessary, mw.log() may be used to output information to the debug console.
- string.dump()
- May expose private data from parent environments.
Additional caveats
- Referential data structures
- Circular data structures and data structures where the same node may be reached by more than one path cannot be correctly sent to PHP.
Attempting to do so will cause undefined behavior. This includes (but is not limited to) returning such data structures from the module called by {{#invoke:}}
and passing such data structures as parameters to Scribunto library functions that are implemented as callbacks into PHP.
Such data structures may be used freely within Lua, including as the return values of modules loaded with mw.loadData()
.
Writing Scribunto libraries
This information is useful to developers writing additional Scribunto libraries, whether for inclusion in Scribunto itself or for providing an interface for their own extensions.
A Scribunto library will generally consist of five parts:
- The PHP portion of the library.
- The Lua portion of the library.
- The PHP portion of the test cases.
- The Lua portion of the test cases.
- The documentation.
Existing libraries serve as a good example.
Library
The PHP portion of the library is a class that must extend Scribunto_LuaLibraryBase
. See the documentation for that class for implementation details. In the Scribunto extension, this file should be placed in engines/LuaCommon/NameLibrary.php
, and a mapping added to Scribunto_LuaEngine::$libraryClasses
. Other extensions should use the ScribuntoExternalLibraries hook. In either case, the key should match the Lua module name ("mw.name" for libraries in Scribunto, or "mw.ext.name" for extension libraries).
The Lua portion of the library sets up the table containing the functions that can be called from Lua modules. In the Scribunto extension, the file should be placed in engines/LuaCommon/lualib/mw.name.lua
. This file should generally include boilerplate something like this:
local object = {}
local php
function object.setupInterface( options )
-- Remove setup function
object.setupInterface = nil
-- Copy the PHP callbacks to a local variable, and remove the global
php = mw_interface
mw_interface = nil
-- Do any other setup here
-- Install into the mw global
mw = mw or {}
mw.ext = mw.ext or {}
mw.ext.NAME = object
-- Indicate that we're loaded
package.loaded['mw.ext.NAME'] = object
end
return object
The module in engines/LuaCommon/lualib/libraryUtil.lua
(load this with local util = require 'libraryUtil'
) contains some functions that may be helpful.
Be sure to run the Scribunto test cases with your library loaded, even if your library doesn't itself provide any test cases. The standard test cases include tests for things like libraries adding unexpected global variables. Also, if the library is loaded with PHP, any upvalues that its Lua functions have will not be reset between #invoke's. Care must be taken to ensure that modules can't abuse this to transfer information between #invoke's.
Test cases
The Scribunto extension includes a base class for test cases, Scribunto_LuaEngineTestBase
, which will run the tests against both the LuaSandbox and LuaStandalone engines.
The library's test case should extend this class, and should not override static function suite()
.
In the Scribunto extension, the test case should be in tests/engines/LuaCommon/NameLibraryTest.php
and added to the array in ScribuntoHooks::unitTestsList()
(in common/Hooks.php
); extensions should add the test case in their own UnitTestsList
hook function, probably conditional on whether $wgAutoloadClasses['Scribunto_LuaEngineTestBase']
is set.
Most of the time, all that is needed to make the test case is this:
class ClassNameTest extends Scribunto_LuaEngineTestBase { protected static $moduleName = 'ClassNameTest'; function getTestModules() { return parent::getTestModules() + array( 'ClassNameTest' => __DIR__ . '/ClassNameTests.lua'; ); } }
This will load the file ClassNameTests.lua
as if it were the page "Module:ClassNameTests", expecting it to return an object with the following properties:
- count: Integer, number of tests
- provide( n ): Function that returns three values:
n
, the name of testn
, and a string that is the expected output for testn
. - run( n ): Function that runs test
n
and returns one string.
If getTestModules()
is declared as shown, "Module:TestFramework" is available which provides many useful helper methods. If this is used, ClassNameTests.lua
would look something like this:
local testframework = require 'Module:TestFramework'
return testframework.getTestProvider( {
-- Tests go here
} )
Each test is itself a table, with the following properties:
- name: The name of the test.
- func: The function to execute.
- args: Optional table of arguments to pass to the function.
- expect: Results to expect.
- type: Optional "type" of the test, default is "Normal".
The type controls the format of expect
and how func
is called. Included types are:
- Normal:
expect
is a table of return values, or a string if the test should raise an error.func
is simply called. - Iterator:
expect
is a table of tables of return values.func
is called as with an iterated for loop, and each iteration's return values are accumulated. - ToString: Like "Normal", except each return value is passed through
tostring()
.
Test cases in another extension
There are (at least) two ways to run PHPUnit tests:
- Run phpunit against core, allowing the tests/phpunit/suites/ExtensionsTestSuite.php to find the extension's tests using the UnitTestsList hook.
If your extension's test class names all contain a unique component (e.g. the extension's name), the --filter
option may be used to run only your extension's tests.
- Run phpunit against the extension directory, where it will pick up any file ending in "Test.php".
Either of these will work fine if Scribunto is loaded in LocalSettings.php. And it is easy for method #1 to work if Scribunto is not loaded, as the UnitTestsList hook can easily be written to avoid returning the Scribunto test when $wgAutoloadClasses[ 'Scribunto_LuaEngineTestBase' ]
is not set.
But Jenkins uses method #2. For Jenkins to properly run the tests, you will need to add Scribunto as a dependency for your extension. See Gerrit change 56570 for an example of how this is done.
If for some reason you need the tests to be able to run using method #2 without Scribunto loaded, one workaround is to add this check to the top of your unit test file:
if ( !isset( $GLOBALS['wgAutoloadClasses']['Scribunto_LuaEngineTestBase'] ) ) {
return;
}
Documentation
Modules included in Scribunto should include documentation in the Scribunto libraries section above. Extension libraries should include documentation in a subpage of their own extension page, and link to that documentation from the Extension libraries subsection above.
Zobacz też
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.