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

Базовая библиотека

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

Глобальные переменные

_G [table]
Содержит глобальный контекст (_G._G = _G). Значение этой переменной не используется интерпретатором и его изменение ни на что не влияет.
_VERSION [string]
Содержит номер версии интерпретатора.
arg [table]
Массив аргументов, переданных при запуске скрипта. Аргументы занумерованы от 1.

Базовые механизмы

type(v)
Возвращает тип аргумента в виде строки. Возможные варианты возвращаемого значения: "nil", "number", "string", "boolean", "table", "function", "thread", "userdata".
tostring(v)
Преобразует аргумент любого типа в строку. Если в мета-таблице v есть поле __tostring, то значение этого поля интерпретируется как функция-конвертор и возвращается результат ее вызова с аргументом v.
tonumber(v [, base])
Пытается конвертировать аргумент в число. Если конвертирование не удается, то возвращает nil. Необязательный аргумент задает основание системы счисления (от 2 до 36). Для случая base = 10 допускается присутствие дробной части и порядка, для остальных значений число интерпретируется как целое беззнаковое.

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

print(e1, e2, …)
Печатает значения аргументов на stdout, используя для конвертирования в строку функцию tostring() и разделяя их табуляциями. В конце выводится перевод строки. Эта функция не предназначена для форматного вывода, а только для быстрого (отладочного) вывода значений переменных.
error(message [, level])
завершает выполнение последней функции, вызванной в защищенном режиме с сообщением об ошибке message. Необязательный параметр level определяет место возникновения ошибки. Если level = 1 (умалчиваемое значение), то местом ошибки считается место вызова функции error(). Если level = 2, то местом ошибки считается место вызова функции, вызвавшей функцию error() и т.д.
assert(val [, message])
Если val имеет значение false или nil, то генерирует ошибку с необязательным сообщением message. В противном случае возвращает значение val. Если message отсутствует, то используется сообщение вида "assertion failed!".
pcall(f, x1, x2, …)
Вызывает функцию f с аргументами x1, x2, … в защищенном режиме. Возвращает статус успешности выполнения. В случае успешного выполнения дополнительно возвращает значения, возвращаемые выполненной функцией. При ошибке дополнительно возвращает сообщение об ошибке.

Управление таблицами

unpack(v)
Возвращает все элементы массива. Полагает, что элементы проиндексированы числами от 1.
next(t [, index])
Аргументы — таблица и значение индекса ее элемента. Возвращает следующее значение индекса и соответствующее значение. При вызове без второго аргумента (или со значением nil) возвращает первое значение индекса и соответствующее значение или nil если таблица пуста. При вызове для последнего значения индекса возвращает nil.
pairs(t)
Возвращает итератор next(), таблицу и nil. Возвращаемый итератор проходит таблицу по всем значениям индекса. Итератор возвращает текущий индекс и соответствующее значение.
ipairs(t)
Возвращает итератор, таблицу и 0. Возвращаемый итератор проходит таблицу по целочисленным индексам от значения 1 до первого индекса со значением nil. Итератор возвращает текущий индекс и соответствующее значение.

Управление мета-таблицами

getmetatable(obj)
Если объект не имеет мета-таблицы, то возвращает nil. Иначе, если в мета-таблице есть поле __metatable, то возвращает соответствующее значение. Иначе возвращает мета-таблицу объекта.
setmetatable(t, mt)
Устанавливает таблицу mt в качестве мета-таблицы для таблицы t. Если mt = nil, то удаляет мета-таблицу таблицы t. Если исходная мета-таблица содержит поле __metatable, генерирует ошибку.

Обход механизма метаметодов

rawequal(v1, v2)
Сравнивает объекты.
rawget(t, j)
Возвращает t[j].
rawset(t, j, v)
Выполняет присвоение t[j] = v.

Управление контекстом функций

getfenv([f])
Возвращает таблицу контекста функции f. Аргумент может быть числом, определяющим положение функции на стеке вызовов. Значение 1 соответствует функции, вызвавшей функцию getfenv(). Если f = 0, то возвращает глобальный контекст. Умалчиваемое значение f = 1. Если контекст содержит поле __fenv, то возвращается его значение.
setfenv(f, t)
Устанавливает таблицу t в качестве контекста для функции f. Аргумент может быть числом, определяющим положение функции на стеке вызовов. Значение 1 соответствует функции, вызвавшей функцию setfenv(). Если f = 0, то изменяет глобальный контекст текущего потока. Если исходный контекст содержит поле __fenv, то генерирует ошибку.

Загрузка и выполнение кода

loadstring(str [, name])
Загружает код из строки str и возвращает его как функцию. В случае ошибок при загрузке возвращает nil и сообщение об ошибке. Необязательный параметр name используется как имя кода в сообщениях об ошибках и отладочной информации. Для загрузки и выполнения кода из строки используется идиома assert(loadstring(s))().
loadfile(filename)
Загружает код из файла с именем filename и возвращает его как функцию. В случае ошибок при загрузке возвращает nil и сообщение об ошибке. Функция dofile(filename) эквивалентна выражению assert(loadfile(s))().
dofile(filename)
Выполняет код из файла с именем filename. Возвращает все значения, возвращенные выполненным кодом.
package.loadlib(filename, funcname)
Загружает динамическую библиотеку с именем filename и возвращает lua-функцию, соответствующую функции с именем funcname из этой библиотеки. В случае ошибки загрузки возвращает nil и сообщение об ошибке.
require(packagename)
Загружает и выполняет пакет. В первую очередь имя packagename ищется в таблице _LOADED уже загруженных пакетов. Если имя найдено, то возвращается значение, которое пакет возвратил при первой загрузке. В противном случае производится поиск пакета. Если глобальная переменная LUA_PATH содержит строку, то она используется в качестве пути. Иначе в качестве пути используется значение переменной LUA_PATH из окружения. Если такой переменной нет, то используется умалчиваемый путь ("?;?.lua"). Путь поиска представляет собой последовательность шаблонов, разделенных символом ';' (точка с запятой). Имя пакета подставляется в шаблон на место символа '?'. После выполнения пакета его имя и возвращенное значение прописываются в таблицу _LOADED. Возвращенное пакетом значение также возвращается функцией require(). Если пакет возвратил значение false (и только в этом случае), то прописывается и возвращается значение false. Во всех остальных случаях (даже если пакет возвратил значение nil или не возвратил значения) прописывается и возвращается значение true. Если в таблице _LOADED прописалось значение false, то при дальнейших вызовах функции require() пакет будет заново загружен. Если во время загрузки или выполнения произошла ошибка или если файл не найден, то функция генерирует ошибку.

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

collectgarbage(opt [, limit])
Общий интерфейс для управления сборщиком мусора.

Первый аргумент определяет выполняемое действие:

'stop'
Остановить сборщик мусора.
'restart'
Запустить сборщик мусора.
'collect'
Выполнить сборку мусора.
'count'
Вернуть размер используемой памяти в kb.

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

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

math математика
table таблицы
string строки
io ввод/вывод
os системные вызовы
debug средства отладки
coroutine сопрограммы

Математическая библиотека

Математическая библиотека содержит следующие функции:

math.abs math.acos math.asin math.atan math.atan2
math.ceil math.cos math.deg math.exp math.floor
math.log math.log10 math.max math.min math.fmod
math.pow math.rad math.sin math.sqrt math.tan
math.frexp math.ldexp math.random math.randomseed math.modf
math.sinh math.cosh math.tanh

Также определяются переменные math.pi и huge, содержащие значения соответствующих констант (M_PI и HUGE_VAL).

Функции math.deg() и math.rad() осуществляют преобразование между радианами и градусами.

Функции math.min() и math.max() возвращают минимальное и максимальное значение для произвольного числа аргументов.

Функция math.modf() возвращает целую и дробную части аргумента. Функция math.frexp() возвращает нормализованную мантиссу и показатель аргумента. Функция math.ldexp(m, e) строит число по мантиссе и показателю.

Функция math.fmod(x, y) возвращает остаток от деления x на y. Функция math.atan2(a, b) возвращает atan(a/b).

Функция math.random(), вызванная без аргументов, возвращает псевдослучайное число из интервала [0, 1). Эта же функция, вызванная с аргументом n возвращает целое псевдослучайное число из интервала [1, n]. Эта же функция, вызванная с двумя аргументами l, u возвращает целое псевдослучайное число из интервала [l, u]. Функция math.randomseed(n) устанавливает стартовое число генератора псевдослучайных чисел. Ее аргумент рассматривается как целое число. При запуске генератор всегда проинициализирован одинаково и выдает одинаковые последовательности. Для случайной стартовой установки можно использовать оператор

math.randomseed(os.time())

Дополнительно математическая библиотека определяет глобальную функцию с именем __pow() для бинарной операции возведения в степень (операция '^').

Управление таблицами

Эта библиотека поддерживает манипулирование таблицами как обычными массивами. В этом случае считается, что массив индексируется, начиная с 1. Длиной массива считается минимальное n такое, что t[n] ~= nil и t[n+1] == nil.

Вставка и удаление

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

Сортировка

table.sort(t [, comp])
Сортирует элементы таблицы в заданном порядке. Если задана функция comp, то она используется для сравнения элементов. Функция comp должна возвращать true, если первый аргумент меньше второго. После сортировки выполнено неравенство not comp(t[j+1], t[j]) Если функция сравнения не задана, то используется стандартный оператор '<'. Алгоритм сортировки не является устойчивым т.е. порядок равных элементов может измениться.

Другие функции

table.concat(t [, sep [, i [, j]]])
Возвращает значение t[i] .. sep .. t[i+1] … sep .. t[j]. По умолчанию sep равно пустой строке, i = 1, j = #t. При i > j возвращает пустую строку.

Обработка строк

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

Базовые операции

string.len()
Возвращает длину строки. Нулевые символы считаются входящими в строку.
string.rep(s, n)
Возвращает строку, состоящую из n копий строки s.
string.lower(s)
Возвращает копию строки, в которой символы приведены к нижнему регистру.
string.upper(s)
Возвращает копию строки, в которой символы приведены к верхнему регистру.
string.reverse(s)
Возвращает результат инверсии строки s.

Форматное преобразование

string.format(fmt, v1, v2, …)
Генерирует строку по форматной строке и аргументам по правилам, принятым в ANSI-C. Спецификаторы *, l, L, n, p, h не поддерживаются. Дополнительно введен спецификатор 'q', предназначенный для безопасного вывода строки таким образом, чтобы получить ее корректную запись с учетом правил экранирования символов, принятых в Lua. Спецификаторам c, d, E, e, f, g, G, i, o, u, X, x должны соответствовать числовые аргументы, а спецификаторам q, s — строковые. Спецификатор s не умеет выводить строки, содержащие нулевые символы.

Не поддержанный спецификатор '*' можно эмулировать конкатенацией: вместо %*g использовать выражение "%"..width.."g".

На практике имеет смысл использовать следующие спецификаторы

%d, %x, %X, %o целые числа
%f, %e, %g вещественные числа
%s, %q строки

Внутреннее представление

string.byte(s [, j])
Возвращает код символа в позиции j. По умолчанию j = 1.
string.char(n1, n2, …)
Возвращает строку, состоящую из символов с кодами n1, n2, ….

Поиск и замена

string.find(s, pat [, start [, plain]])
Ищет первое вхождение паттерна pat в строке s. Если паттерн найден, то функция возвращает позиции его начала и конца, в противном случае возвращается nil. Если паттерн содержит пометки, то их значения возвращаются как дополнительные значения. Необязательный аргумент start задает позицию, с которой начинается поиск (умалчиваемое значение 1). Если в аргументе plain передать значение true, то в паттерне специальные символы теряют свой специальный смысл.
string.match(s, pat [, start])
Ищет первое вхождение паттерна pat в строку s. Если паттерн не содержит пометок, то функция возвращает подстроку, соответствующую паттерну. Если паттерн содержит пометки, то функция возвращает подстроки, соответствующие пометкам. Если паттерн не найден, то функция возвращает nil. Необязательный аргумент start задает позицию, с которой начинается поиск (умалчиваемое значение 1).
string.gmatch(s, pat)
Возвращает функцию-итератор, которая на каждой итерации возвращает подстроку, соответствующую паттерну. Если паттерн содержит пометки, то возвращается набор значений пометок.
string.sub(s, i [, j])
Возвращает подстроку, начиная с позиции i и до позиции j включительно. Оба индекса могут быть отрицательными. Умалчиваемое значение j = -1.
string.gsub(s, pat, repl [, n])
Возвращает копию строки s, в которой все вхождения паттерна pat заменены на строку, заданную аргументом repl. Дополнительно возвращается число сделанных замен. Если repl — строка, то вхождения паттерна заменяются на строку repl, в которой все вхождения последовательности символов вида '%n' (n = 1…9) заменяются на значения группы с соответствующим номером. Если repl — функция, то для каждого вхождения паттерна эта функция вызывается со значениями групп, переданными в качестве аргументов, а возвращаемое значение используется для замены. Если в паттерне нет групп, то в функцию передается вся подстрока, соответствующая паттерну. Если функция возвращает строку, то подставляется эта строка, в противном же случае (false или nil) замена не производится. Необязательный аргумент n задает максимальное число производимых замен.

Паттерны

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

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

'%z' нулевой символ
'%s' пробельный символ
'%l' буква в нижнем регистре
'%u' буква в верхнем регистре
'%a' буква
'%d' цифра
'%x' шестнадцатеричная цифра
'%w' буква или цифра
'%p' символ пунктуации
'%с' управляющий символ

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

В паттернах большинство символов имеют обычный смысл, кроме символов %.^$()*-+?[], интерпретируемых специальным образом. Символы, имеющие специальный смысл экранируются символом '%'.

'%' экранирование или придание специального смысла
'.' любой символ
'^' начало строки
'$' конец строки
'(…)' группа
'%d' (d — цифра) группа с номером d
'*' 0 или больше символов
'-' 0 или больше символов (кратчайшее соответствие)
'+' 1 или больше символов
'?' 0 или 1 символ
'[…]' множество символов
'[^…]' отрицание множества символов
%bxy участок строки между сбалансированными символами

Во всех случаях для символов из класса '%W' символ '%' означает экранирование символа. Аналогично для символов из класса '%w' символ '%' всегда означает придание символу специального смысла.

Внутри множества символов можно перечислять символы, классы символов (например '%a') и диапазоны символов (например '0-7'). Символ '-' внутри множества приобретает специальный смысл. Аналогично символ '^', следующий непосредственно за символом '[' означает переход к дополнительному множеству.

паттерн '%bxy' служит для выделения участка строки, ограниченного сбалансированными символами 'x' и 'y' .

Участки паттерна могут быть заключены в круглые скобки. Такие участки называются группами. Участок строки, соответствующий группе, называется значением группы. Паттерн '%d' (d — цифра) соответствует значению группы с номером d. Такой паттерн можно использовать как внутри самого регулярного выражения, так и в строке замены. Пустая группа вида '()' получает в качестве значения свою позицию в строке.

Ввод/вывод

Пакет io поддерживает две модели ввода/вывода. В первой модели используются умалчиваемые потоки ввода и вывода, которые можно назначить на заданные файлы. Во второй модели каждому файлу соответствует дескриптор и операции ввода/вывода производятся с этим дескриптором. Также таблица io содержит открытые по умолчанию файловые дескрипторы io.stdin, io.stdout и io.stderr.

Открытие файловых дескрипторов

io.open(filename [, mode])
Открывает файл и возвращает файловый дескриптор или nil, сообщение об ошибке и номер ошибки при неудаче.

Допустимые режимы:

'r' чтение
'w' запись
'a' добавление
'r+' обновление с сохранением
'w+' обновление с очисткой
'a+' добавление и обновление с сохранением

Строка режима может содержать на конце букву 'b', что означает открытие файла в бинарном режиме.

io.popen(prog [, mode])
Запускает процесс prog и возвращает файл, связанные с потоком ввода (если mode == 'w') или потоком вывода (если mode == 'r', значение по умолчанию) запущенного процесса.
io.tmpfile()
Возвращает файловый дескриптор временного файла.

Переназначение умалчиваемых потоков

io.input([file])
Устанавливает умалчиваемый поток ввода на переданный дескриптор. Если функция вызвана без аргументов, то она возвращает умалчиваемый дескриптор.
io.output([file])
Аналогична io.input(), но устанавливает умалчиваемый поток вывода.

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

Форматные строки

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

'*all'
Чтение всего файла целиком с текущей позиции. При попытке чтения за концом файла и для пустого файла возвращается пустая строка.
'*line'
Чтение одной строки (символа конца строки не добавляется в строку). При попытке чтения за концом файла возвращается nil. Это — умалчиваемое поведение для функций чтения.
'*number'
Чтение числа. В случае неудачи возвращает nil.
ddd
Чтение не более чем заданного числа (ddd) символов. При попытке чтения за концом файла (если не удалось прочитать ни одного символа) возвращается nil. При num = 0 возвращается пустая строка или nil, если достигнут конец файла.

Операции с файлами

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

read(fmt1, …)
Читает данные в соответствии со строками формата. Каждой строке формата соответствует одно возвращаемое значение.
lines()
Возвращает функцию-итератор по строкам потока ввода.
write(v1, …)
Пишет данные в поток вывода. Умеет писать только числа и строки, а для остальных типов данных нужно явно использовать функции tostring() и string.format(). Не добавляет в выходной поток разделители полей и завершители строк.
flush()
Сбрасывает буфер потока.
close()
Закрывает поток.

В случае умалчиваемых потоков функции flush() и close() относятся к потоку вывода.

Функции io.lines() также можно передать имя файла. В этом случае файл будет открыт в текстовом режиме, а после чтения последней строки файл будет автоматически закрыт. При этом не происходит замены умалчиваемого потока ввода.

Дополнительно файловые дескрипторы имеют функцию seek():

file:seek([base] [, offset])
Устанавливает текущую позицию в файле. Смещение offset задает позицию относительно базы, задаваемой параметром base. При успехе возвращает абсолютную позицию в файле, а при неудаче — nil и сообщение об ошибке. Умалчиваемые значения base = "cur", offset = 0.

Допустимые значения параметра base:

"set" от начала файла
"cur" от текущей позиции
"end" от конца файла

Вызов этой функции без параметров возвращает текущую позицию в файле, вызов file:seek("set") позиционирует указатель на начало файла, вызов file:seek("end") позиционирует указатель на конец файла и возвращает его размер.

Системные вызовы

Общие функции

os.exit([code])
Завершает выполнение программы, возвращая code как код завершения. По умолчанию возвращает код, соответствующий успешному завершению.
os.getenv(varname)
Возвращает значение переменной окружения с именем varname или nil если переменной с таким именем нет.
os.execute(cmd)
Выполняет команду cmd и возвращает код завершения.
os.setlocale(locale [, category])
Устанавливает локаль. Аргумент locale — это строка, определяющая локаль (у нас — '.1251'). Необязательный аргумент category определяет тип изменяемой локали: "all", "collate" (упорядочение символов), "ctype" (тип символов и регистр), "monetary", "numeric", "time". Умалчиваемая категория — "all". Функция возвращает имя новой локали или nil если установка новой локали не была выполнена.

Управление файлами

os.remove(filename)
Удаляет файл с заданным именем. При неудаче возвращает nil и строку с сообщением об ошибке.
os.rename(old_filename, new_filename)
Переименовывает файл. При неудаче возвращает nil и строку с сообщением об ошибке.
os.tmpname()
Возвращает имя временного файла.

Дата и время

Дата и время представляются в виде таблицы, содержащей поля

year год (полностью)
month месяц (1-12)
day день (1-31)
hour час (0-23) *
min минута (0-59) *
sec секунда (0-61) *
isdst флаг летнего времени *
wday день недели (Вс = 1, Пн = 2, …) **
yday номер дня в году **

Звездочкой отмечены поля, необязательные при вызове функции os.time() (используется момент времени 12:00:00). Двумя звездочками отмечены дополнительные поля, возвращаемые функцией os.date().

os.clock()
Возвращает время работы программы в секундах.
os.time([tbl])
При вызове без аргументов возвращает целое число, представляющее текущее системное время. При вызове с аргументом-таблицей переводит табличное представление даты/времени в целое число, представляющее соответствующее системное время.
os.difftime(t2, t1)
Возвращает число секунд, прошедших от момента времени t1 до момента времени t2. Аргументы — целые числа, представляющие системное время.
os.date([format [, time]])
Возвращает строковое или табличное представление даты времени, отформатированное в соответствии со строкой format. Если присутствует аргумент time, то форматируется заданное в этом аргументе время. В противном случае форматируется текущее время. Если строка формата содержит '!' в качестве первого символа, то время форматируется в Coordinated Universal Time. Если после этого (необязательного) символа идет строка '*t', то возвращается табличное представление времени. Если строка формата отлична от '*t', то функция возвращает строковое представление времени, интерпретируя строку формата так же, как функция strftime() из ANSI-C. При вызове без аргументов возвращается умалчиваемое строковое представление текущего времени (соответствующее строке формата '%c').

Вот основные спецификаторы для форматирования строкового представления времени:

%% символ '%'
%Y год полностью (1998)
%y год кратко (98) [00-99]
%m месяц (09) [01-12]
%d день (16) [01-31]
%H час в 24-часовой шкале (23) [00-23]
%M минута (48) [00-59]
%S секунда (10) [00-61]

Другие возможности

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

Базовая библиотека

table.maxn(t)
Возвращает значение максимального положительного числового индекса в таблице t или 0 если таблица не содержит положительных числовых индексов.
xpcall(func, errfunc)
Вызов функции func в защищенном режиме. Аналогична pcall(), но не позволяет передать аргументы в функцию func и при ошибках вызывает функцию-обработчик errfunc.
load(func [, chunkname])
Аналогична функциям loadfile() и loadstring(), но для получения кода извне вызывает функцию func.
select(idx, …)
Если параметр idx имеет числовое значение, то возвращает все аргументы, следующие за аргументом с номером idx. Если idx == '#', то возвращает общее число полученных аргументов.
module(name [, …])
Определяет модуль с именем name. Подробное описание см. в описании библиотеки package.

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

В этом документе полностью опущено описание возможностей библиотек package, debug и coroutine.

io.type(file)
Возвращает состояние файла file.
string.dump(func)
Возвращает двоичное представление функции func.
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License