Lua 5.4 中文参考手册

Appearance

5.1 - 函数和类型 ​

这里按字符序列出了辅助库中的所有函数和类型。

luaL_addchar ​

[-?, +?, m]

void luaL_addchar (luaL_Buffer *B, char c);

将字节 c 添加到缓冲区 B 中（参见luaL_Buffer）。

luaL_addgsub ​

[-?, +?, m]

const void luaL_addgsub (luaL_Buffer *B, const char *s,
                         const char *p, const char *r);

将字符串 s 拷贝到缓冲区 B (参见luaL_Buffer)中，并将其中遇到的字符串 p 替换为 字符串 r 。

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 中的长度为 n 的字符串添加到其中，即之前已经拷贝到缓冲区的内存了，此时是将大小也合并进去（参见luaL_prepbuffer）。

luaL_addstring ​

[-?, +?, m]

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

将 s 所指向的一个零为终止符的字符串添加到缓冲区B中（参见luaL_Buffer）。

luaL_addvalue ​

[-?, +?, 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 是否为真。如果不是，抛出一个关于第 arg 参数的带标准信息的错误（参见luaL_argerror）。

luaL_argerror ​

[-0, +0, v]

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

抛出错误以报告调用C函数的 arg 参数的问题，并使用包含了 extramsg 作为注释的标准信息：

bad argument #arg to 'funcname' (extramsg)

此函数永不返回。

luaL_argexpected ​

[-0, +0, v]

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

检查 cond 是否为真。如果不是，抛出一个关于第 arg 参数的类型的带标准信息的错误（参见luaL_typeerror）。

luaL_Buffer ​

C
typedef struct luaL_Buffer luaL_Buffer;

字符串缓冲区 string buffer 的类型。

字符串缓冲区允许在C代码中分步构建Lua字符串。其按照如下模式使用：

  • 首先声明一个luaL_Buffer类型的变量 b 。
  • 然后使用 luaL_buffinit(L, &b) 初始化。
  • 使用 luaL_add* 类函数来将不同的字符串片段添加到其中。
  • 最后调用 luaL_pushresult(&b) 。其会将最终的字符串放在栈顶上。

如果你提前就知道最终的字符串能有多大，那么你可以像这样使用：

  • 先声明一个luaL_Buffer类型的变量 b 。
  • 然后使用 luaL_buffinitsize(L, &b, sz) 来提前分配 sz 大小的空间并初始化。
  • 再和之前一样在分配的空间里构建字符串。
  • 最后调用 luaL_pushresultsize(&b, sz) ，其中 sz 是在缓冲区空间中的最终字符串的长度（其实可能会小于或等于之前分配的大小）。

一般在以上的操作过程中，字符串缓冲区会使用到不定数目的栈空间。所以当使用缓冲区时，你不可以假设栈顶是已知的。你可以在连续的缓冲区操作之间使用栈，只要能够平衡地去使用它；意思是，当你调用一个缓冲区操作时，栈的层级和上次缓冲区操作后的相同。（这个规则的唯一例外是luaL_addvalue。）在调用luaL_pushresult后，栈应该回到缓冲区初始化的状态，然后将最终的字符串加到栈顶上。

luaL_buffaddr ​

[-0, +0, -]

char *luaL_buffaddr (luaL_Buffer *B);

返回缓冲区 B（参见luaL_Buffer）当前内容的地址。注意任何对缓冲区的添加操作都可能使这个地址失效（可能会在内部空间不够的时候重新分配内存）。

luaL_buffinit ​

[-0, +?, -]

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

初始化缓冲区 B（参见luaL_Buffer。此函数不会分配任何空间；此缓冲区必须声明为变量。

luaL_bufflen ​

[-0, +0, -]

size_t luaL_bufflen (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_buffsub ​

[-?, +?, -]

void luaL_buffsub (luaL_Buffer *B, int n);

从缓冲区 B（参见luaL_Buffer）中移除 n 个字节。缓冲区中必须有足够的字节。

luaL_callmeta ​

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

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

调用某个元函数。

如果处于索引 obj 处的对象拥有元表并且其中包含字段 e ，那么此函数就会将该对象作为唯一参数调用对应字段。这种情况下此函数会返回 true 并将调用结果压入栈中。如果没有找到元表或元函数，此函数会返回 false 并且不会压栈。

luaL_checkany ​

[-0, +0, v]

void luaL_checkany (lua_State *L, int arg);

检查函数的参数列表中是否有第 arg 个的任何类型（包括nil）参数。

luaL_checkinteger ​

[-0, +0, v]

lua_Integer luaL_checkinteger (lua_State *L, int arg);

检查函数的第 n 个参数的类型是否为整数（或者可以转换到整数）并返回其整数值。

luaL_checklstring ​

[-0, +0, v]

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

检查函数的第 n 个参数的类型是否为字符串并返回这个字符串；参数 l 不为NULL时则会被设为该字符串的长度。

此函数使用lua_tolstring获取结果，因此所有相关的转换都可能会生效。

luaL_checknumber ​

[-0, +0, v]

lua_Number luaL_checknumber (lua_State *L, int arg);

检查函数的第 n 个参数的类型是否为 number ，然后将该值转换成 lua_Number 并返回。

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，那么此函数会在没有参数或参数为nil时作为其默认值。

此函数通常被用来匹配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 。关于 t 所对应的的各类型编码请参见lua_type。

luaL_checkudata ​

[-0, +0, v]

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

检查函数的第 arg 个参数类型是否为类型名为 tname 的 userdata（参见luaL_newmetatable）并返回其内存块的地址（参见lua_touserdata）。

luaL_checkversion ​

[-0, +0, v]

void luaL_checkversion (lua_State *L);

检查正在调用的代码和正在调用的Lua库所使用的Lua版本是否相同，以及相同的数值类型。

luaL_dofile ​

[-0, +?, m]

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

加载并运行指定的文件。是一个如下定义的宏：

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

如果没有错误发生会返回0（LUA_OK），否则返回1。

luaL_dostring ​

[-0, +?, -]

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

加载并运行指定的字符串。是一个如下定义的宏：

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

如果没有错误发生会返回0（LUA_OK），否则返回1。

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);

将索引 obj 处的对象的元表中的字段 e 压入栈中，并返回其类型。如果对象没有元表或元表中没有该字段，则不会压栈且返回 LUA_TNIL 。

luaL_getmetatable ​

[-0, +1, m]

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

将注册表中 tname 的元表压入栈中，或者当不存在相关元表时压入nil。返回值为压入栈中的值的类型。

luaL_getsubtable ​

[-0, +1, e]

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

确保 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_Integer返回；其等效于Lua代码中的"#"操作。如果其结果不是一个整数则会抛出错误（这种情况只会发生在元函数中）。

luaL_loadbuffer ​

[-0, +1, -]

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

等效于参数 mode 传NULL以调用luaL_loadbufferx。

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);

等效于参数 mode 传NULL以调用luaL_loadfilex。

luaL_loadfilex ​

[-0, +1, m]

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

将一个文件加载为Lua代码块。此函数使用lua_load来加载名为 filename 的文件。当 filename 为NULL时会从标准输入中加载。文件中以 '#' 开头的第一行会被忽略。

字符串参数 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 中的函数注册在其中。

其实现为一个如下的宏：

C
(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）。

luaL_newmetatable ​

[-0, +1, m]

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

如果注册表中已经存在键 tname ，则直接返回0。否则，创建一个新表用于作为 userdata 的元表，在这个表中添加键值对 __name = tname，再将键值对 [tname] = new tbale 添加到注册表中，并返回1。

luaL_newstate ​

[-0, +0, -]

lua_State *luaL_newstate (void);

创建一个状态机。其会使用一个基于ISO标准C的内存分配函数调用lua_newstate，然后设置警告函数和 panic 函数（参见4.4），使之调用时会打印消息到标准错误输出。

返回值为一个新的状态机，或者在发生内存分配错误时返回NULL。

luaL_openlibs ​

[-0, +0, e]

void luaL_openlibs (lua_State *L);

打开给出的状态机中的所有标准库。

luaL_opt ​

[-0, +0, -]

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

这个宏的定义如下：

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

换言之。如果参数 arg 为nil或者缺失，这个宏的结果都是默认的 dflt 。否则，其结果为使用状态机 L 和 arg 作参数的 func 调用结果。注意表达式 dflt 只会在需要的时候被计算。

luaL_optinteger ​

[-0, +0, v]

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

如果函数的第 arg 个参数是一个整数（或可转换为整数），则返回这个整数值。如果参数缺失或为nil，则返回 d 。其他情况则会抛出错误。

luaL_optlstring ​

[-0, +0, v]

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

如果函数的第 arg 个参数是一个字符串，则返回这个字符串。如果参数缺失或为nil，则返回 d 。其他情况则会抛出错误。

如果 l 不为NULL，则会被置为结果的长度。如果结果是NULL（只可能是返回的 d 且 d == NULL），其长度会被视为0。

此函数使用lua_tolstring获取结果，因此所有相关的转换都会被触发。

luaL_optnumber ​

[-0, +0, v]

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

如果函数的第 arg 个参数是一个 number ，则将其作为 lua_Number 返回。如果参数缺失或为nil，则返回 d 。其他情况则会抛出错误。

luaL_optstring ​

[-0, +0, v]

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

如果函数的第 arg 个参数是一个字符串，则返回这个字符串。如果参数缺失或为nil，则返回 d 。其他情况则会抛出错误。

luaL_prepbuffer ​

[-?, +?, m]

char *luaL_prepbuffer (luaL_Buffer *B);

等效于使用预定义的 LUAL_BUFFERSIZE 调用luaL_prepbuffsize。

luaL_prepbuffsize ​

[-?, +?, m]

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

返回一个大小为 sz 的内存空间地址以供之后向缓冲区 B（参加luaL_Buffer）中复制数据，即提前分配一定的内存而不是在添加时遇到空间不够后再分配。在往其中复制完字符串后你必须调用luaL_addsize来真正将其添加到缓冲区中。

luaL_pushfail ​

[-0, +1, -]

void luaL_pushfail (lua_State *L);

将fail值压入栈中（参见6）。

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 处的表中创建并返回一个引用 reference ，其引用的是于栈顶处的对象（并且会弹出栈顶对象）。

引用是一个唯一的整数键。只要你没有手动给表添加整数键 t ，luaL_ref就会保证其返回的键是唯一的。你可以通过调用 lua_rawgeti(L, t, r) 来取回引用 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_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);

如果 package.loaded[modname] 结果不为 true 时，会使用字符串 modname 作为函数 openf 的参数传入并调用，并将调用结果放到 package.loaded[modname] 中，就好像这个函数由require调用的一样。

如果参数 glb 为true，则将导入的模块也存到与 modname 同名的全局变量中。

最后会将模块的拷贝到栈顶上。

luaL_setfuncs ​

[-nup, +0, m]

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

将数组 l（参见luaL_Reg）中的所有函数注册到栈顶的表中（也可能会在上值下边，见下文）。

当 nup 不为零时，所有的函数创建时都会带上 nup 个上值，这些上值使用之前压入栈顶的 nup 个值的拷贝来初始化，在栈中这些值的下边才是注册目标的表。这些值都会在注册完之后从栈中弹出。

当某个 func 的值为NULL时，其表示只占位，在表中注册时会由false作为键值填充，即 t[name] = false 。

luaL_setmetatable ​

[-0, +0, -]

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

将栈顶上对象的元表设置为在注册表中名为 tname 所关联的表（参见luaL_newmetatable）。

luaL_Stream ​

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

用于表示标准I/O库中文件句柄的结构。

文件句柄是作为一个 full userdata 实现的，其带有一个称为 LUA_FILEHANDLE（一个由宏定义的元表名称）的元表。这个元表是由I/O库创建的（参见luaL_newmetatable）。

其实现的 userdata 中必须由 luaL_Stream结构作为起始，要包含的其他数据应该放在初始结构的后面。字段 f 指向了其对应的 C stream（或者可以为NULL以表示未完全创建的句柄）。字段 closef 指向了一个当句柄被关闭或回收时用来关闭这个流的函数；此函数接收对应的文件句柄作为唯一的参数，成功时必须返回 true，或折失败的时候返回false加上一个错误消息。一旦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字符串。将结果字符串压入栈中并将其作为该函数的返回值（参见4.1.3）。如果 len 不为NULL，此函数也会就将 *len 置为该字符串的长度。

如果给出索引处的Lua值有元表并其中包含了 __tostring 字段，那么luaL_tolstring会将此值作为参数来调用相应的元函数，最后将调用结果作为此函数的结果。

luaL_traceback ​

[-0, +1, m]

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

新建回溯信息并将其压入到L1的栈中。如果参数 msg 不为 NULL，那么会将其添加到回溯信息的开头。参数 level 指出了从哪一级开始回溯。

luaL_typeerror ​

[-0, +0, v]

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

抛出一个标准消息格式的类型错误，其和正在调用的C函数的第 arg 个参数相关；参数 tname 是函数需要的类型。此函数永不返回。

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);

释放索引 index 处表的引用 ref(参见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 层为调用这个函数的函数，以此类推。

此函数一般用于构建错误信息的前缀。