5.1 – Базовые функции

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

assert (v [, message])

Выдает сообщение об ошибке, если значение параметра v равно false (т.е., nil или false); в противном случае, возвращаются все параметры. message – это сообщение об ошибке; если параметр отсутствует, по умолчанию выводится "assertion failed!""

collectgarbage (opt [, arg])

Эта функция является интерфейсом к сборщику мусора (garbage collector). В зависимости от значения параметра opt, выполняются различные функции:

·        "stop": остановка сборщика мусора.

·        "restart": рестарт сборщика мусора.

·        "collect": выполнение полного цикла сборки мусора.

·        count": возврат общего количества используемой Lua памяти (в K байтах).

·        step": выполнение шага по сборке мусора. "Размер" шага регулируется параметром arg (большая величина соответствует большему шагу. Если Вы хотите регулировать размер шага, Вы должны сначала определить экспериментальным путем оптимальное значение arg. Возвращает true если шаг завершает полный цикл сборки мусора.

·        setpause": присвоение значения arg/100 параметру пауза сборки мусора сборщика (см. §2.10).

·        setstepmul": присвоение значения arg/100 параметру коэффициент шага сборки сборщика (см. §2.10).

dofile (filename)

Открывает указанный файл и выполняет его содержимое как Lua задачу (chunk). При вызове без параметров, dofile выполняет содержимое стандартного потока ввода (stdin). Возвращает все данные, возвращаемые выполняемой задачей. В случае ошибки, dofile передает ошибку вызывающей задаче (т.е.dofile запускается в незащищенном режиме).

error (message [, level])

Завершает последнюю вызванную защищенную функцию и возвращает

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

_G

Глобальная переменная (не функция), которая содержит глобальное окружение (environment) (_G._G = _G). Lua не использует эту переменную; изменение значения этой переменной не отражается на окружении и наоборот. (Для изменения окружения используйтеsetfenv.)

getfenv ([f])

Возвращает текущее окружение, в котором выполняется функция. f может бытькак Lua функцией, так и числом, определяющим уровень стека, на котором расположена функция: Уровень 1 – это функция, которая вызвала getfenv. Если данная функция не является функцией Lua, или 0, getfenv возвращает глобальное окружение. По умолчанию f равно 1.

getmetatable (object)

Если object не имеет metatable, возвращается nil. В противном случае, если метатаблица объекта имеет поле "__metatable", возвращается значение этого поля. Иначе возвращается метатаблица данного объекта.

ipairs (t)

Возвращает три значения: итератор, таблицу t, и 0, поэтому конструкция

будет выполнять цикл парами (1,t[1]), (2,t[2]), ···, до первого целого ключа, отсутствующего в таблице.

load (func [, chunkname])

Загружает составной оператор (chunk) с помощью функции func для получения составного оператора по частям. Каждый вызов func должен возвращать строку, которая соединяется с предыдущими результатами. Возврат значения nil (или отсутствие значения) говорит о конце составного оператора.

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

chunkname используется как имя задачи для сообщения об ошибке, т.е. как отладочная информация.

loadfile ([filename])

Аналогично load, но задача считывается из файла filename или из стандартного потока ввода, если имя файла не указано.

loadstring (string [, chunkname])

Аналогично load, но задача считывается из данной строки.

Для загрузки и выполнения данной строки, используйте следующую конструкцию

next (table [, index])

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

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

Результат работы next неопределен (undefined) если, в процессе сканирования таблицы, Вы присваиваете какое либо значение в несуществующее поле таблицы. Однако Вы можете модифицировать существующие поля. В частности, Вы можете очистить существующие поля.

pairs (t)

Возвращает три значения: функцию next (результат вызова, примечание переводчика), таблицу t, и nil, поэтому конструкция

будет выполнять итерацию по всем ключевым парам таблицы t.

См. предупреждения для функции next если Вы хотите в процессе итерации модифицировать таблицу.

pcall (f, arg1, ···)

Вызывает функцию f с данными параметрами в защищенном режиме (protected mode). Это значит, что при возникновении любой ошибки внутри функции f она дальше не передается; напротив, pcall перехватывает ошибку и возвращает статус. pcall возвращает сначала статус (тип boolean), который равен true если вызов завершился без ошибок. В этом случае, pcall также возвращает все данные, которые возвращает функция f, сразу после статуса. В случае возникновения ошибки, pcall возвращает false и сообщение об ошибке.

print (···)

Принимает любое количество параметров и отображает их значения в stdout, используется функция tostring для преобразования параметров в строки. print неудобен для форматированного вывода, он удобен для быстрого отображения значения, обычно используется для отладки. Чтобы сформатировать вывод используйте string.format

rawequal(v1, v2)

Проверка равенства v1 и v2, без вызова каких либо метаметодов. Возвращает статус типа boolean.

rawget (table, index)

Возвращает реальное значение из table[index], без вызова метаметодов. table должен быть таблицей; index может быть любым значением.

rawset (table, index, value)

Присваивает value реальное значение из table[index] без выполнения метаметодов. table должен быть таблицей, index - любое значение отличное от nil, value – любое значение Lua.

Данная функция возвращает table.

select (index, ···)

Если index - число, возвращает все параметры после параметра с номером index. В противном случае, index должен быть строкой "#", в этом случае select возвращает общее количество параметров (исключая index, примечание переводчика).

setfenv (f, table)

Устанавливает окружение, которое будет использовано данной функцией. f может быть как Lua функцией, так и числом, которое указывает уровень стека функции: Уровень 1 – это функция, вызывающая setfenv. setfenv возвращает данную функцию.

В особом случае, когда f равно 0, setfenv изменяет окружение запущеной нити. В этом случае setfenv ничего не возвращает.

setmetatable (table, metatable)

Устанавливает метатаблицу для данной таблицы. (Вы не можете изменить метатаблицу из Lua, это можно сделать только из C.Если параметр metatable равен nil, то производится удаление метатаблицы для данной таблицы. Если метатаблица содержит поле "__metatable", то возникает ошибка.

Функция возвращает таблицу table.

tonumber (e [, base])

Попытка преобразования параметра в число. Если параметр уже является числом или строкой, конвертируемой в число, то tonumber возвращает это число; иначе, возвращает nil.

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

tostring(e)

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

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

type (v)

Возвращает тип параметра в виде строки. Возможные результаты этой функции - это "nil" (как строка, а не значение nil), ">number", "string", "boolean", "table", "function", "thread" и "userdata".

unpack (list [, i [, j]])

Возвращает элементы из данной таблицы. Функция эквивалентна следующей конструкции

с тем исключением, что указанная выше конструкция может быть написана только для фиксированного количества элементов. По умолчанию, i равно 1, а j – длине списка, как это определено в операторе length (см. §2.5.5).

_VERSION

Глобальная переменная (не функция) Содержит строку, описывающую номер версии интерпретаора. В настоящий момент значение этой переменной равно "Lua 5.1".

xpcall (f, err)

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

xpcall вызывает функцию f в защищенном режиме, используя обработчик ошибок err. Любые ошибки внутри f не передаются в вызывающую программу; напротив, xpcall перехватывает ошибку, вызывает функцию err с объектом, вызвавшим ошибку, и возвращает статус. Возвращает сначала статус (тип boolean), который равен true если вызов завершился без ошибок. В этом случае, xpcall также возвращает всё, что возвращает вызов функции f, сразу после статуса. Вслучае возникновения ошибок, xpcall возвращает false и результат из err.