5 – Вспомогательная библиотека
Вспомогательная библиотека предоставляет несколько удобных функций для взаимодействия C с Lua.
В то время как основной API предоставляет простые функции для всех отношений между C и Lua, вспомогательная библиотека обеспечивает высокоуровневые функции для части распространенных задач.
Все функции и виды из дополнительной библиотеки определены в заголовочном файле lauxlib.h и имеют префикс luaL_.
Все функции дополнительной библиотеки выстроены поверх основного API и, поэтому не дают ничего, что нельзя было сделать с помощью этого API. Тем не менее, использование вспомогательной библиотеки обеспечит вашему коду большую насыщенность.
Отдельные функции вспомогательной библиотеки внутри используют несколько дополнительных слотов стека.
При использовании функцией вспомогательной библиотеки менее пяти слотов, она не проверяет размер стека; просто предполагается что имеется достаточно слотов.
Некоторые функции вспомогательной библиотеки используются для проверки аргументов функций на С.
Поскольку сообщение об ошибке форматируются для аргументов (например, "bad argument #1"), не используйте эти функции для других значений стека.
Если условия проверки не выполняются, функции с названиями luaL_check* всегда вызывают ошибку.
Здесь перечислены все функции и типы из вспомогательной библиотеки в алфавитном порядке.
[-?, +?, e]
void luaL_addchar (luaL_Buffer *B, char c);
Добавляет байт c в буфер B (смотрите luaL_Buffer).
[-?, +?, e]
void luaL_addlstring (luaL_Buffer *B,
const char *s,
size_t l);
Добавляет в буфер B строку (длиной l), на которую указывает указатель s (смотрите luaL_Buffer). Строка может содержать встроенные символы нуля.
[-?, +?, e]
void luaL_addsize (luaL_Buffer *B, size_t n);
Добавляет в буфер B (смотрите luaL_Buffer) строку длиной n предварительно скопированную в буферную область (смотрите luaL_prepbuffer).
[-?, +?, e]
void luaL_addstring (luaL_Buffer *B, const char *s);
Добавляет в буфер B строку, заканчивающуюся нулевым символом, и указанную указателем s (смотрите luaL_Buffer).
[-1, +?, e]
void luaL_addvalue (luaL_Buffer *B);
Добавляет значение с верхушки стека в буфер B (смотрите luaL_Buffer). Значение, при этом, извлекается из стека.
Это единственная функция на строковых буферах, которая может (и должна) вызываться с дополнительным элементом на стеке, который и является значением добавляемым в буфер.
[-0, +0, v]
void luaL_argcheck (lua_State *L,
int cond,
int arg,
const char *extramsg);
Проверяет истинно ли условие cond. Если это не так, выдает ошибку со стандартным сообщением об ошибке (смотрите luaL_argerror).
[-0, +0, v]
int luaL_argerror (lua_State *L,
int arg,
const char *extramsg);
Вызывает ошибку, сообщающую о проблеме с аргументом arg функции на C, что вызвала её; использует стандартное сообщение, которое в качестве комментария включает extramsg:
bad argument #arg to 'funcname' (extramsg)
Данная функция никогда не возвращает значение.
typedef struct luaL_Buffer luaL_Buffer;
Тип для строкового буфера (string buffer).
Строковый буфер позволяет C коду выстраивать строки Lua по частям.
Порядок её использования следующий:
- Первоначально объявляется переменная b типа luaL_Buffer.
- Затем она инициализируется вызовом luaL_buffinit(L, &b).
- Далее добавляем части строки в буфер вызывая любую из функций luaL_add*.
- Заканчиваем вызовом luaL_pushresult(&b). Этот вызов оставляет завершенную строку на вершине стека.
Если заранее известен полный размер результирующей строки, можно использовать буфер следующим образом:
- Вначале объявляем переменную b типа luaL_Buffer.
- Затем инициализируем её и предварительно выделяем место размером sz вызовом luaL_buffinitsize(L, &b, sz).
- Далее копируем строку в это выделенное пространство.
- Заканчиваем вызовом luaL_pushresultsize(&b, sz), где sz является полным размером результирующей строки, скопированной в данном месте.
При обычной работе строковый буфер использует переменное количество слотов стека. Так что пока используется буфер, нельзя предположить где находится вершина стека.
Можно использовать стек между последовательными вызовами операций с буфером, пока это использование сбалансировано; то есть, при вызове операции с буфером стек находится на том же уровне, где он был непосредственно после предыдущей операции над буфером.
(Единственным исключением из этого правила является luaL_addvalue.)
После вызова luaL_pushresult стек возвращается обратно на тот уровень, где он был при инициализации буфера, плюс финальная строка находится на его вершине.
[-0, +0, –]
void luaL_buffinit (lua_State *L, luaL_Buffer *B);
Инициализирует буфер B. Эта функция не выделяет никакого пространства; буфер должен быть объявлен как переменная (смотрите luaL_Buffer).
[-?, +?, e]
char *luaL_buffinitsize (lua_State *L,
luaL_Buffer *B,
size_t sz);
Эквивалентна (равноценна) последовательному вызову функций luaL_buffinit, luaL_prepbuffsize.
[-0, +(0|1), e]
int luaL_callmeta (lua_State *L,
int obj,
const char *e);
Вызывает метаметод.
Если у объекта с индексом obj имеется метатаблица и в этой метатаблице есть поле e, эта функция вызывает это поле передавая объект в качестве своего единственного аргумента.
В данном случае эта функция возвратит значение true и помещает в стек значение, возвращенное вызовом.
Если метатаблицы или метаметода не существует, эта функция возвращает значение false (без помещения какого-либо значения в стек).
[-0, +0, v]
void luaL_checkany (lua_State *L, int arg);
Проверяет, имеет ли функция аргумент какого-нибудь типа (включая nil) в позиции arg.
[-0, +0, v]
lua_Integer luaL_checkinteger (lua_State *L, int arg);
Проверяет, является ли аргумент arg функции целым числом (или может быть конвертирован в целое число) и возвращает это целое число приведенное к типу lua_Integer.
[-0, +0, v]
const char *luaL_checklstring (lua_State *L,
int arg,
size_t *l);
Проверяет, является ли аргумент arg функции строкой и возвращает эту строку; если l не является NULL заполняет *l длиной строки.
Эта функция для получения результата использует lua_tolstring, так что здесь применимы все преобразования и предостережения этой функции.
[-0, +0, v]
lua_Number luaL_checknumber (lua_State *L, int arg);
Проверяет, является ли аргумент arg функции числом и возвращает это число.
[-0, +0, v]
int luaL_checkoption (lua_State *L,
int arg,
const char *def,
const char *const lst[]);
Проверяет, является ли аргумент arg функции строкой и разыскивает эту строку в массиве lst (которая должна оканчиваться на NULL).
Возвращает индекс элемента массива в котором была найдена строка. Вызывает ошибку, если аргумент не является строкой или данная строка не была найдена.
Если указатель def не является NULL, функция использует def как значение по умолчанию, когда нет аргумента arg или он является nil.
Это полезная функция для отображения строк в C перечислениях. (В Lua библиотеках обычным соглашением является использование строк вместо чисел для выбора опций.)
[-0, +0, v]
void luaL_checkstack (lua_State *L,
int sz,
const char *msg);
Увеличивает размер стека до top + sz элементов и если не может увеличить этот размер, вызывает ошибку. msg - это дополнительный текст для вывода его в сообщении об ошибке (или значение NULL, когда дополнительный текст отсутствует).
[-0, +0, v]
const char *luaL_checkstring (lua_State *L, int arg);
Проверяет, является ли аргумент arg функции строкой и возвращает эту строку.
Данная функция для получения своего результата использует lua_tolstring, так что все преобразования и предостережения относительно этой функции применимы и здесь.
[-0, +0, v]
void luaL_checktype (lua_State *L, int arg, int t);
Проверяет, имеет ли аргумент arg функции тип t.
Чтобы узнать, как кодируется тип t, смотрите описание функции lua_type.
[-0, +0, v]
void *luaL_checkudata (lua_State *L,
int arg,
const char *tname);
Проверяет, является ли аргумент arg функции пользовательскими данными типа tname (смотрите luaL_newmetatable) и возвращает адрес этих userdata (смотрите lua_touserdata).
[-0, +0, –]
void luaL_checkversion (lua_State *L);
Проверяет, используют ли одну и ту же версию Lua: ядро, выполняющее вызов, ядро, которое создало Lua состояние, и код, сделавший вызов.
Также проверяет, используют ли одно и тоже адресное пространство: ядро, выполняющее вызов, и ядро, которое создало Lua-состояние.
[-0, +?, e]
int luaL_dofile (lua_State *L, const char *filename);
Загружает и запускает заданный файл. Данная функция определяется как следующий макрос:
(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
Если нет ошибок, функция, возвращает false; в случае ошибок - возвращается true.
[-0, +?, –]
int luaL_dostring (lua_State *L, const char *str);
Загружает и запускает заданную строку. Функция определяется как следующий макрос:
(luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
Если нет ошибок, функция, возвращает false; в случае ошибок - возвращается true.
[-0, +0, v]
int luaL_error (lua_State *L, const char *fmt, ...);
Вызывает ошибку. Формат сообщения об ошибке задается fmt плюс любые дополнительные аргументы, следующие тем же правилам что и lua_pushfstring.
Также она добавляет в начале сообщения (если эта информация доступна) имя файла и номер строки, где произошла ошибка.
Данная функция ничего и никогда не возвращает, но она является идиомой для использования в C функциях как return luaL_error(args).
[-0, +3, e]
int luaL_execresult (lua_State *L, int stat);
Данная функция производит возврат значений для функций, связанных с процессом, в стандартной библиотеке (os.execute и io.close).
[-0, +(1|3), e]
int luaL_fileresult (lua_State *L,
int stat,
const char *fname);
Данная функция производит возврат значений для функций, связанных с файлом, в стандартной библиотеке (io.open, os.rename, file:seek, и т.д.).
[-0, +(0|1), e]
int luaL_getmetafield (lua_State *L,
int obj,
const char *e);
Помещает в стек поле e из метатаблицы объекта с индексом obj и возвращает тип размещенного значения.
Если объект не имеет метатаблицы или в метатаблице нет такого поля, функция ничего в стек не записывает и возвращает LUA_TNIL.
[-0, +1, –]
int luaL_getmetatable (lua_State *L,
const char *tname);
Помещает в стек метатаблицу, связанную в реестре с именем tname (смотрите luaL_newmetatable) (или nil, если не существует метатаблицы, связанной с этим именем).
Возвращает тип записанного значения.
[-0, +1, e]
int luaL_getsubtable (lua_State *L,
int idx,
const char *fname);
Убеждается что значение t[fname], где t является значением с индексом idx, является таблицей, и помещает эту таблицу в стек.
Возвращает true, если функция находит там предыдущую таблицу и false, если она создает новую таблицу.
[-0, +1, e]
const char *luaL_gsub (lua_State *L,
const char *s,
const char *p,
const char *r);
Создает копию строки s заменяя любое вхождение строки p строкой r. Помещает результирующую строку в стек и возвращает её.
[-0, +0, e]
lua_Integer luaL_len (lua_State *L, int index);
Возвращает "длину" значения по заданному индексу как число; это эквивалент операции '#' в Lua (смотрите §3.4.7).
Вызывает ошибку если результат операции не является целым числом. (Такой случай может произойти только через метаметоды.)
[-0, +1, –]
int luaL_loadbuffer (lua_State *L,
const char *buff,
size_t sz,
const char *name);
Функция эквивалентна luaL_loadbufferx с аргументом mode равным NULL.
[-0, +1, –]
int luaL_loadbufferx (lua_State *L,
const char *buff,
size_t sz,
const char *name,
const char *mode);
Загружает буфер как блок (chunk) Lua. Эта функция использует lua_load для загрузки блока в буфер, с указателем buff с размером sz.
Данная функция возвращает те же самые результаты, что и lua_load. Аргумент name - это имя блока, используемого для отладочной информации и сообщений об ошибках.
Строка mode работает как в функции lua_load.
[-0, +1, e]
int luaL_loadfile (lua_State *L,
const char *filename);
Функция эквивалентна luaL_loadfilex с аргументом mode равным NULL.
[-0, +1, e]
int luaL_loadfilex (lua_State *L,
const char *filename,
const char *mode);
Загружает файл как блок (chunk) Lua. Данная функция использует lua_load для загрузки блока в файле по имени filename.
Если значением аргумента filename является NULL, то функция загружает из стандартного ввода. Первая строка в файле игнорируется, если начинается с символа #.
Строковый аргумент mode работает как в функции lua_load.
Эта функция возвращает те же результаты, что и lua_load, но имеет дополнительный код ошибки LUA_ERRFILE, на случай, если она не может открыть/считать файл или файл имеет неправильный режим.
Как и lua_load, данная функция только загружает блок, но не запускает его.
[-0, +1, –]
int luaL_loadstring (lua_State *L, const char *s);
Запускает строку как блок (chunk) Lua. Эта функция использует lua_load для загрузки блока в строке s, заканчивающейся символом нуля.
Эта функция возвращает те же результаты, что и lua_load.
Также как lua_load, данная функция только загружает блок, но не запускает его.
[-0, +1, e]
void luaL_newlib (lua_State *L, const luaL_Reg l[]);
Функция создает новую таблицу и регистрирует там функции в списке l.
Она реализуется как следующий макрос:
(luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
Массив l должен быть на самом деле массивом, а не указателем на него.
[-0, +1, e]
void luaL_newlibtable (lua_State *L,
const luaL_Reg l[]);
Функция создает новую таблицу с размером, оптимизированным под хранение всех записей массива l (но на самом деле не хранит их).
Она предназначена для совместной работы с функцией luaL_setfuncs (смотрите luaL_newlib).
Функция реализована как макрос. Массив l должен быть на самом деле архивом, а не указателем на него.
[-0, +1, e]
int luaL_newmetatable (lua_State *L, const char *tname);
Если в реестре уже имеется ключ tname, возвращается 0.
В противном случае, создает новую таблицу, которая будет использоваться как метатаблица для userdata, добавляет в эту новую таблицу пару __name = tname, дополняет реестр парой [tname] = new table и возвращает 1.
(Запись __name используется некоторыми функциями, сообщающими об ошибках.)
В обоих случаях в стек помещается конечное значение, связанное в реестре с tname.
[-0, +0, –]
lua_State *luaL_newstate (void);
Функция создает новое Lua состояние.
Она вызывает lua_newstate с функцией выделения памяти на основе стандартной функции C realloc и затем устанавливает "тревожную" (panic) функцию (смотрите §4.6), которая печатает сообщение об ошибке к стандартному выводу ошибки в случае фатальных (неустранимых) ошибок.
Возвращает новое состояние или значение NULL, если есть ошибка выделения памяти.
[-0, +0, e]
void luaL_openlibs (lua_State *L);
Функция, в заданном состоянии Lua, открывает все стандартные библиотеки.
[-0, +0, v]
lua_Integer luaL_optinteger (lua_State *L,
int arg,
lua_Integer d);
Если аргумент arg функции является целым числом (или возможно преобразование его в целое число), возвращает это целое число.
Если данный аргумент отсутствует или является nil, возвращается аргумент d. В других случаях вызывает ошибку.
[-0, +0, v]
const char *luaL_optlstring (lua_State *L,
int arg,
const char *d,
size_t *l);
Если аргумент arg функции является строкой, возвращается эта строка. Если данный аргумент отсутствует или является nil, возвращается аргумент d. В других случаях вызывает ошибку.
Если аргумент l не является NULL, заполняет позицию указанную *l, длиной получившейся строки.
[-0, +0, v]
lua_Number luaL_optnumber (lua_State *L,
int arg,
lua_Number d);
Если аргумент arg функции является числом, возвращается это число. Если данный аргумент отсутствует или является nil, возвращается аргумент d. В других случаях вызывает ошибку.
[-0, +0, v]
const char *luaL_optstring (lua_State *L,
int arg,
const char *d);
Если аргумент arg функции является строкой, возвращается эта строка. Если данный аргумент отсутствует или является nil, возвращается аргумент d. В других случаях вызывает ошибку.
[-?, +?, e]
char *luaL_prepbuffer (luaL_Buffer *B);
Функция эквивалентна функции luaL_prepbuffsize с предопределенным размером LUAL_BUFFERSIZE.
[-?, +?, e]
char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);
Возвращает адрес на место в памяти размером sz, где можно скопировать строку для добавления в буфер B (смотрите luaL_Buffer).
После копирования строки в этом месте следует вызвать функцию luaL_addsize с размером строки, чтобы на самом деле добавить её в буфер.
[-?, +1, e]
void luaL_pushresult (luaL_Buffer *B);
Завершает использование буфера B оставляя последнюю строку на вершине стека.
[-?, +1, e]
void luaL_pushresultsize (luaL_Buffer *B, size_t sz);
Функция эквивалентна последовательному применению luaL_addsize, luaL_pushresult.
[-1, +0, e]
int luaL_ref (lua_State *L, int t);
Создает и возвращает ссылку, на элемент таблицы с индексом t, для объекта на вершине стека (и выталкивает объект из стека).
Ссылкой является уникальный целочисленный ключ.
До тех пор, пока в таблицу t не добавлять вручную целочисленные ключи, luaL_ref гарантирует уникальность ключа, им возвращаемого.
Получить объект, связанный со ссылкой r можно вызовом lua_rawgeti(L, t, r).
Функция luaL_unref высвобождает ссылку и связанный с ней объект.
Если объект на вершине стека является nil, luaL_ref возвращает константу LUA_REFNIL.
Константа LUA_NOREF гарантированно будет отличаться от каких-либо ссылок, возвращаемых luaL_ref.
typedef struct luaL_Reg {
const char *name;
lua_CFunction func;
} luaL_Reg;
Тип для массивов функций, регистрируемых функцией luaL_setfuncs. name - это имя функции, а func является указателем на функцию.
Любой массив из luaL_Reg должен оканчиваться охранной записью, в которой оба, и name и func являются NULL.
[-0, +1, e]
void luaL_requiref (lua_State *L,
const char *modname,
lua_CFunction openf,
int glb);
Если modname уже не представлена в package.loaded, то данная функция вызывает функцию openf со строкой modname
в качестве аргумента и устанавливает результат вызова в package.loaded[modname], как если бы эта функция была вызвана через require.
Если glb истинно, модуль также сохраняется в глобальной modname.
Оставляет копию модуля в стеке.
[-nup, +0, e]
void luaL_setfuncs (lua_State *L,
const luaL_Reg *l,
int nup);
Регистрирует все функции в массиве l (смотрите luaL_Reg) в таблице на вершине стека (ниже дополнительных , смотрите далее).
Когда nup не является нулем, все функции создают совместно используемые нелокальные переменные nup, которые могут быть предварительно помещены в стек на вершине библиотечной таблицы.
После регистрации эти значения извлекаются из стека.
[-0, +0, –]
void luaL_setmetatable (lua_State *L,
const char *tname);
Устанавливает метатаблицу объекта, находящегося на вершине стека, как метатаблицу, связанную с именем tname в реестре (смотрите luaL_newmetatable).
typedef struct luaL_Stream {
FILE *f;
lua_CFunction closef;
} luaL_Stream;
Стандартное представление для дескрипторов (handle) файла, которые используются стандартной библиотекой ввода/вывода (I/O).
Дескриптор файла реализован в виде полноценного объекта userdata, с метатаблицей, называемой LUA_FILEHANDLE (где LUA_FILEHANDLE - это макрос с фактическим именем метатаблицы).
Метатаблица создается библиотекой ввода/вывода (I/O) (смотрите luaL_newmetatable).
Эти userdata должны начинаться со структуры luaL_Stream; они могут содержать другие данные после этой начальной структуры.
Поле f указывает на соответствующий C поток (или он может быть равен NULL, чтобы показать на не полностью созданный дескриптор).
Поле closef указывает на функцию Lua, которая будет вызываться для завершения потока, когда дескриптор будет закрыт или собран (сборщиком мусора);
эта функция принимает дескриптор файла в качестве своего единственного аргумента и должна возвратить либо true (в случае успешного выполнения) либо nil плюс сообщение об ошибке (в случае ошибки).
После того, как Lua вызовет это поле, значение поля изменяется на NULL чтобы сигнализировать о закрытии дескриптора.
[-0, +0, e]
void *luaL_testudata (lua_State *L,
int arg,
const char *tname);
Данная функция работает как luaL_checkudata, за исключением того, что при неудачах проверки она возвращает NULL вместо вызова ошибки.
[-0, +1, e]
const char *luaL_tolstring (lua_State *L,
int idx,
size_t *len);
Конвертирует любое Lua значение по заданному индексу в C строку в подходящем формате. Получившаяся строка помещается в стек, а также возвращается функцией.
Если аргумент len не является NULL, функция также устанавливает *len с длиной строки.
Если значение имеет метатаблицу с полем "__tostring", то функция luaL_tolstring вызывает соответствующий метаметод со значением в качестве аргумента и использует результат вызова как свой результат.
[-0, +1, e]
void luaL_traceback (lua_State *L,
lua_State *L1,
const char *msg,
int level);
Функция создает и помещает в стек стека L1.
Если msg не является NULL, он добавляется к началу отслеживания. Параметр level указывает, на каком уровне начинать отслеживание стека.
[-0, +0, –]
const char *luaL_typename (lua_State *L, int index);
Возвращает название типа значения по заданному индексу.
[-0, +0, –]
void luaL_unref (lua_State *L, int t, int ref);
Функция высвобождает ссылку ref на объект таблицы по индексу t (смотрите luaL_ref).
Запись удаляется из таблицы, так что объект, на который была ссылка, может буть собран сборщиком мусора. Ссылка ref также освобождается для последующего использования.
Если ref является LUA_NOREF или LUA_REFNIL, функция luaL_unref ничего не делает.
[-0, +1, e]
void luaL_where (lua_State *L, int lvl);
Помещает в стек строку, определяющую текущее положение управления уровнем lvl в вызове стека.
Обычно эта строка имеет следующий формат:
chunkname:currentline:
Уровень 0 - это выполняемая функция, уровень 1 - это функция, которая вызвала выполняемую функцию, и т.д.
Данная функция используется для построения префикса сообщений об ошибках.