Extension:Scribunto/Lua reference manual/ru

Это руководство по в том виде, в каком он используется в MediaWiki с расширением. Некоторые части производны от Lua 5.1 reference manual, доступного под лицензией MIT.

Первые шаги
В вики-проекте с MediaWiki и подключенным Scribunto создайте страницу с заголовком, начинающимся с, например, Module:Bananas. На эту новую страницу скопируйте следующий текст:

Сохраните её, а затем на другой странице (не в модуле) напишите:

При этом имя «Bananas» следует заменить на имя модуля, который вы только что создали. Этот код вызовет функцию «hello» из вашего модуля. При сохранении страницы и последующем просмотре фрагмент  будет заменён на текст, возвращаемый функцией, в данном случае — «Hello, world!»

Обычно лучше вызывать код на Lua посредством шаблона. При таком вызове с точки зрения вызывающей страницы нет разницы, написан ли шаблон с использованием Lua или на чистом вики-тексте. Использование шаблона также позволяет не вводить в основное пространство вики дополнительный усложнённый синтаксис.

Структура модуля
Сам по себе модуль должен возвращать Lua-таблицу, содержащую функции, которые можно вызвать через. Обычно объявляют, как показано выше, локальную переменную, в которую помещается таблица, к этой таблице добавляют функции, и в конце кода модуля эту таблицу возвращают.

Все функции, не добавленные к этой таблице, глобальные они или локальные, через  доступны не будут; однако глобальные могут быть доступны из других модулей, загруженных с помощью. Обычно хорошим стилем для модулей считается объявлять все функции и переменные локальными.

Доступ к параметрам из вики-текста
Функциям, вызываемым с помощью, передаётся единственный параметр, а именно объект frame. Для доступа к параметрам, переданным через, в коде обычно используется таблица   объекта frame. Та же таблица может быть использована для доступа к параметрам, переданным в шаблон, содержащий. Для этого необходимо предварительно вызвать метод frame:getParent  и получить доступ к   возвращённого этим методом фрейма.

Также объект frame используется для доступа к специфичным для конкретного контекста возможностям парсера вики-текста, например, к вызову функций парсера, вызову шаблонов или обработке произвольных строк вики-текста.

Возвращаемый текст
Обычно функция модуля возвращает одну символьную строку (строковый литерал); все возвращаемые значения пропускаются через tostring, а затем конкатенируются (сшиваются) без разделителей. Именно эта строка и встраивается в вики-текст в качестве результата вызова.

В тот момент разбора страницы, когда обрабатывается вызов модуля, шаблоны уже развёрнуты, функции парсера и теги расширений уже обработаны, а предварительные преобразования (например, подстановка подписи вместо тильд или конвейерный приём &#91;pipe trick&#93;) уже совершены. Поэтому модули не могут использовать эти возможности в выходном тексте. Например, если модуль возвращает, то на странице это будет выглядеть как «Hello, world! ».

Также следует помнить, что подстановки вида subst выполняются на более ранней стадии обработки, поэтому код  выполнится не при первом сохранении. Другие подстановки сработают, а эта останется «висеть» в вики-тексте и выполнится только при следующей правке. Поэтому такой подстановки следует избегать.

Документирование модуля
Scribunto позволяет документировать модули, автоматически связывая модуль с вики-текстовой страницей документации; по умолчанию для этого используется подстраница модуля с именем «/doc», содержимое которой внедряется над исходным кодом страницы модуля. Например, документация для модуля «Module:Bananas» может быть размещена на странице «Module:Bananas/doc».

Документирование модуля может быть настроено с помощью следующих системных сообщений в пространстве имён MediaWiki:


 * —Устанавливает имя страницы, используемой для документирования. Имя модуля (без префикса Module:) передается как . Если в пространстве имен модуля, указанные здесь страницы будут интерпретироваться как викитекст, а не как исходный код Lua, и их нельзя использовать с  . По умолчанию это "Module:$1/doc", т.е. подстраница модуля /doc. Обратите внимание, что в этом сообщении нельзя использовать функции синтаксического анализатора и другое раскрытие фигурных скобок.
 * — Message displayed when the doc page does not exist. The name of the page is passed as . По умолчанию пусто.
 * — Сообщение отображается, когда страница документа существует. Имя страницы передается как . The default is to transclude the documentation page.
 * — Header displayed when viewing the documentation page itself. The name of the module (with Module: prefix) being documented is passed as . The default simply displays a short explanation in italics.

Обратите внимание на то, что на страницы модулей нельзя напрямую добавлять категории или интервики-ссылки. Их можно разместить на странице документации внутри тегов, где они будут применены к модулю при включении страницы документации на страницу модуля.

Токены
Имена в Lua (также называемые идентификаторами) могут быть любыми текстовыми строками, состоящими из латинских букв, цифр и знаков подчёркивания, но не начинающимися с цифры. Имена регистрозависимы, т. е. «foo», «Foo», и «FOO», это разные имена.

Нижеследующие ключевые слова зарезервированы и не могут быть использованы в качестве имён:



Имена, начинающиеся с символа подчёркивания, за которым следуют заглавные буквы, зарезервированы для внутренних глобальных переменных Lua.

Другие токены:



Комментарии
Комментарий начинается с символов  в любом месте кода, кроме символьных строк. Если после  сразу же идёт открывающая широкая скобка, то комментарий будет продолжаться до соответствующей закрывающей широкой скобки; в противном случае комментарий продолжается до конца строки.

Типы данных
Lua — динамически типизированный язык, что означает, что тип имеют не переменные и параметры функции, а только назначенные им значения. Все значения имеют тип.

В Lua есть восемь основных типов данных, однако только шесть из них задействованы в расширении Scribunto. Узнать тип значения можно с помощью функции.

Функция  конвертирует значение в символьную строку. Функция  может преобразовать значение в число, если это возможно. Если нет — вернёт nil. Других функций, существующих только для преобразования типа данных, в Lua нет.

Числа автоматически преобразуются в символьные строки, когда используются в ситуации, в которой ожидается вывод именно строкового литерала, например, при использовании в операции конкатенации. Соответственно, строковый литерал, если он в принципе распознаётся функцией, автоматически конвертируется в число при использовании арифметических операций. Если же ожидается вывод логического значения, то получение любого другого, кроме nil или false, интерпретируется как true.

nil
Значение «nil» имеет тип данных  и существует для представления отсутствия какого-либо значения.

Nil не может использоваться в качестве ключа в таблице, и нет никакой разницы между неназначенным ключом таблицы и ключом, назначенным значением nil.

При преобразовании nil в строковый литерал будет получена строка "nil". При преобразовании nil в логическое значение будет получено false.

boolean
Логических (булевых) значений два:  и.

При преобразовании их в символьные строки будут получены строки "true" и "false".

В отличие от многих других языков, логические значения не могут быть напрямую преобразованы в числа. Также в Lua только false и nil в логических операциях считаются значением false; число 0 или пустая символьная строка считаются значением true.

string
Строки Lua считаются последовательностью 8-битных байтов; интерпретация их в соответствии с какой-либо конкретной кодировкой — задача приложения, использующего Lua.

Строковые литералы ограничиваются одинарными или двойными кавычками ( или  ). Так же, как в JavaScript, но не как в PHP, между одинарными и двойными кавычками нет разницы. Определены следующие управляющие последовательности (escape-последовательности):


 * (bell, звуковой сигнал, байт 7)
 * (backspace, возврат на 1 позицию, байт 8)
 * (horizontal tab, горизонтальная табуляция, байт 9)
 * (newline, перевод строки, байт 10)
 * (vertical tab, вертикальная табуляция, байт 11)
 * (form feed, прогон страницы (FF), байт 12)
 * (carriage return, возврат каретки, байт 13)
 * (double quote, двойные кавычки, байт 34)
 * (single quote, одинарные кавычки, байт 39)
 * (backslash, обратная косая черта, байт 92)

Непосредственно перенос строки также может быть включён в символьную строку, если экранировать его обратной косой чертой. Также можно включать в строки байты посредством управляющих последовательностей вида '\ddd', где ddd — это десятичное значение байта в диапазоне 0—255. Чтобы включить символы Unicode с использованием управляющих последовательностей, необходимо указать отдельные байты кодировки UTF-8 (от одного до четырёх); поэтому обычно проще вводить символы Unicode напрямую.

Строковые литералы могут быть обозначены с использованием широких скобок. Открывающая широкая скобка состоит из двух подряд открывающих квадратных скобок, между которыми может располагаться произвольное количество знаков равенства, например,,   или. Открывающей широкой скобке должна соответствовать закрывающая широкая скобка, например,,   или. В качестве особого случая: если после открывающей широкой скобки сразу же следует перенос строки, он не включается в символьную строку, но если перенос строки стоит непосредственно перед закрывающей широкой скобкой, то он в символьную строку входит. В символьных строках, ограниченных широкими скобками, управляющие последовательности не интерпретируются.

Следует помнить, что все строки считаются истинными (true) при преобразовании к логическому типу данных (boolean). Это не похоже на ряд других языков программирования, в которых пустая строка считается ложной (false).

number
Lua имеет только один числовой тип, который обычно представляется как значение двойной точности с плавающей запятой. В этом формате целые числа между -9007199254740992 и 9007199254740992 могут быть представлены точно, в то время как бо́льшие числа и числа с дробной частью могут пострадать от ошибок округления.

В числовых константах в качестве десятичного разделителя используется точка, а разделители групп разрядов не используются, например,. Также числа могут быть представлены с использованием экспоненциальной записи без пробелов, например,,  , или. Целые числа могут быть представлены в шестнадцатеричном виде с использованием префикса, например,.

Хотя и NaN, и бесконечности обоих знаков правильно хранятся и обрабатываются в Lua, под них не предоставлено соответствующих литералов. Константа  хранит положительную бесконечность, и её также можно получить, выполнив деление. А с помощью деления  можно быстро сгенерировать NaN.

Следует помнить, что при преобразовании к логическому типу данных все числа дают true. Это не похоже на ряд других языков программирования, где число 0 даёт false. При конвертации в символьную строку все конечные числа переводятся в десятичную форму, если необходимо — в экспоненциальной форме; NaN даёт  или  ; бесконечности —   или.

table
Таблицы Lua — это ассоциативные массивы, похожие на массивы PHP или объекты JavaScript.

Таблицы создаются с использованием фигурных скобок. Пустая таблица:. Чтобы заполнить поля таблицы при создании, в фигурные скобки можно включить список спецификаторов полей, разделённых запятыми и/или точками с запятой. Они принимают любую из нескольких форм:


 * здесь (первое) значение выражения1 используется как ключ, а (первое) значение выражения2 является значением.
 * , что эквивалентно
 * , что примерно эквивалентно, где i является целым числом, а счёт начинается с 1 и увеличивается на 1 для каждого следующего спецификатора поля. Если последнему спецификатору будет соответствовать выражение, имеющее несколько значений, то будут использованы все они; в противном случае сохраняется только первое значение выражения.

Обращаться к полям таблицы можно с использованием формы записи с квадратными скобками, например,. Символьные ключи, если они соответствуют требованиям к именам, позволяют использовать запись с точкой, например,, что эквивалентно записи. Если значением поля таблицы является функция, её вызов может быть осуществлён в форме записи с двоеточием; например,, что соответствует   или.

Последовательностью называют таблицу с не-nil значениями, ключами для которых служат целые положительные числа от 1 до N (т. е. натуральные числа — прим. пер.), а для ключей, бо́льших N, значения не определены (nil). Множество функций Lua работают только с последовательностями и игнорируют ключи не натурального ряда.

В отличие от многих других языков, таких как PHP или JavaScript, как ключ может использоваться любое значение, кроме nil и NaN, и преобразование типов при этом не выполняется. Всё, представленное ниже, валидно и различается между собой:

Аналогично, любое значение, кроме nil, может быть сохранено как значение таблицы. Хранение nil эквивалентно удалению ключа из таблицы, и обращение к несуществующему ключу даст значение nil.

Следует помнить, что в Lua неявного копирования таблиц не происходит; если таблица передаётся в качестве аргумента функции, которая затем изменяет ключи или значения таблицы, то эти изменения будут видны в вызывающем коде.

При преобразовании таблицы к символьной строке получим результат "table", но это может быть переопределено с помощью метаметода. При логическом преобразовании даже пустая таблица даёт true.

function
Функции в Lua являются значениями первого класса: они могут создаваться анонимно, передаваться как аргументы, назначаться переменным и т. д.

Функции создаются с помощью ключевого слова  и вызываются с помощью круглых скобок. Синтаксический сахар доступен для именованных функций, локальных функций и функций, которые являются значениями в таблице. Подробнее это изложено ниже в разделах Объявление функций и Вызов функций.

Функции в Lua являются замыканием, что означает, что они поддерживают ссылку на область, в которой они объявлены, и могут обращаться к переменным в этой области и управлять ими.

Подобно таблицам, если функция присвоена другой переменной или передана другой функции как аргумент, при её вызове всё равно будет вызван один и тот же внутренний «объект функции».

При преобразовании в строку результатом является "function".

Неподдерживаемые типы
Тип userdata используется для хранения непрозрачных значений, используемых в расширениях для Lua, написанных на других языках. Например, объект userdata может использоваться для хранения указателя или структуры языка Си. Чтобы Scribunto можно было использовать в окружениях, где компилированный пользователем код не допускается, в Scribunto нет расширений, создающих объекты userdata.

Тип thread представляет дескрипторы для сопрограмм, которые недоступны в песочнице Scribunto.

Метатаблицы
У каждой таблицы может быть ассоциированная таблица, известная как метатаблица (metatable). Поля метатаблицы используются некоторыми операциями и функциями для указания другого или резервного поведения таблицы. Метатаблица таблицы может быть получена вызовом функции getmetatable и назначена функцией setmetatable.

Когда Lua обращается к полям метатаблицы с целью осуществления их мета-задач, это обращение по принципам подобно работе функции rawget.

Следующие поля метатаблицы влияют на саму таблицу:
 * __index
 * Это поле используется, когда чтение таблицы вида  вернуло бы nil. Если значение этого поля — таблица, доступ будет перенаправлен на эту таблицу, то есть   (что может затем обращаться к __index уже той таблицы). Если значение этого поля — функция, она будет вызвана как  . При использовании функции rawget обращения к этому метаметоду не происходит.


 * __newindex
 * Это поле используется при записи в таблицу вида  в случаях, когда вызов   вернул бы nil. Если значение этого поля — таблица, запись будет перенаправлена на неё, то есть   (что может затем обратиться к __newindex уже той таблицы). Если значение этого поля — функция, она будет вызвана как  . При использовании функции rawset обращения к этому метаметоду не происходит.


 * __call
 * Это поле используется при попытке вызвать таблицу, то есть . Значение должно быть функцией, которая вызывается как.


 * __mode
 * Это поле используется для создания таблиц со слабыми ссылками. Значение должно быть строкой. По умолчанию, любое значение, используемое как ключ или значение в какой-либо таблице, не будет удалено сборщиком мусора. Но если это метаполе содержит символ 'k', ключи в таблице могут быть удалены сборщиком мусора, если на них нет сильных ссылок. Если в метаполе есть символ 'v', по таким же принципам могут быть удалены значения в таблице. В обоих случаях при удалении ключа и/или значения пара ключ-значение из таблицы удаляется. Обратите внимание, что поведение программы не определено, если это поле будет изменено после назначения содержащей его таблицы как метатаблицы.

Другие поля метатаблиц включают:


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

† При использовании бинарных операций для выбора используемого метаметода Lua сначала смотрит на метатаблицу левого операнда (если она есть), а затем на метатаблицу правого операнда. ‡ При использовании операций сравнения метаметод используется только в том случае, если одна и та же функция задана в метатаблицах обоих операндов. Разные анонимные функции, даже если у них одинаковы код и замыкание, могут не быть сочтены одинаковыми. * __metatable влияет как на getmetatable, так на setmetatable

Обратите внимание: в Lua у всех строк общая метатаблица, в которой  ссылается на таблицу. В Scribunto не доступны ни эта метатаблица, ни таблица, к которой она обращается; таблица string, доступная модулям, является копией.

Переменные
Переменные — это области памяти, хранящие значения. В Lua три вида переменных: глобальные переменные, локальные переменные и поля таблиц.

Имя представляет глобальную или локальную переменную (или аргумент функции, вид локальной переменной). Переменные считаются глобальными, если не были явно объявлены как локальные ключевым словом. Любая переменная, которой не присвоено значение, считается имеющей значение nil.

Глобальные переменные хранятся в таблице Lua, называемой окружением (environment). Эта таблица доступна как глобальная переменная. Таблице глобальных переменных можно задать метатаблицу; метаметоды __index и __newindex будут использоваться при чтении и присвоении глобальных переменных, как в случае с полями любой другой таблицы.

Окружение функции может быть получено вызовом функции getfenv и задано функцией setfenv; в Scribunto эти функции или очень ограничены, или вообще недоступны.

Локальные переменные ограничены областью видимости; для подробностей см. Объявление локальных переменных.

Выражения
Выражение (expression) — что-то, у чего есть значение: литерал (строковый, числовой, true, false, nil), объявление анонимной функции, конструктор таблицы, обращение к переменной, вызов функции, vararg-выражение, выражения в круглых скобках, применённые к выражениям унарные операции и выражения, соединённые бинарными операциями.

У большинства выражений одно значение; вызовы функций и vararg-выражение могут иметь любое число значений. Обратите внимание, что если обернуть вызов функции или vararg-выражение в круглые скобки, будут отброшены все значения, кроме первого.

Списки выражений — разделённые запятыми последовательности выражений. Все выражения в списке, кроме последнего, приводятся к одному значению (лишние значения отбрасываются, а при отсутствии значений используется nil); все значения последнего выражения включаются в значения списка выражений.

Арифметические операции
Lua поддерживает обычный набор арифметических операций: сложение, вычитание, умножение, деление, остаток при делении, возведение в степень и отрицание.

Когда все операнды представлены или числами, или строками, для которых вызов tonumber возвращает не nil, эти операции имеют обычный смысл.

Если какой-либо из операндов — таблица с соответствующим метаметод, этот метаметод будет вызван.

Операции сравнения
Операции сравнения в Lua —,  ,  ,  ,   и. Операции сравнения всегда возвращают булевы значения.

Равенство сначала сравнивает типы операндов, и если они различаются, возвращает false. Затем сравниваются значения: nil, булевы значения, числа и строки сравниваются по значению. Функции равны, только если они ссылаются на один и тот же объект функции;  вернёт false, так как сравнивает две разные анонимные функции. Таблицы по умолчанию сравниваются так же, но это может быть изменено посредством метаметода __eq.

Неравенство — логическое отрицание равенства.

В случае с операциями порядкового сравнения, два числа или две строки сравниваются напрямую. При иных операндах проверяются метаметоды:


 * использует
 * использует, если доступен; иначе, если доступен  , сравнение считается эквивалентным
 * считается эквивалентным
 * считается эквивалентным

Если необходимые метаметоды отсутствуют, вызывается ошибка.

Логические операции
Логические операции —  (и),   (или) и   (не). Все три используют интерпретацию, в которой nil и false считаются ложными, а все другие значения считаются истинными.

При использовании операции, если левый операнд считается ложным, он возвращается, а второй операнд не обрабатывается; иначе возвращается второй операнд.

При использовании операции, если левый операнд считается истинным, он возвращается, а второй операнд не обрабатывается; иначе возвращается второй операнд.

При использовании операции, результат всегда или true, или false.

Обратите внимание, что операции  и   не вычисляют значение правого операнда, если результат операции может быть определён только со знанием левого операнда. Например,  вызовет функцию , только если функция   вернёт как первое значение false или nil.

Операция конкатенации
Операция конкатенации — две точки. Он используется так:. Если оба операнда — числа или строки, они преобразуются в строки и соединяются. В противном случае, если доступен метаметод __concat, будет использован он. Если и он не доступен, будет вызвана ошибка.

Обратите внимание: строки в Lua неизменяемые, и в Lua нет никакого «динамического конструктора строк». Поэтому если в цикле многократно операцию, в каждой итерации будет создана новая строка, а старые через какое-то время будут удалены сборщиком мусора. При необходимости конкатенации большого количества строк может быть быстрее использовать string.format или вставить нужные строки в последовательность и вызвать table.concat после её построения.

Операция длины
Операция длины —. Он используется так:. Если  — строка, операция возвращает её длину в байтах. Если  — таблица-последовательность, операция возвращает длину последовательности.

Если  — таблица, не являющаяся последовательностью,   может вернуть любое такое значение N, для которого a[N] не равно nil, а a[N+1] равно nil, даже если в таблице есть не равные nil значения с бо́льшими индексами. Например,

Приоритетность операций
В Lua используется следующие правила о порядке выполнения (приоритете) операций, в порядке убывания приоритета:


 * 1) not # - (отрицание)
 * 2) + - (вычитание)
 * 3) and
 * or
 * 1) and
 * or
 * 1) and
 * or

В пределах уровня приоритета, большинство бинарных операций левоассоциативно, т. е.  интерпретируется как. Возведение в степень и конкатенация правоассоциативны, т. е.  интерпретируется как.

Вызовы функций
В Lua, как и в большинстве других языков программирования, вызовы функций выглядят как название функции, за которым следует список аргументов в круглых скобках:

функция( список_выражений )

Как и при обычном использовании списков выражений в Lua, последнее выражение в списке может передавать функции несколько аргументов.

Если при вызове функции в списке выражений меньше значений, чем параметров в объявлении функции, дополнительные параметры будут иметь значение nil. Если в списке выражений больше значений, чем у функции параметров, лишние значения будут отброшены. Также возможно, что функция принимает переменное число аргументов; см. Объявления функций для подробной информации.

Lua также позволяет напрямую вызвать значение, возвращённое функцией, то есть. Если для определения вызываемой функции требуется более сложное выражение, чем обращение к переменной по названию, вместо этого обращения может быть использовано заключённое в круглые скобки выражение.

В Lua присутствует синтаксический сахар для двух распространённых вариантов вызова функций. Первый вариант — когда таблица используется как объект, а функция вызывается как метод этого объекта. Синтаксис

таблица:имя_функции( список_выражений )

в точности эквивалентен

таблица.имя_функции( таблица, список_выражений )

Второй вариант — способ, которым в Lua могут быть реализованы «именованные параметры» функций, а именно передача функции единственного аргумента — таблицы, содержащей нужные пары ключ-значение. При таком вызове круглые скобки вокруг списка аргументов могут быть опущены. Также они могут быть опущены, если функции передаётся один строковый литерал. Например, вызовы

func{ arg1 = exp, arg2 = exp } func"string"

эквивалентны вызовам

func( { arg1 = exp, arg2 = exp } ) func( "string" )

Эти два варианта могут использоваться одновременно; например, следующие вызовы функций эквивалентны:

table:name{ arg1 = exp, arg2 = exp } table.name( table, { arg1 = exp, arg2 = exp } )

Определение функций
Синтаксис определений функций выглядит так:

function ( var-list ) block end

Все переменные в списке список_переменных локальные для объявленной функции, а значения им присваиваются из списка выражений в вызове функции. В самом блоке функции могут быть объявлены ещё локальные переменные.

При вызове функции создаются и получают значения локальные переменные из списка список_переменных, а затем исполняются инструкции из блока блок. Если в блоке достигнут оператор return, выполнение блока завершается, а выражению вызова функции присваиваются значения, указанные в операторе return. Если достигнут конец блока, а оператор return не найден, результатом вызова функции является ноль значений.

Функции в Lua являются замыканиями. Нередко в области видимости, где объявляется какая-либо функция, также объявляются «внутренние статические» переменные, используемые этой функцией. Например,

Чтобы функция принимала переменное число аргументов, в её объявлении необходимо указать  как последний элемент в списке список_переменных:

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

В пределах блока может быть использовано varargs-выражение, результатом которого будут все дополнительные аргументы, переданные функции. Например,

Функция select предназначена для работы с varargs-выражением; а именно, следует использовать  вместо   для подсчёта количества значений в varargs-выражении, так как   может не быть последовательностью.

Lua предоставляет синтаксический сахар для сочетания определения функции и присвоения её переменной; см. Операторы определения функции для подробной информации.

Обратите внимание, что этот код не будет работать:

 local factorial = function ( n ) if n <= 2 then return n   else return n * factorial( n - 1 ) end end

Так как определение функции обрабатывается до присвоения её локальной переменной, в теле функции factorial ссылается на (вероятно, неопределённую) переменную с этим именем из внешней области видимости. Этой проблемы можно избежать, если сначала объявить локальную переменную, а в следующей инструкции присвоить её значение этой функции. Также эта проблема не возникает при использовании синтаксиса оператора объявления функции.

Операторы
Оператор или инструкция (англ. statement) — наименьшая исполняемая единица программы: одно присваивание, одна управляющая структура, один вызов функции, одно объявление переменной, и т. п.

Фрагмент (англ. chunk) — последовательность инструкций, на усмотрение программиста разделённых точками с запятой. Фрагмент считается телом анонимной функции, так что он может объявлять локальные переменные, получать аргументы и возвращать значения.

Блок (англ. block) также является последовательностью инструкций, как и фрагмент. Блок может быть выделен в одну инструкцию:. Такой подход может использоваться, чтобы ограничить область видимости локальных переменных, или чтобы добавить  или   в середину другого блока.

Присваивание
Список список_переменных — разделённый запятыми список переменных; список список_выражений — разделённый запятыми список из одного или более выражений. Значения всех выражений вычисляются до выполнения каких-либо присваиваний, поэтому при выполнении кода  значения переменных a и b поменяются местами.

Объявление локальных переменных
Локальные переменные могут быть объявлены где угодно в пределах блока или фрагмента. Первая форма, не содержащая списка выражений, объявляет переменные, но не присваивает никаких значений; поэтому все переменные получат значение nil. Вторая форма присваивает значения локальным переменным, как описано в разделе Присваивание выше.

Обратите внимание, что область видимости локальной переменной начинается с инструкции, следующей за её объявлением. Поэтому объявление наподобие  объявит локальную переменную x и присвоит ей значение x из внешней области видимости. Локальная переменная остаётся видимой до завершения наиболее глубоко вложенного блока, содержащего её объявление.

Управляющие структуры
Оператор while повторяет выполнение блока, пока указанное выражение принимает значение, считающееся истинным.

Оператор repeat повторяет выполнение блока до тех пор, пока указанное выражение не примет значение, считающееся истинным. Локальные переменные, объявленные блоки, могут использоваться в выражении цикла.

Эта первая форма цикла for объявит локальную переменную и станет повторять выполнение блока для каждого значения переменной от выражение1 до выражение2 включительно, добавляя выражение3 после каждой итерации. Обратите внимание, что выражение3 может быть опущено, и в этом случае вместо него будет использовано значение 1; но если выражение3 содержит не числовое значение (например  или  ), будет вызвана ошибка. Значение всех выражений цикла вычисляется один раз перед началом цикла.

Эта форма цикла for примерно эквивалентна следующему коду:

но переменные var, limit и step не доступны в самом цикле. Обратите внимание, что переменная name локальная для блока цикла; чтобы использовать её значение после выполнения цикла, нужно скопировать его в переменную, объявленную вне цикла.

Вторая форма цикла for работает с функциями-итераторами. Как и для первой формы, значение списка список_выражений вычисляется только один раз перед началом цикла.

Эта форма цикла for примерно эквивалентна следующему коду:

но, как и в примере для первого варианта, переменные func, static, and var не доступны в самом цикле. Обратите внимание, что переменные в списке список_переменных локальны для блока цикла; чтобы использовать их значения после цикла, нужно скопировать их в переменные, объявленные вне цикла.

Нередко список_выражений представлен одним вызовом функции, возвращающим нужные три значения. Наиболее эффективна такая функция-итератор, которая зависит только от предоставленных ей аргументов. На случай, если это невозможно, авторы книги Programming in Lua считают, что предпочтительнее создавать замыкание, чем возвращать таблицу как статическую переменную и обновлять её поля каждую итерацию.

Если выражение1 истинно, исполняет блок1, иначе если выражение2 истинно, исполняет блок2, в противном случае исполняет блок3. Часть кода  может быть опущена, а часть кода   может быть повторена несколько раз с разными выражениями и блоками или же может отсутствовать.

Оператор return используется для того, чтобы возвращать значения из функции или из фрагмента (который, по существу, тоже является функцией). список_выражений — разделённый запятыми список из нуля или более выражений.

В Lua реализована оптимизация хвостовой рекурсии: если список_выражений состоит из единственного выражения, являющегося вызовом функции, для вызова функции будет использован уже имеющийся стековый фрейм. Эта оптимизация влияет на функции, работающие со стеком вызовов, включая  и.

Оператор return должен быть последним в своём блоке. Если по какой-то причине return нужен посередине блока, можно создать явный блок оператором.

Оператор break используется для прекращения выполнения цикла while, repeat или for и перехода к оператору, следующему после цикла.

Оператор break должен быть последним в своём блоке. Если по какой-то причине break нужен посередине блока, можно создать явный блок оператором.

Вызовы функций как инструкции
Вызов функции может быть использован как инструкция. В таком случае функция вызывается только ради её побочных эффектов (например, mw.log записывает переданные ей значения в журнал), а возвращённые ей значения отбрасываются.

Операторы объявления функции
Lua предоставляет синтаксический сахар, чтобы объявление функций, их определение и назначение им имени выглядело более естественно. Следующие пары объявлений функций эквивалентны:

-- Основное объявление function func( var-list ) block end func = function ( var-list ) block end

-- Локальная функция local function func( var-list ) block end local func; func = function ( var-list ) block end

-- Функция как поле в таблице function table.func( var-list ) block end table.func = function ( var-list ) block end

-- Функция как метод в таблице function table:func( var-list ) block end table.func = function ( self, var-list ) block end

Заметьте, что приведённая выше запись с двоеточием соответствует использованию двоеточия при вызове функций. При объявлении функции с использованием двоеточия добавляется неявный параметр «self», предшествующий явному списку параметров.

Обработка ошибок
Ошибки могут быть сгенерированы вызовом функций error и assert. Чтобы обработать ошибку, используйте функции pcall или xpcall. Обратите внимание, что некоторые внутренние ошибки Scribunto не могут быть обработаны в пределах модулей Lua.

Сборка мусора
Управление памятью Lua производит автоматически. Ввиду этого вам не нужно беспокоиться ни о выделении памяти под новые объекты, ни об освобождение памяти, когда какие-либо объекты станут ненужными. Lua периодически запускает сборщик мусора для удаления всех объектов, которые больше не будут востребованы программой (обращение к которым из Lua больше невозможно), а также объектов, которые доступны только по слабым ссылкам. Вся используемая Lua память (таблицы, функции, строки, и т. п.) управляется автоматически.

Сборка мусора происходит автоматически и не может быть настроена в коде модулей Scribunto.

Стандартные библиотеки
Стандартные библиотеки Lua предоставляют модулям наиболее важные возможности, а также функции, где производительность критична. Ниже документированы только те функции, которые доступны в Scribunto.

_G


Эта переменная хранит ссылку на текущую таблицу глобальных переменных; к глобальной переменной  можно обратиться выражением. Обратите внимание, что сама таблица _G не отличается от обычных таблиц, и ей может быть присвоено другое значение, как и любой другой переменной:

Таблица глобальных переменных может быть использована, как и любая другая таблица. Например,

_VERSION


Строка, содержащая текущую версию Lua, например "Lua 5.1".

assert
Если  равно nil или false, генерирует ошибку. В этом случае  будет использоваться как текст ошибки: если он равен nil (или не указан), будет использоваться текст "assertion failed!"; если он является строкой или числом, это значение будет использоваться как текст; в противном случае функция assert сама сгенерирует ошибку.

Если  не является ни nil, ни false, assert вернёт все переданные ей аргументы, включая   и.

В Lua нередко используются функции, при нормальном выполнении возвращающие истинное значение, а в случае сбоя возвращающие как первое значение nil или false, а как второе — сообщение об ошибке. Успешное выполнение такой функции можно легко проверить, обернув её вызов в вызов функции :

error
Генерирует ошибку с текстом.

обычно добавляет дополнительную информацию о месте, где возникла ошибка. Если  равен 1 или опущен, это место — сам вызов  ; при значении 2 используется место вызова функции, вызвавшей error; и так далее. Если  равен 0, информация о месте возникновения ошибки приведена не будет.

getfenv
Обратите внимание, что эта функция может не быть доступна в зависимости от того, как задана переменная  в конфигурации движка.

Возвращает окружение (таблицу глобальных переменных) в зависимости от значения :


 * При значении 1, nil, или отсутствии значения, будет возвращено окружение функции, вызвавшей . Нередко это окружение будет таким же, как _G.
 * Если значение — целые число от 2 до 10 включительно, будет возвращено окружение функции, лежащей глубже в стеке вызовов. Например, при значении 2  вернёт окружение функции, вызвавшей функцию, вызвавшую , при значении 3   вернёт окружение функции, окружение которой возвращается при значении 2, и так далее. Будет сгенерирована ошибка, если указано значение большее, чем количество вызовов функций в стеке, или если на указанной глубине стека произошёл возврат с хвостовой рекурсией.
 * Если значение — функция, будет возвращено окружение, которые будет использовано при вызове этой функции.

Окружения, используемые всеми функциями из стандартных библиотек и библиотек Scribunto, защищены. При попытке получить доступ к этим окружениям с помощью  будет возвращено значение nil.

getmetatable
Возвращает метатаблицу переданной функции таблицы. Если функции передано значение любого другого типа, она вернёт nil.

Если в метатаблице есть поле, вместо настоящей метатаблицы будет возращено значение этого поля.

ipairs
Возвращает три значения: функцию-итератор, таблицу  и 0. Эта функция предназначена для использования в итераторной форме цикла :

При выполнении этого кода цикл будет итерировать по парам значений ( 1, t[1] ), ( 2, t[2] ) и так далее до тех пор, пока t[i] не станет равно nil.

Стандартное поведение функции может быть переопределено, если у предоставленного значения есть метаметход. Если этот метаметод задан, вызов ipairs вернёт вместо обычных значений три значения, возвращённые вызовом.

next
Эта функция позволяет итерировать по ключам таблицы. Если  равен nil или не указан, функция возвращает «первый» ключ таблицы и соответствующее ему значение; в противном случае функция возвращает «следующий» ключ таблицы и соответствующее значение. Когда ключей больше не осталось, функция возвращает nil. Вызовом  можно проверить, пуста ли таблица.

Обратите внимание, что порядок, в котором возвращаются ключи, не определён, даже для таблиц с числовыми ключами. Чтобы обработать таблицу в числовом порядке, используйте числовой цикл for или функцию ipairs.

Поведение функции next не определено, если при обходе таблицы этой функцией в таблице присвоено значение ранее отсутствовавшему ключу. Присвоение значения (в том числе nil) существующему полю не вызывает проблем.

pairs
Возвращает три значения: функцию-итератор (next или работающую по схожим принципам), таблицу  и nil. Эта функция предназначена для использования в итераторной форме цикла :

При выполнении этого цикла программа будет итерировать по парам ключ-значение в  так же, как функция next; обратитесь к документации по next для информации об ограничениях на изменение таблицы во время её обхода.

Стандартное поведение функции может быть переопределено, если у предоставленного значения есть метаметод __pairs. Если этот метаметод задан, вызов pairs вернёт вместо обычных значений три значения, возвращённые вызовом.

pcall
Вызывает функцию  с предоставленными аргументами в защищённом режиме. Это значит, что если при вызове  будет сгенерирована ошибка, pcall вернёт false и текст ошибки. Если ошибки не возникнет, pcall вернёт true и все значения, возвращённые вызовом.

В псевдокоде  может быть определена примерно так:

rawequal
Эта функция эквивалентна операции, но в отличие от неё игнорирует метаметод __eq.

rawget
Эта функция эквивалентна операции, но в отличие от неё игнорирует метаметод __index.

rawset
Эта функция эквивалентна операции, но в отличие от неё игнорирует метаметод __newindex.

select
Если  — число, возвращает все аргументы из   с индексом больше этого числа. Если  — строка '#', возвращает количество аргументов в.

Другими словами,  работает примерно так, как код ниже, но корректно обрабатывает случаи, когда некоторые значения в   равны nil (о проблемах с nil см. документацию по # и unpack).

setmetatable
Задаёт метатаблицу заданной таблицы. может быть равен nil, но должен быть указан явно.

Если в текущей метатаблице содержится поле __metatable,  сгенерирует ошибку.

tonumber
Попытается преобразовать  в число. Если оно уже число, или строка, преобразовываемая к числу,  возвращает это число. В противном случае функция вернёт nil.

Необязательный параметр  (по умолчанию равный 10) определяет основание системы счисления, в которой интерпретируется число. Основание может быть от 2 до 36, включая оба этих значения. Если основание больше 11, для разряда со значением 10 используется латинская буква 'A' (в любом регистре), для значения 11 — буква 'B', и так далее; для значения 35 используется буква 'Z'.

Если основание равно 10, у значения может быть дробная часть, оно может выражаться экспоненциальной записью; также в начале значения может присутствовать "0x" для указания шестнадцатеричного числа. Если основание не равно 10, значение должно быть беззнаковым целым.

tostring
Преобразовывает  в строку. См. раздел Типы данных выше для подробностей о преобразовании разных типов данных.

Стандартное поведение функции для таблиц может быть переопределено, если у таблицы есть метаметод __tostring. Если этот метаметод задан, вызов tostring вернёт единственное значение, возвращённое вызовом.

type
Возвращает строку, указывающую тип : ,  ,  ,  ,   или.

unpack
Возвращает значения из заданной таблицы, примерно как делал бы это код. Если эти параметры равны nil или не указаны,  считается равным 1, а   считается равным.

Обратите внимание, что результаты не определены, если   — не последовательность, а   равен nil или не указан; см. раздел Операция длины для более подробной информации.

xpcall
Эта функция аналогична функции, но возвращаемое сообщение об ошибке предварительно передаётся функции.

В псевдокоде  может быть определена примерно так:

debug.traceback
Возвращает строку с трассировкой стека вызовов. Перед началом трассировки может быть приведена необязательная строка message. Необязательное число level может быть использовано для того, чтобы указать, с какого уровня стека начать трассировку.

math.abs
Возвращает абсолютную величину (модуль) числа.

math.acos
Возвращает арккосинус числа  (приведённого в радианах).

math.asin
Возвращает арксинус числа  (приведённого в радианах).

math.atan
Возвращает арктангенс числа  (приведённого в радианах).

math.atan2
Возвращает арктангенс выражения (параметры приведены в радианах). Для определения, в какой четверти лежит результат, используются знаки обоих аргументов.

math.ceil
Возвращает наименьшее целое число, которое больше или равно.

math.cos
Возвращает косинус числа  (приведённого в радианах).

math.cosh
Возвращает гиперболический косинус числа.

math.deg
Возвращает угол  (приведённый в радианах) в градусах.

math.exp
Возвращает значение $$e^x$$.

math.floor
Возвращает наибольшее целое число, которое меньше или равно.

math.fmod
Возвращает остаток от деления с остатком  на. Например, вызов  вернёт.

math.frexp
Возвращает такие два значения  и , что:


 * Если  — конечное число, не равное нулю: $$x = m \times 2^e$$, где   — целое число, а абсолютная величина   лежит в промежутке $$[0.5, 1)$$.
 * Если  равно нулю:   и   равны 0.
 * Если  равно NaN или бесконечности:   равно ,   не приводится.

math.huge
Значение, представляющее собой положительную бесконечность; оно больше или равно любому другому числовому значению.

math.ldexp
Возвращает $$m \times 2^e$$ ( должно быть целым числом).

math.log
Возвращает натуральный логарифм числа.

math.log10
Возвращает десятичный логарифм числа.

math.max
Возвращает наибольшее значение из приведённых аргументов.

Если среди аргументов есть значения NaN, поведение функции не определено. Текущая реализация возвращает NaN, если  равен NaN, но все остальные NaN будут проигнорированы.

math.min
Возвращает наименьшее значение из приведённых аргументов.

Если среди аргументов есть значения NaN, поведение функции не определено. Текущая реализация возвращает NaN, если  равен NaN, но все остальные NaN будут проигнорированы.

math.modf
Возвращает два числа: целую часть  и дробную часть. Например, вызов  вернёт.

math.pi
Значение $$\pi$$.

math.pow
Эквивалентно выражению.

math.rad
Возвращает угол  (приведённый в градусах) в радианах.

math.random
Возвращает псевдослучайное число.

Параметры  и   могут быть опущены, но если они указаны, они должны быть приводимы к целым числам.


 * Если аргументов нет, возвращает вещественное число в промежутке $$[0,1)$$.
 * Если приведён один аргумент, возвращает целое число в промежутке $$[1,m]$$.
 * Если приведено два аргумента, возвращает целое число в промежутке $$[m,n]$$.

math.randomseed
Задаёт  как зерно для генератора псевдослучайных чисел.

Обратите внимание, что при использовании одного и того же зерна  будет возвращать одну и ту же последовательность чисел.

math.sin
Возвращает синус числа  (приведённого в радианах).

math.sinh
Возвращает гиперболический синус числа.

math.sqrt
Возвращает квадратный корень числа. Эквивалентна.

math.tan
Возвращает тангенс числа  (приведённого в радианах).

math.tanh
Возвращает гиперболический тангенс числа.

os.clock
Возвращает приближённое значение задействованного программой времени центрального процессора в секундах.

os.date

 * Функция formatDate из библиотеки lang предоставляет более полные средства форматирования дат.

Возвращает строку или таблицу, содержащую дату и время, отформатированные согласно значению параметра. Если этот параметр опущен или равен nil, используется значение "%c".

Если указан параметр, будет отформатировано это время (см.  ). В противном случае будет использовано текущее время.

Если  начинается с символа '!', то дата форматируется в часовом поясе UTC, а не с использованием локального времени сервера. Если, без учёта символа '!', формат — строка "*t", функция date возвращает таблицу со следующими полями:


 * year — год (полностью)
 * month — месяц (1–12)
 * day — день (1–31)
 * hour — час (0–23)
 * min — минута (0–59)
 * sec — секунда (0–59) (исключение: дополнительная секунда = 60)
 * wday — день недели (воскресенье — 1)
 * yday — день года
 * isdst — флаг летнего времени, булево значение; может отсутствовать, если информация об использовании летнего времени недоступна.

Если формат не равен "*t", функция date вернёт дату как строку, отформатированную по тем же правилам, что и функция языка C strftime.

os.difftime
Возвращает количество секунд от  до.

os.time
Возвращает число, представляющее текущее время.

При вызове без аргументов возвращает текущее время. Если функции передана таблица, будет обработано время, представленное таблицей. В таблице должны быть поля "year" (год), "month" (месяц) и "day" (день); в ней также могут присутствовать поля "hour" (час, по умолчанию 12), "min" (минута, по умолчанию 0), "sec" (секунда, по умолчанию 0) и "isdst".

require
Загружает указанный модуль.

Сначала функция обращается к, проверяя, загружен ли уже этот модуль. Если он загружен, возвращает.

Если модуль не загружен, функция вызывает каждый загрузчик в последовательности, пытаясь найти тот, который загрузит модуль. Если такой загрузчик удастся найти, функция вызовет его. Значение, возвращённое загрузчиком, записывается в  и возвращается.

Обратитесь к документации для  с целью получения информации о доступных загрузчиках.

Например, если у вас есть модуль "Module:Giving", содержащий следующий код:

Вы можете загрузить его в другом модуле, использовав такой код:

package.loaded
В этой таблице хранятся загруженные модули. Ключи — названия модулей, а значения — то, что было возвращено при загрузке модуля.

package.loaders
В этой таблице содержится последовательность функций поиска, используемых при загрузке модулей. Каждая функция поиска вызывается с одним аргументом - именем загружаемого модуля. Если модуль найден, поисковик должен вернуть функцию, которая фактически загрузит модуль и вернет значение, возвращаемое функцией require. В противном случае он должен вернуть ноль.

Scribunto предоставляет два средства поиска:


 * 1) Поиск в   функции загрузчика
 * 2) Поиск в модулях, поставляемых с Scribunto имени модуля, и если это не помогло, посмотрите в пространстве имен Module :. Необходимо указать префикс «Модуль:».

Обратите внимание, что стандартные загрузчики Lua не включены.

package.preload
Эта таблица содержит функции загрузчика, используемые первым искателем, который Scribunto включает в package.loaders.

package.seeall
Устанавливает __index метаметод для  в _G.

Библиотека String
Во всех строковых функциях первый символ находится в позиции 1, а не в позиции 0, как в C, PHP и JavaScript. Индексы могут быть отрицательными, и в этом случае они отсчитываются от конца строки: позиция -1 - последний символ в строке, -2 - второй последний и т. Д.

Библиотека строк предполагает однобайтовые кодировки символов. Он не может обрабатывать символы Юникода. Чтобы работать со строками Unicode, используйте соответствующие методы в Scribunto Ustring library.

string.byte
If the string is considered as an array of bytes, returns the byte values for,  , ···,. The default value for  is 1; the default value for  is. Identical to mw.ustring.byte.

string.char
Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the byte value equal to its corresponding argument.

See mw.ustring.char for a similar function that uses Unicode codepoints rather than byte values.

string.find
Looks for the first match of  in the string. If it finds a match, then  returns the offsets in   where this occurrence starts and ends; otherwise, it returns nil. If the pattern has captures, then in a successful match the captured values are also returned after the two indices.

A third, optional numerical argument  specifies where to start the search; its default value is 1 and can be negative. A value of true as a fourth, optional argument  turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in   being considered "magic".

Note that if  is given, then   must be given as well.

See mw.ustring.find for a similar function extended as described in Ustring patterns and where the  offset is in characters rather than bytes.

string.format
Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string).

The format string uses a limited subset of the format specifiers:


 * Recognized flags are '-', '+', ' ', '#', and '0'.
 * Integer field widths up to 99 are supported. '*' is not supported.
 * Integer precisions up to 99 are supported. '*' is not supported.
 * Length modifiers are not supported.
 * Recognized conversion specifiers are 'c', 'd', 'i', 'o', 'u', 'x', 'X', 'e', 'E', 'f', 'g', 'G', 's', '%', and the non-standard 'q'.
 * Positional specifiers (e.g. "%2$s") are not supported.

The conversion specifier 'q' is like 's', but formats the string in a form suitable to be safely read back by the Lua interpreter: the string is written between double quotes, and all double quotes, newlines, embedded zeros, and backslashes in the string are correctly escaped when written.

Conversion between strings and numbers is performed as specified in Data types; other types are not automatically converted to strings. Strings containing NUL characters (byte value 0) are not properly handled.

Identical to mw.ustring.format.

string.gmatch
Returns an iterator function that, each time it is called, returns the next captures from  over string. If  specifies no captures, then the whole match is produced in each call.

For this function, a ' ' at the start of a pattern is not magic, as this would prevent the iteration. It is treated as a literal character.

See mw.ustring.gmatch for a similar function for which the pattern is extended as described in Ustring patterns.

string.gsub
Returns a copy of  in which all (or the first , if given) occurrences of the   have been replaced by a replacement string specified by  , which can be a string, a table, or a function. also returns, as its second value, the total number of matches that occurred.

If  is a string, then its value is used for replacement. The character  works as an escape character: any sequence in   of the form  , with n between 1 and 9, stands for the value of the n-th captured substring. The sequence  stands for the whole match, and the sequence   stands for a single.

If  is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.

If  is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.

If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).

See mw.ustring.gsub for a similar function in which the pattern is extended as described in Ustring patterns.

string.len
Returns the length of the string, in bytes. Is not confused by ASCII NUL characters. Equivalent to.

See mw.ustring.len for a similar function using Unicode codepoints rather than bytes.

string.lower
Returns a copy of this string with all ASCII uppercase letters changed to lowercase. All other characters are left unchanged.

See mw.ustring.lower for a similar function in which all characters with uppercase to lowercase definitions in Unicode are converted.

string.match
Looks for the first match of  in the string. If it finds one, then  returns the captures from the pattern; otherwise it returns nil. If  specifies no captures, then the whole match is returned.

A third, optional numerical argument  specifies where to start the search; its default value is 1 and can be negative.

See mw.ustring.match for a similar function in which the pattern is extended as described in Ustring patterns and the  offset is in characters rather than bytes.

string.rep
Returns a string that is the concatenation of  copies of the string. Identical to mw.ustring.rep.

string.reverse
Returns a string that is the string  reversed (bytewise).

string.sub
Returns the substring of  that starts at   and continues until  ;   and   can be negative. If  is nil or omitted, it will continue until the end of the string.

Note that a string in Lua begins at index 1. Also, when using this function, the indices at both ends are inclusive.

In particular, the call  returns a prefix of   with length , and   returns a suffix of   with length.

See mw.ustring.sub for a similar function in which the offsets are characters rather than bytes.

string.upper
Returns a copy of this string with all ASCII lowercase letters changed to uppercase. All other characters are left unchanged.

See mw.ustring.upper for a similar function in which all characters with lowercase to uppercase definitions in Unicode are converted.

Patterns
Note that Lua's patterns are similar to regular expressions, but are not identical. In particular, note the following differences from regular expressions and PCRE:


 * The quoting character is percent, not backslash.
 * Dot always matches all characters, including newlines.
 * No case-insensitive mode.
 * No alternation (the  operator).
 * Quantifiers (, ,  , and  ) may only be applied to individual characters or character classes, not to capture groups.
 * The only non-greedy quantifier is, which is equivalent to PCRE's   quantifier.
 * No generalized finite quantifier (e.g. the  quantifier in PCRE).
 * The only zero-width assertions are,  , and the   "frontier" pattern; assertions such as PCRE's   or   are not present.
 * 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.

Character class
A character class is used to represent a set of characters. The following combinations are allowed in describing a character class:


 * x: (where x is not one of the magic characters ) represents the character x itself.
 *  : (a dot) represents all characters.
 *  : represents all ASCII letters.
 *  : represents all ASCII control characters.
 *  : represents all digits.
 *  : represents all ASCII lowercase letters.
 *  : represents all punctuation characters.
 *  : represents all ASCII space characters.
 *  : represents all ASCII uppercase letters.
 *  : represents all ASCII alphanumeric characters.
 *  : represents all hexadecimal digits.
 *  : represents ASCII NUL, the zero byte.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : All characters not in.
 *  : (where x is any non-alphanumeric character) represents the character x. This is the standard way to escape the magic characters. Any punctuation character (even the non magic) can be preceded by a ' ' when used to represent itself in a pattern.
 *  : represents the class which is the union of all characters in set. A range of characters can be specified by separating the end characters of the range with a ' '. All classes  described above can also be used as components in set. All other characters in set represent themselves. For example,   (or  ) represents all alphanumeric characters plus the underscore,   represents the octal digits, and   represents the octal digits plus the lowercase letters plus the ' ' character. The interaction between ranges and classes is not defined. Therefore, patterns like   or   have no meaning.
 *  : represents the complement of set, where set is interpreted as above.

Pattern items
A pattern item can be


 * a single character class, which matches any single character in the class;
 * 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.


 * , a frontier pattern; such item matches an empty string at any position such that the next character belongs to set and the previous character does not belong to set. The set set is interpreted as previously described. The beginning and the end of the subject are handled as if they were the character '\0'. Note that frontier patterns were present but undocumented in Lua 5.1, and officially added to Lua in 5.2. The implementation in Lua 5.2.1 is unchanged from that in 5.1.0.

Pattern
A pattern is a sequence of pattern items.

A ' ' at the beginning of a pattern anchors the match at the beginning of the subject string. A ' ' at the end of a pattern anchors the match at the end of the subject string. At other positions, ' ' and ' ' have no special meaning and represent themselves.

Captures
A pattern can contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored ("captured") for future use. Captures are numbered according to their left parentheses. For instance, in the pattern, the part of the string matching   is stored as the first capture (and therefore has number 1); the character matching   is captured with number 2, and the part matching   has number 3.

Capture references can appear in the pattern string itself, and refer back to text that was captured earlier in the match. For example,  will match any pair of identical lowercase letters, while   will match any 7-letter palindrome.

As a special case, the empty capture  captures the current string position (a number). For instance, if we apply the pattern  on the string , there will be two captures: 3 and 5.

Table library
Most functions in the table library assume that the table represents a sequence.

The functions,  , and   may be available but are deprecated. Use a for loop with pairs, a for loop with ipairs, and the length operator instead.

table.concat
Given an array where all elements are strings or numbers, returns.

The default value for  is the empty string, the default for   is 1, and the default for   is the length of the table. If  is greater than , returns the empty string.

table.insert
Inserts element  at position   in , shifting up other elements to open space, if necessary. The default value for  is the length of the table plus 1, so that a call   inserts   at the end of table.

Elements up to  are shifted; see Length operator for caveats if the table is not a sequence.

table.maxn
Returns the largest positive numerical index of the given table, or zero if the table has no positive numerical indices.

To do this, it iterates over the whole table. This is roughly equivalent to

table.remove
Removes from  the element at position  , shifting down other elements to close the space, if necessary. Returns the value of the removed element. The default value for  is the length of the table, so that a call   removes the last element of table.

Elements up to  are shifted; see Length operator for caveats if the table is not a sequence.

table.sort
Sorts table elements in a given order, in-place, from  to. If  is given, then it must be a function that receives two table elements, and returns true when the first is less than the second (so that   will be true after the sort). If  is not given, then the standard Lua operator   is used instead.

The sort algorithm is not stable; that is, elements considered equal by the given order may have their relative positions changed by the sort.

Библиотеки Scribunto
Все библиотеки Scribunto находятся в таблице.

mw.addWarning
Добавляет предупреждение, которое отображается над окном предварительного просмотра редактирования. анализируется как викитекст.

mw.allToString
Вызывает tostring для всех аргументов, а затем объединяет их с символами табуляции в качестве разделителей.

mw.clone
Создает глубокую копию значения. Все таблицы (и их метатаблицы) востановленны с нуля. Однако функции по-прежнему являются общими.

mw.getCurrentFrame
Возвращает текущий объект frame, обычно объект frame из самого последнего.

mw.incrementExpensiveFunctionCount
Добавляет к "expensive parser function" количество вызовов, и выдает исключение если оно превышает лимит (см. ).

mw.isSubsting
Возвращает true, если текущий  является подстрокой, в противном случае false. См. раздел Возвращаемый текст выше, для рассмотрения различий между подстрокой и не подстрокой.

mw.loadData
Иногда модулю требуются большие таблицы данных; например, модулю общего назначения для преобразования единиц измерения может потребоваться большая таблица распознанных единиц измерения и их коэффициентов пересчета. И иногда эти модули будут использоваться много раз на одной странице. Разбор большой таблицы данных для каждого  может занять значительное количество времени. Чтобы избежать этой проблемы, предоставляется.

работает также как, со следующими отличиями:


 * Загруженный модуль вычисляется только один раз на странице, а не каждый раз при вызове.
 * Загруженный модуль не записывается в.
 * Значение, возвращаемое загруженным модулем, должно быть таблицей. Другие типы данных не поддерживаются.
 * Возвращаемая таблица (и все подтаблицы) могут содержать только логические значения, числа, строки и другие таблицы. Другие типы данных, в частности, функции, не допускаются.
 * Возвращаемая таблица (и все подтаблицы) могут не иметь метатаблиц. SMS
 * Все ключи таблицы должны быть логическими, числовыми или строковыми.
 * The table actually returned by  has metamethods that provide read-only access to the table returned by the module. Since it does not contain the data directly,   and   will work but other methods, including ,  , and the functions in the Table library, will not work correctly.

Упомянутый выше гипотетический модуль преобразования единиц измерения, может хранить код в "Module:Convert", а данные в "Module:Convert/data" и "Module:Convert" будет использовать  для эффективной загрузки данных.

mw.dumpObject
Сериализует  в удобочитаемое представление, а затем возвращает полученную строку.

mw.log
Передает аргументы в mw.allToString, затем добавляет полученную строку в буфер лога.

В консоли отладки функция  является псевдонимом для этой функции.

mw.logObject
Вызывает mw.dumpObject и добавляет полученную строку в буфер лога. Если указан префикс, то он будет добавлен в буфер лога со знаком равенства перед добавлением сериализованной строки (т.е. записываемый текст будет "prefix = object-string").

Объект Frame
Объект frame - это интерфейс для параметров, переданных в.

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
Таблица для доступных аргументов переданных во frame. Например, если модуль вызывается из викитекста с

То  будет возвращать ,    будет возвращать  , и   (или  ) будет возвращать. Также можно перебирать аргументы с помощью  или. 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.

Обратите внимание, что значения в этой таблице всегда строки;  может использоваться для преобразования их в числа, если это необходимо. Однако ключи являются числами, даже если явно предоставлено в вызове:  дает строковые значения   и   индексируется цифровыми ключами   и.

Как и в вызовах шаблонов MediaWiki, у именованных аргументов будут удаленны начальные и конечные пробелы, как из имени, так и из значения, прежде чем они будут переданы Lua. В то время как у безымянных аргументов пробелы не будут удалены.

Для большей производительности,  использует метатаблицу, а не непосредственно содержащую аргументы. Значения аргументов запрашиваются у MediaWiki по требованию. Это означает, что большинство других методов таблицы будут работать неправильно, включая,  , и функции в Table library.

Если в аргументе для #invoke содержатся команды препроцессора, например вызовы шаблонов и параметры в тройных скобках, они разворачиваются только тогда, когда значение аргумента будет запрошено из Lua. Если в аргументе присутствуют некоторые XML-теги, такие как,  ,   и  , то они будут преобразованы в "strip markers" — специальные строки, начинающиеся с символа delete (ASCII 127), которые после возврата из #invoke заменяются на HTML.

frame:callParserFunction

 * Note the use of named arguments.

Call a parser function, returning an appropriate string. Whenever possible, native Lua functions or Scribunto library functions should be preferred to this interface.

The following calls are approximately equivalent to the indicated wikitext:

Note that, as with frame:expandTemplate, the function name and arguments are not preprocessed before being passed to the parser function.

frame:expandTemplate

 * Note the use of named arguments.

This is transclusion. The call

frame:expandTemplate{ title = 'template', args = { 'arg1', 'arg2', name = 'arg3' } }

does roughly the same thing from Lua that  does in wikitext. As in transclusion, if the passed title does not contain a namespace prefix it will be assumed to be in the Template: namespace.

Note that the title and arguments are not preprocessed before being passed into the template:

frame:extensionTag
This is equivalent to a call to frame:callParserFunction with function name  and with   prepended to.

frame:getParent
Вызывается на объекте frame, созданным, возвращает frame для страницы, которая вызвала. Будучи вызвана на этом фрейме, вернет nil.

Например, если шаблон  содержит код , а при вызове этого шаблона в него передаются аргументы ,то код   записанный в Модуле:ModuleName вернет.

frame:getTitle
Возвращает заголовок в виде строки связанный с фреймом. Для фрейма созданного, это название вызванного модуля.

frame:newChild

 * Note the use of named arguments.

Create a new Frame object that is a child of the current frame, with optional arguments and title.

This is mainly intended for use in the debug console for testing functions that would normally be called by. The number of frames that may be created at any one time is limited.

frame:preprocess
This expands wikitext in the context of the frame, i.e. templates, parser functions, and parameters such as  are expanded. Certain special tags written in XML-style notation, such as,  ,   and  , will be replaced with "strip markers" &mdash; special strings which begin with a delete character (ASCII 127), to be replaced with HTML after they are returned from.

If you are expanding a single template, use  instead of trying to construct a wikitext string to pass to this method. It's faster and less prone to error if the arguments contain pipe characters or other wikimarkup.

If you are expanding a single parser function, use  for the same reasons.

frame:getArgument
Gets an object for the specified argument, or nil if the argument is not provided.

The returned object has one method,, that returns the expanded wikitext for the argument.

frame:newParserValue
Returns an object with one method,, that returns the result of.

frame:newTemplateParserValue

 * Note the use of named arguments.

Returns an object with one method,, that returns the result of   called with the given arguments.

frame:argumentPairs
Same as. Included for backwards compatibility.

mw.hash.hashValue
Hashes a string value with the specified algorithm. Valid algorithms may be fetched using mw.hash.listAlgorithms.

mw.hash.listAlgorithms
Returns a list of supported hashing algorithms, for use in mw.hash.hashValue.

HTML library
is a fluent interface for building complex HTML from Lua. A mw.html object can be created using.

Functions documented as  are available on the global   table; functions documented as   and   are methods of an mw.html object (see  ).

A basic example could look like this:

mw.html.create
Creates a new mw.html object containing a  html element. You can also pass an empty string or nil as  in order to create an empty mw.html object.

can be a table with the following keys:


 * : Force the current tag to be self-closing, even if mw.html doesn't recognize it as self-closing
 * : Parent of the current mw.html instance (intended for internal usage)

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.

Note that this stops at the first nil item.

mw.html:newline
Appends a newline to the mw.html object.

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

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.

Language library
Language codes are described at language code. Many of MediaWiki's language codes are similar to IETF language tags, but not all MediaWiki language codes are valid IETF tags or vice versa.

Functions documented as  are available on the global   table; functions documented as   and   are methods of a language object (see   or  ).

mw.language.fetchLanguageName
The full name of the language for the given language code: native name (language autonym) by default, name translated in target language if a value is given for.

mw.language.fetchLanguageNames
Fetch the list of languages known to MediaWiki, returning a table mapping language code to language name.

By default the name returned is the language autonym; passing a language code for  returns all names in that language.

By default, only language names known to MediaWiki are returned; passing  for   will return all available languages (e.g. from ), while passing   will include only languages having customized messages included with MediaWiki core or enabled extensions. To explicitly select the default,  may be passed.

mw.language.getContentLanguage
Returns a new language object for the wiki's default content language.

mw.language.getFallbacksFor


Returns a list of MediaWiki's fallback language codes for the specified code.

mw.language.isKnownLanguageTag
Returns true if a language code is known to MediaWiki.

A language code is "known" if it is a "valid built-in code" (i.e. it returns true for ) and returns a non-empty string for.

mw.language.isSupportedLanguage
Checks whether any localisation is available for that language code in MediaWiki.

A language code is "supported" if it is a "valid" code (returns true for ), contains no uppercase letters, and has a message file in the currently-running version of MediaWiki.

It is possible for a language code to be "supported" but not "known" (i.e. returning true for ). Also note that certain codes are "supported" despite  returning false.

mw.language.isValidBuiltInCode
Returns true if a language code is of a valid form for the purposes of internal customisation of MediaWiki.

The code may not actually correspond to any known language.

A language code is a "valid built-in code" if it is a "valid" code (i.e. it returns true for ); consists of only ASCII letters, numbers, and hyphens; and is at least two characters long.

Note that some codes are "supported" (i.e. returning true from ) even though this function returns false.

mw.language.isValidCode
Returns true if a language code string is of a valid form, whether or not it exists. This includes codes which are used solely for customisation via the MediaWiki namespace.

The code may not actually correspond to any known language.

A language code is valid if it does not contain certain unsafe characters (colons, single- or double-quotes, slashs, backslashs, angle brackets, ampersands, or ASCII NULs) and is otherwise allowed in a page title.

mw.language.new
Creates a new language object. Language objects do not have any publicly accessible properties, but they do have several methods, which are documented below.

There is a limit on the number of distinct language codes that may be used on a page. Exceeding this limit will result in errors.

mw.language:getCode
Returns the language code for this language object.

mw.language:getFallbackLanguages
Returns a list of MediaWiki's fallback language codes for this language object. Equivalent to.

mw.language:isRTL
Returns true if the language is written right-to-left, false if it is written left-to-right.

mw.language:lc
Converts the string to lowercase, honoring any special rules for the given language.

When the Ustring library is loaded, the mw.ustring.lower function is implemented as a call to.

mw.language:lcfirst
Converts the first character of the string to lowercase, as with lang:lc.

mw.language:uc
Converts the string to uppercase, honoring any special rules for the given language.

When the Ustring library is loaded, the mw.ustring.upper function is implemented as a call to.

mw.language:ucfirst
Converts the first character of the string to uppercase, as with lang:uc.

mw.language:caseFold
Converts the string to a representation appropriate for case-insensitive comparison. Note that the result may not make any sense when displayed.

mw.language:formatNum
Formats a number with grouping and decimal separators appropriate for the given language. Given 123456.78, this may produce "123,456.78", "123.456,78", or even something like "١٢٣٬٤٥٦٫٧٨" depending on the language and wiki configuration.

The  is a table of options, which can be:

Digit transformation may still occur, which may include transforming the decimal separator.
 * : Set true to omit grouping separators and use a dot as the decimal separator.

mw.language:formatDate
Formats a date according to the given format string. If  is omitted, the default is the current time. The value for  must be a boolean or nil; if true, the time is formatted in the wiki's local time rather than in UTC.

The format string and supported values for  are identical to those for the #time parser function from. Note however that backslashes may need to be doubled in a Lua string literal, since Lua also uses backslash as an escape character while wikitext does not:

mw.language:formatDuration
Breaks a duration in seconds into more human-readable units, e.g. 12345 to 3 hours, 25 minutes and 45 seconds, returning the result as a string.

, if given, is a table with values naming the interval units to use in the response. These include 'millennia', 'centuries', 'decades', 'years', 'weeks', 'days', 'hours', 'minutes', and 'seconds'.

mw.language:parseFormattedNumber
This takes a number as formatted by lang:formatNum and returns the actual number. In other words, this is basically a language-aware version of.

mw.language:convertPlural
This chooses the appropriate grammatical form from  (which must be a sequence table) or   based on the number. For example, in English you might use  or   to generate grammatically-correct text whether there is only 1 sock or 200 socks.

The necessary values for the sequence are language-dependent, see localization of magic words and translatewiki's FAQ on PLURAL for some details.

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 Special:MyLanguage/Help:Magic words.

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
Chooses the string corresponding to the gender of, which may be "male", "female", or a registered user name.

mw.language:getArrow
Returns a Unicode arrow character corresponding to :


 * forwards: Either "→" or "←" depending on the directionality of the language.
 * backwards: Either "←" or "→" depending on the directionality of the language.
 * left: "←"
 * right: "→"
 * up: "↑"
 * down: "↓"

mw.language:getDir
Returns "ltr" or "rtl", depending on the directionality of the language.

mw.language:getDirMark
Returns a string containing either U+200E (the left-to-right mark) or U+200F (the right-to-left mark), depending on the directionality of the language and whether  is a true or false value.

mw.language:getDirMarkEntity
Returns "&amp;lrm;" or "&amp;rlm;", depending on the directionality of the language and whether  is a true or false value.

mw.language:getDurationIntervals
Breaks a duration in seconds into more human-readable units, e.g. 12345 to 3 hours, 25 minutes and 45 seconds, returning the result as a table mapping unit names to numbers.

For example,

, if given, is a table with values naming the interval units to use in the response. These include 'millennia', 'centuries', 'decades', 'years', 'days', 'hours', 'minutes', and 'seconds'.

The unit names in  may be specified in any order (currently in English only, indendantly of the language object used, and with their plural unabbreviated form only like in the returned table, where unit names are symbolic but still not translated and not grammatically changed according to their assigned value). If the input table contains only unsupported unit names, the returned table will be empty. If the input table is not specified, is nil, or is empty, a static table for any supported units (including 'seconds' for the shortest unit) will be used by default.

The specified duration in seconds is first rounded down to an integer number of the shortest desired unit. The number of members in the returned array is variable, and only unit names mapped to a non-zero value are kept in the returned table if the rounded number of seconds is strictly positive. Otherwise only the member for the shortest desired unit name ('seconds' by default) will be set to the rounded down duration.

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  is unspecified, nil, or "*", returns 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, just the corresponding value is returned instead.

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.

Text library
The text library provides some common text processing functions missing from the String library and the Ustring library. These functions are safe for use with UTF-8 strings.

mw.text.decode
Replaces HTML entities in the string with the corresponding characters.

If boolean  is omitted or false, the only named entities recognized are '&amp;lt;', '&amp;gt;', '&amp;amp;', '&amp;quot;', and '&amp;nbsp;'. Otherwise, the list of HTML5 named entities to recognize is loaded from PHP's function.

mw.text.encode
Replaces characters in a string with HTML entities. Characters '<', '>', '&', '"', and the non-breaking space are replaced with the appropriate named entities; all others are replaced with numeric entities.

If  is supplied, it should be a string as appropriate to go inside brackets in a Ustring pattern, i.e. the "set" in. The default charset is  (the space at the end is the non-breaking space, U+00A0).

mw.text.jsonDecode
Decodes a JSON string. is 0 or a combination (use ) of the flags   and.

Normally JSON's zero-based arrays are renumbered to Lua one-based sequence tables; to prevent this, pass.

To relax certain requirements in JSON, such as no terminal comma in arrays or objects, pass. This is not recommended.

Limitations:


 * Decoded JSON arrays may not be Lua sequences if the array contains null values.
 * JSON objects will drop keys having null values.
 * It is not possible to directly tell whether the input was a JSON array or a JSON object with sequential integer keys.
 * A JSON object having sequential integer keys beginning with 1 will decode to the same table structure as a JSON array with the same values, despite these not being at all equivalent, unless  is used.

mw.text.jsonEncode
Encode a JSON string. Errors are raised if the passed value cannot be encoded in JSON. is 0 or a combination (use ) of the flags   and.

Normally Lua one-based sequence tables are encoded as JSON zero-based arrays; when  is set in , zero-based sequence tables are encoded as JSON arrays.

Limitations:


 * Empty tables are always encoded as empty arrays, not empty objects.
 * Sequence tables cannot be encoded as JSON objects without adding a "dummy" element.
 * To produce objects or arrays with nil values, a tricky implementation of the  metamethod is required.
 * A Lua table having sequential integer keys beginning with 0 will encode as a JSON array, the same as a Lua table having integer keys beginning with 1, unless  is used.
 * When both a number and the string representation of that number are used as keys in the same table, behavior is unspecified.

mw.text.killMarkers
Removes all MediaWiki strip markers from a string.

mw.text.listToText
Joins a list, prose-style. In other words, it's like  but with a different separator before the final item.

The default separator is taken from MediaWiki:comma-separator in the wiki's content language, and the default conjunction is MediaWiki:and concatenated with MediaWiki:word-separator.

Examples, using the default values for the messages:

mw.text.nowiki
Replaces various characters in the string with HTML entities to prevent their interpretation as wikitext. This includes:


 * The following characters: '"', '&', "'", '<', '=', '>', '[', ']', '{', '|', '}'
 * The following characters at the start of the string or immediately after a newline: '#', '*', ':', ';', space, tab ('\t')
 * Blank lines will have one of the associated newline or carriage return characters escaped
 * "" at the start of the string or immediately after a newline will have the first '-' escaped
 * "__" will have one underscore escaped
 * "://" will have the colon escaped
 * A whitespace character following "ISBN", "RFC", or "PMID" will be escaped

mw.text.split
Splits the string into substrings at boundaries matching the Ustring pattern. If  is specified and true,   will be interpreted as a literal string rather than as a Lua pattern (just as with the parameter of the same name for  ). Returns a table containing the substrings.

For example,  would return a table.

If  matches the empty string,   will be split into individual characters.

mw.text.gsplit
Returns an iterator function that will iterate over the substrings that would be returned by the equivalent call to.

mw.text.tag

 * Note the use of named arguments.

Generates an HTML-style tag for.

If  is given, it must be a table with string keys. String and number values are used as the value of the attribute; boolean true results in the key being output as an HTML5 valueless parameter; boolean false skips the key entirely; and anything else is an error.

If  is not given (or is nil), only the opening tag is returned. If  is boolean false, a self-closed tag is returned. Otherwise it must be a string or number, in which case that content is enclosed in the constructed opening and closing tag. Note the content is not automatically HTML-encoded; use mw.text.encode if needed.

For properly returning extension tags such as, use frame:extensionTag instead.

mw.text.trim
Remove whitespace or other characters from the beginning and end of a string.

If  is supplied, it should be a string as appropriate to go inside brackets in a Ustring pattern, i.e. the "set" in. The default charset is ASCII whitespace,.

mw.text.truncate
Truncates  to the specified length, adding   if truncation was performed. If length is positive, the end of the string will be truncated; if negative, the beginning will be removed. If  is given and true, the resulting string including ellipsis will not be longer than the specified length.

The default value for  is taken from MediaWiki:ellipsis in the wiki's content language.

Examples, using the default "..." ellipsis:

mw.text.unstripNoWiki
Replaces MediaWiki &lt;nowiki&gt; strip markers with the corresponding text. Other types of strip markers are not changed.

mw.text.unstrip
Equivalent to.

This no longer reveals the HTML behind special page transclusion, &lt;ref&gt; tags, and so on as it did in earlier versions of Scribunto.

mw.title.equals
Test for whether two titles are equal. Note that fragments are ignored in the comparison.

mw.title.compare
Returns -1, 0, or 1 to indicate whether the title  is less than, equal to, or greater than title.

This compares titles by interwiki prefix (if any) as strings, then by namespace number, then by the unprefixed title text as a string. These string comparisons use Lua's standard  operator.

mw.title.getCurrentTitle
Returns the title object for the current page.

mw.title.new


Creates a new title object.

If a number  is given, an object is created for the title with that page_id. The title referenced will be counted as linked from the current page. If the page_id does not exist, returns nil. The expensive function count will be incremented if the title object created is not for a title that has already been loaded.

If a string  is given instead, an object is created for that title (even if the page does not exist). If the text string does not specify a namespace,  (which may be any key found in  ) will be used. If the text is not a valid title, nil is returned.

mw.title.makeTitle
Creates a title object with title  in namespace , optionally with the specified   and   prefix. may be any key found in. If the resulting title is not valid, returns nil.

Note that, unlike, this method will always apply the specified namespace. For example,  will create an object for the page Template:Module:Foo, while   will create an object for the page Module:Foo.

Title objects
A title object has a number of properties and methods. Most of the properties are read-only.

Note that fields ending with  return titles as string values whereas the fields ending with   return title objects.


 * id: The page_id. 0 if the page does not exist..
 * interwiki: The interwiki prefix, or the empty string if none.
 * namespace: The namespace number.
 * fragment: The fragment, or the empty string. May be assigned.
 * nsText: The text of the namespace for the page.
 * subjectNsText: The text of the subject namespace for the page.
 * text: The title of the page, without the namespace or interwiki prefixes.
 * prefixedText: The title of the page, with the namespace and interwiki prefixes.
 * fullText: The title of the page, with the namespace and interwiki prefixes and the fragment. Interwiki is not returned if equal to the current.
 * rootText: If this is a subpage, the title of the root page without prefixes. Otherwise, the same as.
 * baseText: If this is a subpage, the title of the page it is a subpage of without prefixes. Otherwise, the same as.
 * subpageText: If this is a subpage, just the subpage name. Otherwise, the same as.
 * canTalk: Whether the page for this title could have a talk page.
 * exists: Whether the page exists. Alias for file.exists for Media-namespace titles. For File-namespace titles this checks the existence of the file description page, not the file itself..
 * file, fileExists: See 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..
 * basePageTitle: The same as.
 * rootPageTitle: The same as.
 * talkPageTitle: The same as, or nil 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 false otherwise.
 * protectionLevels: The page's protection levels. This is a table with keys corresponding to each action (e.g., "edit" and "move"). The table values are arrays, the first item of which is a string containing the protection level. If the page is unprotected, either the table values or the array items will be nil..
 * cascadingProtection: The cascading protections applicable to the page. This is a table with keys "restrictions" (itself a table with keys like protectionLevels has) and "sources" (an array listing titles where the protections cascade from). If no protections cascade to the page, "restrictions" and "sources" will be empty..
 * 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.  may be specified to control the scheme of the resulting url: "http", "https", "relative" (the default), or "canonical".
 * localUrl( query ): Returns the local URL (with optional query table/string) for this title.
 * canonicalUrl( query ): Returns the canonical URL (with optional query table/string) for this title.
 * getContent: Returns the (unparsed) content of the page, or nil if there is no page. The page will be recorded as a transclusion.

Title objects may be compared using relational operators. will return.

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

File metadata
Title objects representing a page in the File or Media namespace will have a property called. This is a table, structured as follows:


 * exists: Whether the file exists. It will be recorded as an image usage. The  property on a Title object exists for backwards compatibility reasons and is an alias for this property. If this is false, all other file properties will be nil.
 * width: The width of the file. If the file contains multiple pages, this is the width of the first page.
 * height: The height of the file. If the file contains multiple pages, this is the height of the first page.
 * pages: If the file format supports multiple pages, this is a table containing tables for each page of the file; otherwise, it is nil. The # operator can be used to get the number of pages in the file. Each individual page table contains a width and height property.
 * size: The size of the file in bytes.
 * mimeType: The MIME type of the file.
 * length: The length (duration) of the media file in seconds. Zero for media types which do not support length.

Expensive properties
The properties id, isRedirect, exists, and contentModel require fetching data about the title from the database. For this reason, the expensive function count is incremented the first time one of them is accessed for a page other than the current page. Subsequent accesses of any of these properties for that page will not increment the expensive function count again.

Other properties marked as expensive will always increment the expensive function count the first time they are accessed for a page other than the current page.

mw.uri.encode
Percent-encodes the string. The default type,, encodes spaces using '+' for use in query strings;   encodes spaces as %20; and   encodes spaces as '_'.

Note that the "WIKI" format is not entirely reversible, as both spaces and underscores are encoded as '_'.

mw.uri.decode
Percent-decodes the string. The default type,, decodes '+' to space;   does not perform any extra decoding; and   decodes '_' to space.

mw.uri.anchorEncode
Encodes a string for use in a MediaWiki URI fragment.

mw.uri.buildQueryString
Encodes a table as a URI query string. Keys should be strings; values may be strings or numbers, sequence tables, or boolean false.

mw.uri.parseQueryString
Decodes the query string  to a table. Keys in the string without values will have a value of false; keys repeated multiple times will have sequence tables as values; and others will have strings as values.

The optional numerical arguments  and   can be used to specify a substring of   to be parsed, rather than the entire string. is the position of the first character of the substring, and defaults to 1. is the position of the last character of the substring, and defaults to the length of the string. Both  and   can be negative, as in 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
Constructs a new URI object for the passed string or table. See the description of URI objects for the possible fields for the table.

mw.uri.validate
Validates the passed table (or URI object). Returns a boolean indicating whether the table was valid, and on failure a string explaining what problems were found.

URI object
The URI object has the following fields, some or all of which may be nil:


 * protocol: String protocol/scheme
 * user: String user
 * password: String password
 * host: String host name
 * port: Integer port
 * path: String path
 * query: A table, as from mw.uri.parseQueryString
 * fragment: String fragment.

The following properties are also available:
 * userInfo: String user and password
 * hostPort: String host and port
 * authority: String user, password, host, and port
 * queryString: String version of the query table
 * relativePath: String path, query string, and fragment

will give the URI string.

Methods of the URI object are:

mw.uri:parse
Parses a string into the current URI object. Any fields specified in the string will be replaced in the current object; fields not specified will keep their old values.

mw.uri:clone
Makes a copy of the URI object.

mw.uri:extend
Merges the parameters table into the object's query table.

Ustring library
The ustring library is intended to be a direct reimplementation of the standard String library, except that the methods operate on characters in UTF-8 encoded strings rather than bytes.

Most functions will raise an error if the string is not valid UTF-8; exceptions are noted.

mw.ustring.maxPatternLength
The maximum allowed length of a pattern, in bytes.

mw.ustring.maxStringLength
The maximum allowed length of a string, in bytes.

mw.ustring.byte
Returns individual bytes; identical to string.byte.

mw.ustring.byteoffset
Returns the byte offset of a character in the string. The default for both  and   is 1. may be negative, in which case it counts from the end of the string.

The character at  == 1 is the first character starting at or after byte  ; the character at   == 0 is the first character starting at or before byte. Note this may be the same character. Greater or lesser values of  are calculated relative to these.

mw.ustring.char
Much like string.char, except that the integers are Unicode codepoints rather than byte values.

mw.ustring.codepoint
Much like string.byte, except that the return values are codepoints and the offsets are characters rather than bytes.

mw.ustring.find
Much like string.find, except that the pattern is extended as described in Ustring patterns and the  offset is in characters rather than bytes.

mw.ustring.format
Identical to string.format. Widths and precisions for strings are expressed in bytes, not codepoints.

mw.ustring.gcodepoint
Returns three values for iterating over the codepoints in the string. defaults to 1, and  to -1. This is intended for use in the iterator form of :

mw.ustring.gmatch
Much like string.gmatch, except that the pattern is extended as described in Ustring patterns.

mw.ustring.gsub
Much like string.gsub, except that the pattern is extended as described in Ustring patterns.

mw.ustring.isutf8
Returns true if the string is valid UTF-8, false if not.

mw.ustring.len
Returns the length of the string in codepoints, or nil if the string is not valid UTF-8.

See string.len for a similar function that uses byte length rather than codepoints.

mw.ustring.lower
Much like string.lower, except that all characters with lowercase to uppercase definitions in Unicode are converted.

If the Language library is also loaded, this will instead call lc on the default language object.

mw.ustring.match
Much like string.match, except that the pattern is extended as described in Ustring patterns and the  offset is in characters rather than bytes.

mw.ustring.rep
Identical to string.rep.

mw.ustring.sub
Much like string.sub, except that the offsets are characters rather than bytes.

mw.ustring.toNFC
Converts the string to Normalization Form C. Returns nil if the string is not valid UTF-8.

mw.ustring.toNFD
Converts the string to Normalization Form D. Returns nil if the string is not valid UTF-8.

mw.ustring.upper
Much like string.upper, except that all characters with uppercase to lowercase definitions in Unicode are converted.

If the Language library is also loaded, this will instead call uc on the default language object.

Ustring patterns
Patterns in the ustring functions use the same syntax as the String library patterns. The major difference is that the character classes are redefined in terms of Unicode character properties:


 *  : represents all characters with General Category "Letter".
 *  : 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").

In all cases, characters are interpreted as Unicode characters instead of bytes, so ranges such as, patterns such as  , and quantifiers applied to multibyte characters will work correctly. Empty captures will capture the position in code points rather than bytes.

Loadable libraries
These libraries are not included by default, but if needed may be loaded using.

bit32
This emulation of the Lua 5.2  library may be loaded using

bit32 = require( 'bit32' )

The bit32 library provides bitwise operations on unsigned 32-bit integers. Input numbers are truncated to integers (in an unspecified manner) and reduced modulo 232 so the value is in the range 0 to 232−1; return values are also in this range.

When bits are numbered (as in bit32.extract), 0 is the least-significant bit (the one with value 20) and 31 is the most-significant (the one with value 231).

bit32.band
Returns the bitwise AND of its arguments: the result has a bit set only if that bit is set in all of the arguments.

If given zero arguments, the result has all bits set.

bit32.bnot
Returns the bitwise complement of.

bit32.bor
Returns the bitwise OR of its arguments: the result has a bit set if that bit is set in any of the arguments.

If given zero arguments, the result has all bits clear.

bit32.btest
Equivalent to

bit32.bxor
Returns the bitwise XOR of its arguments: the result has a bit set if that bit is set in an odd number of the arguments.

If given zero arguments, the result has all bits clear.

bit32.extract
Extracts  bits from , starting with bit. Accessing bits outside of the range 0 to 31 is an error.

If not specified, the default for  is 1.

bit32.replace
Replaces  bits in , starting with bit  , with the low   bits from. Accessing bits outside of the range 0 to 31 is an error.

If not specified, the default for  is 1.

bit32.lshift
Returns the number  shifted   bits to the left. This is a logical shift: inserted bits are 0. This is generally equivalent to multiplying by 2undefined.

Note that a displacement over 31 will result in 0.

bit32.rshift
Returns the number  shifted   bits to the right. This is a logical shift: inserted bits are 0. This is generally equivalent to dividing by 2undefined.

Note that a displacement over 31 will result in 0.

bit32.arshift
Returns the number  shifted   bits to the right. This is an arithmetic shift: if  is positive, the inserted bits will be the same as bit 31 in the original number.

Note that a displacement over 31 will result in 0 or 4294967295.

bit32.lrotate
Returns the number  rotated   bits to the left.

Note that rotations are equivalent modulo 32: a rotation of 32 is the same as a rotation of 0, 33 is the same as 1, and so on.

bit32.rrotate
Returns the number  rotated   bits to the right.

Note that rotations are equivalent modulo 32: a rotation of 32 is the same as a rotation of 0, 33 is the same as 1, and so on.

libraryUtil
This library contains methods useful when implementing Scribunto libraries. It may be loaded using

libraryUtil = require( 'libraryUtil' )

libraryUtil.checkType
Raises an error if  does not match. In addition, no error will be raised if  is nil and   is true.

is the name of the calling function, and  is the position of the argument in the argument list. These are used in formatting the error message.

libraryUtil.checkTypeMulti
Raises an error if  does not match any of the strings in the array.

This is for arguments that have more than one valid type.

libraryUtil.checkTypeForIndex
Raises an error if  does not match.

This is intended for use in implementing a  metamethod.

libraryUtil.checkTypeForNamedArg
Raises an error if  does not match. In addition, no error will be raised if  is nil and   is true.

This is intended to be used as an equivalent to  in methods called using Lua's "named argument" syntax,.

libraryUtil.makeCheckSelfFunction
This is intended for use in implementing "methods" on object tables that are intended to be called with the  syntax. It returns a function that should be called at the top of these methods with the  argument and the method name, which will raise an error if that   object is not.

This function will generally be used in a library's constructor function, something like this:

luabit
The luabit library modules "bit" and "hex" may be loaded using

bit = require( 'luabit.bit' ) hex = require( 'luabit.hex' )

Note that the bit32 library contains the same operations as "luabit.bit", and the operations in "luabit.hex" may be performed using  and.

The luabit module "noki" is not available, as it is entirely useless in Scribunto. The luabit module "utf8" is also not available, as it was considered redundant to the Ustring library.

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

ustring = require( 'ustring' )

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
Wikibase Client provides access to localizable structured data. See Extension:Wikibase Client/Lua. This is supported by Wikidata.

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. See Extension:WikibaseMediaInfo/Lua. 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
JsonConfig provides access to localizable tabular and map data. See Extension:JsonConfig/Tabular. 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

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 to evaluate a parser function expressions from Lua.

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.

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

 * Referential data structures: Circular data structures and data structures where the same node may be reached by more than one path cannot be correctly sent to PHP. Attempting to do so will cause undefined behavior. This includes (but is not limited to) returning such data structures from the module called by  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.

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.

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.