3.7 - Функции и типы
В этом разделе описаны все функции и типы из C API в алфавитном порядке..
typedef void * (*lua_Alloc) (void *ud,
void *ptr,
size_t osize,
size_t nsize);
Тип функции выделения памяти, используемый Lua. Функция выделения должна предоставлять функционал, схожий с realloc, но не точно такой же. Ее аргументы: ud, непрозрачный (opaque) указатель, передаваемый
lua_newstate, ptr, указатель на блок block выделенной, перевыделенной или освобожденной памяти; osize, исходный размер блока; nsize, новый размер блока. ptr равен NULL тогда и только тогда когда osize нулевой. Когда nsize равен нулю, процедура выделения памяти (allocator) должна вернуть NULL; если osize не ноль, она должна освободить блок, на который указывает ptr. Когда nsize не ноль, процедура возвращает NULL тогда и только тогда она не может выполнить запрос. Если nsize не ноль и osize ноль, процедура должна вести себя как malloc. Если nsize и osize не ноль, процедура ведят себя как realloc. Луа предполагает, что такая процедура никогда не приводит к ошибочной ситуации при osize >= nsize.
Вот пример реализации простой функии выделения памяти. Он используется во вспомогательной библиотеке состоянием luaL_newstate.
static void *l_alloc (void *ud, void *ptr, size_t osize,
size_t nsize) {
(void)ud; (void)osize; /* not used */
if (nsize == 0) {
free(ptr);
return NULL;
}
else
return realloc(ptr, nsize);
Этот код предполагает что NULL не имеет эффекта и что realloc(NULL, size) эквивалентна malloc(size). ANSI C соответствует обоим поведениям.
lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);
Устанавливает новую panic function и возвращает старую.
Если происходит ошибка вне любого protected environment, Lua вызывает panic function, а затем exit(EXIT_FAILURE), таким образом выходя из приложения. Ваша panic function может предотвратить выход из программы, если не будет оканчиваться (e.g., при помощи long jump).
Panic function может осуществлять доступ к сообщению об ошибке на вершине стека.
void lua_call (lua_State *L, int nargs, int nresults);
Вызывает функцию
Для вызова функции вы должны использовать следующую последовательность: первое, функция, которая должны быть вызвана помещается на вершину стека; затем, аргументы функции помещаются (push) в прямом порядке; т.о., первый аргумент помещается первым. Затем вы вызываете lua_call; nargs это количество аргументов которые вы поместили в стек. Все аргументы и значение функции выбираются(pop) из стека когда вызывается функция. Результаты функции помещаются в стек по окончании вызова. Количество результатов соответствует nresults, если nresults не LUA_MULTRET. В противном случае, все результаты, возвращенные функцией помещаются в стек. Lua заюотится о том чтобы возвращенные значения поместились в стек. Результаты функции помещаются в стек в прямом порядке (первый результат - первым), т.о. после вызова последний результат оказывается на вершине стека.
Любая ошибка внутри вызванной функции распространяется вверх (при помощи longjmp).
Эквивалентыный код в Lua:
a = f('how', t.x, 14)
То же в C:
lua_getfield(L, LUA_GLOBALSINDEX, 'f'); /* function to be called */
lua_pushstring(L, 'how'); /* 1st argument */
lua_getfield(L, LUA_GLOBALSINDEX, 't'); /* table to be indexed */
lua_getfield(L, -1, 'x'); /* push result of t.x (2nd arg) */
lua_remove(L, -2); /* remove 't' from the stack */
lua_pushinteger(L, 14); /* 3rd argument */
lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */
lua_setfield(L, LUA_GLOBALSINDEX, 'a'); /* set global 'a' */
Заметьте что код сбалансирован: в его конце стек возвращается в исходныю конфигурацию. Это считается хорошей практикой программирования.
typedef int (*lua_CFunction) (lua_State *L);
Тип для функций C.
Для правильной связи с Lua, функция C должна использовать следующую последовательность действий, которая определяет, как параметры передаются параметры и результаты: функция C получает аргументы из Lua через стек в прямом порядка (первый аргумент помещается в стек первым). Поэтому, когда функция начинает исполняться, lua_gettop(L) возвращает количество аргументов полученных функцией. Первый аргумент (если он существует) имеет индекс 1, а последний - lua_gettop(L). Для возвращения значений в Lua, функция C просто помещает их в стек, в прямом порядке, и возвращает количество результатов. Любое другое значение в стеке ниже результатов будет проигнорировано Lua. Также как и функция Lua, функция C, вызванная из Lua может также возвращать множество результатов.
В качестве примера, следующая функция получает переменное число аргументов (числовых) и возвращает из среднее значение и сумму:
static int foo (lua_State *L) {
int n = lua_gettop(L); /* number of arguments */
lua_Number sum = 0;
int i;
for (i = 1; i <= n; i++) {
if (!lua_isnumber(L, i)) {
lua_pushstring(L, 'incorrect argument');
lua_error(L);
}
sum += lua_tonumber(L, i);
}
lua_pushnumber(L, sum/n); /* first result */
lua_pushnumber(L, sum); /* second result */
return 2; /* number of results */
}
int lua_checkstack (lua_State *L, int extra);
Проверяет что существует, по крайней мере, extra свободных слотов стека. Функция возвращает false, если не может увеличить стек до требуемого размера. Эта функция никогда не уменьшает размер стека; если стек уже больше, чем требуемый новый размер, он остается неизменным.
void lua_close (lua_State *L);
Уничтожает все объекты в заданном состоянии Lua (Lua state) (вызывая соответствующие garbage-collection метаметоды, если таковые есть) и освобождает всю динамическую память, используемыю этим состоянием (state). На некоторых платформах, вам может не понядобиться вызывать эту функцию, т.к. все ресурсы освобождаются автоматически, когда закрывается программа (host program). С другой стороны, долго работающие программы, такие как демоны или веб-сервера, могут потребовать освобождения состояний, как только они не нужны, для избежания слишком сильного разрастания.
void lua_concat (lua_State *L, int n);
Конкатенирует n значений на вершине стека, выталкивает(pop) их, и оставляет результат на вершине. Еслии n равен 1, результатом является единственная строка в стеке (т.о., функция ничего не делает); если n равен 0, результатом является пустая строка. Конкатенация производится в соответствии с обычной семантикой Lua (см. §2.5.4).
int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);
Вызывает функцию C func в защищенном режиме (protected mode). func запускается с единственным значением в ее стеке, пользовательскими данными, содержащими ud. В случае ошибок,
lua_cpcall возвращает аналогичные коды ошибок как
lua_pcall, а также error object на вершине тека; в противном случае, она возвращает 0, и не изменяет стек. Все значения, возвращаемые func игнорируются.
void lua_createtable (lua_State *L, int narr, int nrec);
Создает новую пустую таблицу, и вставляет (push)ее в стек. Под новую таблицу выделяется место для narr элементов массива и nrec элементов не массива (non-array elements). Это выделение удобно когда вы знаете точное количество элементов, которое будет помещено в таблицу. В противном случае, вы можете использовать функциюlua_newtable
int lua_dump (lua_State *L, lua_Writer writer, void *data);
Выгружает функцию в бинарном формате (binary chunk). Получает функцию Lua с вершины стека и создает binary chunk, который, если будет загружен вновь, дает функцию, эквивалентную выгруженной. В процессе генерации частей chunk, lua_dump вызывает функцию writer (см. lua_Writer) с соответствующими данными для записи.
Возвращает значение, соответствующее коду ошибки (error code), возвращенному последним обращением к writer; 0 обозначает отсутствие ошибок.
Эта функия не выталкивает функцию Lua из стека.
int lua_equal (lua_State *L, int index1, int index2);
Возвращает 1 если два значения с индексами (acceptable indices) index1 и index2 эквивалентны, в соответствии с семантикой Lua оператора == (т.е., может вызывать метаметоды). В противном случае возвращает 0. Также возвращает 0 если любой из индексов ошибочен.
int lua_error (lua_State *L);
Генерирует ошибку Lua. Сообщение об ошибке (которое может быть любым значением Lua любого типа) должно быть на вершине стека. Эта функция делает long jump, и т.о. никогда не заканчивается. (см. luaL_error
int lua_gc (lua_State *L, int what, int data);
Контролироет сборщик мусора.
Эта функция выполняет несколько задач, в соответствии с значением параметра what::
- LUA_GCSTOP: останавливает сборщик.
- LUA_GCRESTART: перезапускает сборщик.
- LUA_GCCOLLECT: производит полный цикл сборки мусора.
- LUA_GCCOUNT: возвращает текущее значение объема памяти (в Kbytes), которое используется Lua.
- LUA_GCCOUNTB: возвращает остаток деления текущего количества байт памяти, используемого Lua на 1024.
- LUA_GCSTEP: выполняет инкрементальный шаг сбора мусора. Размер шага "size" контролируется значением data (большие значения означают большее количество шагов), но нет прямого соответствия между занчсением этого параметра и объемом освобождаемой памяти. Если вы хотите контролировать размер шага вам нужно экспериментально подобрать размер data. Эта функция возвращает 1 если шаг закончил цикл сборки мусора.
- LUA_GCSETPAUSE: выставляет data/100 новым значением для параметра pause сборщика мусора (см. §2.10). Функция возвращает предыдущее значение данного параметра.
- LUA_GCSETSTEPMUL: выставляет data/100 как новое значение step multiplier сборщика (см.§2.10). Функция возвращает предыдущее значение данного параметра.
lua_Alloc lua_getallocf (lua_State *L, void **ud);
Возвращает функцию выделения памяти данного состояния (state). Если ud не равен NULL, Lua сохраняет в *ud непрозрачный (opaque) указатель передаваемый в lua_newstate.
void lua_getfenv (lua_State *L, int index);
Вставляет (Push) в стек таблицуокружения (environment table) значения заданного индекса.
void lua_getfield (lua_State *L, int index, const char *k);
Вставляет (Push) в стек значение t[k], где t – это значение заданного валидного индекса index. Так же, как в Lua, эта йункция может вызывать (trigger) метаметод для события индекса ("index" event) (см. §2.8).
void lua_getglobal (lua_State *L, const char *name);
Вставляет (Push) в стек значение глобальной переменной (value of the global name). Эта функция определяется как следующий макрос:
#define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s)
int lua_getmetatable (lua_State *L, int index);
Вставляет в стек метатаблицу (metatable) значения в заданном валидном индексе (acceptable index). Если индекс не валиден, или значение не имеет метатаблицы, функция возвращает 0 и ничего не вставляет в стек.
void lua_gettable (lua_State *L, int index);
Вставляет в стек значение t[k], где t – это значение у указанном валидном индексе index и k – это значение на вершине стека.
Эта функция выталкивает ключ из стека (вставляет результат на его место). Также как в Lua, эта функция может вызывать (trigger) метаметод для события индекса (см. §2.8).
int lua_gettop (lua_State *L);
Возвращает индекс на значения, находящегося на вершине стека. Т.к. индексы начинаются с 1, это значение равно количеству элементов в стеке (и т.о. 0 обозначает пустой стек).
void lua_insert (lua_State *L, int index);
Перемещает верхний элемент в заданный валидный индекс, сдвигая вверх все элементы, находящиеся выше заданного индекса. Процедура не может быть вызвана с псевдо-индексом (pseudo-index), т.к. псевдо-индекс (pseudo-index) не содержит реального положения в стеке.
typedef ptrdiff_t lua_Integer;
Данный тип используется Lua API для представления целых чисел.
По умолчанию ptrdiff_t, который соответствует наибольшему целому типу со знаком поддерживается "без проблем".
int lua_isboolean (lua_State *L, int index);
Возвращает 1 если значение в заданном допустимом (acceptable) индексе имеет тип boolean, и 0 в противном случае.
int lua_iscfunction (lua_State *L, int index);
Возвращает 1 если значение в заданном допустимом (acceptable) индексе – функция C, и 0 в противном случае
int lua_isfunction (lua_State *L, int index);
Возвращает 1 если значение в заданном допустимом (acceptable) индексе – функция (C или Lua), и 0 в противном случае.
int lua_islightuserdata (lua_State *L, int index);
Возвращает 1 если значение в заданном допустимом (acceptable) индексе – это пользовательские данные (light userdata), и 0 в противном случае.
int lua_isnil (lua_State *L, int index);
Возвращает 1 если значение в заданном допустимом (acceptable) индексе – nil, и 0 в противном случае.
int lua_isnone (lua_State *L, int index);
Возвращает 1 если заданный допустимый индекс не является валидным (т.е., указывает на элемент вне текущего стека), и 0 в противном случае.
int lua_isnoneornil (lua_State *L, int index);
Возвращает 1, если заданный допустимый индекс не является валидным (т.е., указывает на элемент вне текущего стека) или значение элемента по данному индексу равно nil, и 0 в противном случае.
int lua_isnumber (lua_State *L, int index);
Возвращает 1 если значение в заданном допустимом (acceptable) индексе – число или строка, конвертируемая в число, и 0 в противном случае.
int lua_isstring (lua_State *L, int index);
Возвращает 1 если значение в заданном допустимом (acceptable) индексе – строка или число (которое всегда можно сконвертировать в строку), и 0 в противном случае.
int lua_istable (lua_State *L, int index);
Возвращает 1 если значение в заданном допустимом (acceptable) индексе – таблица, и 0 в противном случае.
int lua_isthread (lua_State *L, int index);
Возвращает 1 если значение в заданном допустимом (acceptable) индексе – нить (поток, thread), и 0 в противном случае.
int lua_isuserdata (lua_State *L, int index);
Возвращает 1 если значение в заданном допустимом (acceptable) индексе – пользовательские данные (userdata) (full или light), и 0 в противном случае.
int lua_lessthan (lua_State *L, int index1, int index2);
Возвращает 1 если значение в заданном допустимом (acceptable) индексе index1 меньше чем значение в допустимом индексе index2, в соответствии с семантикой оператора < Lua (т.о., может вызыать метаметоды). В противном случае возвращает 0. Также возвращает 0 если любой из индексов не валиден.
int lua_load (lua_State *L,
lua_Reader reader,
void *data,
const char *chunkname);
Загружает chunk Lua. Если нет ошибок,lua_load вставляет (push) скомпилированный chunk как Lua функцию на вершину стека. В противном случае, функция вставляет сообщение об ошибке. Возвращаемые значения lua_load:
Эта функция только загружает chunk; но не запускает.
lua_load автоматически определяет, является ли chunk текстовым или бинарным, и соответствующе его загружает (см. программу luac).
Функция lua_load использует предоставленную пользователем функцию reader для чтения chunk (см. lua_Reader). Аргумент data – непрзрачное (opaque) значение, передаваемое в функцию reader.
Аргумент chunkname дает имя chunk, которое может быть использовано для обработки сообщений об ошибках и получения отладочной информации (см. §3.8).
lua_State *lua_newstate (lua_Alloc f, void *ud);
Создает новое независимое состояние (state). Возвращает NULL, если не удается создать состояние (из-за недостатка памяти). Аргумент f – функция выделения памяти; Lua совершает все выделения памяти для этого состояния через эту функцию. Второй аргумент, ud – это непрозрачный указатель (opaque pointer), который Lua передает функции выделения памяти при каждом вызове.
void lua_newtable (lua_State *L);
Создает новую пустую таблицу и вставляет ее в стек. Действие этой функции эквивалентно lua_createtable(L, 0, 0).
lua_State *lua_newthread (lua_State *L);
Создает новую нить (thread), вставляет ее в стек, и возвращает указатель на lua_State, , который представляет (represents) эту новую нить. Новое состояние (state), возвращенное функцией разделяет с исходным (original) состоянием все глобальные объекты (такие как tables), но обладет независимым стеком выполнения.
Не существует непосредственно функии, закрывающей или уничтожающей нить. Нити – это забота сборщика мусора, как и любой другой объект Lua.
void *lua_newuserdata (lua_State *L, size_t size);
Эта функция выделяет новый блок памяти с заданного размера, вставляет в стек новую пользовательскую полную информацию (full userdata) с адресом блока, и возвращает этот адрес.
Пользовательская информация (userdata) представляет значения C в Lua. Полная пользовательская информация (full userdata) представляет блок памяти. Это - объект (такой же как таблица): вы должны создать его, он может облатдать собственной метатаблицей, и вы можете определить, когда она будет собрана (collected). Полная пользовательская информаия (full userdata) равна только самой себе (в соответствии с «сырым» сравнением (under raw equality)).
Когда Lua собирает полную пользовательскую информацию (full userdata) с сиспользованием метаметода gc, Lua вызывает метаметод и помечает пользовательскую информацию как finalized. Когда эта пользовательская информация собирается снова, то Lua освобождает соответствующую память.
int lua_next (lua_State *L, int index);
Выталкивает (Pop) ключ из стека, и вставляет пару ключ-значение из таблицы по заданному индексу ("следующую" пару после заданного ключа). Если больше не существует елементов в таблицы, то lua_next возвращает 0 (и ничего не вставляет в стек).
Типичный обход (traversal) выглядит следующим образом:
/* table is in the stack at index 't' */
lua_pushnil(L); /* first key */
while (lua_next(L, t) != 0) {
/* uses 'key' (at index -2) and 'value' (at index -1) */
printf('%s - %s\n',
lua_typename(L, lua_type(L, -2)),
lua_typename(L, lua_type(L, -1)));
/* removes 'value'; keeps 'key' for next iteration */
lua_pop(L, 1);
}
Во время обхода таблицы, не вызывайтеlua_tolstring непосредственно для ключа, если не уверенны точно, что ключ действительно является строкой. Повторный вызов (Recall) lua_tolstring изменяет значение по заданному индесу; это «сбивает с толку» (confuses) следующий вызов lua_next.
typedef double lua_Number;
Тип чисел в Lua. По умолчанию – double, но это можно изменить в luaconf.h.
В конфигурационном файле вы можете изменить настройки Lua так, чтобы оперировать другими типами чисел (напр., float или long).
size_t lua_objlen (lua_State *L, int index);
Возвращает длину данных, расположенных по заданному допустимому индексу: для строк, возвращает длину строки; для таблиц – результат выполнения оператора дляины ('#'); для пользовательских данных – размер блока данных, выделенных для пользовательских данных; для других типов – 0.
nt lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
Вызывает функцию в защищенном режиме.
Параметры nargs и nresults имеют значение, аналогичное lua_call. Во время вызова не произошло ошибок, lua_pcall ведет себя в точности как lua_call. Однако, если встретились ошибки, lua_pcall перехватывает их, вставляет в стек сообщение об ошибке, и возвращает код ошибки. Также как и lua_call, lua_pcall всегда удаляет функцию и ее аргументы из стека.
Если errfunc равен 0, то сообщение об ошибке, возвращенное через стек – это исходное (original) сообщение об ошибке. В противном случае, errfunc – это индекс стека функции-обработчика ошибок. (В текущей реализации, этот индекс не может быть псевдо-индексом.) В случае ошибок времени выполнения, эта функция будет вызвана с сообщением об ошибке и возвращенное ею значение и будет сообщением, возвращенным через стек lua_pcall.
Чаще всего, функция обработки ошибок (error handler function) используется для добавления дополнительной отладочной информации в сообщение об ошибке, такой как stack traceback. Такая информация не может быть собрана после возврата из lua_pcall, , т.к. в этот момент стек был уже изменен (unwound).
Функция lua_pcall возвращает 0 в случае успешного завершения или один из следующих кодов ошибок (определенных в lua.h):
- LUA_ERRRUN:ошибка времени выполнения.
- LUA_ERRMEM:ошибка выделения памяти. Для таких ошибок, Lua не вызвает функию-обработчик ошибок.
- LUA_ERRERR:ошибка во время выполнения функции-обработчика ошибок.
void lua_pop (lua_State *L, int n);
Выталкивает n элементов из стека.
void lua_pushboolean (lua_State *L, int b);
Вставляет булеву переменную со значением b в стек.
void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
Вставляет новый экземпляр функции C в стек.
Когда функция C создана, есть возможность ассоциировать с ней некоторые значения, т.о. создавая экземпляр функции C (C closure) (см. §3.4); ); эти значения затем доступны функции во время ее вызова. Для того чтобы ассоциировать значения с функцией C, сначала эти значения должны быть вставлены в стек (если есть несколько значений, первое вставляется первым). Затем
lua_pushcclosure вызывется для того, чтобы создать и вставить функцию C в стек, с аргументом n, соответствующем количеству ассоциируемых значений. lua_pushcclosure также выталкивает эти значения из стека.
void lua_pushcfunction (lua_State *L, lua_CFunction f);
Вставляет функцию C в стек. Эта функция получает указатель на функцию C и вставляет в стек значение Lua типа function, которое, будучи вызванным, передает управление функции C.
Любая функция, которая должна быть зарегистрирована в Lua должна соответствовать определенным правилам, чтобы получить параметры и вернуть результаты (см.
lua_CFunction).
lua_pushcfunction определена следующим макросом:
#define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
const char *lua_pushfstring (lua_State *L, const char *fmt, ...);
Вставляет в стек отформатированную строку и возвращает указатель на эту строку. Эта функция аналогична функции C sprintf, но обладает некоторыми важными отличиями:
- Вам не нужно выделять память для результата: результат – строка Lua и Lua позаботится о выделении памяти (и освобождении, в процессе сборки мусора).
- Символы замены довольно ограничены. Не существует флагов, длин, или точностей. Символы замены могут быть только '%%' (вставляет '%' в строку), '%s' (вставляет строку, оканчивающуюся 0, без ограничений на длину), '%f' (вставляет lua_Number), '%p' (вставляет указатель в шестнадцатиричном формате), '%d' (вставляет целое число), и '%c' (вставляет целое число как символ).
void lua_pushinteger (lua_State *L, lua_Integer n);
Вставляет число со значением n в стек
void lua_pushlightuserdata (lua_State *L, void *p);
Вставляет light пользовательские данные в стек.
Пользовательские данные представляют значения C в Lua. Light пользовательские данные представляют собой указатель. Это – значение (как число): вы не создаете его, оно не имеет метатаблицы, и оно никогда не собирается сборщиком мусора (т.к.никогда не было создано). Light пользовательские данные эквивалентны любым light пользовательским данным с таким же адресом C.
void lua_pushlstring (lua_State *L, const char *s, size_t len);
Вставляет строку, начинающуюся с указателя s с длиной len в. Lua создает (или многократно использует) внутреннюю копиюданной строки, т.о. память s может быть освобождена или использована заново сразу после того, как функция завершилась. Строка может содержать ноли.
void lua_pushnil (lua_State *L);
Вставляет значение nil в стек.
void lua_pushnumber (lua_State *L, lua_Number n);
Вставляет число со значением n в стек.
void lua_pushstring (lua_State *L, const char *s);
Вставляет строку, оканчивающуюся нулем, начинающуюся с указателя s в стек. Lua создает (или многократно использует) внутреннюю копию данной строки, т.о. память может быть освобождена сразу после завершения функции. Строка не может содержать нолей; т.к. считает окончанием строки.
int lua_pushthread (lua_State *L);
Вставляет нить L в стек. Возвращает 1 если данная нить – основная в данном состоянии.
void lua_pushvalue (lua_State *L, int index);
Вставляет копию элемента в стек по заданному валидному индексу.
const char *lua_pushvfstring (lua_State *L,
const char *fmt,
va_list argp);
Эквивалентна lua_pushfstring, за исключением того, что получает va_list вместо переменного количества аргументов.
int lua_rawequal (lua_State *L, int index1, int index2);
Возвращает 1 если два значения по допустимым индексам index1 и index2 базово равны (т.е., без вызова метаметодов). В противном случае возвращает 0. Также возвращает 0 если любой из индексов не является валидным.
void lua_rawget (lua_State *L, int index);
Аналогична lua_gettable, но совершает «сырой» доступ (т.е., без метаметодов).
void lua_rawgeti (lua_State *L, int index, int n);
Вставляет в стек значение t[n], где t – это значение в заданном валидном индексе index. Доступ «сырой», т.е. метаметоды не вызыаются.
void lua_rawset (lua_State *L, int index);
Аналогича lua_settable, но совершает «сырое»присваивание (т.е., без метаметодов).
void lua_rawseti (lua_State *L, int index, int n);
Выполняет действия, аналогичные t[n] = v, где t – это значение по валидному индексу index, а v – значение на вершине стека.
&Эта функция выталкивает значение из стека. Присваивание – «сырое»; т.е., не вызывает метаметодов.
typedef const char * (*lua_Reader) (lua_State *L,
void *data,
size_t *size);
Функция чтения, используемая
lua_load. Каждый раз, когда требуется новая часть chunk, lua_load вызывает функцию чтения, передавая параметр data. Функция чтения должна возвращать указатель на блок памяти с новой частью chunk и выставлять size в значение разбера блоак. Блок должен существовать до тех пор пока функция не будет вызвана еще раз. Для того, чтобы сигнализировать об окончании chunk, функция чтения должна возвращать NULL. Функция чтения может возвращать части любого размера, большего ноля.
void lua_register (lua_State *L,
const char *name,
lua_CFunction f);
Выставляет функцию C f новым значением global name. Функция определена как макрос:
#define lua_register(L,n,f) \
(lua_pushcfunction(L, f), lua_setglobal(L, n))
void lua_remove (lua_State *L, int index);
Удаляет элемент по данному валидному индексу, сдвигая вниз элементы над этим индексом. Не может быть вызвана с псевдо-индексом, т.к. псевдо-индекс не является реальной позицией в стеке.
void lua_replace (lua_State *L, int index);
Копирует верхний элемент в соответствующую позицию (и выталкивает верхний элемент), без сдвига элементов (т.о. замещая значение в соответствующей позиции).
int lua_resume (lua_State *L, int narg);
Запускает и восстанавливает сопрограмму в данной нити.
Для запуска сопрограммы, вы сначала должны создать новую нить (см. lua_newthread); затем вы вставляете в ее стек главную функцию плюс любые аргументы; затем вы вызываетеlua_resume, с narg равным количеству аргументов. Эта функция закончит работу тогда, когда сопрограмма остановится (suspend) или закончит свое исполнение. Когда она остановится, стек будет содержать все значения, переданные lua_yield, или все значения, возвращенный функцией.lua_resume возвращает LUA_YIELD если сопрограмма уступает ресурсы, 0 если сопрограмма заканчивает свое выполнение без ошибок, или код ошибки в случае ошибочной ситуации (см. lua_pcall). В случае ошибок, стек не очищается (unwound), т.о. вы можете использовать API отладки для его анализа. Сообщение об ошибке находится на вершине стека. Для перезапуска сопрограммы, вы передаете в ее стек только значения, которые должны быть переданы как результаты yield, и затем вызываете lua_resume.
void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);
Изменяет функцию распределения (allocator function) данного состояния на f с пользовательскими данными ud.
int lua_setfenv (lua_State *L, int index);
Выталкивает таблицу из стека из стека и выставляет ей новое окружение для значения по заданному индексу. Если значение по данному индексу не является функцией, нитью или пользовательскими данными, lua_setfenv возвращает 0. Иначе, она возвращает 1.
void lua_setfield (lua_State *L, int index, const char *k);
Выполняет действие, аналогичное t[k] = v, где t – значение по заданному валидному индексу index и v – значение на вершине стека.
Эта функция выталкивает значение из стека. Также как в Lua, эта функция сожжет вызывать метаметод для события "новый индекс" (см. §2.8).
void lua_setglobal (lua_State *L, const char *name);
Выталкивает значение из стека и приравнивает его глобальной переменной (global) name. Определена как макрос:
#define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s)
int lua_setmetatable (lua_State *L, int index);
Выталкивает таблицу из стека и приравнивает ее метатаблице значения по заданному допустимому индексу.
void lua_settable (lua_State *L, int index);
Выполняет аналогичные t[k] = v действия, где t – это значение по заданному валидному индексу index, v – это значение на вершин стека, и k – это значение, находящееся на одно ниже вершины стека.
Эта функция выталкивает ключ и значение из стека. Также как в Lua, эта функция может вызывать метаметод для события "новый индекс" (см. §2.8).
void lua_settop (lua_State *L, int index);
Принивает любой допустимый индекс, или 0, и ставит вершину стека в этот индекс. Если новая вершина выше, чем старая, то новые элементы заполняются nil. Если индекс равен 0, то все значения стека очищаются.
typedef struct lua_State lua_State;
Непоницаемая (Opaque) структура, которая содержит полное состояние интерпретатора Lua. Библиотека Lua полностью реентерабельна: она не содержит глобальных переменных. Вся информация о состоянии содержится в этой структуре.
Указатель на это состояние должен передаваться как первый аргумент любой функции в библиотеке, кроме
lua_newstate, которая создает новое состояние Lua.
int lua_status (lua_State *L);
Возвращает состояние нити L.
Состояние может быть 0 для обычной нити, кодом ошибки, если нить завершила выполнение с ошибкой, или LUA_YIELD если нить остановлена.
int lua_toboolean (lua_State *L, int index);
Конвертирует значение Lua по указанному допустимому индексу в булево значение C (0 или 1). Как и все тесты в Lua, lua_toboolean возвращает 1 для любого значения Lua отличного от false и nil; в противном случае возвращает 0. Также возвращает 0 когда вызывается с не валидным индексом. (Если вы хотите получать только настоящие булевы значения, используйте lua_isboolean для проверки типа.)
lua_CFunction lua_tocfunction (lua_State *L, int index);
Конвертирует значение по заданному допустимому индексу в функцию C. Значение должно быть функцией C; иначе, она возвращает NULL.
lua_Integer lua_tointeger (lua_State *L, int idx);
Конвертирует значение Lua по заданному допустимому индексу в целый тип со знаком lua_Integer. Значение Lua должно быть числом или строкой, конвертируемой в число (см. §2.2.1); в противном случае, lua_tointeger возвращает 0.
Если число не целое, оно обрубается каким-то неопределенным способом (it is truncated in some non-specified way).
const char *lua_tolstring (lua_State *L, int index, size_t *len);
Конвертирует значение Lua по зданному допустимому индексу в функцию C. Если len не равна NULL, функция также возвращает в *len длину строки. Значение Lua должно быть строкой или числом; в противном случае, функция возвращает NULL. Если значение – число, то lua_tolstring также изменяет предыдущее значение в стеке на строку. (Это изменение «смущает» lua_next когда lua_tolstring применяется к ключам при обходе таблицы.)
lua_tolstring возвращает fully aligned pointer на строку в состоянии Lua. Эта строка всегда имеет ноль ('\0') после последнего символа (как в C), но может содержать также другие нули. Т.к. Lua обладает сборщиком мусора, нет гарантии что указатель, возвращенный lua_tolstring будет валиден после удаления соответствующео значения из стека.
lua_Number lua_tonumber (lua_State *L, int index);
Конвертирует значение Lua по данному допустимому индексу в тип C lua_Number
(см. lua_Number). Значение Lua должно быть числом или строкой, конвертируемой в число (см. §2.2.1); иначе, lua_tonumber возвращает 0.
const void *lua_topointer (lua_State *L, int index);
Конвертирует значение по заданному допустимому индексу в безтиповой указатель C (void*). Значение может быть различных типов: пользовательские данные, таблица, нить, или функция; в противном случае, lua_topointer возвращает NULL. Различные объекты дадут различные указатели. Не существует способа сконвертировать указатель назад, в исходное значение.
Обычно эту функцию используют для получения отладочной информации.
const char *lua_tostring (lua_State *L, int index);
Эквивалентна lua_tolstring с длиной len равной NULL.
lua_State *lua_tothread (lua_State *L, int index);
конвертирует значение в указанном допустимом индексе в нить Lua (представленную как lua_State*). Это значение должно буть нитью; иначе, функция возвращает NULL.
void *lua_touserdata (lua_State *L, int index);
Если знаение по указанному допустимому индексу – это full пользовательские данные, возвращает их адрес блока. Если значение – это light пользовательские данные, возвращает их указатель. В противном случае, возвращает NULL.
int lua_type (lua_State *L, int index);
Возвращает тип значения по указанному допустимому индексу, или LUA_TNONE для не валидного индекса (т.е., для индекса "пустой" ячейки стека). Типы, возвращаемые
lua_type,, закодированы следующими константами, определенными в lua.h: LUA_TNIL, LUA_TNUMBER, LUA_TBOOLEAN, LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION, LUA_TUSERDATA, LUA_TTHREAD, и LUA_TLIGHTUSERDATA.
const char *lua_typename (lua_State *L, int tp);
Возвращает имя типа, закодированного значением tp, которое должно быть одним из значений, возвращаемых
lua_type.
typedef int (*lua_Writer) (lua_State *L,
const void* p,
size_t sz,
void* ud);
Функция записи, используемая
lua_dump Каждый раз, когда она создает новую часть chunk, lua_dump вызывает функцию записи, передавая буфер для записи (p), его размер (sz), параметр data, передаваемый
lua_dump.
Функция записи возвращает код ошибки: 0 обозначает, что ошибок не произошло; любое другое значение обозначает ошибку и останавливает
lua_dump, предотвращая вызов функции записи снова.
void lua_xmove (lua_State *from, lua_State *to, int n);
Меняет местами знаяения между различными потоками одного глобального состояния.
Эта функция выталкивает n значений из стека from, и вставляет их в стек to.
int lua_yield (lua_State *L, int nresults);
Останавливает сопрограмму.
Эта функция должна быть использована только при передаче возвращаемого значения функции C, напр.:
return lua_yield (L, nresults);
Когда функция C вызывает
lua_yield таким образом, работающая сопрограмма останавливает свое выполнение, а вызовlua_resume, который заустил эту сопрограмму завершается. Параметр nresults – это число значений из стека, которые передаются как результаты в lua_resume.
|
