参考手册 - 4 - 辅助库

4 -

辅助库为连接C和Lua提供若干便利的函数。基础API为C和Lua间的所有交互提供基本功能，而辅助库为一些通用任务提供高级功能。

所有来在辅助库的函数在头文件lauxlib.h中定义并具有前缀luaL_。

辅助库中的所有函数建立于基础API的顶层，所以该API做不了的它们也不提供。

辅助库中的一些函数用于检查C函数的参数。它们的名字总是luaL_check*或luaL_opt*。如果未满足检查条件，所有这些函数会抛出错误。因为错误消息是为参数格式化的（例如“bad argument #1”），所以不能把这些函数用于其它栈值。

4.1 -

这儿我们以字母顺序列出来自辅助库的所有函数和类型。

---

[-0, +0, m]

void luaL_addchar (luaL_Buffer *B, char c);

把字符c添加到缓冲器B（见）。

---

[-0, +0, m]

void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);

把s指向的长度为l的字符串添加到缓冲器B（见）。字符串可含有内嵌的0。

---

[-0, +0, m]

void luaL_addsize (luaL_Buffer *B, size_t n);

把先前拷贝到缓冲区（见）的长为n的字符串添加到缓冲器B（见）。

---

[-0, +0, m]

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

把s指向的0结尾的字符串添加到缓冲器B（见）。字符串可能不包含内嵌的0。

---

[-1, +0, m]

void luaL_addvalue (luaL_Buffer *B);

把栈顶的值添加到缓冲器B（见）。弹出该值。

这是仅有能（且必须）用栈上的一个额外元素调用的关于字符串缓冲器的函数，该元素是要被添加到缓冲器的值。

---

[-0, +0, v]

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

检查cond是否为真。如果不是，则抛出带下面的消息的错误，其中func是取自调用栈：

     bad argument # to  ()

---

[-0, +0, v]

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

抛出带下面的消息的错误，其中func是取自调用栈：

     bad argument # to  ()

本函数决不返回，但是像return luaL_argerror(args)这样是用在C函数中的习惯用法。

---

typedef struct luaL_Buffer luaL_Buffer;

字符串缓冲器类型。

字符串缓冲器允许C代码逐段地构建Lua字符串。其使用模式如下：

• 首先声明类型的变量b。
• 接着调用luaL_buffinit(L, &b)初始化它。
• 然后调用luaL_add*函数把字符串片断添加到缓冲器。
• 通过调用luaL_pushresult(&b)结束。该调用把最终的字符串放在栈顶。

在字符串缓冲器的常规操作期间，它占用的栈槽数量不固定。所以，使用缓冲器时，你不能假定知道栈顶在哪儿。只要用法是对称的，你就能在连续的对缓冲器操作的调用之间使用栈；就是说，当你调用缓冲器操作时，栈处于前一个缓冲器操作后立刻得到的水平。（该规则的唯一例外是。）调用之后，栈回到缓冲器被初始化时的水平，加上栈顶的最终字符串。

---

[-0, +0, -]

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

初始化缓冲器B。本函数不分配任何空间；缓冲器必须已被声明为变量（见）。

---

[-0, +(0|1), e]

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

调用一个元方法。

如果索引obj处的对象具有元表且该元表具有字段e，本函数调用该字段并传入该对象为其唯一参数。这种情况下，本函数返回1并将该调用返回的值压栈。如果没有元表或没有元方法，本函数返回0（不将任何值压栈）。

---

[-0, +0, v]

void luaL_checkany (lua_State *L, int narg);

检查函数是否在位置narg处有个任意类型（包括nil）的参数。

---

[-0, +0, v]

int luaL_checkint (lua_State *L, int narg);

检查函数参数narg是否数字并把该数转型为int返回。

---

[-0, +0, v]

lua_Integer luaL_checkinteger (lua_State *L, int narg);

检查函数参数narg是否数字并把该数转型为返回。

---

[-0, +0, v]

long luaL_checklong (lua_State *L, int narg);

检查函数参数narg是否数字并把该数转型为long返回。

---

[-0, +0, v]

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

检查函数参数narg是否字符串并返回它；如果l不是NULL则用字符串的长度填充它。

本函数用得到其结果，所以那个函数的所有变换和警告也适用于此处。

---

[-0, +0, v]

lua_Number luaL_checknumber (lua_State *L, int narg);

检查函数参数narg是否数字并返回它。

---

[-0, +0, v]

int luaL_checkoption (lua_State *L,
                      int narg,
                      const char *def,
                      const char *const lst[]);

检查函数参数narg是否字符串并且在数组lst（必须是NULL结尾的）中搜索它。返回数组中发现该字符串的地方的索引。如果该参数不是字符串或没被找到则引发错误。

如果def不是NULL，当参数narg不存在或为nil时，函数用def作为缺省值。

这是个把字符串映射到C枚举的有用函数。（Lua库中的通常约定是用字符串代替数字来选取选项。）

---

[-0, +0, v]

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

增长栈尺寸到top + sz个元素，如果不能增长到那个尺寸则引发错误。msg是加入错误消息的补充文本。

---

[-0, +0, v]

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

检查函数参数narg是否字符串并返回它。

本函数用取得其结果，所以那个函数的所有变换和警告也适用于此处。

---

[-0, +0, v]

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

检查函数参数narg是否具有类型t。用于类型t的编码见。

---

[-0, +0, v]

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

检查函数参数narg是否tname类型的用户数据（见）。

---

[-0, +?, m]

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

载入并运行给定文件。它被定义为下面的宏：

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

如果没有错误则返回0，发生错误时返回1。

---

[-0, +?, m]

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

载入并运行给定的字符串。它被定义为下面的宏：

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

如果没有错误则返回0，发生错误时返回1。

---

[-0, +0, v]

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

引发一个错误。错误消息格式由fmt以及任何额外参数指定，且遵循同一样的规则。如果错误发生的文件名和行号可用，它也在消息开头添加该信息。

本函数从不返回，但是在C函数中return luaL_error(args)是个习惯用法。

---

[-0, +(0|1), m]

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

把来自索引obj处的对象的元表的字段e压栈。如果对象没有元表或其元表没有该字段，则返回0且不回压栈任何东西。

---

[-0, +1, -]

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

把与注册表中的名字tname相关联的元表压栈。（见）。

---

[-0, +1, m]

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

通过把出现的任何字符串p替换为字符串r来创建字符串s的拷贝。把结果字符串压栈并返回它。

---

[-0, +1, m]

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

载入缓冲器并作为一个Lua单元。本函数用来加载缓冲器中由buff指向且长度为sz的单元。

本函数返回同一样的结果。name是单元名字，用于调试信息和错误消息。

---

[-0, +1, m]

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

载入文件作为一个Lua单元。本函数用来载入名为filename的文件中的单元。如果filename是NULL，则从标准输入载入。文件中的第一行如果以#开头则被忽略。

本函数返回同一样的结果，除了有个额外的错误代码，用于不能打开/读取文件的情况。

同一样，本函数只载入单元；不会运行它。

---

[-0, +1, m]

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

载入字符串作为一个Lua单元。本函数用来载入以0结尾的字符串s中的单元。

本函数返回同一样的结果。

本函数只载入单元，这也同一样；不会运行它。

---

[-0, +1, m]

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

如果注册表已经有了键tname则返回0。否则，创建将用作用户数据的元表的新表，把它同键tname一起加入注册表，并且返回1。

两种情况都把注册表中与tname相关联的最终值压栈。

---

[-0, +0, -]

lua_State *luaL_newstate (void);

创建新的Lua状态机。它用基于标准C的realloc函数的分配器调用，然后设置一个在发生重大错误时向标准错误输出打印一条错误消息的应急函数（见）。

返回新的状态机，如果发生内存分配错误则返回NULL。

---

[-0, +0, m]

void luaL_openlibs (lua_State *L);

打开所有的标准Lua库到给定的状态机中。

---

[-0, +0, v]

int luaL_optint (lua_State *L, int narg, int d);

如果函数参数narg是数字，则把该数字转型为int返回。如果该参数不存在或为nil则返回d。否则引发错误。

---

[-0, +0, v]

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

如果函数参数narg是数字，则把该数字转型为返回。如果该参数不存在或为nil则返回d。否则引发错误。

---

[-0, +0, v]

long luaL_optlong (lua_State *L, int narg, long d);

如果函数参数narg是数字，则把该数字转型为long返回。如果该参数不存在或为nil则返回d。否则引发错误。

---

[-0, +0, v]

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

如果函数参数narg是字符串则返回它。如果该参数不存在或为nil则返回d。否则引发错误。

如果l不为NULL，则用结果的长度填充位置*l。

---

[-0, +0, v]

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

如果函数参数narg是数字则返回它。如果该参数不存在或为nil则返回d。否则引发错误。

---

[-0, +0, v]

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

如果函数参数narg是字符串则返回它。如果该参数不存在或为nil则返回d。否则引发错误。

---

[-0, +0, -]

char *luaL_prepbuffer (luaL_Buffer *B);

返回尺寸为的空间的地址，你能把要被加入缓冲器B的字符串拷贝到其中（见）。在把字符串拷贝到该空间中以后，你必须用字符串的尺寸调用来把它加入缓冲器中。

---

[-?, +1, m]

void luaL_pushresult (luaL_Buffer *B);

结束对缓冲器B的使用，把最终字符串留在栈顶。

---

[-1, +0, m]

int luaL_ref (lua_State *L, int t);

在索引t处的表中为栈顶的对象创建一个引用（reference）并返回（而且弹出该对象）。

引用是唯一的整数键。只要你不手工向表t中加入整数键，保证它返回的键的唯一性。你可通过调用lua_rawgeti(L, t, r)取回被引用r引用的对象。函数释放引用及其关联的对象。

如果栈顶的对象是nil，返回常量。常量被确保与返回的任何引用都不同。

---

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

用于要被注册的函数数组的类型。name是函数名，func是函数指针。任何数组必须以name和func都为NULL的标记项结尾。

---

[-(0|1), +1, m]

void luaL_register (lua_State *L,
                    const char *libname,
                    const luaL_Reg *l);

打开一个库。

当以libname等于NULL调用时，它只是注册列表l中的所有函数（见）到栈顶的表中。

当以非空的libname调用时，luaL_register创建新表t，把它设为全局变量libname的值，和package.loaded[libname]的值，并把列表l中的所有函数注册到该表。如果package.loaded[libname]中或变量libname中有个表，则重用该表而不是创建一个新的。

无论如何函数都把表留在栈顶。

---

[-0, +0, -]

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

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

---

[-0, +0, v]

int luaL_typerror (lua_State *L, int narg, const char *tname);

用类似下面的消息产生一个错误：

     location: bad argument narg to 'func' (tname expected, got rt)

其中location由产生，func是但前函数名，且rt是实际参数的类型名。

---

[-0, +0, -]

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

解除来自索引t处的表的引用ref（见）。该项从表中删除，所以被引用的对象可被回收。引用ref也被释放以备再次使用。

如果ref是或，什么也不做。

---

[-0, +1, m]

void luaL_where (lua_State *L, int lvl);

把调用栈中lvl级的控制的当前位置的字符串标识压栈。典型地，该字符串具有如下格式：

     单元名:当前行:

0级是正在运行的函数，1级是调用正在运行函数的函数，依次类推。

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