文字

所述辅助库提供了几个方便的功能的接口下用的Lua。尽管基本API为C和Lua之间的所有交互提供了原始函数,但辅助库为一些常见任务提供了更高级的函数。

辅助库中的所有函数和类型都在头文件中定义lauxlib.h并具有前缀luaL_

辅助库中的所有功能都建立在基本API之上,因此它们不提供任何使用该API无法完成的功能。尽管如此,使用辅助库确保了代码的更一致性。

辅助库中的几个函数在内部使用一些额外的堆栈槽。当辅助库中的函数使用少于5个插槽时,它不检查堆栈大小; 它只是假设有足够的插槽。

辅助库中的几个函数用于检查C函数参数。由于错误消息的格式为参数(例如,“ bad argument #1”),因此不应将这些函数用于其他堆栈值。

luaL_check*如果检查不满足,称为函数总是会引发错误。

5.1 – Functions and Types

这里我们按字母顺序列出辅助库中的所有函数和类型。

luaL_addchar-?, +?, m

void luaL_addchar (luaL_Buffer *B, char c);

将该字节添加c到缓冲区B(请参阅luaL_Buffer)。

luaL_addlstring-?, +?, m

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_Buffern以前复制到缓冲区的长度的字符串(请参阅参考资料luaL_prepbuffer)。

luaL_addstring-?, +?, m

void luaL_addstring (luaL_Buffer *B, const char *s);

将指向的由零结尾的字符串添加s到缓冲区B(请参阅luaL_Buffer)。

luaL_addvalue-1, +?, m

void luaL_addvalue (luaL_Buffer *B);

将堆栈顶部的值添加到缓冲区B(请参阅luaL_Buffer)。弹出该值。

这是字符串缓冲区中唯一可以(并且必须)用堆栈上的额外元素调用的函数,这是要添加到缓冲区的值。

luaL_argcheck-0, +0, v

void luaL_argcheck (lua_State *L,
                    int cond,
                    int arg,                    const char *extramsg);

检查是否cond为真。如果不是,则用标准消息引发错误(请参阅参考资料luaL_argerror)。

luaL_argerror-0, +0, v

int luaL_argerror (lua_State *L, int arg, const char *extramsg);

arg使用包含extramsg以下注释的标准消息引发一个报告问题的错误:调用它的C函数的参数:

bad argument #arg to 'funcname' (extramsg)

这个函数不会返回。

luaL_Buffer

typedef struct luaL_Buffer luaL_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初始化缓冲区时,调用堆栈后返回其级别,并在其顶部添加最后一个字符串。

luaL_buffinit-0, +0, –

void luaL_buffinit (lua_State *L, luaL_Buffer *B);

初始化一个缓冲区B。此功能不分配任何空间; 必须将缓冲区声明为变量(请参阅luaL_Buffer)。

luaL_buffinitsize-?, +?, m

char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);

相当于序列luaL_buffinitluaL_prepbuffsize

luaL_callmeta-0, +(0|1), e

int luaL_callmeta (lua_State *L, int obj, const char *e);

Calls a metamethod.

如果索引处的对象obj具有metatable,并且此metatable具有一个字段e,则此函数将调用此字段作为其唯一参数传递该对象。在这种情况下,该函数返回true,并将该调用返回的值压入堆栈。如果没有metatable或者没有metamethod,这个函数返回false(没有在栈上压入任何值)。

luaL_checkany-0, +0, v

void luaL_checkany (lua_State *L, int arg);

检查函数是否有任何类型的参数(包括arg

luaL_checkinteger-0, +0, v

lua_Integer luaL_checkinteger (lua_State *L, int arg);

检查函数参数arg是否为整数(或可以转换为整数)并将此整型转换为一个lua_Integer

luaL_checklstring-0, +0, v

const char *luaL_checklstring (lua_State *L, int arg, size_t *l);

检查函数参数arg是否是字符串并返回此字符串; 如果lNULL填充*l字符串的长度。

此功能用于lua_tolstring获取其结果,因此此功能的所有转换和注意事项均适用于此。

luaL_checknumber-0, +0, v

lua_Number luaL_checknumber (lua_State *L, int arg);

检查函数参数arg是否是数字并返回此数字。

luaL_checkoption-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或此参数为零时,该函数将用作默认值。

这是一个将字符串映射到C枚举的有用函数。(Lua库中的常规约定是使用字符串而不是数字来选择选项。)

luaL_checkstack-0, +0, v

void luaL_checkstack (lua_State *L, int sz, const char *msg);

将堆栈大小增加到top + sz元素,如果堆栈无法增长到该大小,则会引发错误。msg是进入错误消息(或NULL没有其他文本)的附加文本。

luaL_checkstring-0, +0, v

const char *luaL_checkstring (lua_State *L, int arg);

检查函数参数arg是否为字符串并返回此字符串。

此功能用于lua_tolstring获取其结果,因此此功能的所有转换和注意事项均适用于此。

luaL_checktype-0, +0, v

void luaL_checktype (lua_State *L, int arg, int t);

检查函数参数是否arg具有类型t。请参阅有关lua_type类型的编码t

luaL_checkudata-0, +0, v

void *luaL_checkudata (lua_State *L, int arg, const char *tname);

检查函数参数是否arg是该类型的用户数据tname(请参阅luaL_newmetatable)并返回用户数据地址(请参阅参考资料lua_touserdata)。

luaL_checkversion-0, +0, v

void luaL_checkversion (lua_State *L);

检查运行呼叫的核心,创建Lua状态的核心以及发起呼叫的代码是否都使用相同版本的Lua。还检查运行调用的内核和创建Lua状态的内核是否使用相同的地址空间。

luaL_dofile-0, +?, e

int luaL_dofile (lua_State *L, const char *filename);

加载并运行给定的文件。它被定义为以下宏:

(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))

如果没有错误,则返回false,如果发生错误,则返回true。

luaL_dostring-0, +?, –

int luaL_dostring (lua_State *L, const char *str);

加载并运行给定的字符串。它被定义为以下宏:

(luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))

如果没有错误,则返回false,如果发生错误,则返回true。

luaL_error-0, +0, v

int luaL_error (lua_State *L, const char *fmt, ...);

引发错误。错误消息格式由fmt加上任何额外的参数给出,遵循相同的规则lua_pushfstring。如果该信息可用,它还会在消息的开始处添加文件名和发生错误的行号。

这个函数永远不会返回,但它是一个在C函数中使用它的习惯用法。return luaL_error(args)

luaL_execresult-0, +3, m

int luaL_execresult (lua_State *L, int stat);

该函数为标准库(os.executeio.close)中与进程相关的函数生成返回值。

luaL_fileresult-0, +(1|3), m

int luaL_fileresult (lua_State *L, int stat, const char *fname);

该功能用于在标准库文件有关的功能(生成的返回值io.openos.renamefile:seek等等)。

luaL_getmetafield-0, +(0|1), m

int luaL_getmetafield (lua_State *L, int obj, const char *e);

e从索引处的对象的元表单中将字段推入堆栈,obj并返回推送值的类型。如果对象没有metatable,或者如果metatable没有这个字段,则不会推送并返回LUA_TNIL

luaL_getmetatable-0, +1, m

int luaL_getmetatable (lua_State *L, const char *tname);

将与名称相关联的元数据存入堆栈tname(请参阅参考资料luaL_newmetatable)(如果没有与该名称相关的元数据,则为零)。返回推送值的类型。

luaL_getsubtable-0, +1, e

int luaL_getsubtable (lua_State *L, int idx, const char *fname);

确保 index 的值在t[fname]哪里tidx一个表,并将该表推入堆栈。如果它发现上一个表,则返回true;如果它创建一个新表,则返回false。

luaL_gsub-0, +1, m

const char *luaL_gsub (lua_State *L,                       const char *s,                       const char *p,                       const char *r);

创建字符串的副本s替换字符串出现的任何p以字符串r。将结果字符串推入堆栈并返回。

luaL_len-0, +0, e

lua_Integer luaL_len (lua_State *L, int index);

将给定索引处的值的“长度”作为数字返回; 它相当于#Lua中的' '运算符(参见§3.4.7)。如果操作的结果不是整数,则引发错误。(这种情况只能通过metamethods发生。)

luaL_loadbuffer-0, +1, –

int luaL_loadbuffer (lua_State *L,                     const char *buff,
                     size_t sz,                     const char *name);

相当于luaL_loadbufferxmode等于NULL

luaL_loadbufferx-0, +1, –

int luaL_loadbufferx (lua_State *L,                      const char *buff,
                      size_t sz,                      const char *name,                      const char *mode);

将一个缓冲区加载为Lua块。此函数用于lua_load将大块加载到buff大小指向的缓冲区中sz

该函数返回与。相同的结果lua_loadname是块名称,用于调试信息和错误消息。该字符串mode在函数中起作用lua_load

luaL_loadfile-0, +1, m

int luaL_loadfile (lua_State *L, const char *filename);

相当于luaL_loadfilexmode等于NULL

luaL_loadfilex-0, +1, m

int luaL_loadfilex (lua_State *L, const char *filename,                                            const char *mode);

将文件加载为Lua块。此函数用于lua_load将文件加载到名为的文件中filename。如果filenameNULL,则从标准输入加载。如果以a开头,文件中的第一行将被忽略#

该字符串mode在函数中起作用lua_load

该函数返回lua_load与之相同的结果,但是它具有LUA_ERRFILE与文件相关的错误的额外错误代码(例如,它无法打开或读取文件)。

因为lua_load这个函数只加载块; 它不会运行它。

luaL_loadstring-0, +1, –

int luaL_loadstring (lua_State *L, const char *s);

将一个字符串加载为 Lua 块。该函数用于lua_load加载零终止字符串中的块s

该函数返回与。相同的结果lua_load

另外lua_load,这个函数只加载块; 它不会运行它。

luaL_newlib-0, +1, m

void luaL_newlib (lua_State *L, const luaL_Reg l[]);

创建一个新表并在列表中注册该功能l

它被实现为以下宏:

(luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))

数组l必须是实际的数组,而不是指向它的指针。

luaL_newlibtable-0, +1, m

void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);

创建一个具有优化大小的新表,以存储数组中的所有条目l(但不实际存储它们)。它旨在与luaL_setfuncs(参见luaL_newlib)结合使用。

它是作为一个宏实现的。数组l必须是实际的数组,而不是指向它的指针。

luaL_newmetatable-0, +1, m

int luaL_newmetatable (lua_State *L, const char *tname);

如果注册表已经有密钥tname,则返回0.否则,创建一个新表作为用户数据的元数据,向该新表__name = tname添加该对,向注册表添加该对[tname] = new table,并返回1.(该条目__name用于通过一些错误报告功能)。

在这两种情况下,将与tname注册表中相关的最终值推入堆栈。

luaL_newstate-0, +0, –

lua_State *luaL_newstate (void);

创建一个新的 Lua 状态。它lua_newstate使用基于标准 C realloc函数的分配器进行调用,然后设置一个恐慌函数(请参阅第4.6节),在出现严重错误时将错误消息输出到标准错误输出。

返回新的状态,或者NULL是否有内存分配错误。

luaL_openlibs-0, +0, e

void luaL_openlibs (lua_State *L);

将所有标准 Lua 库打开到给定状态。

luaL_opt-0, +0, e

T luaL_opt (L, func, arg, dflt);

This macro is defined as follows:

(lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))

换言之,如果参数arg为零或不存在,宏将导致默认值dflt。否则,它将导致以func状态L和参数索引arg作为参数调用的结果。请注意,dflt它只在需要时评估表达式。

luaL_optinteger-0, +0, v

lua_Integer luaL_optinteger (lua_State *L,
                             int arg,
                             lua_Integer d);

如果函数参数arg是一个整数(或可转换为整数),则返回此整数。如果这个论点不存在或者为零,则返回d。否则,会引发错误。

luaL_optlstring-0, +0, v

const char *luaL_optlstring (lua_State *L,
                             int arg,                             const char *d,
                             size_t *l);

如果函数参数arg是一个字符串,则返回此字符串。如果这个论点不存在或者为零,则返回d。否则,会引发错误。

如果l不是NULL,则填充*l结果长度的位置。如果结果是NULL(仅返回时可能dd == NULL),它的长度被认为是零。

此功能用于lua_tolstring获取其结果,因此此功能的所有转换和注意事项均适用于此。

luaL_optnumber-0, +0, v

lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);

如果函数参数arg是一个数字,则返回该数字。如果这个论点不存在或者为零,则返回d。否则,会引发错误。

luaL_optstring-0, +0, v

const char *luaL_optstring (lua_State *L,
                            int arg,                            const char *d);

如果函数参数arg是一个字符串,则返回此字符串。如果这个论点不存在或者为零,则返回d。否则,会引发错误。

luaL_prepbuffer-?, +?, m

char *luaL_prepbuffer (luaL_Buffer *B);

等同于luaL_prepbuffsize预定义的大小LUAL_BUFFERSIZE

luaL_prepbuffsize-?, +?, m

char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);

将地址返回到大小sz可以复制要添加到缓冲区的字符串的空间B(请参阅参考资料luaL_Buffer)。将字符串复制到此空间后,必须调用luaL_addsize字符串的大小才能将其实际添加到缓冲区中。

luaL_pushresult-?, +1, m

void luaL_pushresult (luaL_Buffer *B);

完成缓冲区的使用,B将最后一个字符串留在栈顶。

luaL_pushresultsize-?, +1, m

void luaL_pushresultsize (luaL_Buffer *B, size_t sz);

相当于序列luaL_addsizeluaL_pushresult

luaL_ref-1, +0, m

int luaL_ref (lua_State *L, int t);

在索引表中创建并返回一个引用t用于堆栈顶部的对象(并弹出对象)。

A reference is a unique integer key. As long as you do not manually add integer keys into table t, luaL_ref ensures the uniqueness of the key it returns. You can retrieve an object referred by reference r by calling lua_rawgeti(L, t, r). Function luaL_unref frees a reference and its associated object.

如果堆栈顶部的对象为零,则luaL_ref返回常量LUA_REFNIL。常数LUA_NOREF保证与任何返回的引用不同luaL_ref

luaL_Reg

typedef struct luaL_Reg {  const char *name;
  lua_CFunction func;} luaL_Reg;

键入要注册的函数数组luaL_setfuncsname是函数名称,func是一个指向函数的指针。任何数组都luaL_Reg必须以两个name和两个func都是的哨兵条目结束NULL

luaL_requiref-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

将模块的副本留在堆栈上。

luaL_setfuncs-nup, +0, m

void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);

将数组中的所有函数注册到堆栈顶部的表中l(请参阅luaL_Reg下面的可选upvalues)。

nup不为零时,所有函数都将创建共享nup值,这些值必须事先在堆栈顶部的堆栈上进行推送。这些值在注册后从堆栈弹出。

luaL_setmetatable-0, +0, –

void luaL_setmetatable (lua_State *L, const char *tname);

将堆栈顶部的对象的元表单设置为与tname注册表中的名称关联的元表单(请参阅参考资料luaL_newmetatable)。

luaL_Stream

typedef struct luaL_Stream {
  FILE *f;
  lua_CFunction closef;} luaL_Stream;

文件句柄的标准表示,由标准I / O库使用。

一个文件句柄被实现为一个完整的用户数据,带有一个名为metatable LUA_FILEHANDLE(其中LUA_FILEHANDLE是一个具有实际metatable名称的宏)。该metatable由I / O库创建(请参阅参考资料luaL_newmetatable)。

这个用户数据必须以结构开始luaL_Stream; 它可以包含此初始结构之后的其他数据。Field f指向相应的C流(或者它可以NULL指示一个不完全创建的句柄)。Field closef指向一个Lua函数,当句柄关闭或收集时,Lua函数将被调用来关闭流; 该函数接收文件句柄作为唯一参数,并且必须返回true(成功的情况下)或nil加上错误消息(如果有错误)。一旦Lua调用此字段,它将字段值更改为NULL表示句柄已关闭。

luaL_testudata-0, +0, m

void *luaL_testudata (lua_State *L, int arg, const char *tname);

这个函数的作用就像luaL_checkudata,除了当测试失败时,它返回NULL而不是引发错误。

luaL_tolstring-0, +1, e

const char *luaL_tolstring (lua_State *L, int idx, size_t *len);

将给定索引处的任何Lua值转换为合理格式的C字符串。生成的字符串被压入堆栈,并由函数返回。如果len不是NULL,该函数也会设置*len字符串长度。

如果该值具有__tostring字段的metatable ,则将luaL_tolstring值作为参数调用相应的metamethod,并将调用的结果作为结果。

luaL_traceback-0, +1, m

void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
                     int level);

创建并推送堆栈的回溯L1。如果msg不是,NULL它会追溯到回溯开始时。该level参数告诉在哪个级别开始回溯。

luaL_typename-0, +0, –

const char *luaL_typename (lua_State *L, int index);

返回给定索引处的值的类型的名称。

luaL_unref-0, +0, –

void luaL_unref (lua_State *L, int t, int ref);

ref从索引处的表中释放引用t(请参阅luaL_ref)。该条目从表中删除,以便可以收集被引用的对象。该参考ref也被释放以再次使用。

如果refLUA_NOREF或者LUA_REFNILluaL_unref什么也不做。

luaL_where-0, +1, m

void luaL_where (lua_State *L, int lvl);

将一个字符串推入堆栈,标识lvl调用堆栈中级别控件的当前位置。通常这个字符串具有以下格式:

chunkname:currentline:

0级是运行功能,1级是调用运行功能的功能等。

该函数用于为错误消息构建前缀。

上一篇:下一篇: