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.

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.

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ść, gdzie rawget( 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:

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

^† Dla operatorów dwuargumentowych Lua szuka metametody do wykorzystania najpierw w metablicy lewego argumentu (jeśli jest jakikolwiek), a następnie w metatablicy prawego.

^‡ Dla operatorów relacji metametoda jest używane jedynie wtedy gdy ta sama funkcja jest określona w metatablicach obu argumentów. Różne anonimowe funkcje, nawet jeśli mają identyczne źródła i domknięcia, nie są uznawane za takie same.

^* __metatable wpływa zarówno na getmetatable() jak i setmetatable()

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 jest not ( b < a )
• a > b uznawane jest za równoważne z b < a
• a >= b uznawane jest za równoważne z b <= 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:

1. ^
2. not # - (negacja)
3. * / %
4. + - (odejmowanie)
5. ..
6. < > <= >= ~= ==
7. and
8. 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:

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

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

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) returns nil, "bar", nil.
• select("#", "foo", "bar") returns 2.
• select("#", "foo", "bar", nil) returns 3.

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ść $e^{x}$.

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: $x=m\times 2^{e}$, gdzie e jest liczbą całkowitą, a moduł m mieści się w przedziale $[0.5,1)$
• Jeśli x jest zerem: m i e są równe 0
• Jeśli x to NaN lub nieskończoność: m równa się x, a e 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 $m\times 2^{e}$ (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ść $\pi$.

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 $[0,1)$
• Z jednym argumentem zwraca liczbę całkowitą z przedziału $[1,m]$
• Z dwoma argumentami zwraca liczbę całkowitą z przedziału $[m,n]$

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

1. Wyszukiwanie w package.preload[nazwamodułu] żeby znaleźć funkcję ładowarki
2. 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 '-'. All classes %y described above can also be used as components in set. All other characters in set represent themselves. For example, [%w_] (or [_%w]) represents all alphanumeric characters plus the underscore, and [0-7] represents the octal digits. To include literal '-' in the set, use '%-', so [0-7%l%-] represents the octal digits plus the lowercase letters plus the '-' character. The interaction between ranges and classes is not defined. Therefore, patterns like [%a-z] or [a-%%] have no meaning.
[^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, funkcje pairs() i ipairs() 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ącego
• argumenty.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”.

mw.html:newline

html:newline()

Dołącza znak nowej linii do obiektu mw.html.

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

Fallback chains

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 na true 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, while grammar 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 "&lrm;" lub "&rlm;" 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ą '&lt;', '&gt;', '&amp;', '&quot;', i '&nbsp;'. 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 lub PMID 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 ), or nil if this title cannot have a talk page.

• subjectPageTitle: The same as mw.title.makeTitle( mw.site.namespaces[title.namespace].subject.id, title.text ).

• redirectTarget: Returns a title object of the target of the redirect page if the page is a redirect and the page exists, returns false otherwise.

• protectionLevels: The page's protection levels. This is a table with keys corresponding to each action (e.g., "edit" and "move"). The table values are arrays, the first item of which is a string containing the protection level. If the page is unprotected, either the table values or the array items will be nil. This is expensive.

• cascadingProtection: The cascading protections applicable to the page. This is a table with keys "restrictions" (itself a table with keys like protectionLevels has) and "sources" (an array listing titles where the protections cascade from). If no protections cascade to the page, "restrictions" and "sources" will be empty. This is expensive.

• subPageTitle( text ): The same as mw.title.makeTitle( title.namespace, title.text .. '/' .. text ).

• partialUrl(): Returns title.text encoded as it would be in a URL.

• fullUrl( query, proto ): Returns the full URL (with optional query table/string) for this title. proto may be specified to control the scheme of the resulting url: "http", "https", "relative" (the default), or "canonical".

• localUrl( query ): Returns the local URL (with optional query table/string) for this title.

• canonicalUrl( query ): Returns the canonical URL (with optional query table/string) for this title.

• getContent(): Returns the (unparsed) content of the page, or nil if there is no page. The page will be recorded as a transclusion.

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 bugs: When used with a lone frontier pattern (%f[set]), the function will get stuck in an infinite loop. For example, the following loop never terminates:

for capture in mw.ustring.gmatch( "foo bar", "%f[%w]" ) 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 "5" in a string, the value at key [5] or ["5"] would be used); as such, the output is not predictable if they have different (non-nil) values.

This is not an issue for string.gsub(), which ignores any numbers as keys.

mw.ustring.isutf8

mw.ustring.isutf8( s )

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 [０-９], 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 2³², tak aby ich wartość mieściła się w zakresie od 0 do 2³²-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 2⁰), a 31 to najbardziej znaczący (ten o wartości 2³¹).

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

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

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:

• ScribuntoExternalLibraries
• ScribuntoExternalLibraryPaths

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

os.clock()

os.date()

os.difftime()

os.time()

debug.*

Most of the functions are insecure. Available functions are:

debug.traceback()

The following functions and packages are not available:

collectgarbage()

module()

coroutine.*

No application is known for us, so it has not been reviewed for security.

dofile()

loadfile()

io.*, file.*

Allows local filesystem access, which is insecure.

load()

loadstring()

These were omitted to allow for static analysis of the Lua source code. Also, allowing these would allow Lua code to be added directly to article and template pages, which was not desired for usability reasons.

print()

This was discussed on wikitech-l and it was decided that it should be omitted in favour of return values, to improve code quality. If necessary, mw.log() may be used to output information to the debug console.

string.dump()

May expose private data from parent environments.

Additional caveats

Referential data structures

Circular data structures and data structures where the same node may be reached by more than one path cannot be correctly sent to PHP.

Attempting to do so will cause undefined behavior. This includes (but is not limited to) returning such data structures from the module called by {{#invoke:}} and passing such data structures as parameters to Scribunto library functions that are implemented as callbacks into PHP.
Such data structures may be used freely within Lua, including as the return values of modules loaded with mw.loadData().

Writing Scribunto libraries

This information is useful to developers writing additional Scribunto libraries, whether for inclusion in Scribunto itself or for providing an interface for their own extensions.

A Scribunto library will generally consist of five parts:

• The PHP portion of the library.
• The Lua portion of the library.
• The PHP portion of the test cases.
• The Lua portion of the test cases.
• The documentation.

Existing libraries serve as a good example.

Library

The PHP portion of the library is a class that must extend Scribunto_LuaLibraryBase. See the documentation for that class for implementation details. In the Scribunto extension, this file should be placed in engines/LuaCommon/NameLibrary.php, and a mapping added to Scribunto_LuaEngine::$libraryClasses. Other extensions should use the ScribuntoExternalLibraries hook. In either case, the key should match the Lua module name ("mw.name" for libraries in Scribunto, or "mw.ext.name" for extension libraries).

The Lua portion of the library sets up the table containing the functions that can be called from Lua modules. In the Scribunto extension, the file should be placed in engines/LuaCommon/lualib/mw.name.lua. This file should generally include boilerplate something like this:

local object = {}
local php

function object.setupInterface( options )
    -- Remove setup function
    object.setupInterface = nil

    -- Copy the PHP callbacks to a local variable, and remove the global
    php = mw_interface
    mw_interface = nil

    -- Do any other setup here

    -- Install into the mw global
    mw = mw or {}
    mw.ext = mw.ext or {}
    mw.ext.NAME = object

    -- Indicate that we're loaded
    package.loaded['mw.ext.NAME'] = object
end

return object

The module in engines/LuaCommon/lualib/libraryUtil.lua (load this with local util = require 'libraryUtil') contains some functions that may be helpful.

Be sure to run the Scribunto test cases with your library loaded, even if your library doesn't itself provide any test cases. The standard test cases include tests for things like libraries adding unexpected global variables. Also, if the library is loaded with PHP, any upvalues that its Lua functions have will not be reset between #invoke's. Care must be taken to ensure that modules can't abuse this to transfer information between #invoke's.

Test cases

The Scribunto extension includes a base class for test cases, Scribunto_LuaEngineTestBase, which will run the tests against both the LuaSandbox and LuaStandalone engines. The library's test case should extend this class, and should not override static function suite(). In the Scribunto extension, the test case should be in tests/engines/LuaCommon/NameLibraryTest.php and added to the array in ScribuntoHooks::unitTestsList() (in common/Hooks.php); extensions should add the test case in their own UnitTestsList hook function, probably conditional on whether $wgAutoloadClasses['Scribunto_LuaEngineTestBase'] is set.

Most of the time, all that is needed to make the test case is this:

class ClassNameTest extends Scribunto_LuaEngineTestBase {
    protected static $moduleName = 'ClassNameTest';

    function getTestModules() {
         return parent::getTestModules() + array(
             'ClassNameTest' => __DIR__ . '/ClassNameTests.lua';
         );
    }
}

This will load the file ClassNameTests.lua as if it were the page "Module:ClassNameTests", expecting it to return an object with the following properties:

• count: Integer, number of tests
• provide( n ): Function that returns three values: n, the name of test n, and a string that is the expected output for test n.
• run( n ): Function that runs test n and returns one string.

If getTestModules() is declared as shown, "Module:TestFramework" is available which provides many useful helper methods. If this is used, ClassNameTests.lua would look something like this:

local testframework = require 'Module:TestFramework'

return testframework.getTestProvider( {
    -- Tests go here
} )

Each test is itself a table, with the following properties:

• name: The name of the test.
• func: The function to execute.
• args: Optional table of arguments to pass to the function.
• expect: Results to expect.
• type: Optional "type" of the test, default is "Normal".

The type controls the format of expect and how func is called. Included types are:

• Normal: expect is a table of return values, or a string if the test should raise an error. func is simply called.
• Iterator: expect is a table of tables of return values. func is called as with an iterated for loop, and each iteration's return values are accumulated.
• ToString: Like "Normal", except each return value is passed through tostring().

Test cases in another extension

There are (at least) two ways to run PHPUnit tests:

1. Run phpunit against core, allowing the tests/phpunit/suites/ExtensionsTestSuite.php to find the extension's tests using the UnitTestsList hook.

If your extension's test class names all contain a unique component (e.g. the extension's name), the --filter option may be used to run only your extension's tests.

1. Run phpunit against the extension directory, where it will pick up any file ending in "Test.php".

Either of these will work fine if Scribunto is loaded in LocalSettings.php. And it is easy for method #1 to work if Scribunto is not loaded, as the UnitTestsList hook can easily be written to avoid returning the Scribunto test when $wgAutoloadClasses[ 'Scribunto_LuaEngineTestBase' ] is not set.

But Jenkins uses method #2. For Jenkins to properly run the tests, you will need to add Scribunto as a dependency for your extension. See Gerrit change 56570 for an example of how this is done.

If for some reason you need the tests to be able to run using method #2 without Scribunto loaded, one workaround is to add this check to the top of your unit test file:

 if ( !isset( $GLOBALS['wgAutoloadClasses']['Scribunto_LuaEngineTestBase'] ) ) {
     return;
 }

Documentation

Modules included in Scribunto should include documentation in the Scribunto libraries section above. Extension libraries should include documentation in a subpage of their own extension page, and link to that documentation from the Extension libraries subsection above.

Zobacz też

• Lua (programming language)

License

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

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