Расширение:Scribunto/Справочник Lua

Это руководство по Lua в том виде, в каком он используется в MediaWiki с расширением Scribunto . Оно частично основано на справочнике Lua 5.1, доступном по лицензии MIT.

Введение

Первые шаги

На любом вики-проекте Медиавики с включенным Scribunto, создайте страницу с названием начинающимся с «Module:», например «Module:Bananas». Cкопируйте следующий текст в новую страницу:

local p = {} --«p» — сокращение от «package» (т. е. пакет)

function p.hello( frame )
    return "Hello, world!"
end

return p

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

{{#invoke:Bananas|hello}}

Кроме того вам следует заменить «Bananas» на ваше название модуля. Это вызовет функцию «hello», экспортированную из этого модуля. {{#invoke:Bananas|hello}} будет заменен текстом, который вернула функция, в данном случае «Hello, world!».

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

Структура модуля

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

Все функции, не добавленные в эту таблицу, через {{#invoke:}} доступны не будут, неважно, локальные они или глобальные. Однако глобальные функции и переменные могут быть доступны из других модулей, загруженных с помощью require(). Как правило, хорошим стилем программирования модулей считается объявление всех функций и переменных локальными.

Доступ к параметрам из вики-текста

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

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

Возвращаемый текст

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

На этом этапе парсинга страницы шаблоны уже развернуты, функции парсера и теги расширений уже обработаны, а также пред-сохранённые преобразования (т.е. тильда-подписи, pipe-конвейеры и т.д.) уже выполнены. Поэтому модуль не может использовать эти функции в своем выводимом тексте. Например, если модуль возвращает "Hello, [[world]]! {{welcome}}", на странице будет отображаться «Hello, world! {{welcome}}».

С другой стороны, подстановка выполняется на более ранней стадии обработки, поэтому код {{subst:#invoke:}} не будет обработан вместе с остальными подстановками. Неудачная попытка подстановки останется в вики-тексте как есть и будет обработана лишь при следующей правке. Таких случаев следует по возможности избегать.

Документация модуля

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

Страницы документации модулей могут быть настроены с помощью следующих системных сообщений :

• scribunto-doc-page-name — Задаёт название страницы, используемой для документации. Название модуля (без префикса «Module:» или «Модуль:») передается как $1. Указанные здесь страницы будут интерпретироваться как викитекст, а не как исходный код Lua, если размещаются в пространстве имён модулей, и не могут использоваться с {{#invoke:}}. По умолчанию используется «Module:$1/doc», т. е. подстраница модуля «/doc». Обратите внимание, что функции парсера и другие элементы синтаксиса, включающие фигурные скобки, не могут использоваться в этом сообщении.
• scribunto-doc-page-does-not-exist — Сообщение отображается, когда страница документации не существует. Название страницы передаётся как $1. По умолчанию пустая строка.
• scribunto-doc-page-show — Сообщение отображается, когда страница документации существует. Название страницы передаётся как $1. По умолчанию используется включение страницы документации.
• scribunto-doc-page-header — Заголовок, отображаемый при просмотре самой страницы документации. Название описываемого модуля (с префиксом «Module:» или «Модуль:») передаётся как $1. По умолчанию просто отображается краткое объяснение, выделенное курсивом.

Обратите внимание, что модули не могут быть напрямую добавлены в категории; также им нельзя напрямую добавить интервики-ссылки. Категории и интервики-ссылки могут быть размещены на странице документации внутри тегов ‎<includeonly>...‎</includeonly>, где они будут применены к модулю во время включения страницы документации в страницу модуля.

Переименование или перемещение модулей

Чтобы переименовать или переместить модуль, воспользуйтесь ссылкой Переместить страницу на боковой панели «Инструменты». Вам понадобится переместить как сам модуль, так и подстраницу, содержащую его документацию.

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

return require [[Module:Foo]]

Замените Foo именем модуля, на который вы хотели бы создать перенаправление.

Язык Lua

Токены

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

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

• and
• break
• do
• else
• elseif
• end
• false
• for
• function
• if
• in
• local
• nil
• not
• or
• repeat
• return
• then
• true
• until
• while

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

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

• #
• %
• (
• )
• *
• +
• ,
• -
• --
• .
• ..
• ...
• /
• :
• ;
• <
• <=
• =
• ==
• >
• >=
• [
• ]
• ^
• {
• }
• ~=

Комментарии

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

-- Комментарий в Lua начинается с двойного дефиса и продолжается до конца строки.
--[[ Многострочные символьные строки (строковые литералы) и комментарии
     оформляются двойными квадратными скобками. ]]
--[=[ Комментарии, оформленные так, могут иметь другие вложенные --[[комментарии]]. ]=]
--[==[ Комментарии, похожие на этот, могут иметь другие
      --[===[ пространные --[=[комментарии,]=] --вложенные
        ]===] многократно, даже если все они
      --[[ неправильно оформлены широкими скобками! ]===]
  ]==]

Типы данных

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

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

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

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

nil

«nil» это тип данных nil, который существует для обозначения отсутствия значения.

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

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

Обратите внимание: Lua различает nil и отсутствие аргументов в определённых ситуациях. Например, tostring(nil) возвращает "nil", но tostring() выбрасывает ошибку, так как первый параметр обязателен. Это различие особенно важно для функции select().

boolean

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

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

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

string

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

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

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

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

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

-- Эта длинная строка
foo = [[
bar\tbaz
]]

-- эквивалентна этой, ограниченной кавычками
foo = 'bar\\tbaz\n'

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

number

Lua имеет только один числовой тип, который внутренне представлен как 64-битное значение с плавающей точкой двойной точности. В этом формате целые числа от -9007199254740991 (-2⁵³ + 1) до 9007199254740991 (2⁵³ - 1) могут быть представлены точно; большие числа и числа с дробной частью могут содержать ошибку округления.

В числовых константах в качестве десятичного разделителя используется точка (.), а разделители групп разрядов не используются, например, 123456.78. Также числа могут быть представлены с использованием экспоненциальной записи без пробелов, например, 1.23e-10, 123.45e20, или 1.23E+5. Целые числа могут быть представлены в шестнадцатеричном виде с использованием префикса 0x, например, 0x3A.

Несколько числовых значений обрабатываются особым образом:

• Положительная и отрицательная бесконечность, которые оцениваются как большие или меньшие, чем любое другое число, соответственно (кроме NaN - см. ниже). К ним можно получить доступ двумя способами: через библиотеку math, как math.huge и -math.huge, или с помощью числовых операций, таких как 1/0 и -1/0.
• Lua иногда различает 0 и -0 (см. IEEE 754 для получения дополнительной информации о нулях со знаком). 0 и -0 строго эквивалентны практически для всех целей, но ведут себя по-разному при выполнении небольшого числа числовых операций (например, 1/0 возвращает бесконечность, в то время как 1/-0 возвращает отрицательную бесконечность). Это различие также влияет на преобразование числа в строку (и наоборот).
• Положительный и отрицательный NaN (Not a Number). Константа не указана ни для одного из этих значений, но 0/0 равен отрицательному значению NaN. Обратите внимание, что оба NaN обладают уникальным качеством, заключающимся в том, что любое сравнение, в котором они участвуют, оценивает как false (что означает, что они даже не оцениваются как равные самим себе). Единственное практическое различие между ними заключается в преобразовании типа в string и из него (см. ниже).

Обратите внимание, что все числа (включая 0, -0, бесконечность и NaN) считаются true при преобразовании в логическое значение. В этом отличие от большинства других языков, где 0 обычно считается false. При преобразовании в строку конечные числа представляются в десятичном виде, или e-нотации если 10¹⁴ или больше (например, "1e+14"); бесконечность - это "inf" и "-inf"; а NaN - это "nan" и "-nan".

Known bug: the Lua interpreter will treat all instances of 0 and -0 as whichever of the two is encountered first when the script is compiled, which means that the return values of tostring(0), 1/-0 (and so on) are affected by where they occur in the code. This can cause unexpected results, particularly if all instances of 0 are converted to "-0" on return. If necessary, this can be circumvented by generating zero values using tonumber("0") and tonumber("-0"), which doesn't seem to cause or be affected by the issue. See [1].

table

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

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

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

Обращаться к полям таблицы можно с использованием формы записи с квадратными скобками, например, table[key]. Символьные ключи, если они соответствуют требованиям к именам, позволяют использовать запись с точкой, например, table.key, что эквивалентно записи table['key']. Если значением поля таблицы является функция, её вызов может быть осуществлён в форме записи с двоеточием; например, table:func( ... ), что соответствует table['func']( table, ... ) или table.func( table, ... ).

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

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

-- Создание таблицы
t = {}
t["foo"] = "foo"
t.bar = "bar"
t[1] = "один"
t[2] = "два"
t[3] = "три"
t[12] = "номер двенадцать"
t["12"] = "строка двенадцать"
t[true] = "true"
t[tonumber] = "да, даже функции могут быть ключами таблицы"
t[t] = "yes, a table may be a table key too. Even in itself."

-- Теперь создаём таблицу, в целом эквивалентную верхней
t2 = {
    foo = "foo",
    bar = "bar",
    "one",
    "two",
    [12] = "the number twelve",
    ["12"] = "the string twelve",
    "three",
    [true] = "true",
    [tonumber] = "yes, even functions may be table keys",
}
t2[t2] = "yes, a table may be a table key too. Even in itself."

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

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

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

function

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

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

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

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

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

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

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

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

return p

There is a strict limit of max 60 unique upvalues acessed inside a function. An upvalue is a value declared outside of a function and used inside it. As upvalues do count:

• variables (a table with many elements counts as one upvalue)
• functions (only those directly called from function in question, not their dependencies)

A violation of the limit can be triggered by a use of such a variable or function, not by its mere presence or availability. Repeated access to same upvalue does not exhaust the limit further.

Метатаблицы

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

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

Следующие поля метатаблицы влияют на саму таблицу:

__index

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

__newindex

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

__call

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

__mode

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

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

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

^† При использовании бинарных операций для выбора используемого метаметода Lua сначала смотрит на метатаблицу левого операнда (если она есть), а затем на метатаблицу правого операнда.

^‡ При использовании операций сравнения метаметод используется только в том случае, если одна и та же функция задана в метатаблицах обоих операндов. Разные анонимные функции, даже если у них одинаковы код и замыкание, могут не быть сочтены одинаковыми.

^* __metatable влияет как на getmetatable(), так на setmetatable()

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

Переменные

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

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

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

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

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

Выражения

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

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

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

Арифметические операции

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

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

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

Операция	Функция	Пример	Метаметод	Замечания
+	Сложение	a + b	__add
-	Вычитание	a - b	__sub
*	Умножение	a * b	__mul
/	Деление	a / b	__div	деление на ноль не является ошибкой; будут возвращены NaN или бесконечность
%	Остаток при делении	a % b	__mod	определяется как a % b == a - math.floor( a / b ) * b
^	Возведение в степень	a ^ b	__pow	допускается не целочисленный показатель степени
-	Отрицание	-a	__unm

Операции сравнения

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

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

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

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

• a < b использует __lt
• a <= b использует __le, если доступно, или __lt, если доступно, тогда это считается эквивалентным not ( b < a )
• a > b считается эквивалентным b < a
• a >= b считается эквивалентным b <= a

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

Логические операции

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

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

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

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

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

Операция конкатенации

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

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

Операция длины

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

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

-- Это не последовательность, так как aa[3] равно nil, а aa[4] — нет
a = { 1, 2, nil, 4 }

-- Этот вызов может вывести как 2, так и 4.
-- И результат вызова может стать другим, даже если таблица не изменялась.
mw.log( #a )

Приоритетность операций

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

1. ^
2. not # - (отрицание)
3. * / %
4. + - (вычитание)
5. ..
6. < > <= >= ~= ==
7. and
8. or

В пределах уровня приоритета, большинство бинарных операций левоассоциативно, т. е. a / b / c интерпретируется как (a / b) / c. Возведение в степень и конкатенация правоассоциативны, т. е. a ^ b ^ c интерпретируется как a ^ (b ^ c).

Вызовы функций

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Объявление функций

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

function nameoptional ( var-listoptional )
    блок
end

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

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

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

-- Эта функция возвращает функцию, прибавляющую число к своему аргументу
function makeAdder( n )
    return function( x )
        -- Переменная n из внешней области видимости доступна здесь для добавления к x
        return x + n
    end
end

local add5 = makeAdder( 5 )
mw.log( add5( 6 ) )
-- выводит 11

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

function nameoptional ( var-list, ... )
    блок
end
-- or
function nameoptional ( ... )
    блок
end

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

local join = function ( separator, ... )
    -- получить дополнительные аргументы в виде новой таблицы
    local args = { ... }
    -- правильно подсчитать количество дополнительных аргументов
    local n = select( '#', ... )
    return table.concat( args, separator, 1, n )
end

join( ', ', 'foo', 'bar', 'baz' )
-- возвращает строку "foo, bar, baz"

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

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

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

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

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

Состояния

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

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

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

Присваивание

список_переменных = список_выражений

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

Объявление локальных переменных

local список_переменных

local список_переменных = список_выражений

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

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

Управляющие конструкции

while выражение do блок end

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

repeat блок until выражение

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

for имя = выражение1, выражение2, выражение3 do блок end
for имя = выражение1, выражение2 do блок end

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

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

do
    local var, limit, step = tonumber( exp1 ), tonumber( exp2 ), tonumber( exp3 )
    if not ( var and limit and step ) then
        error()
    end
    while ( step > 0 and var <= limit ) or ( step <= 0 and var >= limit ) do
        local name = var
        block
        var = var + step
    end
end

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

for список_переменных in список_выражений do блок end

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

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

do
    local func, static, var = expression-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

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

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

if выражение1 then блок1 elseif выражение2 then блок2 else блок3 end

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

return список_выражений

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

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

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

break

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

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

В отличие от некоторых других языков, в Lua нет инструкции "continue" для циклов (т.е. инструкции для перехода к следующей итерации без полного прерывания цикла). Легко достичь того же эффекта, вложив блок repeat ... until true непосредственно в основной цикл, который будет выполняться только один раз для каждой итерации основного цикла (поскольку его условие всегда истинно). Использование break приведет только к завершению внутреннего цикла, что на практике приводит к продолжению основного цикла на следующей итерации. Если необходимо использовать break в основном цикле, просто объявите переменную (например: local flag = false), которая проверяется каждый раз при завершении внутреннего цикла, и присвойте ей true при необходимости завершении внешнего цикла.

Вызовы функций как инструкции

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

Операторы объявления функции

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

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

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

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

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

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

Обработка ошибок

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

Сборка мусора

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

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

Стандартные библиотеки

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

Основные функции

_G

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

foo = 1
mw.log( foo ) -- logs "1"
_G.foo = 2
mw.log( foo ) -- logs "2"
_G = {}       -- _G больше не указывает на таблицу глобальных переменных
_G.foo = 3
mw.log( foo ) -- still logs "2"

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

-- Вызвать функцию, имя которой хранится в переменной
_G[var]()

-- Записывать имена и строковые значения всех глобальных переменных
for k, v in pairs( _G ) do
   mw.log( k, v )
end

-- Записывать создание новых глобальных переменных
setmetatable( _G, {
    __newindex = function ( t, k, v )
         mw.log( "Creation of new global variable '" .. k .. "'" )
         rawset( t, k, v )
    end
} )

_VERSION

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

assert

assert( v, message, ... )

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

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

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

-- Это не проверяет наличие ошибок
local result1, result2, etc = func( ... )

-- Это работает так же, но проверяет наличие ошибок
local result1, result2, etc = assert( func( ... ) )

error

error( message, level )

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

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

getfenv

getfenv( f )

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

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

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

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

getmetatable

getmetatable( table )

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

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

ipairs

ipairs( t )

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

for i, v in ipairs( t ) do
    -- process each index-value pair
end

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

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

next

next( table, key )

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

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

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

pairs

pairs( t )

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

for k, v in pairs( t ) do
    -- обрабатывать каждую пару ключ-значение
end

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

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

pcall

pcall( f, ... )

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

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

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

rawequal

rawequal( a, b )

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

rawget

rawget( table, k )

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

rawset

rawset( table, k, v )

Эта функция эквивалентна операции table[k] = v, но в отличие от неё игнорирует метаметод __newindex.

select

select( index, ... )

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

Note: unlike tables, lists of arguments (including the vararg expression ...) treat nil as a distinct value (see documentation for # and unpack for the problem with nil in tables). For example:

• select(2, "foo", "bar") returns "bar".
• select(2, "foo", nil, "bar", nil) returns nil, "bar", nil.
• select("#", "foo", "bar") returns 2.
• select("#", "foo", "bar", nil) returns 3.

Другими словами, select примерно похож на следующий код (за исключением того, что он также обрабатывает любые nil-аргументы после последнего не-nil аргумента):

function select( index, ... )
    local t = { ... }
    local maxindex = table.maxn( t )
    if index == "#" then
        return maxindex
    else
        return unpack( t, index, maxindex )
    end
end

setmetatable

setmetatable( table, metatable )

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

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

tonumber

tonumber( value, base )

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

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

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

tostring

tostring( value )

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

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

type

type( value )

Возвращает строку, указывающую тип value: "nil", "number", "string", "boolean", "table" или "function".

unpack

unpack( table, i, j )

Возвращает значения из заданной таблицы, примерно как делал бы это код table[i], table[i+1], ···, table[j]. Если эти параметры равны nil или не указаны, i считается равным 1, а j считается равным #table.

If the table does not have a value for a particular key, unpack will return nil for that value. For example, unpack({"foo", [3] = "bar"}, 1, 4) returns "foo", nil, "bar", nil.

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

xpcall

xpcall( f, errhandler )

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

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

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

Библиотека Debug

debug.traceback

debug.traceback( message, level )

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

Библиотека Math

math.abs

math.abs( x )

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

math.acos

math.acos( x )

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

math.asin

math.asin( x )

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

math.atan

math.atan( x )

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

math.atan2

math.atan2( y, x )

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

math.ceil

math.ceil( x )

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

math.cos

math.cos( x )

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

math.cosh

math.cosh( x )

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

math.deg

math.deg( x )

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

math.exp

math.exp( x )

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

math.floor

math.floor( x )

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

math.fmod

math.fmod( x, y )

Возвращает остаток от деления с остатком x на y. Например, вызов math.fmod( 10, 3 ) вернёт 1.

math.frexp

math.frexp( x )

Возвращает такие два значения m и e, что:

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

math.huge

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

math.ldexp

math.ldexp( m, e )

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

math.log

math.log( x )

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

math.log10

math.log10( x )

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

math.max

math.max( x, ... )

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

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

math.min

math.min( x, ... )

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

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

math.modf

math.modf( x )

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

math.pi

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

math.pow

math.pow( x, y )

Эквивалентно выражению x^y.

math.rad

math.rad( x )

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

math.random

math.random( m, n )

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

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

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

Обратите внимание, что могут быть получены неверные выходные данные, если m или n меньше −2147483648 или больше 2147483647, или если n - m больше 2147483646.

math.randomseed

math.randomseed( x )

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

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

math.randomseed( tonumber( mw.getContentLanguage():formatDate( "U" ) ) * 10000 + os.clock() * 10000 )

math.sin

math.sin( x )

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

math.sinh

math.sinh( x )

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

math.sqrt

math.sqrt( x )

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

math.tan

math.tan( x )

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

math.tanh

math.tanh( x )

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

Библиотека Os (функций операционной системы)

os.clock

os.clock()

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

os.date

os.date( format, time )

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

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

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

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

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

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

os.difftime

os.difftime( t2, t1 )

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

os.time

os.time( table )

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

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

Библиотека Package

require

require( modulename )

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

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

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

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

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

local p = {}

p.someDataValue = 'Привет!'

return p

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

local giving = require( "Module:Giving" )

local value = giving.someDataValue -- value теперь равно 'Привет!'

package.loaded

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

package.loaders

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

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

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

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

package.preload

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

package.seeall

package.seeall( table )

Задаёт $3 __index для table в таблице глобальных переменных _G.

Библиотека String

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

Предупреждение: Библиотека String использует однобайтовые кодировки символов. Она не может обрабатывать символы Юникода. Для работы со строками в Юникоде используйте соответствующие методы в библиотеки Ustring Scribunto.

string.byte

string.byte( s, i, j )

Если строка рассматривается как массив байтов, возвращает байтовые значения для s[i], s[i+1], ···, s[j]. Значением по умолчанию для i является 1; Значением по умолчанию для j является i. Идентично mw.ustring.byte().

string.char

string.char( ... )

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

local value = string.char( 0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x21 ) --value теперь равно 'Hello!'

См. аналогичную функцию mw.ustring.char(), которая использует символы Юникода, а не байты.

string.find

string.find( s, pattern, init, plain )

Ищет первое совпадение с шаблоном pattern в строке s. Если находит совпадение, то find возвращает смещения в строке s, где начинается и где заканчивается найденное вхождение; в противном случае возвращает nil. Если шаблон содержит захваты (группы), то при успешном совпадении захваченные значения также возвращаются после первых двух индексов.

Третий необязательный числовой аргумент init указывает, с какого индекса начинать поиск; его значение по умолчанию равно 1 и может быть отрицательным. Значение true в качестве четвертого необязательного аргумента plain отключает средства сопоставления с образцом (отключает регулярные выражения и шаблон становится обычной литеральной строкой), поэтому функция выполняет простую операцию "найти подстроку", при этом никакие символы в шаблоне pattern не считаются "волшебными" (регулярными).

Обратите внимание, что если задан plain, то также должен быть задан init.

См. аналогичную функцию mw.ustring.find(), расширенную, как описано в разделе шаблоны Ustring где смещение init указано в символах, а не в байтах.

string.format

string.format( formatstring, ... )

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

Форматирование строки использует ограниченное подмножество спецификаторов формата printf:

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

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

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

Аналогично mw.ustring.format().

string.gmatch

string.gmatch( s, pattern )

Возвращает функцию-итератор, которая при каждом вызове возвращает следующие захваты шаблона pattern из строки s. Если в шаблоне pattern не указаны захваты, то при каждом вызове создаётся полное совпадение с шаблоном.

Для этой функции ^ в начале шаблона не является магическим, поскольку это предотвратило бы повторение. Он обрабатывается как буквальный символ (литерал).

См. аналогичную функцию mw.ustring.gmatch(), для которой шаблон расширен, как описано в разделе шаблоны Ustring.

string.gsub

string.gsub( s, pattern, repl, n )

Возвращает копию строки s, в которой все (или первые n, если указано) вхождения шаблона pattern были изменены заменяющей строкой, указанной в repl (от англ. replace). Аргумент repl может быть строкой, таблицей или функцией. Функция gsub также возвращает в качестве своего второго значения общее количество произошедших совпадений (замен).

Если repl является строкой, то для замены используется ее значение. Символ % работает как экранирующий символ: любая последовательность в repl вида %n, где n от 1 до 9, обозначает значение n-я захваченная подстрока (группа). Последовательность %0 обозначает совпадение целого шаблона, а последовательность %% обозначает сам символ %.

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

Если repl является функцией, то эта функция вызывается каждый раз, когда происходит совпадение, со всеми захваченными подстроками, передаваемыми в качестве аргументов, по порядку; если шаблон не указывает никаких захватов (групп), то полное совпадение шаблона передаëтся в качестве единственного аргумента.

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

См. аналогичную функцию mw.ustring.gsub(), в которой шаблон расширен, как описано в разделе шаблоны Ustring.

string.len

string.len( s )

Возвращает длину строки в байтах. Символы ASCII NUL (нулевой байт) не приводят к ошибке. Эквивалентно #s.

См. аналогичную функцию mw.ustring.len(), которая использует символы Юникода, а не байты.

string.lower

string.lower( s )

Возвращает копию строки со всеми прописными буквами ASCII, заменëнными на строчные. Все остальные символы будут оставлены без изменений.

См. аналогичную функцию mw.ustring.lower(), в которой преобразуются все символы с определениями верхнего регистра в нижний регистр в Юникоде.

string.match

string.match( s, pattern, init )

Ищет первое совпадение шаблона pattern в строке. Если оно найдено, то функция match возвращает найденные данные (сколько захватов, столько и данных возвращается); в противном случае возвращает nil. Если в шаблоне pattern не указано никаких захватов (групп), то возвращается полное совпадение с шаблоном.

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

См. аналогичную функцию mw.ustring.match(), в которой шаблон расширен, как описано в разделе шаблоны Ustring, а смещение init указано в символах, а не в байтах.

string.rep

string.rep( s, n )

Возвращает строку, представляющую собой конкатенацию (объединение) n раз копий строк s. Идентично mw.ustring.rep().

string.reverse

string.reverse( s )

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

string.sub

string.sub( s, i, j )

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

Частные случаи: вызов string.sub(s,1,j) возвращает префикс s длиной j, а string.sub(s, -i) возвращает суффикс s длиной i.

См. аналогичную функцию mw.ustring.sub(), в которой смещениями (индексами) являются символы, а не байты.

string.ulower

string.ulower( s )

Аналогично mw.ustring.lower().

string.upper

string.upper( s )

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

См. аналогичную функцию mw.ustring.upper(), в которой преобразуются все символы со строчных букв в прописные в Юникоде.

string.uupper

string.uupper( s )

Аналогично mw.ustring.upper().

Шаблоны

Обратите внимание, что шаблоны Lua похожи на нотацию регулярных выражений, но не идентичны. В частности, обратите внимание на следующие отличия от регулярных выражений и Perl Compatible Regular Expressions (PCRE):

• В качестве символа экранирования используется процент (%), а не обратный слэш (\).

• Точка (.) всегда соответствует любым символам, включая перевод строки.

• Отсутствует регистронезависимый режим.

• Отсутствует перебор вариантов с помощью оператора |

• Квантификаторы (*, +, ? и -) могут применяться только к отдельным символам (литералам) и к символьным классам, но не к группам захвата.

• Единственным нежадным (минорным) квантификатором является -, аналог квантификатора *? из PCRE.

• Отсутствует обобщенные конечные квантификаторы (такие как {n,m} в PCRE).

• Единственными утверждениями нулевой ширины являются ^, $ и %f[set] «frontier»-паттерн; такие утверждения, как \b или (?=···) как в PCRE, отсутствуют.

• Сами шаблоны не распознают экранирование символов, таких как "\ddd". Однако, поскольку шаблоны являются строками, такого рода экранирования могут использоваться в строковых литералах, используемых для создания строк-шаблонов.

Также обратите внимание, что шаблон не может содержать встроенных нулевых байтов (ASCII NUL, "\0"). Вместо этого используйте %z.

Также см. раздел шаблоны Ustring, где описана аналогичная схема сопоставления с образцом с использованием символов Юникода.

Символьные классы

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

x	(где x не является одним из магических символов ^$()%.[]*+-?) представляет сам символ x.
.	(точка) Соответствует любому символу.
%a	Соответствует всем буквам ASCII.
%c	Соответствует всем управляющим символам ASCII.
%d	Соответствует всем цифрам.
%l	Соответствует всем строчным буквам ASCII.
%p	Соответствует всем знакам пунктуации.
%s	Соответствует всем пробельным символам ASCII.
%u	Соответствует всем заглавным буквам ASCII.
%w	Представляет все буквенно-цифровые символы ASCII. Обратите внимание, что этот класс не включает знак подчёркивания (_), в отличие от обычного класса \w в регулярных выражениях.
%x	Представляет все шестнадцатеричные цифры.
%z	Представляет ASCII NUL, нулевой байт.
%A	Все символы не в %a.
%C	Все символы не в %c.
%D	Все символы не в %d.
%L	Все символы не в %l.
%P	Все символы не в %p.
%S	Все символы не в %s.
%U	Все символы не в %u.
%W	Все символы не в %w.
%X	Все символы не в %x.
%Z	Все символы не в %z.
%y	(где y - любой не буквенно-цифровой символ) представляет символ y. Это стандартный способ экранирования магических символов. Любому знаку препинания (даже немагическому) может предшествовать символ '%', если он используется для представления в паттерне.
[set]	Представляет класс, который объединяет все символы в set. Диапазон символов можно задать, разделив конечные символы диапазона дефисом '-'. Все классы %y, описанные выше, также могут использоваться в качестве компонентов в set. Все остальные символы в set представляют самих себя. Например, [%w_] (или [_%w]) представляют все буквенно-цифровые символы плюс знак подчеркивания, а [0-7] представляет восьмеричные цифры. Чтобы включить в набор литерал дефис '-', используйте '%-', таким образом, [0-7%l%-] представляет собой восьмеричные цифры плюс строчные буквы плюс символ '-'. Взаимодействие между диапазонами и классами не определено. Следовательно, шаблоны, подобные [%a-z] или [a-%%], не имеют значения.
[^set]	Представляет исключение от set (кроме символов в классе set), где set интерпретируется, как указано выше.

Элементы шаблона

Элементом шаблона может быть

• литерал (одиночный символ класса), который соответствует любому отдельному символу в классе;
• одиночный символ класса, за которым следует '*', который соответствует 0 или более повторениям символов в классе. Эти элементы повторения всегда будут соответствовать максимально длинной последовательности;
• одиночный символ класса, за которым следует '+', который соответствует 1 или более повторениям символов в классе. Эти элементы повторения всегда будут соответствовать максимально длинной последовательности;
• одиночный символ класса, за которым следует '-', который также соответствует 0 или более повторениям символов в классе. В отличие от '*', эти элементы повторения всегда будут соответствовать самой короткой возможной последовательности;
• одиночный символ класса, за которым следует '?', что соответствует 0 или 1 вхождению символа в классе;
• %n, для n между 1 и 9; такой элемент соответствует подстроке, равной n-й захваченной строке (см. ниже);
• %bxy, где x и y - два разных символа; такой элемент соответствует строкам, которые начинаются с x, заканчиваются на y и где x и y сбалансированы. Это означает, что если читать строку слева направо, считая +1 для x и -1 для y, конечная цифра y будет первой цифрой y, где счетчик достигнет 0. Например, элемент %b() соответствует выражениям со сбалансированными круглыми скобками.
• %f[set], границы шаблона; такой элемент соответствует пустой строке в любой позиции таким образом, что следующий символ принадлежит set, а предыдущий символ не принадлежит set. Набор set интерпретируется так, как описано ранее. Начало и конец субъекта обрабатываются так, как если бы они были символом '\0'.
  Обратите внимание, что шаблоны frontier присутствовали, но не были задокументированы в Lua 5.1 и официально добавлены в Lua в 5.2. Реализация в Lua 5.2.1 не изменилась по сравнению с реализацией в 5.1.0.

Паттерн

Шаблон - это последовательность элементов.

Символ ^ в начале паттерна привязывает соответствие к началу строки субъекта. 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.

Захваты

Шаблон может содержать вложенные шаблоны, заключенные в круглые скобки; они описывают захваты (группы) . При успешном совпадении подстроки строки субъекта, которые соответствуют захватам, сохраняются ("захвачено") для использования в будущем. Захваты нумеруются в соответствии с их левыми круглыми скобками. Например, в шаблоне (a*(.)%w(%s*)) часть строки, соответствующая a*(.)%w(%s*), сохраняется в качестве первого захвата (и, следовательно, имеет номер 1); символ, соответствующий ., записывается с номером 2, а часть, соответствующая %s*, имеет номер 3.

Ссылки на захват могут использоваться в самой строке шаблона и отсылать к тексту, который был захвачен ранее в ходе сопоставления. Например, ([a-z])%1 будет соответствовать любой паре одинаковых строчных букв, в то время как ([a-z])([a-z])([a-z])[a-z]%3%2%1 будет соответствовать любому 7-буквенному палиндрому.

В качестве особого случая пустой захват () фиксирует текущую позицию строки (число). Например, если мы применим шаблон "()aa()" к строке "flaaap", будет два захвата: 3 и 5.

Известные ограничения: В отличие от шаблонов библиотеки Ustring, шаблоны библиотеки String могут содержать не более 32 захватов. Если в шаблоне больше, функция String выдаст ошибку. Поскольку библиотека Ustring имеет свой собственный максимум в 10 000 байт для шаблонов (в отличие от библиотеки String), следовательно, невозможно использовать шаблон, который превышает оба ограничения, поскольку он будет несовместим с обеими библиотеками.

Библиотека Table

Большинство функций в библиотеке Table предполагают, что таблица представляет собой последовательность.

Функции table.foreach(), table.foreachi() и table.getn() могут быть доступны, но устарели; используйте цикл for с pairs(), цикл for с ipairs() и вместо этого используйте оператор длины. Однако функция table.setn() полностью устарела и при использовании выдаст ошибку.

table.concat

table.concat( table, sep, i, j )

Учитывая массив, где все элементы являются строками или числами, возвращает table[i] .. sep .. table[i+1] ··· sep .. table[j].

Значением по умолчанию для sep является пустая строка, значением по умолчанию для i является 1, а значением по умолчанию для j является длина таблицы. Если i больше, чем j, он возвращает пустую строку.

table.insert

table.insert( table, value )
table.insert( table, pos, value )

Вставляет элемент value в позицию pos в таблицу table, при необходимости сдвигая другие элементы, чтобы освободить место. Значением по умолчанию для pos является длина таблицы плюс 1, так что вызов table.insert(t, x) вставляет x в конец таблицы t.

Элементы вплоть до #table сдвигаются; см. оператор длины для получения разъяснений, если таблица не является последовательностью.

Note: when using the pos parameter, value should not be nil. Attempting to insert an explicit nil value into the middle of a table will result in undefined behaviour, which may delete elements in the table unpredictably.

table.maxn

table.maxn( table )

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

Чтобы сделать это, он выполняет итерацию по всей таблице. Это примерно эквивалентно

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

table.remove( table, pos )

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

Элементы вплоть до #table сдвигаются; см. оператор длины для дополнительной информации, если таблица не является последовательностью.

table.sort

table.sort( table, comp )

Сортирует элементы таблицы в заданном порядке, на месте (inplace) , от table[1] до table[#table]. Если задано значение comp, то это должна быть функция, которая получает два элемента таблицы и возвращает true, когда первый меньше второго (так что not comp(a[i+1],a[i]) будет true после сортировки). Если comp не задан, то вместо него используется стандартный оператор Lua <. Алгоритм сортировки нестабилен; то есть элементы, считающиеся равными в заданном порядке, могут изменять свое относительное положение при сортировке.

Библиотеки Scribunto

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

Основные функции

mw.addWarning

mw.addWarning( text )

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

mw.allToString

mw.allToString( ... )

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

mw.clone

mw.clone( value )

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

mw.getCurrentFrame

mw.getCurrentFrame()

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

mw.incrementExpensiveFunctionCount

mw.incrementExpensiveFunctionCount()

Увеличивает количество "ресурсоёмких функций парсера", и выдает исключение если оно превышает лимит (см. $wgExpensiveParserFunctionLimit ).

mw.isSubsting

mw.isSubsting()

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

mw.loadData

mw.loadData( module )

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

mw.loadData работает также как require(), со следующими отличиями:

• Загруженный модуль вычисляется только один раз на странице, а не каждый раз при вызове {{#invoke:}}

• Загруженный модуль не записывается в package.loaded.
• Значение, возвращаемое загруженным модулем, должно быть таблицей. Другие типы данных не поддерживаются.
• Возвращаемая таблица (и все подтаблицы) могут содержать только логические значения, числа, строки и другие таблицы. Другие типы данных, в частности, функции, не допускаются.
• Возвращаемая таблица (и все подтаблицы) могут не иметь метатаблиц. SMS
• Все ключи таблицы должны быть логическими, числовыми или строковыми.

• Таблица, фактически возвращаемая mw.loadData(), имеет метаметоды, которые обеспечивают доступ только для чтения к таблице, возвращаемой модулем. Поскольку он не содержит данных напрямую, pairs() и ipairs() будут работать, но другие методы, включая #value, next(), и функции в библиотеке Table, не будут работать корректно.

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

mw.loadJsonData

mw.loadJsonData( page )

Это то же самое, что и mw.loadData() выше, за исключением того, что он загружает данные со страниц JSON, а не из таблиц Lua. Содержимое JSON должно быть массивом или объектом. См. также mw.text.jsonDecode().

mw.dumpObject

mw.dumpObject( object )

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

mw.log

mw.log( ... )

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

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

mw.logObject

mw.logObject( object )
mw.logObject( object, prefix )

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

Объект Frame

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

Обратите внимание, что нет библиотеки frame и нет глобальной переменной с именем frame. Объект frame обычно получается путем передачи в качестве параметра функции, вызываемой с помощью {{#invoke:}}, а также может быть получен из mw.getCurrentFrame().

frame.args

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

{{#invoke:module|function|arg1|arg2|name=arg3}}

тогда frame.args[1] вернет "arg1", frame.args[2] вернет "arg2", а frame.args['name'] (или frame.args.name) вернет "arg3". Также возможно выполнить итерацию по аргументам, используя pairs( frame.args ) или ipairs( frame.args ). Однако из-за того, как Lua реализует табличные итераторы, перебор аргументов вернет их в неопределенном порядке, и нет никакого способа узнать исходный порядок, в котором они отображаются в викитексте.

Обратите внимание, что значения в этой таблице всегда строки; tonumber() может использоваться для преобразования их в числа, если это необходимо. Однако ключи являются числами, даже если явно предоставлено в вызове: {{#invoke:module|function|1|2=2}} дает строковые значения "1" и "2", индексируемые цифровыми ключами 1 и 2.

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

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

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

frame:callParserFunction

• frame:callParserFunction( name, args )
• frame:callParserFunction( name, ... )
• frame:callParserFunction{ name = string, args = table }

Обратите внимание на использование именованных аргументов.

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

Следующие вызовы приблизительно эквивалентны указанному викитексту:

-- {{ns:0}}
frame:callParserFunction( 'ns', { 0 } )
frame:callParserFunction( 'ns', 0 )
frame:callParserFunction{ name = 'ns', args = { 0 } }

-- {{#tag: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', args = { 'nowiki', 'some text' } }

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

Обратите внимание, что, как и в случае с frame:expandTemplate(), имя функции и аргументы не обрабатываются предварительно перед передачей в функцию парсера.

frame:expandTemplate

frame:expandTemplate{ title = title, args = table }

Обратите внимание на использование именованных аргументов.

Это эквивалентно вызову frame:callParserFunction() с именем функции 'msg' (см. Помощь:Волшебные слова#Модификаторы перевода) и с добавлением title к args.

Это встраивание шаблона. Вызывается так:

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

выполняет примерно то же самое из Lua, что и {{template|arg1|arg2|name=arg3}} в викитексте. Как при встраивании, если переданный заголовок не содержит префикса пространства имен, предполагается, что он находится в пространстве имен Шаблон.

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

-- Это примерно эквивалентно викитексту {{template|{{!}}}}
frame:expandTemplate{ title = 'template', args = { '|' } }
frame:callParserFunction{ 'msg', { 'template', '|' } }

-- Это примерно эквивалентно викитексту {{template|{{((}}!{{))}}}}
frame:expandTemplate{ title = 'template', args = { '{{!}}' } }
frame:callParserFunction{ 'msg', { 'template', '{{!}}' } }

frame:extensionTag

• frame:extensionTag( name, content, args )
• frame:extensionTag{ name = string, content = string, args = table_or_string }

Это эквивалентно вызову frame:callParserFunction() с именем функции '#tag' (см. Помощь:Волшебные слова#Разное) и с name и content, добавленными к args.

-- Они эквивалентны
frame:extensionTag( 'ref', 'some text', { name = 'foo', group = 'bar' } )
frame:extensionTag{ name = 'ref', content = 'some text', args = { name = 'foo', group = 'bar' } }
frame:callParserFunction( '#tag', { 'ref' ,
    'some text', name = 'foo', group = 'bar'
} )

-- Они эквивалентны
frame:extensionTag{ name = 'ref', content = 'some text', args = { 'some other text' } }
frame:callParserFunction( '#tag', { 'ref',
    'some text', 'some other text'
} )

frame:getParent

frame:getParent()

Вызывается для фрейма, созданного с помощью {{#invoke:}}, возвращает фрейм для страницы, которая вызывала {{#invoke:}}. Вызывается для этого фрейма, возвращает nil.

Например, если шаблон {{Example}} содержит код {{#invoke:ModuleName|FunctionName|A|B}}, а страница преобразует этот шаблон с кодом {{Example|C|D}}, то в Module:ModuleName вызовы frame.args[1] и frame.args[2] возвращают "A" и "B", а вызовы frame:getParent().args[1] и frame:getParent().args[2] возвращают "C" и "D", с frame является первым аргументом в вызове функции.

frame:getTitle

frame:getTitle()

Возвращает заголовок, связанный с фреймом, в виде строки. Для фрейма, созданного с помощью {{#invoke:}}, это заголовок вызываемого модуля.

frame:newChild

frame:newChild{ title = title, args = table }

Обратите внимание на использование именованных аргументов.

Создайте новый объект Frame, который является дочерним по отношению к текущему фрейму, с необязательными аргументами и заголовком.

Это в основном предназначено для использования в консоли отладки для тестирования функций, которые обычно вызываются с помощью {{#invoke:}}. Количество фреймов, которые могут быть созданы в любой момент времени, ограничено.

frame:preprocess

• frame:preprocess( string )
• frame:preprocess{ text = string }

Разворачивает викитекст из фрейма, т.е. шаблоны, функции парсера и параметры, такие как {{{1}}}, разворачиваются и возвращаются в виде развернутого текста. Некоторые специальные теги, написанные в формате XML, такие как ‎<pre>, ‎<nowiki>, ‎<gallery> и ‎<ref>, будут заменены на «strip-маркеры» - специальные строки, начинающиеся с символа удаления (ASCII 127), которые будут заменены на HTML после того, как они будут возвращены из #invoke.

Если вы разворачиваете одиночный шаблон, используйте frame:expandTemplate вместо того, чтобы пытаться создать строку викитекста для передачи этому методу. Это быстрее и менее подвержено ошибкам, если аргументы содержат символы вертикальной черты или другую викиразметку.

Если вы разворачиваете одиночную функцию парсера, используйте frame:callParserFunction по тем же причинам.

frame:getArgument

• frame:getArgument( arg )
• frame:getArgument{ name = arg }

Получает объект для указанного аргумента или значение nil, если аргумент не указан.

Возвращаемый объект имеет один метод, object:expand(), который возвращает развёрнутый викитекст для аргумента.

frame:newParserValue

• frame:newParserValue( text )
• frame:newParserValue{ text = text }

Возвращает объект с помощью одного метода, object:expand(), который возвращает результат frame:preprocess( text ).

frame:newTemplateParserValue

frame:newTemplateParserValue{ title = title, args = table }

Обратите внимание на использование именованных аргументов.

Возвращает объект с помощью одного метода, object:expand(), который возвращает результат frame:expandTemplate, вызванного с заданными аргументами.

frame:argumentPairs

frame:argumentPairs()

То же, что и pairs( frame.args ). Добавлено для обеспечения обратной совместимости.

Библиотека Hash

mw.hash.hashValue

mw.hash.hashValue( algo, value )

Хэширует строковое значение с помощью указанного алгоритма. Допустимые алгоритмы могут быть выбраны с помощью mw.hash.listAlgorithms().

mw.hash.listAlgorithms

mw.hash.listAlgorithms()

Возвращает список поддерживаемых алгоритмов хэширования для использования в mw.hash.hashValue().

Библиотека HTML

mw.html - это удобный интерфейс для создания сложного HTML кода из Lua. Объект mw.html может быть создан с помощью mw.html.

Функции, задокументированные как mw.html.name доступны в глобальной таблице mw.html; функции, задокументированные как mw.html:name и html:name являются методами объекта mw.html (см. mw.html.name).

Базовый пример может выглядеть так:

local div = mw.html.create( 'div' )
div
     :attr( 'id', 'testdiv' )
     :css( 'width', '100%' )
     :wikitext( 'Some text' )
     :tag( 'hr' )
return tostring( div )
-- Output: <div id="testdiv" style="width:100%;">Some text<hr /></div>

mw.html.create

mw.html.create( tagName, args )

Создает новый объект mw.html, содержащий html-элемент tagName. Вы также можете передать пустую строку или nil как tagName для создания пустого объект mw.html.

args может быть таблица со следующими ключами:

• args.selfClosing: заставляет текущий тег самозакрываться, даже если mw.html не распознает его как самозакрывающийся
• args.parent: родитель текущего экземпляра mw.html (предназначен для внутреннего использования)

mw.html:node

html:node( builder )

Добавляет дочерний узел mw.html (builder) к текущему экземпляру mw.html. Если передан параметр nil, это не работает. Узел (builder) - это строковое представление элемента html.

mw.html:wikitext

html:wikitext( ... )

Добавляет неопределенное количество строк викитекста к объекту mw.html.

Обратите внимание, что это останавливается на первом элементе nil.

Basic wikitext will get parsed, like HTML, links, bold, lists or tables. However, templates and parser functions won't be evaluated if they are passed directly to this function, unless they came from template parameters. Those will be rendered in plain text instead. To evaluate them, they'll have to be passed through frame:preprocess.

mw.html:newline

html:newline()

Добавляет новую строку к объекту mw.html. Useful when used before and after mw.html:wikitext(), when the wikitext contains lists or tables, whose syntax only has a special meaning when present at the start of a line.

mw.html:tag

html:tag( tagName, args )

Добавляет новый дочерний узел с заданным tagName к конструктору и возвращает экземпляр mw.html, представляющий этот новый узел. Параметр args идентичен параметру tagName

Обратите внимание, что в отличие от других методов, таких как html:node(), этот метод возвращает не текущий экземпляр mw.html, а экземпляр mw.html недавно вставленного тега. Обязательно используйте html:done(), чтобы перейти к родительскому элементу mw.html например, или html:allDone(), если у вас есть вложенные теги на нескольких уровнях.

mw.html:attr

html:attr( name, value )
html:attr( table )

Устанавливает атрибут HTML с заданными name и value узла. В качестве альтернативы можно передать таблицу, содержащую пары атрибутов имя->значение, которые нужно установить. В первой способе установки значение nil приводит к сбросу любого атрибута с заданным именем, если он был установлен ранее.

mw.html:getAttr

html:getAttr( name )

Получить значение атрибута html, ранее установленное с помощью html:attr() с данным name.

mw.html:addClass

html:addClass( class )

Добавляет имя класса к атрибуту класса узла. Если передан параметр nil, это не работает.

mw.html:css

html:css( name, value )
html:css( table )

Задаёт свойство CSS с заданными name и value узла. В качестве альтернативы можно передать таблицу, содержащую пары свойств name->value, которые требуется установить. В первом способе значение nil приводит к сбросу любого свойства с заданным именем, если оно было установлено ранее.

mw.html:cssText

html:cssText( css )

Добавьте строку css к атрибуту стиля узла. Если передан параметр nil, это не работает.

mw.html:done

html:done()

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

mw.html:allDone

html:allDone()

Как html:done(), но проходит весь путь до корневого узла дерева и возвращает его.

Библиотека Language

Языковые коды описаны на странице коды языка. Многие языковые коды MediaWiki похожи на языковые теги IETF, но не все языковые коды MediaWiki являются допустимыми тегами IETF или наоборот.

Функции, задокументированные как mw.language.name доступны в глобальной таблице mw.language; функции задокументированы как mw.language:name и lang:name - это методы языкового объекта (см. mw.language.new или mw.language.getContentLanguage).

mw.language.fetchLanguageName

mw.language.fetchLanguageName( code, inLanguage )

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

mw.language.fetchLanguageNames

mw.language.fetchLanguageNames()
mw.language.fetchLanguageNames( inLanguage )
mw.language.fetchLanguageNames( inLanguage, include )

Извлекает список языков, известных MediaWiki, возвращая таблицу, сопоставляющую код языка названию языка.

По умолчанию возвращаемое имя является автонимом языка; передача кода языка для inLanguage возвращает все имена на этом языке.

По умолчанию возвращаются только названия языков, известные MediaWiki; передача 'all' для include вернет все доступные языки (например, от Расширение:CLDR ), в то время как передача 'mwfile' будет включать только языки наличие настроенных сообщений, включенных в ядро MediaWiki или включенных расширений. Чтобы явно выбрать значение по умолчанию, может быть передан 'mw'.

mw.language.getContentLanguage

mw.language.getContentLanguage()
mw.getContentLanguage()

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

mw.language.getFallbacksFor

Резервные цепочки

mw.language.getFallbacksFor( code )

Возвращает список резервных языковых кодов MediaWiki для указанного кода.

mw.language.isKnownLanguageTag

mw.language.isKnownLanguageTag( code )

Возвращает значение true, если код языка известен MediaWiki.

Код языка "известен", если он является "допустимым встроенным кодом (valid built-in code)" (т.е. он возвращает значение true для mw.language.isValidBuiltInCode) и возвращает непустую строку для мвт.язык.fetchLanguageName.

mw.language.isSupportedLanguage

mw.language.isSupportedLanguage( code )

Проверяет, доступна ли какая-либо локализация для этого языкового кода в MediaWiki.

Код языка "поддерживается (supported)", если он является "допустимым (valid)" кодом (возвращает значение true для mw.language.isValidCode), не содержит заглавных букв и содержит файл сообщения в текущей версии MediaWiki.

Код языка может быть "поддерживаемым (supported)", но не "известным (known)" (т.е. возвращать значение true для mw.language.isKnownLanguageTag). Также обратите внимание, что некоторые коды "поддерживаются (supported)", несмотря на то, что mw.language.isValidBuiltInCode возвращает значение false.

mw.language.isValidBuiltInCode

mw.language.isValidBuiltInCode( code )

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

Код на самом деле может не соответствовать ни одному известному языку.

Код языка является "допустимым встроенным кодом (valid built-in code)", если это "допустимый (valid)" код (т.е. он возвращает значение true для mw.language.isValidCode); состоит только из букв ASCII, цифр и дефисов; и является длиной не менее двух символов.

Обратите внимание, что некоторые коды "поддерживаются (supported)" (т.е. возвращают значение true из mw.language.isSupportedLanguage), даже если эта функция возвращает значение false.

mw.language.isValidCode

mw.language.isValidCode( code )

Возвращает значение true, если строка языкового кода имеет допустимую форму, независимо от того, существует она или нет. Сюда входят коды, которые используются исключительно для настройки через пространство имен MediaWiki.

Код на самом деле может не соответствовать ни одному известному языку.

Код языка действителен, если он не содержит определенных небезопасных символов (двоеточия, одинарные или двойные кавычки, косые черты, обратные косые черты, угловые скобки, амперсанды или ASCII-нули) и иным образом разрешен в заголовке страницы.

mw.language.new

mw.language.new( code )
mw.getLanguage( code )

Создает новый языковой объект. Языковые объекты не имеют общедоступных свойств, но у них есть несколько методов, которые описаны ниже.

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

mw.language:getCode

lang:getCode()

Возвращает код языка для этого языкового объекта.

mw.language:toBcp47Code

lang:toBcp47Code()

Возвращает стандартный код языка BCP-47 для этого языкового объекта. Это строка кода, которую целесообразно использовать в HTML, например, в качестве значения атрибута lang.

mw.language:getFallbackLanguages

lang:getFallbackLanguages()

Возвращает список резервных языковых кодов MediaWiki для этого языкового объекта. Эквивалентно mw.language.getFallbacksFor( lang:getCode() ).

mw.language:isRTL

lang:isRTL()

Возвращает значение true, если язык написан справа налево, и значение false, если он написан слева направо.

mw.language:lc

lang:lc( s )

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

Когда библиотека Ustring загружена, mw.ustring.lower() реализован как вызов mw.language.getContentLanguage():lc( s ).

mw.language:lcfirst

lang:lcfirst( s )

Преобразует первый символ строки в нижний регистр, как в lang:lc().

mw.language:uc

lang:uc( s )

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

Когда библиотека Ustring загружена, mw.ustring.upper() реализован как вызов mw.language.getContentLanguage():uc( s ).

mw.language:ucfirst

lang:ucfirst( s )

Преобразует первый символ строки в верхний регистр, как в lang:uc().

mw.language:caseFold

lang:caseFold( s )

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

mw.language:formatNum

lang:formatNum( n )
lang:formatNum( n, options )

Форматирует число с помощью группирующих и десятичных разделителей, соответствующих данному языку. Учитывая 123456.78, это может привести к появлению "123,456.78", "123.456,78", или даже чего-то вроде "١٢٣٬٤٥٦٫٧٨" в зависимости от языка и викиконфигурации.

options - это таблица параметров, которая может быть такой:

• noCommafy: Установите значение true, чтобы отключить группирующие разделители и использовать точку (.) в качестве десятичного разделителя.

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

mw.language:formatDate

lang:formatDate( format, timestamp, local )

Форматирует дату в соответствии с заданной строкой формата. Если timestamp отсутствует, по умолчанию используется текущее время. Значение для local должно быть логическим или nil; если true, время будет отформатировано в формате локального времени вики, а не в UTC.

Строка формата и поддерживаемые значения для timestamp идентичны значениям для функции парсера #time из Расширение:Функции парсера . Однако обратите внимание, что обратные косые черты, возможно, потребуется удвоить в строковом литерале Lua, поскольку Lua также использует обратную косую черту в качестве экранирующего символа, в то время как викитекст этого не делает:

-- Этот строковый литерал содержит новую строку, а не два символа "\n", поэтому он не эквивалентен {{#time:\n}}.
lang:formatDate( '\n' )

-- Это эквивалентно {{#time:\n}}, а не {{#time:\\n}}.
lang:formatDate( '\\n' )

-- Это эквивалентно {{#time:\\n}}, а не {{#time:\\\\n}}.
lang:formatDate( '\\\\n' )

mw.language:formatDuration

lang:formatDuration( seconds )
lang:formatDuration( seconds, chosenIntervals )

Разбивает длительность в секундах на более удобочитаемые единицы измерения, например, 12345 на 3 часа, 25 минут и 45 секунд, возвращая результат в виде строки.

chosenIntervals, если указано, то это таблица со значениями, обозначающими единицы измерения интервала, которые будут использоваться в ответе. К ним относятся 'millennia', 'centuries', 'decades', 'years', 'weeks', 'days', 'hours', 'minutes', и 'seconds'.

mw.language:parseFormattedNumber

lang:parseFormattedNumber( s )

Принимает число в формате lang:formatNum() и возвращает фактическое число. Другими словами, это, по сути, языковая версия tonumber().

mw.language:convertPlural

lang:convertPlural( n, ... )
lang:convertPlural( n, forms )
lang:plural( n, ... )
lang:plural( n, forms )

Выбирается соответствующая грамматическая форма из форм forms (которая должна быть таблицей-последовательностью) или ... на основе числа n. Например, в английском языке вы могли бы использовать n .. ' ' .. lang:plural( n, 'sock', 'socks' ) или n .. ' ' .. lang:plural( n, { 'sock', 'socks' } ) для генерации грамматически правильного текста, независимо от того, есть только 1 носок или 200 носков.

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

mw.language:convertGrammar

lang:convertGrammar( word, case )
lang:grammar( case, word )

"Обратите внимание на различный порядок параметров между двумя псевдонимами. convertGrammar соответствует порядку одноименного метода в языковом объекте MediaWiki, в то время как grammar соответствует порядку одноименной функции парсера, задокументированной на странице Помощь:Волшебные слова#Локализация."

Выбирается соответствующая склоняемая форма слова word для данного кода склонения case.

Возможные значения для word и case зависят от языка, дополнительную информацию см. на страницах Помощь:Волшебные слова#Локализация и translatewiki:Grammar.

mw.language:gender

lang:gender( what, masculine, feminine, neutral )
lang:gender( what, { masculine, feminine, neutral } )

Выбирает строку, соответствующую полу what, которая может быть "male", "female" или зарегистрированным пользовательским названием.

mw.language:getArrow

lang:getArrow( direction )

Возвращает символ стрелки в Юникоде, соответствующий направлению direction:

• forwards: Либо "→", либо "←" в зависимости от направленности языка.
• backwards: Либо "←", либо "→" в зависимости от направленности языка.
• left: "←"
• right: "→"
• up: "↑"
• down: "↓"

mw.language:getDir

lang:getDir()

Возвращает "ltr" или "rtl", в зависимости от направленности языка.

mw.language:getDirMark

lang:getDirMark( opposite )

Возвращает строку, содержащую либо U+200E (метка left-to-right), либо U+200F (метка right-to-left), в зависимости от направленности языка и от того, является ли opposite значением true или false.

mw.language:getDirMarkEntity

lang:getDirMarkEntity( opposite )

Возвращает "‎" или "‏", в зависимости от направленности языка и от того, является ли opposite значением true или false.

mw.language:getDurationIntervals

lang:getDurationIntervals( seconds )
lang:getDurationIntervals( seconds, chosenIntervals )

Разбивает длительность в секундах на более удобочитаемые единицы измерения, например, 12345 на 3 часа, 25 минут и 45 секунд, возвращая результат в виде таблицы, преобразующей названия единиц измерения в числа.

chosenIntervals, если указано, то это таблица со значениями, обозначающими единицы измерения интервала, которые будут использоваться в ответе. К ним относятся 'millennia', 'centuries', 'decades', 'years', 'weeks', 'days', 'hours', 'minutes', и 'seconds'.

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

Библиотека Message

Эта библиотека представляет собой интерфейс к локализованным сообщениям и пространству имен MediaWiki: namespace.

Функции, задокументированные как mw.message.name доступны в глобальной таблице mw.message; функции задокументированы как mw.message:name и msg:name - это методы объекта message (см. mw.message.new).

mw.message.new

mw.message.new( key, ... )

Создает новый объект message для данного ключа message key. Остальные параметры передаются методу params() нового объекта.

Объект message не имеет свойств, но имеет несколько методов, описанных ниже.

mw.message.newFallbackSequence

mw.message.newFallbackSequence( ... )

Создает новый объект message для заданных сообщений (будет использоваться первый существующий).

Объект message не имеет свойств, но имеет несколько методов, описанных ниже.

mw.message.newRawMessage

mw.message.newRawMessage( msg, ... )

Создает новый объект message, используя данный текст напрямую, а не просматривая интернационализированное сообщение. Остальные параметры передаются методу params().

Объект message не имеет свойств, но имеет несколько методов, описанных ниже.

mw.message.rawParam

mw.message.rawParam( value )

Обертывает значение так, что оно не будет проанализировано как викитекст с помощью msg:parse().

mw.message.numParam

mw.message.numParam( value )

Преобразует значение таким образом, что оно автоматически будет отформатировано как lang:formatNum(). Обратите внимание, что это не зависит от фактической доступности библиотеки Language.

mw.message.getDefaultLanguage

mw.message.getDefaultLanguage()

Возвращает объект Language для языка по умолчанию.

mw.message:params

msg:params( ... )
msg:params( params )

Добавьте в сообщение параметры, которые могут быть переданы в виде отдельных аргументов или в виде таблицы-последовательности. Параметрами должны быть числа, строки или специальные значения, возвращаемые mw.message.numParam() или mw.message.rawParam(). Если используется таблица-последовательность, параметры должны присутствовать непосредственно в таблице; ссылки с использованием метаметода __index работать не будут.

Возвращает объект msg, позволяющий создавать цепочки вызовов.

mw.message:rawParams

msg:rawParams( ... )
msg:rawParams( params )

Как :params(), но сначала все параметры передаются через mw.message.rawParam().

Возвращает объект msg, позволяющий создавать цепочки вызовов.

mw.message:numParams

msg:numParams( ... )
msg:numParams( params )

Как :params(), но имеет эффект передачи всех параметров сначала через mw.message.numParam().

Возвращает объект msg, позволяющий создавать цепочки вызовов.

mw.message:inLanguage

msg:inLanguage( lang )

Указывает язык, который будет использоваться при обработке сообщения. lang может быть строкой или таблицей с методом getCode() (т.е. объект Language).

Язык по умолчанию - это тот, который возвращается mw.message.getDefaultLanguage().

Возвращает объект msg, позволяющий создавать цепочки вызовов.

mw.message:useDatabase

msg:useDatabase( bool )

Указывает, следует ли искать сообщения в пространстве имен MediaWiki:namespace (т.е. искать в базе данных) или просто использовать сообщения по умолчанию, распространяемые с помощью MediaWiki.

Значение по умолчанию равно true.

Возвращает объект msg, позволяющий создавать цепочки вызовов.

mw.message:plain

msg:plain()

Заменяет параметры и возвращает викитекст сообщения как есть. Вызовы шаблонов и функций парсера остаются неизменными.

mw.message:exists

msg:exists()

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

mw.message:isBlank

msg:isBlank()

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

mw.message:isDisabled

msg:isDisabled()

Возвращает логическое значение, указывающее, отключен ли ключ сообщения. Возвращает значение true, если ключ сообщения не существует или если сообщение представляет собой пустую строку или строку "-".

Библиотека Site

mw.site.currentVersion

Строка, содержащая текущую версию MediaWiki.

mw.site.scriptPath

Значение $wgScriptPath .

mw.site.server

Значение $wgServer

mw.site.siteName

Значение $wgSitename

mw.site.stylePath

Значение $wgStylePath .

mw.site.namespaces

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

Имеющиеся данные таковы:

• id: * $1: Номер пространства имен.
• name: * $1: Имя локального пространства имен.
• 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.

Также задана метатаблица, позволяющая искать пространства имен по имени (локализованному или каноническому). Например, и mw.site.namespaces[4], и mw.site.namespaces.Project вернут информацию о пространстве имен проекта.

mw.site.contentNamespaces

Таблица, содержащая только пространства имен содержимого, проиндексированные по номеру. Подробности см. на странице mw.site.namespaces.

mw.site.subjectNamespaces

Таблица, содержащая только тематические пространства имен, проиндексированные по номеру. Подробности см. на странице mw.site.namespaces.

mw.site.talkNamespaces

Таблица, содержащая только пространства имен Обсуждение, проиндексированные по номеру. Подробности см. на странице mw.site.namespaces.

mw.site.stats

Таблица, содержащая статистику сайта. Доступными статистическими данными являются:

• pages: Number of pages in the wiki.
• articles: Number of articles in the wiki.
• files: Number of files in the wiki.
• edits: Number of edits in the wiki.
• users: Number of users in the wiki.
• activeUsers: Number of active users in the wiki.
• admins: Number of users in group 'sysop' in the wiki.

mw.site.stats.pagesInCategory

mw.site.stats.pagesInCategory( category, which )

Это ресурсоёмкая функция

Получает статистику по категории. Если which имеет специальное значение "*", результатом будет таблица со следующими свойствами:

• all: Total pages, files, and subcategories.
• subcats: Number of subcategories.
• files: Number of files.
• pages: Number of pages.

Если which является одним из вышеуказанных ключей ("all", "subcats", "files", "pages"), результатом будет число с соответствующим значением.

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

mw.site.stats.pagesInNamespace

mw.site.stats.pagesInNamespace( namespace )

Возвращает количество страниц в заданном пространстве имен (указать по номеру).

mw.site.stats.usersInGroup

mw.site.stats.usersInGroup( group )

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

mw.site.interwikiMap

mw.site.interwikiMap( filter )

Возвращает таблицу, содержащую данные о доступных префиксах интервики. Если filter является строкой "local", то возвращаются только данные для локальных префиксов интервики. Если filter является строкой "!local", то возвращаются только данные для нелокальных префиксов. Если фильтр не указан, возвращаются данные для всех префиксов. Префикс "local" в этом контексте - это префикс, который предназначен для одного и того же проекта. Например, в английской Википедии Википедии на других языках считаются локальными, в то время как викисловарь и тому подобное - нет.

Ключи в таблице, возвращаемые этой функцией, являются префиксами интервики, а значения - подтаблицами со следующими свойствами:

• prefix - the interwiki prefix.
• url - the URL that the interwiki points to. The page name is represented by the parameter $1.
• isProtocolRelative - a boolean showing whether the URL is protocol-relative.
• isLocal - whether the URL is for a site in the current project.
• isCurrentWiki - whether the URL is for the current wiki.
• isTranscludable - whether pages using this interwiki prefix are transcludable. This requires scary transclusion, which is disabled on Wikimedia wikis.
• isExtraLanguageLink - whether the interwiki is listed in $wgExtraInterlanguageLinkPrefixes .
• displayText - for links listed in $wgExtraInterlanguageLinkPrefixes, this is the display text shown for the interlanguage link. Nil if not specified.
• tooltip -

for links listed in $wgExtraInterlanguageLinkPrefixes, this is the tooltip text shown when users hover over the interlanguage link. Nil if not specified.

Библиотека Text

Библиотека Text предоставляет некоторые распространенные функции обработки текста, отсутствующие в библиотеке String и библиотеке Ustring. Эти функции безопасны для использования со строками в кодировке UTF-8.

mw.text.decode

mw.text.decode( string )
mw.text.decode( string, decodeNamedEntities )

Заменяет мнемоники в HTML в строке соответствующими символами.

Если логическое значение decodeNamedEntities равно false или пропущено, распознаются только именованные объекты $2 (<), $3 (>), & (&), " (") и $4 (неразрывный пробел, U+00A0). В противном случае список распознаваемых объектов с именами HTML5 загружается из функции PHP [$url get_html_translation_table].

Известные ошибки: Примерно 600 из примерно 2200 именованных объектов в стандарте HTML5 не декодируются, даже когда используется decodeNamedEntities; это включает примерно 40 из примерно 250 объектов, которые также включены в HTML4. Это происходит потому, что функция PHP get_html_translation_table возвращает только одно отображение для каждого символа, поэтому, например, → не декодируется, поскольку PHP возвращает только → в качестве отображения для →.

mw.text.encode

mw.text.encode( string )
mw.text.encode( string, charset )

Заменяет символы в строке на мнемоники. Пять символов заменяются соответствующими именованными объектами: <, >, &, " и неразрывным пробелом (U+00A0). Все остальные заменяются числовыми объектами.

Если указана кодировка charset, она должна быть соответствующей строкой, заключенной в квадратные скобки в шаблоне Ustring, т.е. "набор" в [set]. Кодировка по умолчанию содержит шесть символов: <, >, &, ", ' и неразрывный пробел (U+00A0).

mw.text.jsonDecode

mw.text.jsonDecode( string )
mw.text.jsonDecode( string, flags )

Декодирует строку JSON. flags равен 0 или комбинации (используйте +) флагов mw.text.JSON_PRESERVE_KEYS и mw.text.JSON_TRY_FIXING.

Обычно массивы JSON, основанные на нуле, перенумеруются в таблицы последовательностей Lua, основанные на единице; чтобы предотвратить это, передайте mw.text.JSON_PRESERVE_KEYS.

Чтобы смягчить определенные требования в JSON, такие как отсутствие конечной запятой в массивах или объектах, передайте mw.text.JSON_TRY_FIXING. Однако это не рекомендуется.

Ограничения:

• Декодированные массивы JSON могут не быть последовательностями Lua, если массив содержит значения null.
• Объекты JSON будут удалять ключи, имеющие значения null.
• Невозможно напрямую определить, были ли входные данные массивом JSON или объектом JSON с последовательными целыми ключами.
• Объект JSON, имеющий последовательные целочисленные ключи, начинающиеся с 1, будет декодироваться в ту же структуру таблицы, что и массив JSON с теми же значениями, несмотря на то, что они совсем не эквивалентны, если только не используется ключ mw.text.JSON_PRESERVE_KEYS.

mw.text.jsonEncode

mw.text.jsonEncode( value )
mw.text.jsonEncode( value, flags )

Кодирует строку JSON. Возникнет ошибка, если переданное значение не может быть закодировано в JSON. flags равен 0 или комбинации (используйте +) флагов mw.text.JSON_PRESERVE_KEYS и mw.text.JSON_PRETTY.

Обычно таблицы-последовательности, начинающиеся с единицы в Lua, кодируются как массивы, начинающиеся с нуля в JSON; если ключ mw.text.JSON_PRESERVE_KEYS установлен в flags, таблицы-последовательности кодируются как массивы JSON с добавлением "фиктивного" нуля.

Ограничения:

• Пустые таблицы всегда кодируются как пустые массивы ([]), а не как пустые объекты ({}).
• Таблицы-последовательности нельзя закодировать как объекты JSON без добавления "фиктивного" элемента.
• Для создания объектов или массивов с нулевыми значениями требуется сложная реализация метаметода __pairs.
• Таблица Lua, имеющая последовательные целочисленные ключи, начинающиеся с 0, будет кодироваться как массив JSON, так же, как таблица Lua, имеющая целочисленные ключи, начинающиеся с 1, если только не используется флаг mw.text.JSON_PRESERVE_KEYS.
• Когда и число, и строковое представление этого числа используются в качестве ключей в одной и той же таблице, поведение не определено.

mw.text.killMarkers

mw.text.killMarkers( string )

Удаляет все MediaWiki strip маркеры из строки.

mw.text.listToText

mw.text.listToText( list )
mw.text.listToText( list, separator, conjunction )

Объединяет список в прозаическом стиле. Другими словами, это похоже на table.concat(), но с другим разделителем перед конечным элементом.

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

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

 -- Возвращает пустую строку
 mw.text.listToText( {} )
 
 -- Возвращает "1"
 mw.text.listToText( { 1 } )
 
 -- Возвращает "1 и 2"
 mw.text.listToText( { 1, 2 } )
 
 -- Возвращает "1, 2, 3, 4 и 5"
 mw.text.listToText( { 1, 2, 3, 4, 5 } )
 
 -- Возвращает "1; 2; 3; 4 или 5"
 mw.text.listToText( { 1, 2, 3, 4, 5 }, '; ', ' or ' )

mw.text.nowiki

mw.text.nowiki( string )

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

• Следующие символы: ", &, ', <, =, >, [, ], {, |, }
• Следующие символы в начале строки или сразу после новой строки: #, *, :, ;, пробел, табуляция (\t)
• В пустых строках будет экранирован один из связанных символов новой строки или возврата каретки
• ---- в начале строки или сразу после новой строки будет экранирован первый -
• __ будет пропущен один символ подчеркивания
• :// будет пропущено двоеточие
• Символ пробела, следующий за ISBN, RFC, или PMID, будет экранирован

• The following characters at the start of the string or immediately after a newline: #, *, :, ;, space, tab (\t)

• Blank lines will have one of the associated newline or carriage return characters escaped

• ---- at the start of the string or immediately after a newline will have the first - escaped

• __ will have one underscore escaped

• :// will have the colon escaped

• A whitespace character following ISBN, RFC, or PMID will be escaped

mw.text.split

mw.text.split( string, pattern, plain )

Разбивает строку на подстроки по границам, соответствующим шаблону Ustring pattern. Если указано значение plain и значение true, pattern будет интерпретироваться как литеральная строка, а не как шаблон Lua (точно так же, как с одноименным параметром для mw.ustring.find()). Возвращает таблицу, содержащую подстроки.

Например, mw.text.split( 'a b\tc\nd', '%s' ) вернет таблицу { 'a', 'b', 'c', 'd' }.

Если шаблон pattern соответствует пустой строке, s будет разделен на отдельные символы.

Note that this function can be over 60 times slower than a reimplementation that is not Unicode-aware, such as the following:

function split(text, pattern, plain)
    local ret = {}
    local s, l = 1, string.len( text )
    while s do
    	local e, n = string.find( text, pattern, s, plain )
    	if not e then
    		ret[#ret+1] = string.sub ( text, s )
    		s = nil
    	elseif n < e then
    		-- Empty separator!
    		ret[#ret+1] = string.sub ( text, s, e )
    		if e < l then
    			s = e + 1
    		else
    			s = nil
    		end
    	else
    		ret[#ret+1] = e > s and string.sub( text, s, e - 1 ) or ''
    		s = n + 1
    	end
    end
    return ret
end

mw.text.gsplit

mw.text.gsplit( string, pattern, plain )

Возвращает функцию-итератор, которая будет выполнять итерацию по подстрокам, которые были бы возвращены эквивалентным вызовом mw.text.split().

Note that this function can be over 60 times slower than a reimplementation that is not Unicode-aware, such as the following:

function gsplit( text, pattern, plain )
	local s, l = 1, string.len( text )
	return function ()
		if s then
			local e, n = string.find( text, pattern, s, plain )
			local ret
			if not e then
				ret = string.sub( text, s )
				s = nil
			elseif n < e then
				-- Empty separator!
				ret = string.sub( text, s, e )
				if e < l then
					s = e + 1
				else
					s = nil
				end
			else
				ret = e > s and string.sub( text, s, e - 1 ) or ''
				s = n + 1
			end
			return ret
		end
	end, nil, nil
end

mw.text.tag

mw.text.tag( name, attrs, content )
mw.text.tag{ name = string, attrs = table, content = string|false }

Обратите внимание на использование именованных аргументов.

Генерирует тег в стиле HTML для name.

Если задан attrs, то это должна быть таблица со строковыми ключами. В качестве значения атрибута используются строковые и числовые значения; логическое значение true приводит к тому, что ключ выводится как параметр без значения HTML5; логическое значение false полностью пропускает ключ; а все остальное является ошибкой.

Если content не задан (или равен nil), возвращается только открывающий тег. Если content имеет логическое значение false, возвращается самозакрывающийся тег. В противном случае это должна быть строка или число, и в этом случае содержимое будет заключено в созданный открывающий и закрывающий тег. Обратите внимание, что содержимое автоматически не кодируется в HTML; при необходимости используйте mw.text.encode().

Для правильного возврата тегов расширения, таких как ‎<ref>, используйте вместо этого frame:extensionTag().

mw.text.trim

mw.text.trim( string )
mw.text.trim( string, charset )

Удалите пробелы или другие символы из начала и конца строки.

Если указана кодировка charset, она должна быть соответствующей строкой, заключенной в квадратные скобки в шаблоне Ustring, т.е. "набор" в [set]. Кодировка по умолчанию - все пробельные символы ASCII, %s, что эквивалентно "\t\r\n\f\v ".

mw.text.truncate

mw.text.truncate( text, length )
mw.text.truncate( text, length, ellipsis )
mw.text.truncate( text, length, ellipsis, adjustLength )

Усекает text до указанной длины в кодовых точках, добавляя ellipsis, если было выполнено усечение. Если длина положительная, конец строки будет усечен; если отрицательная, начало будет усечено. Если задано значение adjustLength и значение true, результирующая строка, включающая ellipsis, не будет длиннее указанной длины.

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

Примеры, использующие многоточие (ellipsis) "..." по умолчанию:

-- Возвращает "foobarbaz"
mw.text.truncate( "foobarbaz", 9 )

-- Возвращает "fooba..."
mw.text.truncate( "foobarbaz", 5 )

-- Возвращает "...arbaz"
mw.text.truncate( "foobarbaz", -5 )

-- Возвращает "foo..."
mw.text.truncate( "foobarbaz", 6, nil, true )

-- Возвращает "foobarbaz", потому что это короче, чем "foobarba..."
mw.text.truncate( "foobarbaz", 8 )

mw.text.unstripNoWiki

mw.text.unstripNoWiki( string )

Заменяет MediaWiki strip маркер <nowiki> соответствующим текстом. Другие типы strip маркеров не изменяются.

mw.text.unstrip

mw.text.unstrip( string )

Эквивалентно mw.text.killMarkers( mw.text.unstripNoWiki( s ) ).

Это больше не раскрывает HTML-код, находящийся на специальных встраиваемых страницах, с тегами <ref> и так далее, как это было в более ранних версиях Scribunto.

Библиотека Title

mw.title.equals

mw.title.equals( a, b )

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

mw.title.compare

mw.title.compare( a, b )

Возвращает -1, 0 или 1, чтобы указать, является ли заголовок a меньше, равен или больше заголовка b.

При этом заголовки сравниваются по префиксу интервики (если таковой имеется) в виде строк, затем по номеру пространства имен, затем по тексту заголовка без префикса в виде строки. При сравнении строк используется стандартный оператор Lua <.

mw.title.getCurrentTitle

mw.title.getCurrentTitle()

Возвращает объект title для текущей страницы.

mw.title.new

mw.title.new( text, namespace )
mw.title.new( ID )

При вызове с идентификатором id это ресурсоёмкая функция

Создает новый объект title.

Если задан идентификатор id, для заголовка создается объект с этим идентификатором (page_id). Заголовок, на который ссылается ссылка, будет считаться связанным с текущей страницей. Если page_id не существует, возвращает значение nil. Количество ресурсоёмких функций будет увеличено, если созданный объект title не предназначен для заголовка, который уже был загружен.

Если вместо этого задана строка text, для этого заголовка создается объект (даже если страница не существует). Если в текстовой строке не указано пространство имен, будет использовано пространство имен namespace (которое может быть любым ключом, найденным в mw.site.namespaces). Если текст не является допустимым заголовком, возвращается значение nil.

mw.title.makeTitle

mw.title.makeTitle( namespace, title, fragment, interwiki )

Создает объект title с заголовком title в пространстве имен namespace, необязательно с указанным фрагментом fragment и префиксом interwiki. namespace может быть любым ключом, найденным в mw.site.namespaces. Если результирующий заголовок недопустим, возвращает значение nil.

Обратите внимание, что, в отличие от mw.title.new(), этот метод всегда будет применять указанное пространство имен. Например, mw.title.makeTitle( 'Шаблон', 'Модуль:Foo' ) создаст объект для шаблона страницы Шаблон:Модуль:Foo, в то время как mw.title.new( 'Модуль:Foo', 'Шаблон' ) создаст объект для страницы Модуль:Foo.

Обратите также внимание, что функциональность для заголовков интервики ограничена interwiki / isExternal / isLocal и методами, связанными с URL; другие методы могут вести себя не так, как ожидалось.

Объекты Title

Объект title обладает рядом свойств и методов. Большинство свойств доступны только для чтения.

Обратите внимание, что поля, оканчивающиеся на text, возвращают заголовки в виде строковых значений, тогда как поля, оканчивающиеся на title, возвращают объекты заголовка.

• id: page_id. 0 если страница не существует.

Это может быть ресурсоёмким свойством.

• interwiki: Префикс интервики или пустая строка, если отсутствует.
• namespace: Номер пространства имен.
• fragment: Фрагмент (он же раздел/привязка к якорю) или пустая строка. Может быть присвоен.
• nsText: Текст пространства имен для страницы.
• subjectNsText: Текст субъекта пространства имен для страницы.

• talkNsText: Текст пространства имен Обсуждение для страницы или nil, если в этом заголовке не может быть страницы обсуждения. (добавлено в MediaWiki 1.42.0-wmf.15, ссылки T180911)

• text: Заголовок страницы без префиксов пространства имен или интервики.
• prefixedText: Заголовок страницы с префиксами пространства имен и интервики.
• fullText: Заголовок страницы с префиксами пространства имен и интервики и фрагментом. Интервики не возвращаются, если они равны текущему.

• rootText: Если это подстраница, то заголовок корневой страницы без префиксов. В противном случае то же самое, что title.text.

• baseText: Если это подстраница, то название страницы, к которой она относится, без префиксов. В противном случае то же самое, что title.text.

• subpageText: Если это подстраница, просто название подстраницы. В противном случае, то же самое, что title.text.

• canTalk: Может ли страница с таким заголовком содержать страницу обсуждения.
• exists: Существует ли страница. Псевдоним для file.exists для заголовков в пространстве имен Медиа. Для заголовков в пространстве имен Файлов проверяется существование страницы описания файла, а не самого файла. Это может быть ресурсоёмким свойством
• file, fileExists: См. #Метаданные файла ниже.
• isContentPage: Находится ли этот заголовок в пространстве имен содержимого.
• isExternal: Имеет ли этот заголовок префикс интервики.
• isLocal: Присутствует ли это название в данном проекте. Например, в английской Википедии любая другая Википедия считается "local", в то время как Викисловарь и тому подобные - нет.
• isRedirect: Является ли это заголовком страницы, которая является перенаправлением. Это может быть ресурсоёмким свойством.
• isSpecialPage: Является ли это заголовком для возможной специальной страницы (т.е. страницы в пространстве имен Special:namespace).
• isSubpage: Является ли этот заголовок подстраницей какого-либо другого заголовка.
• isTalkPage: Является ли это заголовком для страницы обсуждения.
• isSubpageOf( title2 ): Является ли этот заголовок подстраницей данного заголовка.

• inNamespace( ns ): Находится ли этот заголовок в данном пространстве имен. Пространства имен могут быть заданы любым ключом, найденным в mw.site.namespaces.

• inNamespaces( ... ): Находится ли этот заголовок в каком-либо из заданных пространств имен. Пространства имен могут быть заданы любым ключом, найденным в mw.site.namespaces.

• hasSubjectNamespace( ns ): Находится ли пространство имен субъекта этого заголовка в данном пространстве имен. Пространства имен могут быть заданы любым ключом, найденным в mw.site.namespaces.

• contentModel: Модель контента для этого заголовка в виде строки. Это может быть ресурсоёмким свойством.

• basePageTitle: То же самое, что mw.title.makeTitle( title.namespace, title.baseText ).

• rootPageTitle: Тоже самое что mw.title.makeTitle( title.namespace, title.rootText ).

• talkPageTitle: Тоже самое что mw.title.makeTitle( mw.site.namespaces[title.namespace].talk.id, title.text ), или nil, если это название не является страницей обсуждения.

• subjectPageTitle: Тоже самое что mw.title.makeTitle( mw.site.namespaces[title.namespace].subject.id, title.text ).

• redirectTarget: Возвращает объект title целевой страницы перенаправления, если страница является перенаправлением и страница существует, возвращает false в противном случае.

• protectionLevels: Уровни защиты страницы. Это таблица с ключами, соответствующими каждому действию (например, "edit" и "move"). Значения таблицы представляют собой массивы, первым элементом которых является строка, содержащая уровень защиты. Если страница не защищена, либо значения таблицы, либо элементы массива будут равны nil. Это может быть ресурсоёмким свойством.

• cascadingProtection: Каскадные средства защиты, применимые к странице. Это таблица с ключами "restrictions" (сама по себе таблица с ключами типа имеет protectionLevels) и "sources" (массив, содержащий заголовки, из которых каскадируются защиты). Если страница не защищена каскадно, "restrictions" и "sources" будут пустыми. Это может быть ресурсоёмким свойством.

• subPageTitle( text ): Тоже самое что mw.title.makeTitle( title.namespace, title.text .. '/' .. text ).

• partialUrl(): Возвращает title.text, закодированный так, как это было бы в URL.

• fullUrl( query, proto ): Возвращает полный URL-адрес (с необязательной таблицей/строкой запроса) для этого заголовка. proto может быть указан для управления схемой результирующего URL: "http", "https", "relative" (по умолчанию) или "canonical".

• localUrl( query ): Возвращает локальный URL-адрес (с необязательной таблицей/строкой запроса) для этого заголовка.
• canonicalUrl( query ): Возвращает канонический URL-адрес (с необязательной таблицей/строкой запроса) для этого заголовка.

• getContent(): Возвращает (неразпарсеное) содержимое страницы или nil, если страницы нет. Страница будет записана как встраивание.

• pageLang: A language object for the title's page content language, which defaults to the wiki's content language. This is expensive.

Объекты Title могут сравниваться с использованием реляционных операторов. tostring( title ) вернет title.prefixedText.

Обратите внимание, что доступ к любому ресурсоёмкому полю в объекте title трактуется как ссылка на эту страницу (как показано, например, на странице Special:WhatLinksHere). Использование метода getContent() объекта title или обращение к полю redirectTarget считается как «включение», а обращение к полям объекта title file или fileExists — как «ссылка на файл».

Файл metadata

Объекты заголовка, представляющие страницу в пространстве имен Файла или Медиа, будут иметь свойство, называемое file. Это ресурсоёмкое свойство. Это таблица, структурированная следующим образом:

• exists: Существует ли файл. Это будет записано как использование изображения. Свойство fileExists в объекте Title существует по соображениям обратной совместимости и является псевдонимом для этого свойства. Если это значение равно false, все остальные свойства файла будут равны nil.

• width: Ширина файла. Если файл содержит несколько страниц, это ширина первой страницы.
• height: Высота файла. Если файл содержит несколько страниц, это высота первой страницы.

• pages: Если формат файла поддерживает несколько страниц, это таблица, содержащая таблицы для каждой страницы файла; в противном случае будет nil. Оператор # можно использовать для получения количества страниц в файле. Каждая отдельная таблица страниц содержит свойства ширины и высоты.

• size: Размер файла в байтах.

• mimeType: Список MIME-типов файла.

• length: Длина (длительность) медиафайла в секундах. Ноль для типов медиафайлов, которые не поддерживают длину.

Ресурсоёмкие свойства

Свойства id, isRedirect, exists и contentModel требуют извлечения данных о заголовке из базы данных. По этой причине значение количества ресурсоёмких функций увеличивается при первом обращении к одному из них для страницы, отличной от текущей страницы. Последующие обращения к любому из этих свойств для этой страницы не приведут к повторному увеличению количества ресурсоёмких функций.

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

Библиотека URI

mw.uri.encode

mw.uri.encode( string, enctype )

Процентное кодирование строки. Тип по умолчанию, "QUERY", кодирует пробел как '+' для использования в строках запроса; "PATH" кодирует пробел как %20; и "WIKI" кодирует пробел как '_'.

Обратите внимание, что формат "WIKI" не является полностью обратимым, поскольку как пробелы, так и символы подчеркивания кодируются как "_".

mw.uri.decode

mw.uri.decode( string, enctype )

Процентное декодирование строки. Тип по умолчанию, "QUERY", декодирует '+' в пробел; "PATH" не выполняет никакого дополнительного декодирования; и "WIKI" декодирует '_' в пробел.

mw.uri.anchorEncode

mw.uri.anchorEncode( string )

Кодирует строку для использования во фрагменте URI MediaWiki.

mw.uri.buildQueryString

mw.uri.buildQueryString( table )

Кодирует таблицу как строку запроса URI. Ключами должны быть строки; значениями могут быть строки или числа, таблицы-последовательности или логическое значение false.

mw.uri.parseQueryString

mw.uri.parseQueryString( s, i, j )

Декодирует строку запроса s в таблицу. Ключи в строке без значений будут иметь значение false; ключи, повторенные несколько раз, будут иметь таблицы-последовательности в качестве значений; а другие будут иметь строки в качестве значений.

Необязательные числовые аргументы i и j могут использоваться для указания подстроки s, подлежащей синтаксическому анализу, а не всей строки. i - это позиция первого символа подстроки, значение по умолчанию равно 1. j - это позиция последнего символа подстроки, значение по умолчанию равно длине строки. Как i, так и j могут быть отрицательными, как в string.sub.

mw.uri.canonicalUrl

mw.uri.canonicalUrl( page, query )

Возвращает объект URI для канонического URL для страницы с необязательной строкой запроса/таблицей.

mw.uri.fullUrl

mw.uri.fullUrl( page, query )

Возвращает объект URI для полного URL для страницы с необязательной строкой запроса/таблицей.

mw.uri.localUrl

mw.uri.localUrl( page, query )

Возвращает объект URI для локального URL для страницы с необязательной строкой запроса/таблицей.

mw.uri.new

mw.uri.new( string )

Создает новый объект URI для переданной строки или таблицы. Возможные поля для таблицы приведены в описании объектов URI.

mw.uri.validate

mw.uri.validate( table )

Проверяет переданную таблицу (или объект URI). Возвращает логическое значение, указывающее, была ли таблица допустимой, и в случае ошибки - строку, объясняющую, какие проблемы были обнаружены.

Объект URI

Объект URI содержит следующие поля, некоторые или все из которых могут быть равны nil:

• protocol: Строка протокол/схема
• user: Строка пользователь
• password: Строка пароль
• host: Строка имя хоста
• port: Целочисленный номер порта
• path: Строка путь
• query: Таблица, как в mw.uri.parseQueryString
• fragment: Строка фрагмент.

Также доступны следующие свойства:

• userInfo: Строка - пользователь и пароль
• hostPort: Строка - хост и порт
• authority: Строка - пользователь, пароль, хост и порт
• queryString: Строковая версия таблицы запроса
• relativePath: Строка - путь, строка запроса, фрагмент

tostring() выдаст строку URI.

Методами объекта URI являются:

mw.uri:parse

uri:parse( string )

Преобразует строку в текущий объект URI. Все поля, указанные в строке, будут заменены в текущем объекте; поля, которые не указаны, сохранят свои старые значения.

mw.uri:clone

uri:clone()

Создает копию объекта URI.

mw.uri:extend

uri:extend( parameters )

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

Библиотека Ustring

Библиотека Ustring предназначена для прямого переопределения стандартной библиотеки String, за исключением того, что методы оперируют символами в строках, закодированных в UTF-8, а не байтами.

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

mw.ustring.maxPatternLength

Максимально допустимая длина шаблона в байтах.

mw.ustring.maxStringLength

Максимально допустимая длина строки в байтах.

mw.ustring.byte

mw.ustring.byte( s, i, j )

Возвращает отдельные байты; идентично string.byte().

mw.ustring.byteoffset

mw.ustring.byteoffset( s, l, i )

Возвращает байтовое смещение символа в строке. Значение по умолчанию как для l, так и для i равно 1. i может быть отрицательным, в этом случае отсчет ведется с конца строки.

Символ при l == 1 является первым символом, начинающимся с байта i или после него; символ при l == 0 является первым символом, начинающимся с или перед ним байта i. Обратите внимание, что это может быть один и тот же символ. Относительно них вычисляются большие или меньшие значения l.

mw.ustring.char

mw.ustring.char( ... )

Очень похоже на string.char(), за исключением того, что целые числа являются кодовыми точками Юникода, а не байтовыми значениями.

local value = mw.ustring.char( 0x41f, 0x440, 0x438, 0x432, 0x435, 0x442, 0x21 ) -- value теперь равно 'Привет!'

mw.ustring.codepoint

mw.ustring.codepoint( s, i, j )

Очень похоже на string.byte(), за исключением того, что возвращаемые значения являются кодовыми точками Юникода; а смещения - символами, а не байтами.

mw.ustring.find

mw.ustring.find( s, pattern, init, plain )

Очень похоже на string.find(), за исключением того, что шаблон расширен, как описано в разделе шаблоны Ustring, и смещение init указано в символах, а не в байтах.

mw.ustring.format

mw.ustring.format( format, ... )

Идентично string.format(). Ширина и точность строк выражаются в байтах, а не в кодовых точках.

mw.ustring.gcodepoint

mw.ustring.gcodepoint( s, i, j )

Возвращает три значения для перебора кодовых точек в строке. i по умолчанию равно 1, а j -1. Это необходимо для использования в итеративной форме цикла for:

for codepoint in mw.ustring.gcodepoint( s ) do
     -- блок
end

mw.ustring.gmatch

mw.ustring.gmatch( s, pattern )

Очень похоже на string.gmatch(), за исключением того, что шаблон расширен, как описано в разделе шаблоны Ustring.

Known bug - When used with a pattern which can match the empty string, the function will get stuck in an infinite loop. For example, the following loop never terminates:

for capture in mw.ustring.gmatch( "foo bar", ".*" ) do
     -- block
end

mw.ustring.gsub

mw.ustring.gsub( s, pattern, repl, n )

Очень похоже на string.gsub(), за исключением того, что шаблон расширен, как описано в разделе шаблоны Ustring.

Известные ошибки: Когда repl является таблицей, можно использовать числа в качестве ключей вместо строк (например, для замены экземпляров "5" в строке будет использоваться значение в ключе [5] или ["5"]); таким образом, выходные данные не являются предсказуемыми, если они имеют разные (отличные от нуля) значения. Это не проблема для string.gsub(), который игнорирует любые числа в качестве ключей.

mw.ustring.isutf8

mw.ustring.isutf8( string )

Возвращает true, если строка имеет кодировку UTF-8, false, если нет.

mw.ustring.len

mw.ustring.len( string )

Возвращает длину строки в кодовых точках или nil, если строка не соответствует кодировке UTF-8.

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

mw.ustring.lower

mw.ustring.lower( string )

Очень похоже на string.lower(), за исключением того, что преобразуются все символы со строчных букв в прописные в Юникоде.

Если также загружена библиотека Language, то вместо этого будет вызван lc() для языкового объекта по умолчанию.

mw.ustring.match

mw.ustring.match( s, pattern, init )

Очень похоже на string.match(), за исключением того, что шаблон расширен, как описано в разделе шаблоны Ustring, и смещение init указано в символах, а не в байтах.

mw.ustring.rep

mw.ustring.rep( string, n )

Идентично string.rep().

mw.ustring.sub

mw.ustring.sub( s, i, j )

Очень похоже на string.sub(), за исключением того, что смещения являются символами, а не байтами.

mw.ustring.toNFC

mw.ustring.toNFC( string )

Преобразует строку в нормализованную форму С (также известная как Каноническая композиция (NFC)). Возвращает nil, если строка не соответствует кодировке UTF-8.

mw.ustring.toNFD

mw.ustring.toNFD( s )

Преобразует строку в нормализованную форму D (также известная как Каноническая декомпозиция (NFD)). Возвращает nil, если строка не соответствует кодировке UTF-8.

mw.ustring.toNFKC

mw.ustring.toNFKC( s )

Преобразует строку в нормализованную форму KC (также известная как Совместимая композиция (NFKC)). Возвращает nil, если строка не соответствует кодировке UTF-8.

mw.ustring.toNFKD

mw.ustring.toNFKD( s )

Преобразует строку в нормализованную форму KD (также известная как Совместимая декомпозиция (NFKD)). Возвращает nil, если строка не соответствует кодировке UTF-8.

mw.ustring.upper

mw.ustring.upper( s )

Очень похоже на string.upper(), за исключением того, что все символы с определениями верхнего регистра преобразуются в нижний регистр в Юникоде.

Если также загружена библиотека Language, то вместо этого будет вызван uc() для языкового объекта по умолчанию.

Шаблоны Ustring

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

• %a: представляет все символы с общей категорией "Буква".
• %c: представляет все символы с общей категорией "Управляющие символы".
• %d: представляет все символы с общей категорией "Число, десятичная цифра".
• %l: представляет все символы с общей категорией "Строчная буква".
• %p: представляет все символы с общей категорией "Знаки препинания".
• %s: представляет все символы с общей категорией "Пробельные символы", включая такие символы как - табуляция (\t), перевод строки (\n), возврат каретки (\r), вертикальная табуляция (\v) и перевод страницы (\f).
• %u: представляет все символы с общей категорией "Заглавная буква".
• %w: представляет все символы с общей категорией "Буква" или "Десятичное число".
• %x: добавляет полноразмерные символьные версии шестнадцатеричных цифр.

Как и в паттернах библиотеки String, %A, %C, %D, %L, %P, %S, %U, %W и %X здесь представляет дополнительный набор («все символы без указания общей категории»).

Во всех случаях символы интерпретируются как символы Юникода, а не байты, поэтому диапазоны, такие как [０-９], шаблоны, такие как %b«», и квантификаторы, применяемые к многобайтовым символам, будут работать корректно. Пустые захваты (группы) будут фиксировать позицию в кодовых точках, а не в байтах.

Известные ограничения: В отличие от шаблонов библиотеки String, шаблоны библиотеки Ustring имеют максимальную длину 10 000 байт. Если шаблон превышает эту длину, функция Ustring выдаст ошибку. Поскольку библиотека String имеет свой собственный максимум в 32 захвата (группы) (в отличие от библиотеки Ustring), следовательно, невозможно использовать шаблон, который превышает оба ограничения, поскольку он будет несовместим с обеими библиотеками.

Примечание: 9 ASCII символов, $, +, <, =, >, ^, `, |, ~, могут совпадать с %p в библиотеке строк, но не в библиотеке Ustring, поскольку Юникод классифицирует их как символы, а не как знаки препинания.

Загружаемые библиотеки

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

Библиотека bit32

Это эмуляция библиотеки Lua 5.2 bit32 может быть загружена с помощью:

 bit32 = require( 'bit32' )

Библиотека bit32 предоставляет побитовые операции для 32-разрядных целых чисел без знака. Входные числа усекаются до целых чисел (неопределенным образом) и уменьшаются по модулю 2³² таким образом, что значение находится в диапазоне от 0 до 2³²-1; возвращаемые значения также находятся в этом диапазоне.

Когда биты пронумерованы (как в bit32.extract()), 0 является наименее значимым битом (бит со значением 2⁰), а 31 - наиболее значимым (бит со значением 2³¹).

bit32.band

bit32.band( ... )

Возвращает побитовое И из своих аргументов: результат имеет установленный бит только в том случае, если этот бит задан во всех аргументах.

Если заданы нулевые аргументы, то в результате будут установлены все биты.

bit32.bnot

bit32.bnot( x )

Возвращает побитовое отрицание из x.

bit32.bor

bit32.bor( ... )

Возвращает побитовое ИЛИ из своих аргументов: результат имеет установленный бит, если этот бит задан в любом из аргументов.

Если заданы нулевые аргументы, то в результате все биты будут исходными.

bit32.btest

bit32.btest( ... )

Эквивалентно bit32.band( ... ) ~= 0

bit32.bxor

bit32.bxor( ... )

Возвращает побитовое исключающее ИЛИ своих аргументов: результат имеет установленный бит, если этот бит задан в нечетном числе аргументов.

Если заданы нулевые аргументы, то в результате все биты будут исходными.

bit32.extract

bit32.extract( n, field, width )

Извлекает биты width из n, начиная с бита field. Доступ к битам за пределами диапазона от 0 до 31 выдаст ошибку.

Если не указано, значение по умолчанию для width равно 1.

bit32.replace

bit32.replace( n, v, field, width )

Заменяет биты width в n, начиная с бита field, на на меньшие биты width из v. Доступ к битам за пределами диапазона от 0 до 31 выдаст ошибку.

Если не указано, значение по умолчанию для width равно 1.

bit32.lshift

bit32.lshift( n, disp )

Возвращает число n побитово сдвинутое на disp бит влево. Это логический сдвиг: вставленные биты равны 0. Как правило, это эквивалентно умножению на 2^disp.

Обратите внимание, что смещение более 31 приведет к 0.

bit32.rshift

bit32.rshift( n, disp )

Возвращает число n побитово сдвинутое на disp бит вправо. Это логический сдвиг: вставленные биты равны 0. Как правило, это эквивалентно умножению на 2^disp.

Обратите внимание, что смещение более 31 приведет к 0.

bit32.arshift

bit32.arshift( n, disp )

Возвращает число n побитово сдвинутое на disp бит вправо. Это арифметический сдвиг: если disp положительное значение, вставленные биты будут такими же, как бит 31 в исходном числе.

Обратите внимание, что смещение более 31 приведет к 0 или 4294967295.

bit32.lrotate

bit32.lrotate( n, disp )

Возвращает число n циклически сдвинутое на disp бит влево.

Обратите внимание, что переходы зациклены и эквивалентны модулю 32 (disp % 32): переход на 32 совпадает с переходом на 0, 33 совпадает с 1 и так далее.

bit32.rrotate

bit32.rrotate( n, disp )

Возвращает число n циклически сдвинутое на disp бит вправо.

Обратите внимание, что переходы зациклены и эквивалентны модулю 32 (disp % 32): переход на 32 совпадает с переходом на 0, 33 совпадает с 1 и так далее.

Библиотека libraryUtil

Эта библиотека содержит методы, полезные при реализации библиотек Scribunto. Она может быть загружена с помощью:

 libraryUtil = require( 'libraryUtil' )

libraryUtil.checkType

libraryUtil.checkType( name, argIdx, arg, expectType, nilOk )

Выдает ошибку, если type( arg ) не соответствует expectType. Кроме того, ошибка не возникнет, если arg является nil, а nilOk имеет значение true.

name - это имя вызывающей функции, а argIdx - позиция аргумента в списке аргументов. Они используются при форматировании сообщения об ошибке.

libraryUtil.checkTypeMulti

libraryUtil.checkTypeMulti( name, argIdx, arg, expectTypes )

Выдает ошибку, если type( arg ) не соответствует ни одной из строк в массиве expectTypes.

Это относится к аргументам, которые имеют более одного допустимого типа.

libraryUtil.checkTypeForIndex

libraryUtil.checkTypeForIndex( index, value, expectType )

Выдает ошибку, если type( value ) не соответствует expectType.

Это предназначено для использования при реализации __newindex метаметода.

libraryUtil.checkTypeForNamedArg

libraryUtil.checkTypeForNamedArg( name, argName, arg, expectType, nilOk )

Выдает ошибку, если type( arg ) не соответствует expectType. Кроме того, ошибка не возникнет, если arg является nil, а nilOk имеет значение true.

Это предназначено для использования в качестве эквивалента libraryUtil.checkType() в методах, вызываемых с использованием синтаксиса "именованный аргумент" Lua, func{ name = value }.

libraryUtil.makeCheckSelfFunction

libraryUtil.makeCheckSelfFunction( libraryName, varName, selfObj, selfObjDesc )

Это предназначено для использования при реализации "методов" в таблицах объектов, которые предназначены для вызова с помощью синтаксиса obj:method(). Он возвращает функцию, которая должна вызываться перед всеми методами с аргументом self и именем метода, что вызовет ошибку, если этот объект self не является selfObj.

Эта функция обычно будет использоваться в библиотечной функции-конструкторе, например так:

 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

Модули "bit" и "hex" библиотеки luabit могут быть загружены с помощью:

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

Обратите внимание, что библиотека bit32 содержит те же операции, что и "luabit.bit", а операции в "luabit.hex" могут быть выполнены с использованием string.format() и tonumber().

Модуль "noki" библиотеки luabit недоступен, поскольку он совершенно бесполезен в Scribunto. Модуль "utf8" библиотеки luabit также недоступен, поскольку он был сочтен избыточным для библиотеки Ustring.

strict

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

 require( 'strict' )

На многих вики-ресурсах Викимедиа это ранее было реализовано в модуле Модуль:No globals, который был заменен на phab:T209310. Он частично заимствован из strict.lua.

ustring

Серверная часть (бэкенд, backend) pure-Lua для библиотеки String может быть загружена с помощью:

 ustring = require( 'ustring' )

Во всех случаях вместо этого следует использовать библиотеку Ustring (mw.ustring), поскольку это заменяет многие из более медленных и требующих больших затрат памяти операций обратными вызовами в PHP-коде.

Библиотеки расширений

Некоторые расширения MediaWiki предоставляют дополнительные библиотеки Scribunto. Они также расположены в таблице mw, обычно в таблице mw.ext, однако они присутствуют только при установке определенных расширений (в дополнение к самому расширению Scribunto).

Такие расширения используют предоставляемые Scribunto перехватчики:

• ScribuntoExternalLibraries
• ScribuntoExternalLibraryPaths

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

mw.wikibase

Wikibase Client предоставляет доступ к локализуемым структурированным данным, в первую очередь к Викиданным. См. docs_topics_lua.html и Extension:Wikibase Client/Lua .

mw.wikibase.lexeme

Расширение WikibaseLexeme предоставляет доступ к лексемным объектам Викибазы. Это поддерживается Викиданные:Лексикографические данные. See md_docs_2topics_2lua.html and Extension:WikibaseLexeme/Lua .

mw.wikibase.mediainfo

Расширение WikibaseMediaInfo предоставляет доступ к объектам Wikibase MediaInfo. См. WikibaseMediaInfo/Lua . Это поддерживается Структурированные данные на Викискладе. См. Структурированные данные/Lua.

mw.bcmath

BCmath предоставляет Lua-модулям арифметику произвольной точности. См. документацию по BCmath по ссылке «LDoc» в BCmath § Usage.

mw.smw

Semantic Scribunto обеспечивает встроенную поддержку Scribunto для расширения Semantic MediaWiki .

mw.ext.data

JsonConfig предоставляет доступ к локализуемым табличным и картографическим данным. См. JsonConfig/Tabular . Tabular Data и GeoJSON Данные для географических карт поддерживаются в пространстве имен «Data:» на сайте Commons.

• mw.ext.data.get( pagename )

mw.ext.cargo

Cargo предоставляет средство для запроса своего хранилища данных из Lua. См. Extension:Cargo/Other features#Lua support .

mw.ext.cattools

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

mw.ext.FlaggedRevs

FlaggedRevs предоставляет средство для доступа к настройкам стабильности страницы из Lua.

mw.ext.TitleBlacklist

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

mw.ext.ParserFunctions

ParserFunctions предоставляет средства из Lua для вычисления выражений таким же образом, как и функция парсера на основе PHP #expr .

mw.ext.proofreadPage

Proofread Page предоставляет доступ к пространствам имен индексов и страниц. См. Extension:Proofread Page/Lua reference . Это подтверждается Wikisource:ProofreadPage. См. Help:Extension:ProofreadPage .

mw.ext.articlePlaceholder

ArticlePlaceholder предоставляет средство для переопределения рендеринга Викибазы по умолчанию из Lua. См. Extension:ArticlePlaceholder/Module:AboutTopic .

mw.ext.externalData

ExternalData предоставляет средство для получения структурированных данных из Интернета с помощью Lua. См. Extension:External Data/Lua .

mw.ext.UnlinkedWikibase

См. UnlinkedWikibase .

• mw.ext.UnlinkedWikibase.getEntity( id )
• mw.ext.UnlinkedWikibase.query( sparql )

mw.ext.seo

WikiSEO предоставляет средство для настройки SEO-данных для текущей страницы. См. Extension:WikiSEO#Usage in lua modules.

mw.slots

WSSlots предоставляет ряд функций Lua для работы со слотами MCR:

• mw.slots.slotContent(slotName, pageName)
• mw.slots.slotTemplates(slotName, pageName) (deprecated)
• mw.slots.slotContentModel(slotName, pageName)
• mw.slots.slotData(slotName, pageName)

Отличия от стандартного Lua

Измененные функции

Следующие функции были изменены:

setfenv()

getfenv()

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

getmetatable()

Работает только с таблицами, чтобы предотвратить несанкционированный доступ к родительским средам.

tostring()

Адреса указателей таблиц и функций не указаны. Это сделано для того, чтобы затруднить использование уязвимостей, связанных с повреждением памяти (exploit).

pairs()

ipairs()

Добавлена поддержка метаметодов __pairs и __ipairs (добавлено в Lua 5.2).

pcall()

xpcall()

Некоторые внутренние ошибки не могут быть перехвачены.

require()

Может извлекать определенные встроенные модули, распространяемые с помощью Scribunto, а также модули, присутствующие в пространстве имен модулей wiki. Для извлечения модулей wiki используйте полное имя страницы, включая пространство имен. Иным образом невозможно получить доступ к локальной файловой системе.

Удаленные функции и пакеты

Следующие пакеты в основном удалены. Доступны только те функции, которые перечислены в списке:

package.*

Доступ к файловой системе и библиотеке C был удален. Доступные функции и таблицы следующие:

package.loaded

package.preload

package.loaders

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

package.seeall()

os.*

Здесь есть некоторые небезопасные функции, такие как os.execute(), которые не могут быть разрешены. Доступными функциями являются:

os.clock()

os.date()

os.difftime()

os.time()

debug.*

Большинство функций небезопасны. Доступными функциями являются:

debug.traceback()

Следующие функции и пакеты недоступны:

collectgarbage()

module()

coroutine.*

Нам не известно ни об одном приложении, поэтому оно не проверялось на предмет безопасности.

dofile()

loadfile()

io.*, file.*

Разрешает доступ к локальной файловой системе, что небезопасно.

load()

loadstring()

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

print()

Это обсуждалось на wikitech-l, и было решено, что его следует убрать в пользу возвращаемых значений, чтобы улучшить качество кода. При необходимости mw.log() может быть использован для вывода информации на консоль отладки.

string.dump()

Может предоставлять доступ к личным данным из родительской среды.

Дополнительные предостережения

Ссылочные структуры данных

Циклические структуры данных и структуры данных, в которых один и тот же узел может быть достигнут более чем одним путем, не могут быть корректно отправлены в PHP. Попытка сделать это приведет к неопределенному поведению. Это включает в себя (но не ограничивается этим) возврат таких структур данных из модуля, вызываемого с помощью {{#invoke:}}, и передачу таких структур данных в качестве параметров библиотечным функциям Scribunto, которые реализованы как обратные вызовы в PHP.
Такие структуры данных могут свободно использоваться в Lua, в том числе в качестве возвращаемых значений модулей, загружаемых с помощью mw.loadData().

Написание библиотек Scribunto

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

Библиотека Scribunto обычно состоит из пяти частей:

• PHP-часть библиотеки.
• Lua-часть библиотеки.
• PHP-часть тестовых примеров.
• Lua-часть тестовых примеров.
• Документация.

Хорошим примером могут служить существующие библиотеки.

Библиотека

PHP-часть библиотеки - это класс, который должен расширять Scribunto_LuaLibraryBase. Смотрите документацию для этого класса для получения подробной информации о реализации. В расширении Scribunto этот файл должен быть помещен в engines/LuaCommon/NameLibrary.php, а сопоставление добавлено в Scribunto_LuaEngine::$libraryClasses. Другие расширения должны использовать ScribuntoExternalLibraries. В любом случае ключ должен соответствовать имени модуля Lua ("mw.name" для библиотек в Scribunto или "mw.ext.name" для библиотек расширений).

Lua-часть библиотеки настраивает таблицу, содержащую функции, которые могут быть вызваны из Lua-модулей. В расширении Scribunto файл должен быть помещен в engines/LuaCommon/lualib/mw.name.lua. Обычно этот файл должен содержать примерно такой шаблон:

local object = {}
local php

function object.setupInterface( options )
    -- Удаление настроек функции
    object.setupInterface = nil

    -- Копирование обратных вызовов PHP в локальную переменную и удаление глобальной
    php = mw_interface
    mw_interface = nil

    -- Выполнение каких-либо других настроек здесь

    -- Установка mw в глобальной области
    mw = mw or {}
    mw.ext = mw.ext or {}
    mw.ext.NAME = object

    -- Отображение результата загрузки
    package.loaded['mw.ext.NAME'] = object
end

return object

Модуль в engines/LuaCommon/lualib/libraryUtil.lua (загрузите его с помощью local util = require('libraryUtil')) содержит некоторые функции, которые могут быть полезны.

Обязательно запускайте тестовые примеры Scribunto с загруженной библиотекой, даже если ваша библиотека сама по себе не предоставляет никаких тестовых примеров. Стандартные тестовые примеры включают тесты для таких вещей, как библиотеки, добавляющие неожиданные глобальные переменные. Кроме того, если библиотека загружена с помощью PHP, любые повышающие значения, которые есть у ее Lua-функций, не будут сбрасываться между вызовами функций парсера #invoke. Необходимо позаботиться о том, чтобы модули не могли злоупотреблять этим для передачи информации между вызовами функций парсера #invokes.

Тестовые примеры

Расширение Scribunto включает базовый класс для тестовых случаев, Scribunto_LuaEngineTestBase, который будет запускать тесты как для движков LuaSandbox , так и для LuaStandalone . Тестовый пример библиотеки должен расширять этот класс и не должен переопределять static function suite(). В расширении Scribunto тестовый пример должен быть в tests/engines/LuaCommon/NameLibraryTest.php и добавляться в массив в ScribuntoHooks::unitTestsList() (в common/Hooks.php); расширения должны добавлять тестовый пример в свою собственную функцию перехвата UnitTestsList , при условии, что задано значение $wgAutoloadClasses['Scribunto_LuaEngineTestBase'].

В большинстве случаев все, что необходимо для создания тестового примера:

class ClassNameTest extends Scribunto_LuaEngineTestBase {
    protected static $moduleName = 'ClassNameTest';

    function getTestModules() {
         return parent::getTestModules() + array(
             'ClassNameTest' => __DIR__ . '/ClassNameTests.lua';
         );
    }
}

Это загрузит файл ClassNameTests.lua, как если бы это была страница "Module:ClassNameTests", ожидая, что он вернет объект со следующими свойствами:

• count: целое число (Integer), количество тестов
• provide( n ): функция, которая возвращает три значения: n, имя теста n и строку, которая является ожидаемым результатом для теста n.
• run( n ): функция, которая запускает тест n и возвращает одну строку.

Если getTestModules() объявлен, как показано, то доступен "Module:Test Framework", который предоставляет множество полезных вспомогательных методов. Если это используется, ClassNameTests.lua будет выглядеть примерно так:

local testframework = require 'Module:TestFramework'

return testframework.getTestProvider( {
    -- Тесты проходят здесь
} )

Каждый тест сам по себе представляет собой таблицу со следующими свойствами:

• name: Название теста.
• func: Функция для выполнения.
• args: Необязательная таблица аргументов для передачи в функцию.
• expect: Ожидаемые результаты.
• type: "тип" теста (необязательный аргумент), по умолчанию - "Normal".

Тип управляет форматом expect и способом вызова func. Включенными типами являются:

• Normal: expect - это таблица возвращаемых значений или строка, если тест должен выдать ошибку. func просто вызывается.
• Iterator: expect - это таблица таблиц возвращаемых значений. func вызывается как итерируемая в цикле, и возвращаемые значения каждой итерации накапливаются.
• ToString: Как "Normal", за исключением того, что каждое возвращаемое значение передается через tostring().

Тестовые примеры в другом расширении

Существует (по крайней мере) два способа запуска тестов PHPUnit:

1. Запуск phpunit в ядре, позволяя tests/phpunit/suites/ExtensionsTestSuite.php найти тесты расширения, используя хук UnitTestsList . Если все имена тестовых классов вашего расширения содержат уникальный компонент (например, имя расширения), опция --filter может использоваться для запуска только тестов вашего расширения.
2. Запуск phpunit в каталоге расширений, где он найдет любой файл, заканчивающийся на "Test.php".

Любой из них будет работать нормально, если Scribunto загружен в LocalSettings.php. И метод #1 легко сработает, если Scribunto не загружен, поскольку можно легко записать хук UnitTestsList, чтобы избежать возврата теста Scribunto, когда значение $wgAutoloadClasses[ 'Scribunto_LuaEngineTestBase' ] не установлено.

Но Jenkins использует метод #2. Чтобы Jenkins мог правильно запускать тесты, вам нужно будет добавить Scribunto в качестве зависимости для вашего расширения. См. Gerrit change 56570 для примера того, как это делается.

Если по какой-то причине вам нужно, чтобы тесты можно было запускать с использованием метода #2 без загрузки Scribunto, одним из обходных путей является добавление этой проверки в начало вашего файла модульного теста:

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

Документация

Модули, включенные в Scribunto, должны включать документацию в разделе библиотеки Scribunto выше. Библиотеки расширений должны включать документацию на подстранице своей собственной страницы расширений и ссылку на эту документацию из подраздела Библиотеки расширений выше.

См. также

• Lua (язык программирования)

Лицензия

Это руководство является производным от Lua 5.1 справочного руководства, которое доступно по лицензии MIT.

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