The Auxiliary Library

所述辅助库提供了几个方便的功能的接口下用的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_Buffer）n以前复制到缓冲区的长度的字符串（请参阅参考资料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_buffinit，luaL_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是否是字符串并返回此字符串; 如果l不NULL填充*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.execute和io.close）中与进程相关的函数生成返回值。

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

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

该功能用于在标准库文件有关的功能（生成的返回值io.open，os.rename，file: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]哪里t是idx一个表，并将该表推入堆栈。如果它发现上一个表，则返回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_loadbufferx用mode等于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_load。name是块名称，用于调试信息和错误消息。该字符串mode在函数中起作用lua_load。

luaL_loadfile-0, +1, m

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

相当于luaL_loadfilex用mode等于NULL。

luaL_loadfilex-0, +1, m

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

将文件加载为Lua块。此函数用于lua_load将文件加载到名为的文件中filename。如果filename是NULL，则从标准输入加载。如果以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（仅返回时可能d和d == 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_addsize，luaL_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_setfuncs。name是函数名称，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也被释放以再次使用。

如果ref是LUA_NOREF或者LUA_REFNIL，luaL_unref什么也不做。

luaL_where-0, +1, m

void luaL_where (lua_State *L, int lvl);

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

chunkname:currentline:

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

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