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-subpage-name: Устанавливает имя подстраницы документации. Указанные тут подстраницы будут интерпретироваться как викитекст, а не код Lua, и их нельзя будет вызывать через . По умолчанию.
 * scribunto-doc-subpage-does-not-exist: Сообщение, показываемое, когда страницы нет. Имя подстраницы подставляется через . По умолчанию пусто.
 * scribunto-doc-subpage-show: Сообщение, показываемое, когда страница документации есть. Имя подстраницы подставляется через . По умолчанию включение страницы документации.
 * scribunto-doc-subpage-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 реализована хвостовая рекурсия: если список выражений состоит из ровно одного выражения — вызова функции, текущий стековый кадр будет использоваться по новой для вызова той же функции. Это влияет на функции, оперирующие со стеком вызовов, такие, как  и.

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

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

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

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

Операторы объявления функций
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
Returns three values: an iterator function (next or a work-alike), the table, and nil. This is intended for use in the iterator form of :

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

This will iterate over the key-value pairs in  just as next would; see the documentation for next for restrictions on modifying the table during traversal.

The standard behavior may be overridden by providing a __pairs метаметод. If that metamethod exists, the call to pairs will return the three values returned by  instead.

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
This is equivalent to  except that it ignores any __index метаметод.

rawset
This is equivalent to  except that it ignores any __newindex метаметод.

select
If  is a number, returns all arguments in   after that index. If  is the string '#', returns the count of arguments in.

In other words,  is something roughly like the following except that it will work correctly even when   contains nil values (see documentation for # and unpack for the problem with nils).

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 library
In all string functions, the first character is at position 1, not position 0 as in C, PHP, and JavaScript. Indexes may be negative, in which case they count from the end of the string: position -1 is the last character in the string, -2 is the second-last, and so on.

The string library assumes one-byte character encodings. It cannot handle Unicode characters. To operate on Unicode strings, use the corresponding methods in the Scribunto Ustring library.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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
Looks for the first match of  in the string. If it finds one, then  returns the captures from the pattern; otherwise it returns nil. If  specifies no captures, then the whole match is returned.

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

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

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

string.sub
Returns the substring of  that starts at   and continues until  ;   and   can be negative. If  is nil or omitted, -1 is used.

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

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

Patterns
Note that Lua's patterns are similar to regular expressions, but are not the same. In particular, note the following differences from regular expressions and PCRE:
 * The quoting character is percent, not backslash.
 * Dot always matches all characters, including newlines.
 * No case-insensitive mode.
 * No alternation (the  operator).
 * Quantifiers (, ,  , and  ) may only be applied to individual characters or character classes, not to capture groups.
 * The only non-greedy quantifier is, which is equivalent to PCRE's   quantifier.
 * No generalized finite quantifier (e.g. the  quantifier in PCRE).
 * The only zero-width assertions are  and  ; assertions such as PCRE's   or   are not present.

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


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

Pattern items
A pattern item can be


 * a single character class, which matches any single character in the class;
 * a single character class followed by ' ', which matches 0 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence;
 * a single character class followed by ' ', which matches 1 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence;
 * a single character class followed by ' ', which also matches 0 or more repetitions of characters in the class. Unlike ' ', these repetition items will always match the shortest possible sequence;
 * a single character class followed by ' ', which matches 0 or 1 occurrence of a character in the class;
 * , for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below);
 * , where x and y are two distinct characters; such item matches strings that start with x, end with y, and where the x and y are balanced. This means that, if one reads the string from left to right, counting +1 for an x and -1 for a y, the ending y is the first y where the count reaches 0. For instance, the item  matches expressions with balanced parentheses.

Pattern
A pattern is a sequence of pattern items.

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

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

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

A pattern cannot contain embedded zero bytes (ASCII NUL). Use  instead.

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

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

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

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

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

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

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

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

function table.maxn( table ) local maxn, k = 0, nil repeat k = next( table, k ) if type( k ) == 'number' and k > maxn then maxn = k        end until not k    return maxn end

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

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

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

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