Extension:Scribunto/Lua reference manual/ru

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

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

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

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

(где  надо заменить на название вашего модуля). В результате будет вызвана функция, экспортируемая этим модулем. будет заменено на текст, возвращаемый функцией, в данном случае на «Hello, world!».

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

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

Это можно настраивать посредством следующих сообщений пространства MediaWiki:
 * scribunto-doc-page-name: Устанавливает имя подстраницы документации. Указанные тут подстраницы будут интерпретироваться как викитекст, а не код Lua, и их нельзя будет вызывать через . По умолчанию.
 * scribunto-doc-page-does-not-exist: Сообщение, показываемое, когда страницы нет. Имя подстраницы подставляется через . По умолчанию пусто.
 * scribunto-doc-page-show: Сообщение, показываемое, когда страница документации есть. Имя подстраницы подставляется через . По умолчанию включение страницы документации.
 * scribunto-doc-page-header: Шапка при показе самой страницы документации. Имя документируемого модуля передаётся через . По умолчанию это короткое пояснение курсивом.

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

Следующие ключевые слова зарезервированы и не могут использоваться как имена:  Имена, начинающиеся с подчёркивания, за которым следует заглавная буква, зарезервированы для внутренних глобальных переменных Lua.
 * and
 * break
 * do
 * else
 * elseif
 * end
 * false
 * for
 * function
 * if
 * in
 * local
 * nil
 * not
 * or
 * repeat
 * return
 * then
 * true
 * until
 * while

Другие литералы: 
 * &#x25;
 * &#x3a;
 * &#x3b;
 * ]
 * }
 * &#x3a;
 * &#x3b;
 * ]
 * }
 * &#x3a;
 * &#x3b;
 * ]
 * }
 * &#x3b;
 * ]
 * }
 * ]
 * }
 * ]
 * }
 * ]
 * }
 * }
 * }
 * }

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

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

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

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

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

nil
"Nil" — это тип данных для, показывающего отсутствие значения. Nil не может быть ключом в таблице, а запись таблицы со значением nil не отличается от отсутствующего ключа.

При преобразовании в строку результат "nil", в логическое ложь (false).

Логические (boolean)
Логическое значение — это либо  (истина), либо   (ложь).

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

Строки (string)
Строки в Lua — это последовательности байтов по 8 бит; конкретную кодировку им задаёт применение.

Строковые литералы можно заключать в 'одинарные' или "двойные" кавычки; как в JavaScrpit и не как в Perl и PHP, разницы между ними нет. Распознаются специальные ESC-последовательности: '\a' (звонок), '\b' (шаг назад), '\f' (перевод страницы), '\n' (перевод строки), '\r' (возврат каретки), '\t' (горизонтальная табуляция), '\v' (вертикальная табуляция), '\\' (обратная косая черта), '\"' (двойная кавычка) и '\&#x27;' (одинарная кавычка). Собственно перевод строки может быть включён в строковой литерал, если перед ним стоит '\'. Байты можно также вводить последовательностями '\ddd', где ddd — десятичное значение байта (0—255). Символы юникода требуется вводить по отдельным байтам кодировки UTF-8; обычно проще вставить в строку сам символ.

Строковые литералы также можно задавать, используя длинные скобки. Открывающая длинная скобка состоит из открывающей квадратной скобки '[', за которой следуют ноль или более знаков равенства '=', за которыми следует ещё одна открывающая квадратная скобка '[', например,:,   или. Открывающей длинной скобке должна соответствовать закрывающая длинная скобка: соответственно,,   или. ESC-последовательности в строках, ограниченных длинными скобками, не работают. Кроме того, если за открывающей длинной скобкой сразу следует разрыв строки, он не включается в строку.

Все строки, включая пустые, преобразуются к логическому значению.

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

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

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

Все числа, включая 0, преобразуются в логический тип к true. При преобразовании в строки конечные числа представляются в десятичной форме, возможно, в экспоненциальной нотации; нечисловые значения преобразуются в "nan" или "-nan", а бесконечности — в "inf" или "-inf".

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

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

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

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

В отличие от PHP и JavaScript, в качестве ключа можно использовать любое значение, за исключением nil и NaN, и преобразование типов не выполняется. Ниже перечислены корректные примеры:

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

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

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

Функции (function)
Функции в Lua — объекты первого класса: можно создавать анонимные функции, передавать их как аргументы, присваивать переменным и т.п.

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

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

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

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

Неподдерживаемые типы

 * Тип   используется для хранения "тёмных" значений для расширений Lua, написанных на других языках; например, userdata может содержать указатель или структуру языка C. Для возможности использования Scribunto в средах, где специально скомпилированный код не разрешён, такие расширения там не используются.


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

Метатаблицы
С любой таблицей может быть ассоциирована специальная таблица — метатаблица. Поля метатаблицы используются некоторыми операторами и функциями, чтобы указать для таблицы в них иное или резервное поведение. К метатаблице таблицы можно обращаться с помощью функции, а устанавливается она функцией.

Изнутри метафункций доступ к полям таблиц осуществляется при помощи.

Следующие метаполя влияют на работу с самой таблицей:
 * __index : Используется, когда обращение к  должно бы было возвратить nil. Если значение этого поля — таблица, доступ будет переадресован в эту таблицу, т. е.   (что может привести к вызову __index метатаблицы этой таблицы). Если значение поля — функция, она будет вызвана в форме  . Функция   обходит этот метаметод.
 * __newindex : Используется при присвоении ключа таблицы  в том случае, когда   возвратил бы nil. Если значение этого поля — таблица, присваивание перенаправится в эту таблицу, т. е.   (что может привести к вызову __newindex метатаблицы данной таблицы). Если значение этого поля — функция, она будет вызвана в виде  . Функция rawset обходит этот метаметод.
 * __call : Используется, когда к таблице применяется синтаксис вызова функции: . Значение должно быть функцией, которая будет вызываться наподобие.
 * __mode : Используется для хранения в таблице слабых ссылок. Значение должно быть строкой. По умолчанию, любое значение, используемое в таблице как ключ или как значение поля, не будет вычищено из памяти в процессе работы модуля. Но если в данном метаполе есть буква 'k', ключи могут выбрасываться, если на них нет неслабых ссылок, а если есть 'v', то значения; в обоих случаях убираются и ключ, и соответствующее значение. Заметьте, что это поведение становится неопределённым, если данное поле изменено после того, как метатаблица сопоставлена таблице.

В числе других полей метатаблиц: * В бинарных операторах Lua, определяя, какой метаметод использовать, сначала рассматривает метатаблицу левого аргумента, если она есть, а потом правого. ** В операторах сравнения метаметод используется только в том случае, если одна и та же функция определена для обоих аргументов. Разные анонимные функции, даже если их код одинаков, не считаются тождественными. *** __metatable влияет на getmetatable и на setmetatable
 * __add*
 * __sub*
 * __mul*
 * __div*
 * __mod*
 * __pow*
 * __unm
 * __concat*
 * __eq**
 * __lt**
 * __le**
 * __pairs
 * __ipairs
 * __metatable***
 * __tostring

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

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

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

Глобальные переменные хранятся в стандартной таблице Lua, называемой средой; эта таблица часто доступна в виде глобальной переменной. К этой таблице глобальных переменных допускается объявлять метатаблицу; метаметоды __index и __newindex будут вызываться для чтения и присваивания значений глобальных переменных, как они бы работали для доступа к полям любой таблицы.

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

Выражения
Выражение — это что-то, возвращающее значения: литералы (числа, строки,,  ,  ), объявления анонимных функций, конструкторы таблиц, ссылки на переменные, вызовы функций, выражения  , выражения в круглых скобках, унарные операторы, применённые к выражениям, и выражения, объединённые бинарным оператором. Большинство выражений имеет одно значение; вызовы функций и выражения vararg могут иметь любое количество значений. Заметьте, что оборачивание вызова функции или vararg'а в круглые скобки приведёт к потере всех значений, кроме первого.

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

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

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

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

Операторы сравнения
Операторы сравнения в Lua такие:,  ,  ,  ,   и. Результаты операторов сравнения — всегда логические значения.

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

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

В операторах ранжирования аргументы сравниваются напрямую, если оба они числа или оба строки. Иначе проверяются метаметоды: Если нужных метаметодов нет, возникает ошибка.
 * →, если определён, иначе, если есть  , он считается эквивалентным
 * считается эквивалентным
 * считается эквивалентным
 * считается эквивалентным

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

В, если левый операнд ложный, то он возвращается, а второй операнд не вычисляется; иначе возвращается второй операнд.

В, если левый операнд истинен, то он возвращается, а второй операнд не вычисляется; иначе возвращается второй операнд.

Результат  всегда   либо.

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

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

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

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

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

Приоритет операторов
Приоритет операторов Lua, от высшего к низшему:


 * not # - (знаковый)
 * + - (вычитание)
 * and
 * or
 * and
 * or
 * and
 * or

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

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

func( exp-list )

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

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

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

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

table:name( exp-list )

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

table.name( table, exp-list )

Во-вторых, в 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 ( список переменных ) блок end

Все переменные в  локальны для функции; значения присваиваются им из списка выражений при вызове функции. Дополнительные локальные переменные можно задать в блоке.

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

Функции Lua — лексические замыкания. Обычной практикой является создание "private static"-переменных как локальных для области, где функция объявлена. Например,

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

function ( список переменных, ... ) блок end

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

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

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

Внимание, это работать не будет:  local factorial = function ( n ) if n <= 2 then return n   else return n * factorial( n - 1 ) end end Поскольку объявление функции осуществляется до того, как завершено присваивание значения локальной переменной,  внутри функции ссылается на глобальную переменную с таким именем (вероятно, не определённую). Такой проблемы можно избежать, если сперва объявить локальную переменную, а присвоить ей функцию уже в следующем операторе.

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

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

Блок — так же, как и кусок, последовательность операторов. Блок можно ограничить и сделать единым оператором:. Таким образом можно ограничить область видимости локальных переменных, или поместить  или   в середине другого блока.

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

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

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

Управляющие конструкции
Оператор  повторяет , покуда   возвращает истину.

Оператор  повторяет   до тех пор, пока   не возвратит истину. Локальные переменные блока доступны и из выражения.

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

Эта форма оператора  примерно эквивалентна

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

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

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

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

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

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

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

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

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

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

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

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

-- Обычное объявление function func( список переменных ) блок end func = function ( список переменных ) блок end

-- Локальная функция local function func( список переменных ) блок end local func; func = function ( список переменных ) блок end

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

-- Функция — метод таблицы function table:func( список переменных ) блок end table.func = function ( self, список переменных ) блок end

Заметьте, что нотация с двоеточием здесь параллельна нотации для вызова метода и добавляет параметр  в начало списка параметров.

Обработка ошибок
Ошибки могут порождаться с помощью функций error и assert. Для их "перехвата" используйте функции pcall или xpcall. Замечание: некоторые внутренние ошибки Scribunto в коде Lua не перехватываются.

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

Сборка мусора случается автоматически, изнутри Scribunto повлиять на неё нельзя.

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

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

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

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

assert
Если  — nil или false, возникает ошибка. В этом случае  используется в качестве её текста; если оно не указано, текст будет "assertion failed!"; если там не строка и не число,   сама породит ошибку.

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

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

error
Производит ошибку с сообщением.

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

getfenv
Note this function may not be available, depending on  in the engine configuration.

Returns an environment (global variable table), as specified by :
 * If 1, nil, or omitted, returns the environment of the function calling . Often this will be the same as _G.
 * Integers 2–10 return the environment of functions higher in the call stack. For example, 2 returns the environment for the function that called the current function, 3 returns the environment for the function calling that function, and so on. An error will be raised if the value is higher than the number of function calls in the stack, or if the targeted stack level returned with a tail call.
 * Passing a function returns the environment that will be used when that function is called.

The environments used by all standard library functions and Scribunto library functions are protected. Attempting to access these environments using  will return nil instead.

getmetatable
Возвращает метатаблицу таблицы. Со всех прочих типов возвращает nil.

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

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

for i, v in ipairs( t ) do    блок end

Тут будут выполняться итерации по парам ( 1, t[1] ), ( 2, t[2] ) и т. д. до тех пор, пока t[i] не станет nil.

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

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

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

Поведение не определено, если в процессе перебора с помощью  присвоить значение какому-либо не существовавшему ранее ключу. Присваивание нового значения (в том числе nil) существующему полю допустимо.

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

for k, v in pairs( t ) do    block end

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

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

pcall
Вызывает функцию  с соответствующими аргументами в защищённом режиме. This means that if an error is raised during the call to, pcall will return false and the error message raised. If no error occurs, pcall will return true and all values returned by the call.

In pseudocode,  might be defined something like this:

function pcall( f, ... ) try return true, f( ... ) catch ( message ) return false, message end end

rawequal
Эквивалент, но игнорирует любые метаметоды.

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

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

select
Если  это число, возвращает все аргументы в , следующие после index. Если  это строковая константа '#', возвращает число аргументов в.

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

function select( index, ... ) local t = { ... }    if index == '#' then return #t else return unpack( t, index ) end end

setmetatable
Sets the метатаблиц of a table. may be nil, but must be explicitly provided.

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

tonumber
Tries to convert  to a number. If it is already a number or a string convertible to a number, then  returns this number; otherwise, it returns nil.

The optional  (default 10) specifies the base to interpret the numeral. The base may be any integer between 2 and 36, inclusive. In bases above 10, the letter 'A' (in either upper or lower case) represents 10, 'B' represents 11, and so forth, with 'Z' representing 35.

In base 10, the value may have a decimal part, be expressed in E notation, and may have a leading "0x" to indicate base 16. In other bases, only unsigned integers are accepted.

tostring
Converts  to a string. See Data types above for details on how each type is converted.

The standard behavior for tables may be overridden by providing a __tostring метаметод. If that metamethod exists, the call to tostring will return the single value returned by  instead.

type
Returns the type of  as a string: "nil", "number", "string", "boolean", "table", or "function".

unpack
Returns values from the given table, something like  would do if written out manually. If nil or not given,  defaults to 1 and   defaults to.

Note that results are not deterministic if  is not a sequence and   is nil or unspecified; see Length operator for details.

xpcall
This is much like, except that the error message is passed to the function   before being returned.

In pseudocode,  might be defined something like this:

function xpcall( f, errhandler ) try return true, f catch ( message ) message = errhandler( message ) return false, message end end

debug.traceback
Returns a string with a traceback of the call stack. An optional message string is appended at the beginning of the traceback. An optional level number tells at which stack level to start the traceback.

math.abs
Returns the absolute value of.

math.acos
Returns the arc cosine of  (given in radians).

math.asin
Returns the arc sine of  (given in radians).

math.atan
Returns the arc tangent of  (given in radians).

math.atan2
Returns the arc tangent of  (given in radians), using the signs of both parameters to find the quadrant of the result.

math.ceil
Returns the smallest integer larger than or equal to.

math.cos
Returns the cosine of  (given in radians).

math.cosh
Returns the hyperbolic cosine of.

math.deg
Returns the angle  (given in radians) in degrees.

math.exp
Returns the value $$e^x$$.

math.floor
Returns the largest integer smaller than or equal to.

math.fmod
Returns the remainder of the division of  by   that rounds the quotient towards zero.

math.frexp
Returns two values  and   such that:
 * If  is finite and non-zero: $$x = m \times 2^e$$,   is an integer, and the absolute value of   is in the range $$[0.5, 1)$$
 * If  is zero:   and   are 0
 * If  is NaN or infinite:   is   and   is not specified

math.huge
The value representing positive infinity; larger than or equal to any other numerical value.

math.ldexp
Returns $$m \times 2^e$$ ( should be an integer).

math.log
Returns the natural logarithm of.

math.log10
Returns the base-10 logarithm of.

math.max
Returns the maximum value among its arguments.

Behavior with NaNs is not specified. With the current implementation, NaN will be returned if  is NaN, but any other NaNs will be ignored.

math.min
Returns the minimum value among its arguments.

Behavior with NaNs is not specified. With the current implementation, NaN will be returned if  is NaN, but any other NaNs will be ignored.

math.modf
Returns two numbers, the integral part of  and the fractional part of.

math.pi
The value of $$\pi$$.

math.pow
Equivalent to.

math.rad
Returns the angle  (given in degrees) in radians.

math.random
Returns a pseudo-random number.

The arguments  and   may be omitted, but if specified must be convertible to integers.
 * With no arguments, returns a real number in the range $$[0,1)$$
 * With one argument, returns an integer in the range $$[1,m]$$
 * With two arguments, returns an integer in the range $$[m,n]$$

math.randomseed
Sets  as the seed for the pseudo-random generator.

Note that using the same seed will cause  to output the same sequence of numbers.

math.sin
Returns the sine of  (given in radians).

math.sinh
Returns the hyperbolic sine of.

math.sqrt
Returns the square root of. Equivalent to.

math.tan
Returns the tangent of  (given in radians).

math.tanh
Returns the hyperbolic tangent of.

os.clock
Returns an approximation of the amount in seconds of CPU time used by the program.

os.date

 * Language library's formatDate may be used for more comprehensive date formatting

Returns a string or a table containing date and time, formatted according to. If the format is omitted or nil, "%c" is used.

If  is given, it is the time to be formatted (see [[#os.time|  starts with '!', then the date is formatted in UTC rather than the server's local time. After this optional character, if format is the string "*t", then date returns a table with the following fields:
 * year (full)
 * month (1–12)
 * day (1–31)
 * hour (0–23)
 * min (0–59)
 * sec (0–61)
 * wday (weekday, Sunday is 1)
 * yday (day of the year)
 * isdst (daylight saving flag, a boolean; may be absent if the information is not available)

If format is not "*t", then date returns the date as a string, formatted according to the same rules as the C function strftime.

os.difftime
Returns the number of seconds from  to.

os.time
Returns a number representing the current time.

When called without arguments, returns the current time. If passed a table, the time encoded in the table will be parsed. The table must have the fields "year", "month", and "day", and may also include "hour" (default 12), "min" (default 0), "sec" (default 0), and "isdst".

require
Загружает модуль.

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

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

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

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

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

Scribunto предоставляет две поисковых функции:
 * 1) Искать загрузчик по
 * 2) Искать имя модуля среди модулей, поставляемых со Scribunto; при неудаче искать в пространстве имён  . Префикс "Module:" должен быть передан.

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

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

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

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

string.byte
Рассматривая строку  как массив байтов, возвращает значения байтов ,  , ···,. По умолчанию  равно 1,   равно.

string.char
Принимает нуль и более целых чисел. Возвращает строку длиной в количество аргументов, где код каждого символа равен соответствующему аргументу.

string.find
Находит первое совпадение с  в строке. Если включение найдено,  возвращает смещения в , на которых этот экземпляр начинается и заканчивается; иначе возвращает nil. Если в образце есть группировки, то при успешном поиске группы включаются в результат после этих двух индексов.

Третий необязательный числовой аргумент  указывает, с какого символа начинать поиск (если отрицательное число - с какого символа с конца начинать поиск). По умолчанию это 1. Но какой бы числовой аргумент не был указан (положительный или отрицательный) или не указан вообще, номер найденного совпадения позиция всегда отсчитывается от начала строки. Т.е. все три запроса вернут в данном случае один и тот же результат:

k = string.find("Lua reference manual", "n") (k = 11)

k = string.find("Lua reference manual", "n", 5) (k = 11, а не 6, как может быть ожидалось)

k = string.find("Lua reference manual", "n", -15) (k = 11, а не 17 или -4, как может быть ожидалось)

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

Замечание: если  задано,   тоже должно быть задано.

string.format
Возвращает форматированную по аргументу  (должен быть строкой) версию своих последующих аргументов.

Строка формата использует ограниченное подмножество указателей формата:
 * Опознаются флаги '-', '+', ' ', '#', and '0'.
 * Целочисленные поля могут иметь ширину до 99. '*' не поддерживается.
 * Точность целых чисел может достигать 99. '*' не поддерживается.
 * Модификаторы длины не поддерживаются.
 * Распознаются указатели преобразования 'c', 'd', 'i', 'o', 'u', 'x', 'X', 'e', 'E', 'f', 'g', 'G', 's', '%' и нестандартный 'q'.
 * Позиционные указатели (типа ) не поддерживаются.

Указатель 'q' подобен 's', но форматирует строку так, чтобы она после безопасно могла быть вычитана вновь интерпретатором Lua: строка пишется в двойных кавычках и все двойные кавычки, переводы строки, нулевые байты и обратные косые черты в строке корректно экранируются.

Преобразование между строками и числами выполняется, как указано выше в описании типов данных; другие типы автоматически в строки не преобразуются. Строки, содержащие символ NUL (байт с кодом 0), поддерживаются не полностью.

string.gmatch
Возвращает функцию-итератор, которая при каждом вызове возвращает новые группировки из  в строке. Если в  нет группировок, возвращает всё совпадение.

Для этой функции « » в начале образца не имеет специального значения (обратное не позволило бы итерировать) и обрабатывается как обычный символ.

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

Если  — строка, её значение используется для замены. Символ  работает как специальный: все последовательности в   вида , где n — цифра от 1 до 9, заменяются на n-ю подстроку, захваченную группировкой. Последовательность  подставляет всё совпадение, а   заменяет единичный.

Если  — таблица, она опрашивается на каждом совпадении по ключу из первой группировки (или по полному совпадению, если в образце нет группировок).

Если  — функция, она вызывается по всякому найденному совпадению со всеми группировками по порядку в качестве аргументов (или с полным совпадением как единственным аргументом, если в образце нет групп).

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

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

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

string.match
Ищет первое совпадение с  в строке. Если найдено,  возвращает группировки из образца (или весь образец, если нет группировок), иначе nil.

Третий необязательный аргумент  указывает, с какого места искать; по умолчанию равен 1 и может быть отрицательным.

string.rep
Returns a string that is the concatenation of  copies of the string.

string.reverse
Возвращает строку, являющуюся записанной в обратном порядке (побайтно).

string.sub
Возвращает подстроку, начинающуюся с позиции   и продолжающуюся до позиции  ;   и   могут быть отрицательными. Если  не указан (или nil), используется -1.

В обычном применении  возвращает начальные   байт строки , а   — её конечные   байт.

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

Образцы
Заметьте, что образцы Lua похожи на регулярные выражения, но не во всём. Обратите внимание на следующие отличия образцов модуля string в Lua от модели PCRE:
 * Экранирующий символ процент « » вместо обратной косой черты « ».
 * Точка « » всегда совпадает со всеми символами, включая разрывы строки.
 * Нет режима нечувствительности к регистру.
 * Нет вариантного выбора ( не имеет специального значения).
 * Множители (, ,   и  ) могут относиться только к отдельным символам и их классам, но не к группам.
 * Единственный «ленивый» множитель — это, соответствующий в PCRE конструкции.
 * Нет множителей с ограниченным числом повторов (в PCRE обозначаемого ).
 * Единственные элементы нулевой длины — это  и  ; то, что в PCRE обозначается   или , здесь отсутствует.

Классы символов
Класс символов соответствует любому символу из некоторого набора. Следующие комбинации допустимы при описании классов символов:


 * x (где x не один из специальных символов ): сам символ x.
 *   (точка): любой символ.
 *  : представляет все буквы ASCII (эквивалент ).
 *  : представляет все управляющие символы ASCII.
 *  : представляет все цифры (эквивалент ).
 *  : представляет все строчные буквы ASCII (эквивалент ).
 *  : представляет все знаки пунктуации.
 *  : представляет все пробельные символы ASCII.
 *  : представляет все заглавные буквы ASCII (эквивалент ).
 *  : представляет все цифробуквенные символы ASCII.
 *  : представляет все шестнадцатеричные цифры.
 *  : представляет ASCII NUL, нулевой байт.
 *  : Все символы не в.
 *  : Все символы не в.
 *  : Все символы не в.
 *  : Все символы не в.
 *  : Все символы не в.
 *  : Все символы не в.
 *  : Все символы не в.
 *  : Все символы не в.
 *  : Все символы не в.
 *  : Все символы не в.
 *   (где x — любой не алфавитно-цифровой символ): просто символ x. Это обычный способ экранирования специальных символов. Перед любым (даже не имеющим специального значения) символом пунктуации можно поставить, и в образце он будет представлять сам себя.
 *  : класс, объединяющий все символы из последовательности . Диапазон символов может быть указан крайними символами, между которыми стоит ' '. В набор могут включаться и все вышеописанные классы вида  . Все прочие символы представляют сами себя. Например,   (равным образом  ) представляет все алфавитно-цифровые символы или подчёркивание,   — восьмеричные цифры, а   — восьмеричные цифры, строчные буквы и символ ' '. Взаимодействие классов и диапазонов не определено; образцы   и   не имеют смысла.
 *  : представляет дополнение к набору символы, задаваемому, как указано выше.

Атомы образцов
Атомами образцов могут быть:


 * Один класс символов: соответствует любому из символов в этом классе;
 * Один класс символов, за которым следует ' ': соответствует подстроке из нуля или более любых символов из этого класса. Эти повторные элементы всегда будут сопоставлены наиболее длинной из возможных последовательностей;
 * Один класс символов, за которым следует ' ': соответствует подстроке из одного или более любых символов из этого класса. Эти повторные элементы всегда будут сопоставлены наиболее длинной из возможных последовательностей;
 * Один класс символов, за которым следует ' ': соответствует подстроке из нуля или более любых символов из этого класса, но в отличие от ' ' будет сопоставлен кратчайшей из возможных последовательностей;
 * Один класс символов, за которым следует ' ': соответствует любому из символов в этом классе или нулю символов;
 * , где n от 1 до 9: соответствует подстроке, равной захваченной n-й группировкой (см. ниже);
 * , где x и y — два разных символа; такие элементы соотвествуют строкам, начинающимся с x, кончающимся на y и сбалансированных по x и y. Это обозначает, что, если читать строку слева направо и отсчитывать +1 на каждый x и -1 на каждый y, то конечное y станет первым y, на котором счёт достигнет 0. Например,  соответствует выражениям со сбалансированными круглыми скобками.
 * , где множество — класс символов, см. описание выше. Данный атом имеет нулевую длину и соответствует границе между символами, один из которых принадлежит данному классу, а второй — нет; при этом начало и конец строки считаются символами . В Lua 5.1 данная возможность не документирована, однако работает так же, как в версии 5.2.

Образец
Образец — это строка, составленная из атомов образцов.

' ' в начале образца ограничивает соответствие появлением образца в начале строки. ' ' в конце образца ограничивает соответствие появлением образца в конце строки. В других местах ' ' (кроме как в начале классов символов) и ' ' (везде) специального значения не имеют и представляют сами себя.

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

Специальным случаем является, захватывающая текущую позицию в строке (число). Например, применив образец  к строке , получим две группы, содержащие 3 и 5.

В образце не может быть нулевых байтов (ASCII NUL), вместо них надо использовать.

Библиотека table
Большинство функций библиотеки предполагают, что таблица — последовательность. Функции,   и   могут быть доступны, но устарели, используйте циклы с  , циклы   с ipairs и оператор длины.

table.concat
Для последовательности, содержащей строки и числа, возвращает.

По умолчанию,  ,. Если  задано больше , возвращает пустую строку.

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

Элементы до  сдвигаются; см. для описания того, что будет, если это не последовательность.

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

table.remove
Убирает из таблицы  элемент с индексом  ; если есть последующие элементы, сдвигает их, чтобы заполнить пропуск. Возвращает значение убранного элемента. По умолчанию, поэтому   удаляет последний элемент.

Элементы до  сдвигаются; см. для описания того, что будет, если это не последовательность.

table.sort
Сортирует заданную таблицу в указанном порядке от  до. Если задан параметр, он должен быть функцией, принимающей два элемента таблицы и возвращающей true, если первый меньше второго (т. е.   станет истиной после сортировки). Если  не задан, применяется стандартный оператор Lua.

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

Библиотеки Scribunto
Все библиотеки Scribunto размещены в таблице.

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

mw.clearLogBuffer
Стирает все данные, записанные.

mw.clone
Делает глубинную копию значения. Все таблицы с их метатаблицами пересоздаются с нуля. Тем не менее функции остаются теми же самыми.

mw.executeFunction
Создаёт копию объекта фрейма и вызывает функцию с ней в качестве параметра, после чего применяет  ко всем результатам, конкатенирует их (без разделителя) и возвращает получившуюся строку.

Замечание: в отладочной консоли не будет правильно работать, так как там нет объекта фрейма, который можно бы было скопировать.

mw.executeModule
Выполняет функцию в среде-«песочнице»; функция не может ничего изменить в текущей среде, кроме как за счёт побочных эффектов существующих замыканий.

Название "executeModule" объясняется тем, что эта самая функция применяется после загрузки модуля из пространства имён.

mw.getCurrentFrame
Возвращает текущий объект фрейма.

mw.getLogBuffer
Возвращает как строку данные, записанные.

mw.incrementExpensiveFunctionCount
увеличивает на единицу число "тяжёлых функций парсера" и выдаёт исключение, если ограничение превышено (see $wgExpensiveParserFunctionLimit).

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

работает как, но со следующими отличиями:
 * Загружаемый модуль выполняется один раз на всю страницу, а не на каждый вызов через.
 * Загружаемый модуль не попадает в.
 * Значение, возвращаемое модулем, должно быть таблицей. Другие типы данных не поддерживаются.
 * Возвращаемая таблица и все её подтаблицы может содержать только логические значения, числа, строки и другие таблицы. Другие типы данных, т. е. функции, не разрешены.
 * Возвращаемая таблица (и все её подтаблицы) не может иметь метатаблиц.
 * Все ключи таблиц могут быть только логическими, числовыми или строковыми.
 * Таблица, которую на самом деле возвращает, имеет метаметоды, предоставляющие доступ только для чтения к таблице, возвращённой модулем. Поскольку непосредственно в первой таблице данные не содержатся, то, хотя   и  будут работать, другие методы, включая  ,   и функции библиотеки table, правильно работать не будут.

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

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

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

mw.logObject
Представляет  в читаемом для человека виде и помещает результат в буфер лога. Если задан, он будет помещён в буфер со знаком равенства перед данной строкой (т. е. в лог пойдёт  ).

Объект фрейма
Объект фрейма — это интерфейс к параметрам, переданным  и парсеру.

frame.args
frame.args — таблица, через которую происходит доступ к аргументам, переданным через фрейм. К примеру, если вызвать модуль из викитекста с помощью конструкции

Тогда  вернёт "arg1",   — "arg2", а   (как и  ) — "arg3". Можно также поместить список аргументов в итератор с помощью  или.

Заметьте, что всем полученным через frame.args значениям присваивается строковый тип. Их можно преобразовать в числа через. Ключам же, по возможности присваивается числовой тип, в том числе если имя параметра указано явно. Например, при вызове в frame.args записываются значения "1" и "2", сопоставленные с ключами 1 и 2, а не 1 и "2".

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

Для увеличения быстродействия, frame.args — метатаблица, а не таблица значений. Значения аргументов запрашиваются из MediaWiki при каждом вызове. Поэтому, многие методы таблиц не работают, включая,  , а также функции библиотеки table.

При вызове модуля через #invoke конструкции препроцессора, такие как вызовы шаблонов и аргументы в тройных фигурных скобках, разворачиваются до вызова модуля. Специальные теги, записанные в нотации XML, например, ,   или  , преобразуются в специальные маркеры разметки — строки, начинающиеся с символа забоя (ASCII 127), которые будут преобразованы в 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:

--      frame:callParserFunction{ name = 'ns', args = 0 } --  frame:callParserFunction{ name = '#tag', args = { 'nowiki', 'some text' } } frame:callParserFunction( '#tag', { 'nowiki', 'some text' } ) frame:callParserFunction( '#tag', 'nowiki', 'some text' ) frame:callParserFunction( '#tag:nowiki', 'some text' ) --  frame:callParserFunction{ name = '#tag:ref', args = { 'some text', name = 'foo', group = 'bar' } }

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:

-- This is roughtly equivalent to wikitext like --  frame:expandTemplate{ title = 'template', args = { '|' } } -- This is roughtly equivalent to wikitext like --  frame:expandTemplate{ title = 'template', args = { ' | ' } }

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

-- These are equivalent frame:extensionTag{ name = 'ref', content = 'some text', args = { name = 'foo', group = 'bar' } } frame:extensionTag( 'ref', 'some text', { name = 'foo', group = 'bar' } ) frame:callParserFunction{ name = '#tag:ref', args = { 'some text', name = 'foo', group = 'bar' } }

frame:getParent
, будучи вызванная из модуля, вызывающего текущий модуль с помощью, возвращает фрейм вызывающего модуля. Для модуля, вызывающего самого себя возвращает nil.

frame:expandTemplate
Используется синтаксический сахар именованных аргументов (см. Вызовы функций)

Функция предназначена для вставки шаблона. К примеру, вызов frame:expandTemplate{ title = 'template', args = { 'arg1', 'arg2', name = 'arg3' } } приведёт к тому же результату, что и вызов  внутри викитекста. Так же как и при вызове шаблона, пространство имён «шаблон» указывать не обязательно.

Учтите, что имя шаблона и аргументы не проходят препроцессинг при передаче в шаблон:

--Команда, приведённая ниже эквивалентна следующему викитексту: --  frame:expandTemplate{ title = 'template', args = { '|' } }

--Команда, приведённая ниже эквивалентна следующему викитексту: --  frame:expandTemplate{ title = 'template', args = { ' | ' } }

frame:newChild

 * Note the use of named arguments.

Создаёт новый Frame object — потомок текущего фрейма с необязательными аргументами и заглавием.

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

frame:preprocess
Указанные функции позволяют раскрыть викитекст в контексте фрейма, т.е. раскрыть шаблоны, функции парсера и переданные параметры, типа. Также специальные теги, записаны в нотации XML, наподобие,  ,  , или   заменяются на маркеры разметки, начинающиеся с символа забоя.

Чтобы раскрыть только один шаблон, лучше использовать конструкцию, которая будет работать быстрее, чем   а вероятность ошибки при передаче в параметрах символов викиразметки, таких как «|» будет меньше.

frame:getArgument
Данные конструкции позволяют получить аргумент в виде объекта, имеющего один метод —, возвращающий викитекст с развёрнутыми шаблонами, аргументами и т.д. Если аргумент не был передан, данные конструкции возвращают nil.

frame:newParserValue
Возвращает объект с единственным методом —, который в свою очередь возвращает результат, аналогичный.

frame:newTemplateParserValue
Возвращает объект с единственным методом,, который в свою очередь возвращает результат  , вызванной с указанными аргументами.

frame:argumentPairs
Аналогично. Оставлен для совместимости.

Language library
Language codes are described at Language code.

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

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.getContentLanguage
Returns a new language object for the wiki's default content language.

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

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

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.

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.

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.

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

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

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 server's local time rather than in UTC.

The format string and supported values for  are identical to those for the #time parser function from Extension:ParserFunctions. Note that backslashes may need to be doubled in the Lua string where they wouldn't in wikitext:

-- This outputs a newline, where would output a literal "n" lang:formatDate( '\n' ) -- This outputs a literal "n", where would output a backslash -- followed by the month number. lang:formatDate( '\\n' ) -- This outputs a backslash followed by the month number, where -- would output two backslashes followed by the month number. lang:formatDate( '\\\\n' )

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 Help:Magic words and FAQ 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 Help:Magic words.

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

The possible values for  and   are language-dependent, see Help:Magic words and 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.

Библиотека message
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   are methods of a message object (see  ).

mw.message.new
Creates a new message object for the given message.

The message object has no properies, 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 properies, 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 properies, 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.

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:title
Specifies the title to use when processing the message; this affects magic words like  and. The value may be nil (to use the default), a string, or a table with a  field (i.e. a Title object).

The default is the title of the page being parsed.

Returns the  object, to allow for call chaining.

mw.message:parse


Parses the message to HTML, and returns that text as a string.

Note this is not likely to be extremely useful, as  must return wikitext.

mw.message:parseAsBlock


Parses the message to HTML, and returns that text as a string. The result is always enclodes in a block-level tag.

Note this is not likely to be extremely useful, as  must return wikitext.

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

mw.message:text
Processes parameters, templates transclusions, parser functions, and such, and returns the resulting wikitext.

mw.message:escaped
Processes parameters, templates transclusions, parser functions, and such. Except within raw parameters, any,  ,  ,  , and   are replaced by the corresponding HTML entities.

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 exists 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 $wgScriptPath.

mw.site.server
The value of $wgServer.

mw.site.siteName
The value of $wgSitename.

mw.site.stylePath
Значение.

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.
 * views: Number of views in the wiki. Not available if $wgDisableCounters is set.
 * 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.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

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

mw.title.new


Creates a new title object. The expensive function count will be incremented if the title object created is not for the current page and is not for a title that has already been loaded.

If a number  is given, an object is created for the title with that page_id. If the page_id does not exist, returns nil.

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. This function is expensive under the same conditions as.

Note that  will create an object for the page Module:Foo, while   will create an object for the page Template:Module:Foo.

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


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

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

Библиотека text
Библиотека text предоставляет некоторые популярные функции для работы с текстом, отсутствующие в библиотеке string.

mw.text.decode
Заменяет ссылки HTML в строке соответствующими символами. Если  пропущен или false, из именованных мнемоник опознаются только '&amp;lt;', '&amp;gt;', '&amp;amp;', '&amp;quot;' и '&amp;nbsp;'. Иначе подгружается список мнемоник HTML5 из функции PHP [//www.php.net/get_html_translation_table ].

mw.text.encode
Заменяет символы строки &-последовательностями HTML. Символы '<', '>', '&', '"' и неразрывный пробел заменяются соответствующими мнемониками, все остальные — цифровыми ссылками.

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

mw.text.listToText
Объединяет список в стиле предложения. Другими словами, это как, но с другим разделителем перед последним элементом.

Разделитель по умолчанию берётся из MediaWiki:comma-separator на языке содержимого вики, а союз по умолчанию MediaWiki:and, конкатенированный с MediaWiki:word-separator.

Примеры при значениях сообщений по умолчанию:

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 immdiately after a newline: '#', '*', ':', ';'
 * The following additional sequences: "://", "ISBN ", "RFC "

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
Убирает пробелы и другие символы из начала и конца строки.

If  is supplied, it should be a string as appropriate to go inside brackets in a Lua 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:

-- Returns "foobarbaz" mw.text.truncate( "foobarbaz", 9 ) -- Returns "fooba..." mw.text.truncate( "foobarbaz", 5 ) -- Returns "...arbaz" mw.text.truncate( "foobarbaz", -5 ) -- Returns "foo..." mw.text.truncate( "foobarbaz", 6, nil, true ) -- Returns "foobarbaz", because that's shorter than "foobarba..." mw.text.truncate( "foobarbaz", 8 )

mw.text.unstrip
Заменяет маркеры фрагментов MediaWiki соответствующим текстом. Заметьте, что содержимое маркера не обязательно соответствует вводу и не обязательно соответствует окончательному виду на странице.

Note that strip markers are typically used for a reason, and replacing them in Lua rather than allowing the parser to do so at the appropriate time may break things.

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

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

mw.uri.decode
Percent-decodes the string. The default type, "QUERY", decodes '+' to space; "PATH" does not perform any extra decoding; and "WIKI" 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 a 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.

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
Библиотека ustring предназначена быть прямой реализацией библиотеки string во всём, кроме того, что оперирует на строках в кодировке UTF-8, а не в однобайтовой.

Большинство функций вызовут ошибку, если строка не соответствует правилам UTF-8; исключения отмечены.

mw.ustring.maxPatternLength
Максимально разрешённая длина образца в байтах.

mw.ustring.maxStringLength
Максимально разрешённая длина строки в байтах.

mw.ustring.byte
Возвращает отдельный байт; полностью идентична.

mw.ustring.byteoffset
Возвращает смещение в байтах отдельного символа в строке. По умолчанию  и   оба равны 1. может быть отрицательным для отсчёта с конца строки.

Символ для  — это первый символ, начинающийся не раньше байта  ; символ для   — это первый символ, начинающийся не позже байта. (То есть это может быть один и тот же символ). Большие и меньшие значения  обрабатываются в соответствии с этим.

mw.ustring.char
Подобна, но числа — это коды Юникода, а не значения байтов.

mw.ustring.codepoint
Подобна, но возвращаемые значения — коды Юникода, а смещения указываются в символах, а не в байтах.

mw.ustring.find
Подобна, но образцы интерпретируются как образцы ustring, а   задаёт смещение в символах, а не в байтах.

mw.ustring.format
Идентично. Длины и точности для строк выражаются в байтах, а не в чём-либо ещё.

mw.ustring.gcodepoint
Возвращает три значения для итератора по символам Юникода в строке. По умолчанию, а. Предназначено для итераторной формы :

mw.ustring.gmatch
Похожа на, но образцы интерпретируются как образцы ustring.

mw.ustring.gsub
Подобна string.gsub, но образцы интерпретируются как образцы ustring.

mw.ustring.isutf8
Возвращает логическое значение, проверяя, является ли строка корректно кодированным UTF-8.

mw.ustring.len
Возвращает длину строки в символах, или, если строка — не корректный UTF-8.

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
Подобна, но смещения задаются в символах, а не в байтах.

mw.ustring.toNFC
Приводит строку к форме нормализации C (каноническая композиция, превращает все стандартные комбинации диакритики в один символ). Возвращает  с некорректного UTF-8.

mw.ustring.toNFD
Приводит строку к форме нормализации D (каноническая декомпозиция, все диакритические знаки становятся доступны как отдельный символ). Возвращает  с некорректного 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
Образцы для функций библиотеки ustring используют тот же синтаксис, что и образцы string. Основное отличие в том, что классы символов переопределены с позиций Unicode character properties:
 *  : represents all characters with General Category "Letter".
 *  : represents all characters with General Category "Control".
 *  : represents all characters with General Category "Decimal Number".
 *  : 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.

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

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

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.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 of that   object is not.

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

function myLibrary.new local obj = {} local checkSelf = libraryUtil.makeCheckSelfFunction( 'myLibrary', 'obj', obj, 'myLibrary object' ) function obj:method checkSelf( self, 'method' ) end function obj:method2 checkSelf( self, 'method2' ) end return obj end

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

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

Note that the bit32 library contains the same operations as "luabit.bit", and the operations in "luabit.hex" may be performed using  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.

Библиотеки расширений
Следующие расширения MediaWiki поставляют дополнительные библиотеки Scribunto:


 * WikibaseClient – см. Extension:WikibaseClient/Lua(англ.; рус.)

Planned Scribunto libraries
These libraries are planned, or are in Gerrit pending review.


 * (none at this time)

Differences from standard Lua
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.

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.

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

local object = {} local php function object.setupInterface( options ) -- Remove setup function object.setupInterface = nil -- Copy the PHP callbacks to a local variable, and remove the global php = mw_interface mw_interface = nil -- Do any other setup here -- Install into the mw global mw = mw or {} mw.ext = mw.ext or {} mw.ext.name = object -- Indicate that we're loaded package.loaded['mw.ext.name'] = object end return object

The module in  (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.

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

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

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