Дополнительные функции
Базовая библиотека содержит некоторые основные функции 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 паузе сборки мусора.
"setstepmul": присвоение значения arg/100 коэффициенту шага сборки мусора.
dofile (filename)
Открывает указанный файл и выполняет его содержимое как порцию Lua. При вызове без параметров выполняет содержимое стандартного потока ввода (stdin). Возвращает все данные, возвращаемые порцией. В случае ошибки передает ошибку вызывающей задаче (т.е. dofile исполняется в незащищенном режиме).
Примечание. Необходимо чтобы файл был обязательно сохранен в кодировке ANSI (CP1251). Для этого вставьте код в блокнот Windows, нажмите Сохранить... - и укажите кодировку ANSI.
error (message [, level])
Завершает последнюю вызванную защищенную функцию и возвращает message как сообщение об ошибке. Ошибка функции никогда не возвращается.
Обычно добавляет информацию о местоположении возникновения ошибки в начало сообщения. Параметр level указывает способ определения места возникновения ошибки. Уровень 1 (значение по умолчанию) определяет положение ошибки в месте вызова функции error . Уровень 2 – в месте, где была вызвана функция, которая вызвала error ; и т.д. Если level = 0, положение ошибки не добавляется в сообщение.
Глобальная переменная (не функция), которая содержит глобальное окружение (т.е. _G._G = _G). Сама по себе Lua не использует эту переменную; изменение значения этой переменной не отражается на окружении и наоборот. (Для изменения окружения используйте setfenv ).
getfenv ([f])
Возвращает текущее окружение, используемое функцией. f может быть как Lua-функцией, так и числом, определяющим уровень стека, на котором расположена функция: Уровень 1 – это функция, которая вызвала getfenv . Если данная функция не является функцией Lua или f=0, getfenv возвращает глобальное окружение. По умолчанию f равно 1.
getmetatable (object)
Если object не имеет метатаблицы, возвращается nil. В противном случае, если метатаблица объекта имеет поле "__metatable", возвращается значение этого поля. Иначе возвращается метатаблица данного объекта.
ipairs (t)
Возвращает три значения: функцию итератора, таблицу t и 0, поэтому конструкция
for i,v in ipairs(t) do <дeйcтвия> end
будет выполнять цикл над парами (1,t[1]), (2,t[2]), ··· до первого целого ключа, отсутствующего в таблице.
load (func [, chunkname])
Загружает порцию по частям с помощью функции func. Каждый вызов func должен возвращать строку, которая соединяется с предыдущими результатами. Возврат значения nil (или отсутствие значения) указывает конец порции.
В случае отсутствия ошибок возвращает компилированную порцию как функцию; иначе возвращает nil и сообщение об ошибке. Окружением возвращаемой функции является глобальное окружение.
chunkname используется как имя порции для сообщения об ошибке и отладочной информации. Если отсутствует, заменяется значением по умолчанию – "=(load)".
loadfile ([filename])
Аналогична load , но получает порцию из файла filename или из стандартного потока ввода, если имя файла не указано.
loadstring (string [, chunkname])
Аналогична load , но получает порцию из заданной строки.
Для загрузки и выполнения строки используйте следующую идиому:
assert(loadstring(s))()
next (table [, index])
Позволяет программе просмотреть все поля таблицы. Первый аргумент – это таблица, второй – индекс в этой таблице. next возвращает следующий индекс в таблице и соответствующее ему значение. Если next вызывается с index=nil, возвращается начальный индекс и связанное с ним значение. При вызове последнего индекса или с nil в пустой таблице, next возвращает nil. Если второй аргумент отсутствует, он интерпретируется как nil. В частности, Вы можете использовать next(t) для проверки, является ли таблица пустой.
Порядок следования индексов не определен, даже для чиcлoвыx индekcoв. (Для прохождения по таблице в числовом порядке, используйте числовой for или функцию ipairs ).
Результат работы next нe oпpeдeлeн, если в процессе сканирования таблицы Вы присваиваете какое либо значение в несуществующее поле таблицы. Однако Вы можете модифицировать существующие поля. В частности, Вы можете очистить существующие поля.
pairs (t)
Возвращает три значения: функцию next , таблицу t, и nil, поэтому конструкция
for k,v in pairs(t) do <дeйcтвия> end
будет выполнять действие по всем парам "ключ-значение" таблицы t.
Модификация таблицы в процессе обхода объясняется в описании функции next .
pcall (f, arg1, ···)
Вызывает функцию f с заданными аргументами в зaщищeннoм peжимe. Это значит, что при возникновении любой ошибки внутри функции f эта ошибка дальше не передается; вместо этого pcall перехватывает ошибку и возвращает статус. pcall возвращает сначала статус (тип boolean), который равен true, если вызов завершился без ошибок. В этом случае pcall также возвращает все результаты вызова сразу после статуса. В случае возникновения ошибки pcall возвращает false и сообщение об ошибке.
См. пример в разделе Обработка ошибок.
print (···)
Принимает любое количество параметров и печатает их значения в stdout, используя функцию tostring для преобразования этих значений в строки. print неудобен для форматированного вывода, он удобен для быстрого отображения значения, обычно используется для отладки. Чтобы форматировать вывод, используйте string.format .
В MasterOPC данную функцию применять не следует - используйте функцию server.Message.
rawequal(v1, v2)
Проверка равенства v1 и v2 без вызова каких либо метаметодов. Возвращает статус типа boolean.
rawget (table, index)
Получает реальное значение table[index] без вызова метаметодов. table должно быть таблицей; index может быть любым значением.
rawset (table, index, value)
Присваивает реальное значение table[index] аргументу value без выполнения метаметодов. table должно быть таблицей, index – любым значением, отличным от nil, value – любым значением Lua.
Данная функция возвращает table.
select (index, ···)
Если index – число, возвращает все аргументы после аргумента с номером index. Иначе index должен быть строкой "#", в этом случае возвращается общее количество дополнительных аргументов, полученных функцией select .
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]])
Возвращает элементы из данной таблицы. Функция эквивалентна следующей конструкции
return list[i], list[i+1], ···, list[j]
с тем исключением, что указанная выше конструкция может быть написана только для фиксированного количества элементов. По умолчанию i равно 1, а j – длине списка, как это определено в операторе length (см. 2.5.5 Получение длины ).
Глобальная переменная (не функция). Содержит строку, описывающую номер версии интерпретатора. В настоящий момент значение этой переменной равно "Lua 5.1".
xpcall (f, err)
Эта функция аналогична pcall с тем отличием, что здесь Вы можете установить новый обработчик ошибок.
xpcall вызывает функцию f в защищенном режиме, используя обработчик ошибок err. Любые ошибки внутри f не передаются в вызывающую программу; вместо этого xpcall перехватывает ошибку, вызывает функцию err с объектом, вызвавшим ошибку, и возвращает статус. Возвращает сначала статус (тип boolean), который равен true, если вызов завершился без ошибок. В этом случае xpcall также возвращает также всё, что возвращает вызов функции f, сразу после статуса. В случае возникновения ошибок xpcall возвращает false и результат из err.