Справочное руководство по языку Lua 5.1 :: 4.1 -
4.1 – Функции и типы
В этой главе мы опишем все функции и типа из вспомогательной библиотеки в алфавитном порядке.
luaL_addchar
void luaL_addchar (luaL_Buffer *B, char c);
Добавляет символ c в буфер B (см. luaL_Buffer).
luaL_addlstring
void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);
Добавляет строку, на которую ссылается указатель s, длиной l в буфер B(см. luaL_Buffer). Строка может содержать нулевые символы.
luaL_addsize
void luaL_addsize (luaL_Buffer *B, size_t n);
Добавляет в буфер B (см. luaL_Buffer) строку длиной n, первоначально скопированную в область буфера (см. luaL_prepbuffer).
luaL_addstring
void luaL_addstring (luaL_Buffer *B, const char *s);
Добавляет строку с нулевым символом в конце, на которую указывает указатель s в буфер B (см. luaL_Buffer). Строка не может содержать нулевых символов кроме последнего..
luaL_addvalue
void luaL_addvalue (luaL_Buffer *B);
Добавляет значение из вершины стека в буфер B (см. luaL_Buffer. При этом, из стека это значение извлекается.
Это единственная функция, которая должна быть вызвана с дополнительным значением, размещенным в стеке, которое затем и помещается в буфер.
luaL_argcheck
void luaL_argcheck (lua_State *L,
int cond,
int narg,
const char *extramsg);
Проверяет на истинность условие cond. Если значение ложно, вызывает ошибку следующего содержания (где func определяется из стека вызова):
bad argument #<narg> to <func> (<extramsg>)
luaL_argerror
int luaL_argerror (lua_State *L, int narg, const char *extramsg);
вызывает ошибку следующего содержания (где func определяется из стека вызова):
bad argument #<narg> to <func> (<extramsg>)
Эта функция ничего не возвращает, но для поддержки идиомы C ее можно использовать как return luaL_argerror(args).
luaL_Buffer
typedef struct luaL_Buffer luaL_Buffer;
Тип данных для буфера строк.
Буфер строк позволяет коду на C постепенно строить строки Lua. Использовать его можно по следующей схеме:
- Сначала вы объявляете переменную b типа luaL_Buffer.
- Затем вы инициализируете ее при помощи luaL_buffinit(L, &b).
- После этот добавляйте фрагменты строк, вызывая любую функцию из семейства luaL_add*.
- Для окончания, вызывайте luaL_pushresult(&b). Этот вызов оставляет результирующую строку на вершине стека..
Во время обычной операции, буфер строк использует переменное количество слотов стека. Поэтому, используя буфер, вы не можете предполагать, что вы знаете, где находится вершина стека. Вы можете использовать стек между успешными вызовами к операциями над буфером до тех пор, пока его использование сбалансировано; т.е. когда вы вызываете операцию над буфером, стек находится на том же уровне, что и был после предыдущей операцией над буфером. (Единственное исключение из этого правила – это luaL_addvalue.) После вызова luaL_pushresult стек возвращается обратно на тот уровен, на котором он был, когда буфер был инициализирован, но на вершине у него будет храниться результирующая строка.
luaL_buffinit
void luaL_buffinit (lua_State *L, luaL_Buffer *B);
Инициализирует буфер B. Эта функция не выделяет место в памяти; буфер должен быть объявлен как переменная (см. luaL_Buffer
luaL_callmeta.
int luaL_callmeta (lua_State *L, int obj, const char *e);
Вызывает метаметод.
Если объект под индексом obj имеет метатаблицу и она имеет поле e, эта функция вызывает это поле и передает ему объект как единственный аргумент. В этом случае функция возвращает 1 и записывает в стек значение, возвращаемое таким вызовом. Если объект не имеет ни метатаблицы ни метаметода, функция возвращает 0 (и ничего не записывает в стек).
luaL_checkany
void luaL_checkany (lua_State *L, int narg);
Проверяет, имеет ли функция аргумент любого типа (включая nil) на позиции narg.
luaL_checkint
int luaL_checkint (lua_State *L, int narg);
Проверяет, является ли narg-ый аргумент функции числом и возвращает это число, приведенное к типу int<
luaL_checkinteger<
lua_Integer luaL_checkinteger (lua_State *L, int narg);
Проверяет, является ли narg-- ый аргумент функции числом и возвращает это число, приведенное к типу lua_Integer.
luaL_checklong
long luaL_checklong (lua_State *L, int narg);
Проверяет, является ли narg-ый аргумент функции числом и возвращает это число, приведенное к типу long.
luaL_checklstring
const char *luaL_checklstring (lua_State *L, int narg, size_t *l);
Проверяет, является ли narg--ый аргумент функции строки и возвращает эту строку; если l не NULL, заполняет *lзначением, равным длине строки.
luaL_checknumber
lua_Number luaL_checknumber (lua_State *L, int narg);
Проверяет, является ли narg-ый аргумент функции числом и возвращает это число.
luaL_checkoption
int luaL_checkoption (lua_State *L,
int narg,
const char *def,
const char *const lst[]);
Проверяет, является ли narg-ый аргумент функции строкой и ищет эту строку в массиве lst (который должен оканчиваться на NULL). Возвращает индекс элемента массива, в котором была найдена строка. Порождает ошибку, если аргумент строкой не является, или она не была найдена в массиве.
Если def не NULL, функция использует def как значение по умолчанию, когда не существует narg-ого аргумента или если этот аргумент является nil.
Эта функция часто используется для сопоставления строк с перечисляемыми типами C. (Обычно, в библиотеках Lua используется соглашение использовать строки вместо чисел для выбора опций.)
luaL_checkstack
void luaL_checkstack (lua_State *L, int sz, const char *msg);
Увеличивает размер стека до top + sz элементов, порождает ошибку, если стек не может быть увеличен до такого размера. Строка msg содержит дополнительный текст для сообщения об ошибке.
luaL_checkstring
const char *luaL_checkstring (lua_State *L, int narg);
Проверяет, является ли narg-ый аргумент функции строкой и возвращает эту строку.
luaL_checktype
void luaL_checktype (lua_State *L, int narg, int t);
Проверяет, имеет ли narg–ый аргумент функции тип t.
luaL_checkudata
void *luaL_checkudata (lua_State *L, int narg, const char *tname);
Проверяет, является ли narg-ый аргумент функции переменной C, хранящейся в переменной LUA (т.н. userdata) типа tname (см. luaL_newmetatable
luaL_dofile
int luaL_dofile (lua_State *L, const char *filename);
Загружает и запускает указанный файл. Эта функция определена как следующий макрос:
(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
Возвращает 0, если в процессе выполнения не встретились ошибки, 1 в противном случае.
luaL_dostring
int luaL_dostring (lua_State *L, const char *str);
Загружает и запускает указанную строку. Эта функция определена как следующий макрос:
(luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
Возвращает 0, если в процессе выполнения не встретились ошибки, 1 в противном случае.
luaL_error<
int luaL_error (lua_State *L, const char *fmt, ...);
Возбуждает ошибку. Формат сообщения об ошибках задается параметром fmt и любыми дополнительными аргументами, подчиняющиеся тем же правилам, что и параметры lua_pushfstring.Кроме того, эта функция добавляет в начало сообщения имя файла и номер строки, в которых обнаружилась ошибка, если эта информация доступна.
Эта функция ничего не возвращает, но для поддержки идиомы C ее можно использовать как return luaL_error(args).
luaL_getmetafield
int luaL_getmetafield (lua_State *L, int obj, const char *e);
Записывает в стек поле e из метатаблицы объекта с индексом obj. Если объект не имеет метатаблицы или она не имеет указанного поля, функция возвращает 0 и ничего в стек не записывает.
luaL_getmetatable
void luaL_getmetatable (lua_State *L, const char *tname);
Записывает в стек метатаблицу, ассоциированную в реестре с именем tname (см. luaL_newmetatable<).
luaL_gsub
const char *luaL_gsub (lua_State *L,
const char *s,
const char *p,
const char *r);
Создает копию строки s, заменяя любое вхождение строки p строкой r. Записывает в стек результирующую строку и возвращает ее же.
luaL_loadbuffer
int luaL_loadbuffer (lua_State *L,
const char *buff,
size_t sz,
const char *name);
Загружает буфер как модуль (chunk) Lua. Эта функция используетlua_load для загрузки модули в буфер, на который указывает buff размером sz.
Эта функция возвращает те же результаты, что иlua_load. Параметр name - это имя модуля (chunk), используемое для отладочной информации и в сообщениях об ошибках.
luaL_loadfile
int luaL_loadfile (lua_State *L, const char *filename);
Загружает файл как модуль (chunk) Lua. Эта функция использует lua_load для загрузки модуля из файла с именем filename. Если filename является NULL, тогда загрузка происходит из стандартного потока ввода. Первая строка файла игнорируется, если она начинается с символа #.
Эта функция возвращает такие же результаты, что и lua_load, но помимо этого обладает дополнительным кодом ошибки LUA_ERRFILE на тот случае, если невозможно открыть или прочитать файл.
Как и lua_load, эта функция, только загружает модуль (chunk), но не запускает его.
luaL_loadstring
int luaL_loadstring (lua_State *L, const char *s);
Загружает строку как модуль (chunk) Lua. Эта функция используетlua_load для загрузки модуля (chunk) в оканчивающейся нулем строке s.
Эта функция возвращает такие же результаты, как и lua_load.
Как и lua_load, эта функция, только загружает модуль (chunk), но не запускает его.
luaL_newmetatable
int luaL_newmetatable (lua_State *L, const char *tname);
Если реестр уже содержит ключ tname, возвращает 0. В противном случае, создает новую таблицу в качестве метатаблицы для переменной C, хранящейся в переменной LUA (userdata), добавляет ее в реестр с именем tname и возвращает 1.
В каждом из этих двух случаев, помещает в стек последнее значение, ассоциированное с именем tname в реестре.
luaL_newstate
lua_State *luaL_newstate (void);
Создает новое состояние Lua. Функция вызывает lua_newstate, используя стандартную функцию C realloc для выделения памяти, а затем использует функцию обработки ошибок (см. lua_atpanic), которая выводит сообщение об ошибке на стандартный поток вывода в случае фатальных ошибок.
Возвращает новое состояние или NULL, если в процессе выделения памяти встретились ошибки.
luaL_openlibs
void luaL_openlibs (lua_State *L);
Открывает все стандартные библиотеки Lua в контексте заданного состояния.
luaL_optint
int luaL_optint (lua_State *L, int narg, int d);
Если аргумент функции narg является числом, возвращает это число, приведенное к типу int. Если аргумент опущен или является nil – возвращает d. В противном случае – возбуждает ошибку.
luaL_optinteger
lua_Integer luaL_optinteger (lua_State *L,
int narg,
lua_Integer d);
Если аргумент функции narg является числом, возвращает это число, приведенное к типу данных lua_Integer. Если аргумент опущен или является nil – возвращает d. В противном случае – возбуждает ошибку.
luaL_optlong
long luaL_optlong (lua_State *L, int narg, long d);
Если аргумент функции narg является числом, возвращает это число, приведенное к типу данных long. Если аргумент опущен или является nil – возвращает d. В противном случае – возбуждает ошибку.
luaL_optlstring
const char *luaL_optlstring (lua_State *L,
int narg,
const char *d,
size_t *l);
Если аргумент функции narg является строкой, то возвращает эту строку. Если аргумент опущен или является nil – возвращает d. В противном случае – возбуждает ошибку.
Если l не является NULL, записывает в положение *l длину результата.
luaL_optnumber
lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);
Если аргумент функции narg является числом, то возвращает это число. Если аргумент опущен или является nil – возвращает d. В противном случае – возбуждает ошибку.
luaL_optstring
const char *luaL_optstring (lua_State *L,
int narg,
const char *d);
Если аргумент функции narg является строкой, то возвращает эту строку. Если аргумент опущен или является nil – возвращает d. В противном случае – возбуждает ошибку.
luaL_prepbuffer
char *luaL_prepbuffer (luaL_Buffer *B);
Возвращает указатель на место в памяти, размером LUAL_BUFFERSIZE, где можно копировать строку для добавления в буфер B (см. luaL_Buffer). После копирования строки в эту область памяти необходимо вызватьluaL_addsize с указанием размера строки, чтобы действительно добавить ее в буфер.
luaL_pushresult
void luaL_pushresult (luaL_Buffer *B);
Завершает использование буфера B, оставляя окончательную строчку на вершине стека.
luaL_ref
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.
luaL_Reg
typedef struct luaL_Reg {
const char *name;
lua_CFunction func;
} luaL_Reg;
Тип для массивов функций, регистрируемых функциейluaL_register. Параметр name – имя функции, func – указатель на эту функцию. Каждый массив luaL_Regдолжен оканчиваться предупреждающей записью, в которой name и func являются NULL.
luaL_register<
void luaL_register (lua_State *L,
const char *libname,
const luaL_Reg *l);
Открывает библиотеку.
При вызове со значением libname равным NULL, эта функция просто регистрирует все функции в списке l (см. luaL_Regв таблице на вершине стека.
При вызове с не null значением libname, luaL_register создает новую таблицу t, устанавливает ее как значение глобальной переменной libname, устанавливает ее также как значение package.loaded[libname] и регистрирует в ней все функции из списка l. Если таблица уже находится в package.loaded[libname] или в переменной libname, использует заново эту таблицу взамен создания новой.
В любом случае, функция оставляет таблицу на вершине стека.
luaL_typename
const char *luaL_typename (lua_State *L, int idx);
Возвращает имя типа данных значения с индексом idx.
luaL_typerror
int luaL_typerror (lua_State *L, int narg, const char *tname);
Генерирует ошибку с сообщением, подобным следующему:
location: bad argument narg to 'func' (tname expected, got rt)
где location заполняется luaL_where,func имя текущей функции и rt имя типа актуального аргумента.
luaL_unref
void luaL_unref (lua_State *L, int t, int ref);
Освобождение ссылки ref из таблицы с индексом t (см. luaL_ref). Запись удаляется из таблицы, таким образом, что объекты, на которые они ссылаются, могут быть собраны. Ссылка ref is также освобождается для дальнейшего использования.
Если ref имеет значение LUA_NOREF или LUA_REFNIL, функция luaL_unref не выполняет никаких действий.
luaL_where
void luaL_where (lua_State *L, int lvl);
Записывает в стек строку, идентифицирующую текущее положение котролирующей единицы с уровнем lvl в стеке вызова. Обычно, эта строка имеет следующий формат:
chunkname:currentline
Уровень 0 - это выполняемая функция, уровень 1 - это функция, которая вызвала выполняемую функцию и т.д.
Эта функция используется для построения префикса для сообщений об ошибках.