Extension:Scribunto/Lua reference manual/pl

Niniejsza instrukcja przedstawia w jaki sposób jest używane przez roszerzenie. 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:

Zapisz ją, a następnie na innej (nie modułowej) stronie wpisz:

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  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. 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, jednak globalne mogą być dostępne z innych modułów załadowanych przez. 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  przekazywany jest jeden argument, tak zwany obiekt ramki. Aby uzyskać dostęp do parametrów przekazanych z wikitekstu do  zwykle stosuje się tablicę   z tego obiektu. Możliwy jest również dostęp do pól szablonu zawierającego  przez użycie   i odwołanie do tablicy   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.

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, na stronie będzie można przeczytać „Cześć świecie! ”.

Z drugiej strony, subst jest obsługiwany na wcześniejszym etapie przetwarzania, więc w przypadku  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):


 * —Ustala nazwę strony używanej jako dokumentacja. Nazwa modułu (bez prefiksu Moduł:) jest przekazana jako . 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  . 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.
 * — Komunikat wyświetlany w przypadku gdy odpowiednia strona z dokumentacją nie istnieje. Nazwa strony jest przekazywana jako . Domyślnie nazwa jest pusta.
 * — Komunikat wyświetlany w przypadku gdy odpowiednia strona z dokumentacją istnieje. Nazwa strony jest przekazywana jako . Domyślnie transkluduje stronę dokumentacji.
 * — Nagłówek wyświetlany podczas przeglądania samej strony dokumentacji. Nazwa dokumentowanego modułu (z prefiksem Moduł:) jest przekazana jako . 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 , które je zaaplikują do modułu kiedy strona z dokumentacją jest transkludowana w stronę modułu.



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:



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.



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  zwraca typ wartości.

Funkcja  zamienia wartość na łańcuch znaków. Funkcja  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  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, 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.

boolean
Wartości logiczne to  i.

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:


 * (bell, dzwonek, bajt 7)
 * (backspace, powrót o 1 pozycję, bajt 8)
 * (horizontal tab, tabulacja pozioma, bajt 9)
 * (newline, przesunięcie o 1 wiersz, bajt 10)
 * (vertical tab, tabulacja pionowa, bajt 11)
 * (form feed, przesunięcie o 1 stronę, bajt 12)
 * (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.

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. Liczby można również przedstawiać w zapisie naukowym bez odstępów, np. ,, lub. Liczby całkowite można również zapisać w systemie szesnastkowym poprzedzając je przedrostkiem  na przykład.

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  to dodania nieskończoność, jak również wynik dzielenia , a dzielenie takie jak   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  lub  ; a nieskończoności to   lub.

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:


 * używa (pierwszą) wartość z wyrażenie1 jako klucza i (pierwszą) wartość z wyrażenie2 jako wartość.
 * jest równoważne do
 * to mniej więcej to samo co, 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. . Klucze w postaci łańcuchów tekstowych, które są również poprawnymi nazwami mogą być dostępne dzięki zapisowi z kropką np. jest równoważne z. Wywoływanie funkcji, która jest wartością w tabeli, można dokonać za pomocą zapisu z dwukropkiem; na przykład  jest równoważne z   lub.

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:

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

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  zwróciłby nil. Jeśli wartością pola jest tabela, dostęp będzie powtórzony na tej tabeli, np.   (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  . Funkcja rawget omija tę metametodę.


 * __newindex
 * To pole jest używane gdy przypisywany jest klucz do tablicy, gdzie   zwróciłoby nil. Jeśli wartością pola jest tablica, przypisanie będzie powtórzone w tej tablicy, np.   (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  . Funkcja rawset omija tę metametodę.


 * __call
 * To pole jest używane gdy stosowana jest składnia wywołania funkcji na tablicy, . Wartość pola musi być funkcją, której wywołanie będzie będzie podobne do.


 * __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  odwołuje się do tablicy. Ta metatablica jest niedostępna w Scribunto, podobnie nie jest dostępna oryginalna tablica ; 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. 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. 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.



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


 * używa
 * używa  jeśli dostępne, lub jeśli   jest dostępne to uznaje się zamiennikiem jest
 * uznawane jest za równoważne z
 * uznawane jest za równoważne z

Jeśli niezbędne metametody są niedostępne zgłaszany jest błąd.



Operatory logiczne
Operatorami logicznymi są  (i),   (lub) i   (nie). Wszystkie stosują typową interpretację, w której nil i false jest uznawane za fałsz, a wszystko inne za prawdę.

W operatorze, 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, 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  jest zawsze true lub false.

Należy wspomnieć o zwarciach dla  i. Na przykład  wywoła   jeśli   zwróci false lub nil jako swoją pierwszą wartość.



Operator połączenia
Operator połączenia to dwie kropki, używany jako. 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  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. Jeśli  jest łańcuchem tekstowym, to zwraca on długość w bajtach. Jeśli  jest tablicą z sekwencją, to wynikiem jest długość sekwencji.

Jeśli  jest tablicą lecz nie sekwencją,   może zwrócić dowolną wartość N >= 1, taką, że a[N] nie jest nil, a a[N+1] jest nil, poczynając od N = 1, nawet jeśli w tablicy znajdują się wartości różne od nil na wyższych indeksach. Na przykład,



Kolejność wykonywania działań
Posortowana kolejność wykonywania działań w Lua od pierwszego do ostatniego:


 * 1) not # - (negacja)
 * 2) + - (odejmowanie)
 * 3) and
 * or
 * 1) and
 * or
 * 1) and
 * or

Wśród jednego poziomu kolejności większość operatorów dwuargumentowych jest lewostronnie łączna, np. jest interpretowane jako. Potęgowanie i połączenie są prawostronnie łączne, np. jest interpretowane jako.

<span id="Function_calls">

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

<span id="Function_declarations">

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,

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,

Funkcja select jest przeznaczona do pracy z wyrażeniem zmiennoargumentowym; w szczególności należy używać  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 &lt;= 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ę:. Ta forma może być stosowana aby ograniczyć zakres zmiennych lokalnych lub dodać  bądź   w środku innego bloku.

Przypisania
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  spowoduje, że zmienne a i b wymienią się na wzajem swoimi wartościami.

<span id="Local_variable_declarations">

Deklaracje zmiennych lokalnych
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  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.

<span id="Control_structures">

Struktury kontrolne
Instrukcja  powtarza blok tak długo jak długo prawdziwe jest wyrażenie exp.

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

Pierwsza forma pętli  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  i   jest błędem. Wszystkie wyrażenia są obliczane raz przed uruchomieniem pętli.

Forma pętli  jest mniej więcej równoważna do

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.

Druga forma pętli  pracuje z funkcjami „iteratora”. Tak jak w pierwszej formie lista-wyrażeń jest rozwijana tylko raz przed uruchomieniem pętli.

Ta forma pętli  jest mniej więcej równoważna do

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.

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ęść  można pominąć lub część   powtórzyć lub pominąć jeśli to konieczne.

Instrukcja  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 jak i.

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.

Instrukcja przerwania jest używana do zakończenia wykonywania pętli,   lub  , 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.

<span id="Function_calls_as_statements">

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.

<span id="Function_declaration_statements">

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  at the beginning of the arguments list.

<span id="Error_handling">

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.

<span id="Garbage_collection">

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.

<span id="Standard_libraries">

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.

<span id="Basic_functions">

_G
<span id="_G">

Ta zmienna przechowuje referencję do głównej tablicy zmiennych globalnych; zmienna globalna  może być również osiągalna jako. Jednak należy pamiętać, że w _G nie ma nic specjalnego, i można tę zmienną nadpisać jak każdą inną.

Tablica zmiennych globalnych może być używana jak każda inna tablica. Na przykład

_VERSION
<span id="_VERSION">

Łańcuch tekstowy zawierający uruchomioną wersję Lua, np. „Lua 5.1”.

assert
Jeśli  to nil lub , to zgłasza błąd. W takim przypadku  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  jest dowolną inną wartością, assert zwraca wszystkie argumenty włączając w to   i.

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

error
Zgłasza błąd o treści.

zwykle dodaje pewne informacje o miejscu błędu. Jeśli  to 1 lub jest pominięty, dodawana informacja jest o miejscu wywołania funkcji  ; 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
Uwaga! Ta funkcja może być niedostępna. To zależy od nastawy  w konfiguracji silnika.

Zwraca środowisko (tablica zmiennych globalnych) tak jak to określa :


 * Jeśli 1, nil lub pominięte to zwraca środowisko funkcji wywołującej . 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  zwraca nil zamiast środowiska.

getmetatable
Zwraca metatablicę z tablicy. Dla każdego innego typu zwraca nil.

Jeśli metatablica ma pole, to jego wartość będzie zwrócona zamiast rzeczywistej metatablicy.

ipairs
Zwraca trzy wartości: funkcję iteratora, tablicę  i 0. To ma na celu używanie w iterowanej postaci pętli :

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. Jeśli ta metametoda istnieje to wywołanie ipairs zwróci trzy wartości uzyskane przez  zamiast domyślnych.

next
To pozwala na iterowanie po kluczach w tablicy. Jeśli  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.

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
Zwraca trzy wartośći: funkcję iteratora (next lub działającą podobnie), tablicę  i nil. To ma na celu używanie w iterowanej postaci pętli :

To iteruje po parach klucz-wartość w  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  zamiast domyślnych.

pcall
Wywołuje funkcję  z podanymi argumentami w trybie chronionym. To oznacza, że jeśli zostanie zgłoszony błąd podczas wywołania, funkcja pcall zwróci   i komunikat zgłoszonego błędu. Jeśli błąd się nie pojawi, funkcja pcall zwróci  i wszystkie wartości zwracane przez wywołaną funkcję.

W pseudokodzie,  może być zdefiniowane podobnie do:

rawequal
To jest równoważne do  z takim wyjątkiem, że ignoruje dowolną metametodę __eq.

rawget
To jest równoważne do  z takim wyjątkiem, że ignoruje dowolną metametodę __index.

rawset
To jest równoważne do  z takim wyjątkiem, że ignoruje dowolną metametodę __newindex.

select
Jeśli  jest liczbą, to zwraca wszystkie argumenty w   po tym indeksie. Jeśli  jest łańcuchem tekstowym '#', to zwraca liczbę argumentów w.

Innymi słowy  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).

setmetatable
Ustawia metatablicę w tablicy. może być nil, lecz musi być jawnie dostarczona.

If the current metatable has a __metatable field,  will throw an error.

tonumber
Próbuje zamienić  na liczbę. Jeśli to już jest liczba lub łańcuch tekstowy zamienialny na liczbę, to  zwraca tę liczbę; w przeciwnym razie zwraca nil.

Opcjonalna  (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
Zamienia  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  zamiast domyślnej.

type
Zwraca typ wartości  jako łańcuch tekstowy: ,  ,  ,  ,   lub.

unpack
Zwraca wartości z podanej tablicy, coś jak  gdyby to zapisać ręcznie. Domyślną wartością dla  jest 1, a dla   to , które są również przyjmowane gdy przekazane zostanie nil.

Należy pamiętać, że wyniki nie są deterministyczne jeśli  nie jest sekwencją, a   jest nil lub niepodane; zobacz szczegóły w sekcji Operator długości.

xpcall
Prawie to samo co  z takim wyjątkiem, że komunikat błędu jest przekazany do funkcji   przed powrotem.

W pseudokodzie  może być zdefiniowane podobnie do:

<span id="Debug_library">

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

<span id="Math_library">

math.abs
Zwraca moduł liczby.

math.acos
Zwraca arcus cosinus z  (w radianach)

math.asin
Zwraca arcus sinus z  (w radianach)

math.atan
Zwraca arcus tangens z  (w radianach)

math.atan2
Zwraca arcus tangens z  (w radianach), używając znaków z obu argumentów aby ustalić właściwą ćwiartkę wyniku.

math.ceil
Zwraca najmniejszą liczbę całkowitą większą lub równą.

math.cos
Zwraca cosinus z  (w radianach)

math.cosh
Zwraca cosinus hiperboliczny z.

math.deg
Zamienia kąt  z radianów na stopnie.

math.exp
Zwraca wartość $$e^x$$.

math.floor
Zwraca największą liczbę całkowitą mniejszą lub równą.

math.fmod
Zwraca resztę z dzielenia  przez   zaokrąglając iloraz w kierunku zera. Na przykład  dają.

math.frexp
Zwraca dwie wartości  i   takie, że:


 * Jeśli  jest skończone i różne od zera: $$x = m \times 2^e$$, gdzie   jest liczbą całkowitą, a moduł   mieści się w przedziale $$[0.5, 1)$$
 * Jeśli  jest zerem:   i   są równe 0
 * Jeśli  to NaN lub nieskończoność:   równa się , a   jest nieokreślone

math.huge
Wartość oznaczająca dodatnią nieskończoność; większa lub równa od dowolnej innej wartości liczbowej.

math.ldexp
zwraca $$m \times 2^e$$ ( powinien być liczbą całkowitą).

math.log
Zwraca logarytm naturalny z.

math.log10
Zwraca logarytm dziesiętny z.

math.max
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  jest równe NaN, lecz wszystkie pozostałe wartości NaN będą zignorowane.

math.min
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  jest równe NaN, lecz wszystkie pozostałe wartości NaN będą zignorowane.

math.modf
Zwraca dwie liczby, część całkowitą z  i część ułamkową z. Na przykład  dają.

math.pi
Zwraca wartość $$\pi$$.

math.pow
Równoważne z.

math.rad
Zamienia wartość kąta  ze stopni na radiany.

math.random
Zwraca liczbę pseudolosową.

Argumenty  i   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  or   are less than −2147483648 or greater than 2147483647, or if   is greater than 2147483646.

math.randomseed
Ustawia  jako  ziarno dla generatora liczb pseudolosowych.

Należy pamiętać, że używanie tego samego ziarna spowoduje, że  będzie generowało takie same sekwencje liczb.

math.sin
Zwraca sinus z  (w radianach)

math.sinh
Zwraca sinus hiperboliczny z.

math.sqrt
Zwraca pierwiastek kwadratowy z. Równoważne z.

math.tan
Zwraca tangens z  (w radianach).

math.tanh
Zwraca tangens hiperboliczny z.

<span id="Operating_system_library">

os.clock
Zwraca przybliżony czas w sekundach używania procesora przez program.

os.date

 * Dla bardziej wszechstronnego formatowania daty można skorzystać z  z biblioteki językowej

Zwraca łańcuch tekstowy lub tablicę zawierającą datę i czas sformatowane zgodnie z formate w. Jeśli format jest pominięty lub nil to będzie użyty „%c”.

Jeśli podano, to będzie on sformatowany (zobacz  ). W przeciwnym razie zostanie użyty czas bieżący.

Jeśli  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–59) (wyjątek: sekunda przestępna = 60)
 * 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
Zwraca liczbę sekund między  a.

os.time
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”.

<span id="Package_library">

require
Ładuje określony moduł.

Najpierw zagląda do  żeby sprawdzić czy moduł już jest załadowany. Jeśli tak to zwraca.

W przeciwnym razie wywołuje każdą ładowarkę z sekwencji  aby spróbować znaleźć ładowarkę modułu. Jeśli ładowarka jest znaleziona to jest ona wywołana. Wartość uzyskana z ładowarki jest umieszczana w  i zwracana.

Zobacz dokumentację dla  na temat dostępnych ładowarek.

Na przykład jeśli masz moduł „Module:Giving” zawierający co następuje:

Możesz go załadować w innym module w następujący sposób:

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   ż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
Ustawia metametodę __index na _G.

<span id="String_library">

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.

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
Jeśli łańcuch tekstowy jest rozważany jako tablica bajtów to funkcja zwraca bajtowe wartości dla,  , ···,. Domyślna wartość dla  to 1; domyślna wartość dla  to. Identycznie z mw.ustring.byte.

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.

Zobacz mw.ustring.char, która jest podobną funkcją jednak operującą na znakach kodowanych w Unikodzie zamiast na bajtach.

string.find
Szuka pierwszego wystąpienia wartości   w łańcuchu tekstowym. Jeśli znajdzie wystąpienie to  zwraca pozycje w , 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  określa gdzie rozpocząć wyszukiwanie; domyślną wartością jest 1, a może być ujemne. Wartość  jako czwarty argument   wyłącza wsparcie wyrażeń regularnych, czyli funkcja pracuje w trybie zwykłego „wyszukiwania podłańcucha tekstowego”, bez uznawania znaków w argumencie   jako „magicznych”.

Należy pamiętać, że jeśli argument  jest podany, to musi być również podany argument.

Zobacz mw.ustring.find, która jest podobną funkcją rozszerzającą możliwości tak jak to opisano we Wzory Ustring, oraz gdzie indeks  jest obliczany według pozycji znaków a nie bajtów.

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


 * 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
Zwraca funkcję iteratora, która w każdym wywołaniu zwraca następne znalezione grupy zdefiniowane przez  podczas przeszukiwania. Jeśli  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
Zwraca kopię, w którym wszystkie (lub pierwsze  , jeśli podano) wystąpienia podtekstu określonego przez   są zamienione przez łańcuch tekstowy określony przez  , który może być łańcuchem tekstowym, tablicą lub funkcją. Funkcja  zwraca również drugą wartość, całkowitą liczbę znalezionych wystąpień podanego wzoru.

Jeśli  jest łańcuchem tekstowym, to jego wartość jest używana jako zamiennik. Znak  rozpoczyna sekwencję specjalną: każdy ciąg w   w postaci  , z n pomiędzy 1 i 9, oznaczającą wartość n-tej znalezionej grupy. Ciąg  oznacza pełne znalezione wyrażenie, a   oznacza pojedynczy.

Jeśli  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  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
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
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
Szuka pierwszego wystąpienia wyrażenia określonego przez  w łańcuchu tekstowym. Jeśli znajdzie jedno, to funcja  zwraca znalezione grupy ze wzoru; w przeciwnym razie zwraca nil. Jeśli  nie określa grup, to zwracane jest pełne znalezione wyrażenie.

Trzeci opcjonalny argument liczbowy  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  jest liczony w znakach zamiast bajtach.

string.rep
Zwraca łańcuch tekstowy będący połączeniem  kopii łańcucha tekstowego. Identyczne z mw.ustring.rep.

string.reverse
Zwraca łańcuch tekstowy, który jest zapisem  od tyłu (w bajtach).

string.sub
Zwraca podłańcuch tekstowy z, który rozpoczyna się w   a kończy w  ;   i   mogą być ujemne. Jeśli  jest nil lub pominięte to zostanie użyte -1, będzie trwać do końca ciągu.

W szególności wywołanie  zwraca początek   o długości , a   zwraca koniec z   o długości.

Zobacz podobną funkcję mw.ustring.sub, w której zakresy są liczone w znakach zamiast bajtach.

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

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  w PCRE).
 * Jedyne twierdzenia o zerowej szerokości to,  , i   wzór „graniczny”; twierdzenia takie jak w PCRE   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, ). Use  instead.

Also see Ustring patterns for a similar pattern-matching scheme using Unicode characters.

<span id="Character_class">

Klasa znaku
Klasa znaku jest używana do reprezentowania zbioru znaków. Następujące kombinacje są dopuszczalne w opisywaniu klasy znaku:

<span id="Pattern_items">

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;
 * , dla n między 1 a 9; taki element wyszukuje podłańcuch tekstowy identyczny jak n-ta wyszukana grupa (zobacz niżej);
 * , 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   wyszukuje wyrażenia w odpowiednio sparowanych nawiasach.


 * , 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;
 * , for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below);
 * , 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  matches expressions with balanced parentheses.

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.
 * , 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'.

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.

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  część łańcucha pasująca do   jest zapamiętana jako pierwsza grupa (i w konsekwencji ma numer 1); znak wyszukany przez   jest zgrupowany pod numerem 2, a część wyszukana przez   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  będzie wyszukiwał par identycznych małych liter, podczas gdy   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  na łańcuchu tekstowym , to wynikiem będą dwie grupy: 3 i 5.

<span id="Table_library">

Biblioteka tablicowa
Większość funkcji w bibliotece tablicowej zakłada, że tablica przedstawia sekwencję.

Funkcje,   i   mogą być dostępne, lecz są przestarzałe. Zamiast nich należy używać pętli  z pairs lub z ipairs i operatora długości.

table.concat
Jeśli przekazana zostanie tablica zawierająca łańcuchy tekstowe lub liczby wynikiem będzie.

Domyślną wartością dla  jest pusty łańcuch tekstowy, domyślną dla   jest 1, a domyślną dla   jest długość tablicy. Jeśli  jest większe niż   to wynikiem będzie pusty łańcuch tekstowy.

table.insert
Wstawia element  na pozycji   w tablicy , przesuwając w górę inne elementy aby utworzyć wolne miejsce jeśli to konieczne. Domyślną wartością dla  jest długość tablicy plus 1, tak więc wywołanie   wstawia   na koniec tablicy.

Elementy aż do są przesuwane; zobacz sekcję Operator długości aby poznać zastrzeżenia jeśli tablica nie jest sekwencją.

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

table.remove
Usuwa z tablicy  element na pozycji , przesuwając w dół inne elementy aby uzupełnić zwolnione miejsce jeśli potrzeba. Zwraca wartość usuniętego elementu. Domyślną wartością dla  jest długość tablicy, tak więc wywołanie   usuwa ostatni element z tablicy.

Elementy aż do są przesuwane; zobacz sekcję Operator długości aby poznać zastrzeżenia jeśli tablica nie jest sekwencją.

table.sort
Sortuje elementy tablicy w zadanym porządku, w miejscu, od  do. Jeśli  jest podany, to musi to być funkcja, która otrzymuje dwa elementy tablicy i zwraca   kiedy pierwszy element jest mniejszy niż drugi (tak więc   będzie zachodziło po sortowaniu). Jeśli  nie jest podana, to w zamian używany jest standardowy operator Lua.

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.

<span id="Scribunto_libraries">

Biblioteki Scribunto
Wszystkie biblioteki Scribunto są umieszczone w tablicy.

<span id="Base_functions">

mw.addWarning
Dodaje ostrzeżenie, które jest wyświetlane na podglądzie edycji. jest interpretowany jak wikitekst.

mw.allToString
Wywołuje tostring na wszystkich argumentach, które następnie łączy używając znaki tabulacji jako separatorów.

mw.clone
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
Zwraca bieżący obiekt ramki, zazwyczaj jest to obiekt ramki z ostatniego wywołania.

mw.incrementExpensiveFunctionCount
Dodaje jeden do licznika „złożonych obliczeniowo funkcji parsera” i zgłasza wyjątek jeśli limit zostaje przekroczony (zobacz ).

mw.isSubsting
Zwraca  jeśli bieżące wywołanie   jest wywołany w trybie subst:, w przeciwnym razie. Zobacz sekcję Zwracanie tekstu powyżej aby zapoznać z opisem różnic w działaniu.

mw.loadData
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  może zająć zauważalnie dużo czasu. Funkcja  została wprowadzona w celu uniknięcia tych problemów.

działa jak  z następującymi różnicami:


 * Ładowany moduł jest ładowany tylko raz na stronę, zamiast raz na każde wywołanie.
 * Ładowany moduł nie jest umieszczany w tablicy.
 * 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  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   i   będą działać, lecz inne metody, w tym ,   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ć  aby wydajnie ładować dane.

mw.loadJsonData
This is the same as  above, except it loads data from JSON pages rather than Lua tables. The JSON content must be an array or object. See also.

mw.dumpObject
Serializes  to a human-readable representation, then returns the resulting string.

mw.log
Przekazuje argumenty do mw.allToString, a następnie dołącza wynikowy tekst do bufora logu.

Funkcja  jest jej aliasem w konsoli debugowania.

mw.logObject
Calls mw.dumpObject and appends the resulting string to the log buffer. If  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  i parsera.

Note that there is no frame library, and there is no global variable named. A frame object is typically obtained by being passed as a parameter to the function called by, and can also be obtained from.

frame.args
Tablica udostępniająca argumenty przekazane do ramki. Na przykład jeśli moduł jest wywołany z wikitekstu przez

to  zwróci ,   zwróci  , a   (lub  ) zwróci. Możliwe jest również iterowanie po argumentach używając  lub. 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śći w tej tablicy są zawsze łańcuchami tekstowymi; jeśli zachodzi potrzeba ich zamiany na liczby to można użyć funkcji. Jednak klucze są liczbami nawet jesli są jawnie podane w wywołaniu:  otrzymuje wartości łańcuchów tekstowych   i   indeksowane liczbowymi kluczami   i.

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  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,   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 #invoke, nie zostaną one rozwinięte po przekazaniu do Lua, dopóki ich wartości nie zostaną zażądane w Lua. Jeśli argument do #invoke zawiera pewne specjalne tagi w zapisie XML takie jak,  ,   lub  , 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

 * Należy pamiętać o używaniu nazwanych argumentów.

Wywołuje funkcję parsera zwracając odpowiedni łańcuch tekstowy. Jeśli tylko to możliwe to należy skorzystać z natywnych funcji Lua lub biblioteki Scribunto zamiast tego interfejsu.

Następujące wywołania są w przybliżeniu równoważne z podanym wikikodem:

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

 * Należy pamiętać o używaniu nazwanych argumentów.

To jest transkluzja. Wywołanie

w Lua robi mniej więcej to samo co  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:

frame:extensionTag
To jest równoważne wywołaniu frame:callParserFunction z nazwą funkcji, a następnie podaną treścią z   i argumentami z.

frame:getParent
Wywołane na ramce utworzonej przez  zwraca ramkę dla strony, która wywołała. Wywołane dla tamtej ramki zwraca nil.

Na przykład jeśli szablon  zawiera kod   i strona transkluduje ten szablon wraz z polami, wywołując   w module „Moduł:NazwaModułu” otrzymuje się.

frame:getTitle
Zwraca tytuł stowarzyszony z ramką jako łańcuch tekstowy. Dla ramki utworzonej przez  jest to tytuł wywołanego modułu.

frame:newChild

 * 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. Liczba ramek, która może być utworzona w danym momencie jest ograniczona.

frame:preprocess
Rozwija wikikod w kontekście ramki, np. szablony, funkcje parser i parametry takie jak  są rozwijane. Niektóre specjalne tagi zapisane w postaci XML, takie jak,  ,   i  , będą zamienione na specjalne znaczniki („strip markers”) &mdash; ł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ć  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  for the same reasons.

frame:getArgument
Zwraca obiekt dla określonego argumentu, lub nil jeśli argument nie jest dostarczony.

Zwrócony obiekt ma jedną metodę, która zwraca rozwinięty wikikod argumentu.

frame:newParserValue
Zwraca obiekt z jedną metodą, która zwraca wynik.

frame:newTemplateParserValue

 * Należy pamiętać o używaniu nazwanych argumentów.

Zwraca obiekt z jedną metodą, która zwraca wynik   wywołanego z podanymi argumentami.

frame:argumentPairs
To samo co. Dostępne ze względu na wsteczną kompatybilność.

<span id="Hash_library">

mw.hash.hashValue
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
Zwraca listę wspieranych algorytmów funkcji skrótu do użycia w funkcji mw.hash.hashValue.

<span id="HTML_library">

Biblioteka HTML
to fluent interface do tworzenia skomplikowanego kodu HTML z Lua. Objekt mw.html można utworzyć stosując.

Funkcje udokumentowane jako  są dostępne globalnie w tablicy  ; funkcje udokumentowane jako   są metodami obiektu mw.html (zobacz  ).

Podstawowy przykład mógłby wyglądać tak:

mw.html.create
Tworzy nowy obiekt mw.html zawierający element HTML. Można podać pusty łańcuch tekstowy lub jako  aby utworzyć pusty obiekt mw.html.

może być tablicą z następującymi kluczami:


 * : Wymuszenie utworzenia bieżącego taga jako samozamykającego, nawet jeśli mw.html nie rozpoznaje go jako samozamykającego
 * : Rodzic dla bieżącej instancji mw.html (przeznaczony do użytku wewnętrznego)

mw.html:node
Appends a child mw.html node to the current mw.html instance. If a nil parameter is passed, this is a no-op. A node is a string representation of an html element.

mw.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
Dołącza znak nowej linii do obiektu mw.html.

mw.html:tag
Appends a new child node with the given  to the builder, and returns a mw.html instance representing that new node. The  parameter is identical to that of

Note that contrarily to other methods such as, this method doesn't return the current mw.html instance, but the mw.html instance of the newly inserted tag. Make sure to use  to go up to the parent mw.html instance, or   if you have nested tags on several levels.

mw.html:attr
Set an HTML attribute with the given  and   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
Get the value of a html attribute previously set using  with the given.

mw.html:addClass
Adds a class name to the node's class attribute. If a nil parameter is passed, this is a no-op.

mw.html:css
Set a CSS property with the given  and   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
Add some raw  to the node's style attribute. If a nil parameter is passed, this is a no-op.

mw.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
Like, but traverses all the way to the root node of the tree and returns it.

<span id="Language_library">

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  są dostępne w globalnej tablicy  ; funkcje udokumentowane jak   są metodami obiektu językowego (zobacz  ).

mw.language.fetchLanguageName
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  z językiem docelowym.

mw.language.fetchLanguageNames
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  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  w   zwrócone będą wszystkie dostępne języki (np. z ), natomiast gdy przekazane zostanie   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.language.getContentLanguage
Zwraca nowy obiekt językowy dla domyślnego języka zawartości wiki.

mw.language.getFallbacksFor


Zwraca listę alternatywnych kodów języka (awaryjnych zamienników) dla określonego kodu języka.

mw.language.isKnownLanguageTag
Zwraca  jeśli kod języka jest znany przez MediaWiki.

Kod języka jest „znany” jeśli jest „poprawnym kodem wbudowanym” (np.  zwraca  ) i zwraca niepusty łańcuch tekstowy w wywołaniu.

mw.language.isSupportedLanguage
Sprawdza czy istnieje jakiekolwiek tłumaczenie w tym języku w MediaWiki.

Kod języka jest „wspierany” jeśli jest „poprawny” (wywołanie  zwraca  ), 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  z  ). Należy również pamiętać, że niektóre kody są „wspierane” chociaż  zwraca.

mw.language.isValidBuiltInCode
Zwraca  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  zwraca  ); 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  z  ) nawet jeśli ta funkcja zwraca.

mw.language.isValidCode
Zwraca  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
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
Zwraca kod języka dla tego obiektu językowego.

mw.language:getFallbackLanguages
Zwraca listę alternatywnych kodów języka (awaryjnych zamienników) dla tego obiektu językowego. Równoważne wywołaniu.

mw.language:isRTL
Zwraca  jeśli język jest zapisywane od prawej do lewej, lub   jeśli jest zapisywany od lewej do prawej.

mw.language:lc
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:lcfirst
Zamienia pierwszy znak w łańcuchu tekstowym na małą literę, tak jak lang:lc.

mw.language:uc
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:ucfirst
Zamienia pierwszy znak z łańcucha tekstowego na wielką literę, tak jak lang:uc.

mw.language:caseFold
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
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  można otrzymać ,   a nawet coś takiego jak   w zależności od języka i konfiguracji wiki.

Argument  jest tablicą opcji, w których może być:


 * : Ustawione na  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
Przedstawia datę zgodnie z podanym wzorem. Jeśli  jest pominięty to użyty zostanie czas bieżący. Wartość  musi być logiczna lub nil; jeśli jest to   to czas jest przedstawiany w lokalnej strefie czasowej wiki zamiast w UTC.

Wzór i wspierane wartości dla  są identyczne jak te w funkcji parser #time z. 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.

mw.language:formatDuration
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ę, 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' i 'seconds'.

mw.language:parseFormattedNumber
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.

mw.language:convertPlural
Wybiera właściwą formę gramatyczną z  (która musi być tablicą sekwencyjną) lub z , na podstawie liczby. Na przykład w języku polskim można użyć  lub   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

 * Note the different parameter order between the two aliases.  matches the order of the method of the same name on MediaWiki's Language object, while   matches the order of the parser function of the same name, documented at Help:Magic words#Localisation.

This chooses the appropriate inflected form of  for the given inflection code.

The possible values for  and   are language-dependent, see Special:MyLanguage/Help:Magic words and translatewiki:Grammar for some details.

mw.language:gender
Wybiera łańcuch testowy odpowiadający rodzajowi w, który może być wartością „male”, „female” lub zarejestrowaną nazwą użytkownika.

mw.language:getArrow
Zwraca znak strzałki w Unikodzie odpowiadający wartości :


 * 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
Zwraca "ltr" lub "rtl", w zależności od kierunku zapisu języka.

mw.language:getDirMark
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  czy jest włączony, czy nie.

mw.language:getDirMarkEntity
Zwraca "&amp;lrm;" lub "&amp;rlm;" w zależności od kierunku zapisu języka i flagi  czy jest włączona  czy nie.

mw.language:getDurationIntervals
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ę, 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' i '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  are available on the global   table; functions documented as   and   are methods of a message object (see  ).

mw.message.new
Creates a new message object for the given message. The remaining parameters are passed to the new object's  method.

The message object has no properties, but has several methods documented below.

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

The message object has no properties, but has several methods documented below.

mw.message.rawParam
Wraps the value so that it will not be parsed as wikitext by.

mw.message.numParam
Wraps the value so that it will automatically be formatted as by. Note this does not depend on the Language library actually being available.

mw.message.getDefaultLanguage
Returns a Language object for the default language.

mw.message: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  object, to allow for call chaining.

mw.message:rawParams
Like params, but has the effect of passing all the parameters through mw.message.rawParam first.

Returns the  object, to allow for call chaining.

mw.message:numParams
Like params, but has the effect of passing all the parameters through mw.message.numParam first.

Returns the  object, to allow for call chaining.

mw.message:inLanguage
Specifies the language to use when processing the message. may be a string or a table with a  method (i.e. a Language object).

The default language is the one returned by.

Returns the  object, to allow for call chaining.

mw.message:useDatabase
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  object, to allow for call chaining.

mw.message:plain
Substitutes the parameters and returns the message wikitext as-is. Template calls and parser functions are intact.

mw.message:exists
Returns a boolean indicating whether the message key exists.

mw.message: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
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 "-".

mw.site.currentVersion
A string holding the current version of MediaWiki.

mw.site.scriptPath
The value of.

mw.site.server
The value of.

mw.site.siteName
The value of.

mw.site.stylePath
The value of.

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


Gets statistics about the category. If  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  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
Returns the number of pages in the given namespace (specify by number).

mw.site.stats.usersInGroup
Returns the number of users in the given group.

mw.site.interwikiMap
Returns a table holding data about available interwiki prefixes. If  is the string "local", then only data for local interwiki prefixes is returned. If  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.
 * 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.

<span id="Text_library">

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
Zamienia encje HTML w łańcuchu tekstowym na odpowiednie znaki.

Jeśli  jest pominięte lub ma wartość , to jedynymi rozpoznawanymi encjami są '&amp;lt;', '&amp;gt;', '&amp;amp;', '&amp;quot;', i '&amp;nbsp;'. W przeciwnym razie list rozpoznawalnych nazwanych encji HTML5 jest ładowana funkcją PHP.

mw.text.encode
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.

Jeśli jest podany zbiór znaków, 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. Domyślnym zbiorem znaków jest  (spacja na końcu to spacja niełamiąca, U+00A0).

mw.text.jsonDecode
Dekoduje łańcuch tekstowy z danymi w formacie JSON. Flagi  to 0 lub kombinacja (za pomocą  ) flag   i.

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

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ę. 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.jsonEncode
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  to 0 lub kombinacja (za pomocą  ) flag   i.

Tablice w Lua są indeksowane od jednego lecz podczas przekształcania ich w JSON ich indeksy standardowo zaczynają się od zera; użycie flagi  w argumencie   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.
 * 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.
 * 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
Usuwa wszystkie specjalne znaczniki MediaWiki („strip marker”) z łańcucha tekstowego.

mw.text.listToText
Łączy listę w opisowym stylu. Innymi słowy działa podobnie jak  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:

mw.text.nowiki
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 lini 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
Dzieli łańcuch tekstowy na podłańcuchy, w których granice dzielenia wyznacza wzrór Ustring. Jeśli wartość  jest ustawiona na , to   będzie interpretowany jako literalny łańcuch tekstowy zamiast wzoru wyrażenia regularnego Lua (tak jak odpowiedni argument  ). Funkcja zwraca tablicę zawierającą podłańcuchy tekstowe.

Na przykład  zwróci tablicę.

Jeśli wzór  wyszukuje pusty tekst, to   będzie podzielony na pojedyncze znaki.

mw.text.gsplit
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.tag

 * Należy pamiętać o używaniu nazwanych argumentów.

Tworzy znacznik w stylu HTML o nazwie.

Jeśli jest podany argument, 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ść  powoduje, że klucz będzie wyemitowany jako parametr bezwartościowy, wartość   pomija klucz całkowicie; inne wartości są błędami.

Jeśli argument  nie jest podany (lub jest nil), to zwracany jest tylko znacznik otwierający. Jeśli  to wartość logiczna , 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 należy stosować frame:extensionTag.

mw.text.trim
Usuwa odstępy i inne znaki na początku i końcu łańcucha tekstowego.

Jeśli jest podany zbiór znaków, 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. Domyślnym zbiorem znaków jest odstęp w ASCII,.

mw.text.truncate
Obcina  do określonej długości, dodając wielokropek  jeśli obcięcie zostało wykonane. Jeśli długość jest dodatnia, to koniec tekstu będzie obcięty; jeśli ujemna, to obcięty będzie początek. Jeśli jest podany argument  i ma on wartość , to wynikowy łańcuch tekstowy wraz z wielokropkiem nie będzie dłuższy niż określona długość.

Domyślna wartość dla wielokropka jest brana z MediaWiki:ellipsis w języku, w którym tworzona jest zawartość wiki.

Przykłady używające domyślnego wielokropka „...”:

mw.text.unstripNoWiki
Zamienia specjalne znaczniki MediaWiki (strip marker) pochodzące od &lt;nowiki&gt; przez odpowiadający im tekst. Znaczniki utworzone z innych powodów pozostają nietknięte.

mw.text.unstrip
Równoważne wywołaniu.

Ta funkcja już nie ujawnia kodu HTML utworzonego przez transkluzję stron specjalnych, znaczników &lt;ref&gt; i innych, co było możliwe we wcześniejszych wersjach Scribunto.

<span id="Title_library">

mw.title.equals
Sprawdza czy dwa tytuły są równe. Należy pamiętać, że fragmenty są ignorowane w porównywaniu.

mw.title.compare
Zwraca -1, 0 lub 1 aby wskazać czy tytuł  jest mniejszy, równy lub większy niż tytuł.

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
Zwraca obiekt tytułu dla bieżącej strony.

mw.title.new


Tworzy nowy obiekt tytułu.

Jeśli podano numer, 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, 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ść  (która może być dowolnym kluczem znalezionym w  ). Jeśli wartość  nie jest prawidłową nazwą tytułu, to wynikiem będzie nil.

mw.title.makeTitle
Tworzy obiekt tytułu z tytułem  w przestrzeni nazw , opcjonalnie z określonym fragmentem   i przedrostkiem. Wartość  może być dowolnym kluczem znalezionym w. Jeśli wynik byłby nieprawidłowy zwracany jest nil.

Należy pamiętać, że inaczej niż w funkcji, ta metoda zawsze zastosuje określoną nazwę przestrzeni. Na przykład  utworzy obiekt dla strony Szablon:Moduł:Foo, natomiast   utworzy obiekt dla strony Moduł:Foo.

Note also that functionality for interwiki titles is limited to  /   /   and URL-related methods; other methods might not behave as expected.

<span id="Title_objects">

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  zwracają tytuły jako wartości będące łańcuchami tekstowymi, natomiast pola kończące się na   zwracają obiekty tytułów.

.
 * id: Identyfikator strony. 0 jeśli strona nie istnieje.
 * 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.
 * 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.
 * baseText: Jeśli jest to podstrona, to tytuł strony, której jest ona podstroną, bez przedrostków. W przeciwnym razie to samo co.
 * subpageText: Jeśli jest to podstrona, to ostatni człon jej nazwy. W przeciwnym razie to samo co.
 * canTalk: Wskazuje czy strona o tym tytule może mieć stronę dyskusji.
 * exists: Whether the page exists. Alias for  for Media-namespace titles. For File-namespace titles this checks the existence of the file description page, not the file itself..
 * 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..
 * 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.
 * inNamespaces( ... ): Whether this title is in any of the given namespaces. Namespaces may be specified by anything that is a key found in.
 * 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.
 * contentModel: The content model for this title, as a string..
 * pageLanguage: The page language for this title, as a language object similar to the default returned from  but specific to this page..
 * basePageTitle: The same as.
 * rootPageTitle: The same as.
 * talkPageTitle: The same as, or   if this title cannot have a talk page.
 * subjectPageTitle: The same as.
 * redirectTarget: Returns a title object of the target of the redirect page if the page is a redirect and the page exists, returns  otherwise.
 * protectionLevels: The page's protection levels. This is a table with keys corresponding to each action (e.g.,  and  ). 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  ..
 * cascadingProtection: The cascading protections applicable to the page. This is a table with keys  (itself a table with keys like   has) and   (an array listing titles where the protections cascade from). If no protections cascade to the  page,   and   will be empty..
 * subPageTitle( text ): The same as.
 * partialUrl: Returns  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:,  ,   (the default), or.
 * 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  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  zwróci.

Since people find the fact surprising, 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  method or accessing the   field records it as a "", and accessing the title object's   or   fields records it as a "".

<span id="File_metadata">

Metadane pliku
Obiekty tytułów przedstawiające strony z przestrzeni nazw Plik lub Media będą miały cechę zwaną. Jest to tablica o następującej budowie:


 * exists: Wskazuje czy plik istnieje. Użycie będzie zarejestrowane jako wykorzystanie obrazu/pliku. Cecha  w obiekcie tytułu istnieje z powodu wstecznej kompatybilności i jest aliasem dla tej cechy. Jeśli ma ona wartość , to wszystkie pozostałe cechy 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 . 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.

<span id="Expensive_properties">

Cechy skomplikowane obliczeniowo
Cechy,  ,   i   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.

<span id="URI_library">

mw.uri.encode
Koduje procentowo łańcuch tekstowy. Domyślny typ,  koduje spacje używając '+' do stosowania w zapytaniach;   koduje spacje jako %20, a   koduje spacje jako '_'.

Należy pamiętać, że format  nie jest w pełni odwracalny, ponieważ zarówno spacje jak i znaki podkreślenia są kodowane przez '_'.

mw.uri.decode
Dekoduje procentowo zakodowany łańcuch tekstowy. Domyślny typ,, zamienia '+' na spacje,   nie wykonuje żadnych dodatkowych zmian, a   zamienia '_' na spacje.

mw.uri.anchorEncode
Koduje łańcuch tekstowy do wykorzystania jako fragment w URI MediaWiki.

mw.uri.buildQueryString
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.

mw.uri.parseQueryString
Zamienia łańcuch tekstowy, który jest zapytaniem z URI, na tablicę. Klucze z zapytania bez wartości będą miały przypisaną wartość ; 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   można użyć aby wskazać podłańcuch tekstowy to analizy, zamiast całego łańcucha tekstowego. Argument  określa pozycję pierwszego znaku w łańcuchu tekstowym i domyślnie przyjmuje się 1. Argument  jest pozycją ostatniego znaku w łańcuchu tekstowym i domyślnie przyjmuje się długość łańcucha tekstowego. Zarówno  jak i   mogą być ujemne tak jak w string.sub.

mw.uri.canonicalUrl
Returns a URI object for the canonical URL for a page, with optional query string/table.

mw.uri.fullUrl
Returns a URI object for the full URL for a page, with optional query string/table.

mw.uri.localUrl
Returns a URI object for the local URL for a page, with optional query string/table.

mw.uri.new
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
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.

<span id="URI_object">

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  zwraca łańcuch tekstowy z URI.

Metodami obiektu URI są:

mw.uri:parse
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
Tworzy kopię obiektu URI.

mw.uri:extend
Scala zawartość tablicy  z tablicą zapytania w obiekcie.

<span id="Ustring_library">

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
Zwraca pojedyncze bajty; identycznie jak string.byte.

mw.ustring.byteoffset
Zwraca bajtową pozycję znaku w łańcuchu tekstowym. Domyślnie dla obu wartości  i   przyjmowane jest 1. Wartość  może być ujemna, i w takim przypadku odliczanie będzie prowadzone od końca łańcucha tekstowego.

Dla  == 1 pierwszy znak zaczyna się na pozycji bajtowej   lub po niej. Dla  == 0 pierwszy znak zaczyna się na pozycji bajtowej   lub przed nią. Należy zauważyć, że może to być ten sam znak. Większe lub mniejsze wartości  są obliczane względem tych.

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.

mw.ustring.codepoint
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
Podobnie jak string.find, z tą różnicą, że wzór  jest poszerzony tak jak to opisano w sekcji wzory Ustring oraz indeks   wskazuje numer znaku, a nie bajtu.

mw.ustring.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
Zwraca trzy wartości do iterowania po znakach Unikode w łańcuchu tekstowym. Domyślna wartość dla  to 1, a dla   to -1. Funkcja jest przeznaczona do użycia przez iterowaną postać pętli :

mw.ustring.gmatch
Podobnie jak string.gmatch, z tą różnicą, że wzór  jest poszerzony tak jak jest to opisane w sekcji wzory Ustring.

mw.ustring.gsub
Podobnie jak string.gsub, z tą różnicą, że wzór  jest poszerzony tak jak to opisano w sekcji wzory Ustring.


 * When  is a table, it is possible to use numbers as keys instead of strings (e.g. the value at key   or   would be substituted for any instances of   in a string); as such, using both in a table results in undefined behaviour. This is not possible with string.gsub, which ignores any numbers as keys.

mw.ustring.isutf8
Zwraca  jeśli łańcuch tekstowy jest prawidłowy w kodowaniu UTF-8, w przeciwnym razie wynikiem jest.

mw.ustring.len
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
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
Podobnie jak string.match, z tą różnicą, że wzór  jest poszerzony tak jak to opisano w sekcji wzory Ustring, oraz indeks   wskazuje numer znaku, a nie bajtu.

mw.ustring.rep
Identycznie do string.rep.

mw.ustring.sub
Podobnie jak string.sub, z tą różnicą, że indeksy wskazują numer znaku, a nie bajtu.

mw.ustring.toNFC
Zamienia łańcuch tekstowy na Znormalizowaną Postać C. Zwraca nil jeśli łańcuch tekstowy nie jest poprawny w UTF-8.

mw.ustring.toNFD
Zamienia łańcuch tekstowy na Znormalizowaną Postać D. Zwraca nil jeśli łańcuch tekstowy nie jest poprawny w UTF-8.

mw.ustring.upper
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.

<span id="Ustring_patterns">

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.


 *  : reprezentuje wszystkie znaki z kategorii ogólnej „Litera”.
 *  : reprezentuje wszystkie znaki z kategorii ogólnej „Znak sterujący”.
 *  : reprezentuje wszystkie znaki z kategorii ogólnej „Cyfra dziesiętna”.
 *  : reprezentuje wszystkie znaki z kategorii ogólnej „Mała litera”.
 *  : reprezentuje wszystkie znaki z kategorii ogólnej „Interpunkcja”.
 *  : 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).
 *  : reprezentuje wszystkie znaki z kategorii ogólnej „Wielka litera”.
 *  : reprezentuje wszystkie znaki z kategorii ogólnej „Litera” lub „Cyfra dziesiętna”.
 *  : dodaje warianty znaków cyfr szesnastkowych o pełnej szerokości.
 *  : represents all characters with General Category "Control".
 *  : represents all characters with General Category "Number, decimal digit".
 *  : represents all characters with General Category "Lowercase Letter".
 *  : represents all characters with General Category "Punctuation".
 *  : represents all characters with General Category "Separator", plus tab, linefeed, carriage return, vertical tab, and form feed.
 *  : represents all characters with General Category "Uppercase Letter".
 *  : represents all characters with General Category "Letter" or "Decimal Number".
 *  : adds fullwidth character versions of the hex digits.

Like in String library patterns,  ,  ,  ,  ,  ,  ,    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   i kwantyfikatory dołączone do wielobajtowych znaków działają prawidłowo. Puste grupy rejestrują pozycję w numerze znaku Unikodu zamiast w bajtach.


 * 9 ASCII characters,  ,  ,  ,  ,  ,  ,  ,  ,  , can be matched by   in the string library, but not in the ustring library.

<span id="Loadable_libraries">

Ładowalne biblioteki
Te biblioteki nie są ładowane domyślnie, lecz jeśli zajdzie taka potrzeba mogą być załadowane przez użycie.

bit32
Ta emulacja biblioteki  z Lua 5.2 może być załadowana przez

Biblioteka bit32 dostarcza operatory bitowe dla nieujemnych liczb całkowitych. Wejściowe liczby są obcinane do wartości całkowitych (w bliżej nieokreślony sposób) i zredukowane do reszty z dzielenia przez 232, tak aby ich wartość mieściła się w zakresie od 0 do 232-1; zwracane wyniki są również z tego przedziału.

Kiedy bity są numerowane (tak jak w bit32.extract), 0 to najmniej znaczący bit (ten o wartości 20), a 31 to najbardziej znaczący (ten o wartości 231).

bit32.band
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
Zwraca bitowe dopełnienie z.

bit32.bor
Zwraca alternatywę 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
Równoważne z

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
Wycina fragment bitowy o szerokości, zaczynający się od bitu o numerze. Próba odczytu bitów o numerach spoza zakresu od 0 do 31 jest błędem.

Wartością domyślną dla  jest 1, jeśli jej nie podano.

bit32.replace
Zamienia fragment bitowy o szerokości  w liczbie , zaczynający się od bitu o numerze   przez fragment o szerokości   z najmłodszy bitów wartości. Próba odczytu bitów o numerach spoza zakresu od 0 do 31 jest błędem.

Wartością domyślną dla  jest 1, jeśli jej nie podano.

bit32.lshift
Zwraca liczbę  przesuniętą o   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 2undefined.

Należy pamiętać, że wynikiem przesunięcia o ponad 31 bitów jest 0.

bit32.rshift
Zwraca liczbę  przesuniętą o   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 2undefined.

Należy pamiętać, że wynikiem przesunięcia o ponad 31 bitów jest 0.

bit32.arshift
Zwraca liczbę  przesuniętą o   bitów w prawo. Jest to przesunięcie arytmetyczne: jeśli  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
Zwraca liczbę  obróconą o   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
Zwraca liczbę  obróconą o   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.checkType
Zgłasza błąd jeśli  nie pasuje do oczekiwanego typu w. Ponadto błąd nie będzie zgłoszony jeśli  będzie nil, a   będzie miało wartość.

Argument  to nazwa wywołującej funkcji, a   jest pozycją argumentu na liście argumentów. Są one używane przy formatowaniu komunikatów błędów.

libraryUtil.checkTypeMulti
Zgłasza błąd jeśli  nie pasuje do żadnego łańcucha tekstowego w tablicy.

Ta funkcja jest przeznaczona dla argumentów, które mogą mieć więcej niż jeden poprawny typ.

libraryUtil.checkTypeForIndex
Zgłasza błąd jeśli  nie pasuje do wartości w.

Głównym przeznaczeniem tej funkcji jest jej użycie podczas implementowania metametody.

libraryUtil.checkTypeForNamedArg
Zgłasza błąd jeśli  nie pasuje do wartości w. Ponadto błąd nie będzie zgłoszony jeśli wartość  będzie nil, a wartość   będzie ustawiona na.

Główne zastosowanie tej funkcji jest takie samo jak  lecz dla metod, które stosują składnię „nazwanych argumentów” w Lua,.

libraryUtil.makeCheckSelfFunction
Przeznaczeniem tej funkcji jest implementowanie „metod” w obiektach tablicowych, które mają być wywoływane zgodnie ze składnią. Wynikiem jest funkcja, która powinna być wywołana na początku tych metod z argumentem  i nazwą metody, i ta funkcja zgłasza błąd jeśli obiekt   jest inny niż.

Ta funkcja ma ogólnie zastosowanie w funkcji bibliotecznej będącej konstruktorem obiektu, czegoś podobnego do:

luabit
Moduły „bit” i „hex” z biblioteki luabit można załadować przez

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

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 variable is used and 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:

On many Wikimedia wikis this was formerly implemented in. It is in part derived from strict.lua.

ustring
The pure-Lua backend to the Ustring library may be loaded using:

In all cases the Ustring library 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, usually in the table  , 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.

The following libraries are planned, or are in Gerrit pending review.


 * (none at this time)

mw.wikibase
provides access to localizable structured data, most notably Wikidata. See docs_topics_lua.html and.

mw.wikibase.lexeme
WikibaseLexeme provides access to Wikibase Lexeme entities. This is supported by Wikidata:Lexicographical data.

mw.wikibase.mediainfo
WikibaseMediaInfo provides access to Wikibase MediaInfo entities. Zobacz. This is supported by Structured Data on Commons. See Commons:Structured data/Lua.

mw.bcmath
BCmath provides arbitrary-precision arithmetic to Lua modules. See BCmath documentation via "LDoc" link at Extension:BCmath.

mw.smw
Semantic Scribunto provides native support for the Scribunto extension to Semantic MediaWiki extension.

mw.ext.data
provides access to localizable tabular and map data. Zobacz. Tabular Data and GeoJSON Map Data is supported in Commons "Data:" namespace.

mw.ext.cargo
Cargo provides a means to query its data store from Lua. See Extension:Cargo/Other features.

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.

mw.ext.proofreadPage
Proofread Page provides access to Index and Page namespaces. See. This is supported by Wikisource:ProofreadPage. See Help:Proofread.

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.seo
WikiSEO provides a means to set SEO Data for the current page. See Extension:WikiSEO.

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
Attempting to do so will cause undefined behavior. This includes (but is not limited to) returning such data structures from the module called by  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.
 * 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.

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. See the documentation for that class for implementation details. In the Scribunto extension, this file should be placed in, and a mapping added to. 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. This file should generally include boilerplate something like this:

The module in  (load this with  ) 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,, 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. In the Scribunto extension, the test case should be in  and added to the array in  (in  ); extensions should add the test case in their own   hook function, probably conditional on whether   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  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:, the name of test  , and a string that is the expected output for test.
 * run( n ): Function that runs test  and returns one string.

If  is declared as shown, "Module:TestFramework" is available which provides many useful helper methods. If this is used,  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  and how   is called. Included types are:


 * Normal:  is a table of return values, or a string if the test should raise an error.   is simply called.
 * Iterator:  is a table of tables of return values.   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.

Test cases in another extension
There are (at least) two ways to run PHPUnit tests:

If your extension's test class names all contain a unique component (e.g. the extension's name), the  option may be used to run only your extension's tests.
 * 1) Run phpunit against core, allowing the tests/phpunit/suites/ExtensionsTestSuite.php to find the extension's tests using the  hook.
 * 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 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 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:

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.

<span id="See_also">

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.