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 : This is used when assigning a key to a table  where   would return nil. If the value of this field is a table, the assignment will be repeated in that table, i.e.   (which may invoke that table's metatable's __newindex). If the value of this field is a function, the function will be called as  . The rawset function bypasses this metamethod.
 * __call : This is used when function call syntax is used on a table, . The value must be a function, which is called as something like.
 * __mode : This is used to make tables holding weak references. The value must be a string. By default, any value that is used as a key or as a value in a table will not be garbage collected. But if this metafield contains the letter 'k', keys may be garbage collected if there are no non-weak references, and if it contains 'v' values may be; in either case, both the corresponding key and value are removed from the table. Note that behavior is undefined if this field is altered after the table is used as a metatable.

Other metatable fields include: † For binary operators, Lua looks first at the left argument's metatable (if any) then the right's when looking for a metamethod to use. ‡ For relational operators, the metamethod is only used if the same function is specified in both arguments' metatables. Different anonymous functions, even with identical body and closure, may not be considered the same. * __metatable affects both getmetatable and setmetatable
 * __add†
 * __sub†
 * __mul†
 * __div†
 * __mod†
 * __pow†
 * __unm
 * __concat†
 * __eq‡
 * __lt‡
 * __le‡
 * __pairs
 * __ipairs
 * __metatable*
 * __tostring

Note: In Lua, all strings also share a single metatable, in which __index refers to the  table. This metatable is not accessible in Scribunto, nor is the referenced  table; the string table available to modules is a copy.

Переменные
Variables are places that store values. There are three kinds of variables in Lua: global variables, local variables, and table fields.

A name represents a global or local variable (or a function argument, which is just a kind of local variable). Variables are assumed to be global unless explicitly declared as local using the  keyword. Any variable that has not been assigned a value is considered to have a nil value.

Global variables are stored in a standard Lua table called an environment; this table is often available as the global variable. It is possible to set a metatable for this global variable table; the __index and __newindex metamethods will be called for accesses of and assignments to global variables just as they would for accesses of and assignments to fields in any other table.

The environment for a function may be accessed using the getfenv function and changed using the setfenv function; in Scribunto, these functions are severely restricted if they are available at all.

Local variables are lexically scoped; see Local variable declarations for details.

Выражения
An expression is something that has values: literals (numbers, strings, true, false, nil), anonymous function declarations, table constructors, variable references, function calls, the vararg expression, expressions wrapped in parentheses, unary operators applied to expressions, and expressions combined with binary operators.

Most expressions have one value; function calls and the vararg expression can have any number. Note that wrapping a function call or vararg expression in parentheses will lose all except the first value.

Expression lists are comma-separated lists of expressions. All except the last expression are forced to one value (dropping additional values, or using nil if the expression has no values); all values from the last expression are included in the values of the expression list.

Арифметические операторы
Lua supports the usual arithmetic operators: addition, subtraction, multiplication, division, modulo, exponentiation, and negation.

When all operands are numbers or strings for which tonumber returns non-nil, the operations have their usual meaning.

If either operand is a table with an appropriate metamethod, the metamethod will be called.

Операторы сравнения
The relational operators in Lua are,  ,  ,  ,  , and. The result of a relational operator is always a boolean.

Equality first compares the types of its operands; if they are different, the result is false. Then it compares the values: nil, boolean, number, and string are compared in the expected manner. Functions are equal if they refer to the exact same function object;  will return false, as it is comparing two different anonymous functions. Tables are by default compared in the same manner, but this may be changed using the __eq metamethod.

Inequality is the exact negation of equality.

For the ordering operators, if both are numbers or both are strings, they are compared directly. Next, metamethods are checked: If the necessary metamethods are not available, an error is raised.
 * uses __lt
 * uses __le if available, or if __lt is available then it is considered equivalent to
 * is considered equivalent to
 * is considered equivalent to

Логические операторы
The logical operators are,  , and. All use the standard interpretation where nil and false are considered false and anything else is considered true.

For, if the left operand is considered false then it is returned and the second operand is not evaluated; othewise the second operand is returned.

For, if the left operand is considered true then it is returned and the second operand is not evaluated; othewise the second operand is returned.

For, the result is always true or false.

Note that  and   short circuit. For example,  will only call   if   returns false or nil as its first value.

Оператор конкатенации
The concatenation operator is two dots, used as. If both operands are numbers or strings, they are converted to strings and concatenated. Otherwise if a __concat metamethod is available, it is used. Otherwise, an error is raised.

Note that Lua strings are immutable and Lua does not provide any sort of "string builder", so a loop that repeatedly does  will have to create a new string for each iteration and eventually garbage-collect the old strings. If many strings need concatenating, it may be faster to use string.format or to insert all the strings into a sequence and use table.concat at the end.

Оператор длины
The length operator is, used as. If  is a string, it returns the length in bytes. If  is a sequence table, it returns the length of the sequence.

If  is a table that is not a sequence, the   may return any value N such that a[N] is not nil and a[N+1] is nil, even if there are non-nil values at higher indexes. For example,

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


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

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

Вызовы функций
Lua function calls look like those in most other languages: a name followed by a list of arguments in parentheses:

func( exp-list )

As is usual with expression lists in Lua, the last expression in the list may supply multiple argument values.

If the function is called with fewer values in the expression list than there are arguments in the function definition, the extra arguments will have a nil value. If the expression list contains more values than there are arguments, the excess values are discarded. It is also possible for a function to take a variable number of arguments; see Function declarations for details.

Lua also allows direct calling of a function return value, i.e. . If an expression more complex than a variable access is needed to determine the function to be called, a parenthesized expression may be used in place of the variable access.

Lua has syntactic sugar for two common cases. The first is when a table is being used as an object, and the function is to be called as a method on the object. The syntax

table:name( exp-list )

is exactly equivalent to

table.name( table, exp-list )

The second common case is Lua's method of implementing named arguments by passing a table containing the name-to-value mappings as the only positional argument to the function. In this case, the parentheses around the argument list may be omitted. This also works if the function is to be passed a single literal string. For example, the calls

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

are equivalent to

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

These may be combined; the following calls are equivalent:

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

Объявления функций
The syntax for function declaraion looks like this:

function ( var-list ) block end

All variables in var-list are local to the function, with values assigned from the expression list in the function call. Additional local variables may be declared inside the block.

When the function is called, the statements in block are executed after local variables corresponding to var-list are created and assigned values. If a return statement is reached, the block is exited and the values of the function call expression are those given by the return statement. If execution reaches the end of the function's block without encountering a return statement, the result of the function call expression has zero values.

Lua functions are lexical closures. A common idiom is to declare "private static" variables as locals in the scope where the function is declared. For example,

-- This returns a function that adds a number to its argument function makeAdder( n ) return function( x ) -- The variable n from the outer scope is available here to be added to x        return x + n     end end local add5 = makeAdder( 5 ) mw.log( add5( 6 ) ) -- prints 11

A function may be declared to accept a variable number of arguments, by specifying  as the final item in the var-list:

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

Within the block, the varargs expression  may be used, with the result being all the extra values in the function call. For example,

local join = function ( separator, ... ) -- get the extra arguments as a table local args = { ... }    -- get the count of extra arguments, correctly local n = select( '#', ... ) return table.concat( args, separator, 1, n ) end join( ', ', 'foo', 'bar', baz' ) -- returns the string "foo, bar, baz"

The select function is designed to work with the varargs expression; in particular,  should be used instead of   to count the number of values in the varargs expression.

Lua provides syntactic sugar to combine function declaraion and assignment to a variable; see Function declaration statements for details.

Note that this will not work:  local factorial = function ( n ) if n <= 2 then return n   else return n * factorial( n - 1 ) end end Since the function declaration is processed before the local variable assignment statement is complete, "factorial" inside the function body refers to the (probably undefined) global variable of that name. This problem may be avoided by declaring the local variable first and then assigning it in a subsequent statement.

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

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

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

Присваивание
The variable-list is a comma-separated list of variables; the expression-list is a comma-separated list of one or more expressions. All expressions are evaluated before any assignments are performed, so  will swap the values of a and b.

Объявление локальных переменных
Local variables may be declared anywhere within a block. The first form, without an expression list, declares the variables but does not assign a value so all variables have nil as a value. The second form assigns values to the local variables, as described in Assignments above.

Note that visibility of the local variable begins with the statement after the local variable declaration. So a declaration like  declares a local variable x and assigns it the value of x from the outer scope. The local variable remains in scope until the end of the innermost block containing the local variable declaration.

Управляющие конструкции
The while statement repeats a block as long as an expression evaluates to a true value.

The repeat statement repeats a block until an expression evaluates to a true value. Local variables declared inside the block may be accessed in the expression.

The first form of the for loop will declare a local variable, and repeat the block for values from exp1 to exp2 adding exp3 on each iteration. exp3 may be omitted, in which case 1 is used. All expressions are evaluated once before the loop is started.

This form of the for loop is roughly equivalent to

except that the variables var, limit, and step are not accessible anywhere else. Note that the variable name is local to the block; to use the value after the loop, it must be copied to a variable declared outside the loop.

The second form of the for loop works with iterator functions. As in the first form, the exp-list is evaluated only once before beginning the loop.

This form of the for loop is roughly equivalent to

do    local func, static, var = exp-list while true do        local var-list = func( static, var ) var = var1 -- var1 is the first variable in var-list if var == nil then break end block end end

except that again the variables func, static, and var are not accessible anywhere else. Note that the variables in var-list are local to the block; to use them after the loop, they must be copied to variables declared outside the loop.

Often the exp-list is a single function call that returns the three values. If the iterator function can be written so it only depends on the parameters passed into it, that would be the most efficient. If not, Programming in Lua suggests that a closure be preferred to returning a table as the static variable and updating its members on each iteration.

Executes block1 if exp1 returns true, otherwise executes block2 if exp2 returns true, and block3 otherwise. The  portion may be omitted, and the   portion may be repeated or omitted as necessary.

The return statement is used to return values from a function or a chunk (which is just a function). The expression-list is a comma-separated list of zero or more expressions.

Lua implements tail calls: if expression-list consists of exactly one expression which is a function call, the current stack frame will be reused for the call to that function. This has implication for functions that deal with the call stack, such as  and.

The return statement must be the last statement in its block. If for some reason a return is needed in the middle of a block, an explicit block  may be used.

The break statement is used to terminate the execution of a while, repeat, or for loop, skipping to the next statement after the loop.

The break statement must be the last statement in its block. If for some reason a break is needed in the middle of a block, an explicit block  may be used.

ВЫзов функции как оператор
A function call may be used as a statement; in this case, the function is being called only for any side effects it may have (e.g. mw.log logs values) and any return values are discarded.

Операторы объявления функций
Lua provides syntactic sugar to make declaring a function and assigning it to a variable more natural. The following pairs of declaraions are equivalent

-- Basic declaration function func( var-list ) block end func = function ( var-list ) block end

-- Local function local function func( var-list ) block end local func; func = function ( var-list ) block end

-- Function as a field in a table function table.func( var-list ) block end table.func = function ( var-list ) block end

-- Function as a method in a table function table:func( var-list ) block end table.func = function ( self, var-list ) block end

Note the colon notation here parallels the colon notation for function calls, adding an implicit argument named "self" at the beginning of the arguments list.

Error handling
Errors may be "thrown" using the error and assert functions. To "catch" errors, use pcall or xpcall. Note that certain internal Scribunto errors cannot be caught in Lua code.

Garbage collection
Lua performs automatic memory management. This means that you have to worry neither about allocating memory for new objects nor about freeing it when the objects are no longer needed. Lua manages memory automatically by running a garbage collector from time to time to collect all dead objects (that is, objects that are no longer accessible from Lua) and objects that are only reachable via weak references. All memory used by Lua is subject to automatic management: tables, functions, strings, etc.

Garbage collection happens automatically, and cannot be configured from within Scribunto.