5 – 辅助库

原文：https://www.lua.org/manual/5.4/manual.html

5 – The Auxiliary Library – 辅助库

The auxiliary library provides several convenient functions to interface C with Lua. While the basic API provides the primitive functions for all interactions between C and Lua, the auxiliary library provides higher-level functions for some common tasks.

​ 辅助库提供了几个方便的函数，用于在 C 和 Lua 之间进行接口。虽然基本 API 提供了 C 和 Lua 之间所有交互的原始函数，但辅助库为一些常见任务提供了更高级别的函数。

All functions and types from the auxiliary library are defined in header file lauxlib.h and have a prefix luaL_.

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

All functions in the auxiliary library are built on top of the basic API, and so they provide nothing that cannot be done with that API. Nevertheless, the use of the auxiliary library ensures more consistency to your code.

​ 辅助库中的所有函数都建立在基本 API 之上，因此它们提供的功能都可以通过该 API 实现。尽管如此，使用辅助库可以确保代码更具一致性。

Several functions in the auxiliary library use internally some extra stack slots. When a function in the auxiliary library uses less than five slots, it does not check the stack size; it simply assumes that there are enough slots.

​ 辅助库中的几个函数在内部使用一些额外的栈槽。当辅助库中的函数使用少于五个槽时，它不会检查栈大小；它只是假设有足够的槽。

Several functions in the auxiliary library are used to check C function arguments. Because the error message is formatted for arguments (e.g., “bad argument #1”), you should not use these functions for other stack values.

​ 辅助库中的几个函数用于检查 C 函数参数。由于错误消息的格式适用于参数（例如，“ bad argument #1 ”），因此您不应将这些函数用于其他栈值。

Functions called luaL_check* always raise an error if the check is not satisfied.

​ 如果检查不满足，则始终调用 luaL_check* 函数引发错误。

5.1 – Functions and Types 函数和类型

Here we list all functions and types from the auxiliary library in alphabetical order.

​ 此处按字母顺序列出了辅助库中的所有函数和类型。

luaL_addchar

[-?, +?, m]

void luaL_addchar (luaL_Buffer *B, char c);

Adds the byte c to the buffer B (see luaL_Buffer).

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

luaL_addgsub

[-?, +?, m]

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

Adds a copy of the string s to the buffer B (see luaL_Buffer), replacing any occurrence of the string p with the string r.

​ 将字符串 s 的副本添加到缓冲区 B （参见 luaL_Buffer ），用字符串 r 替换字符串 p 的任何出现。

luaL_addlstring

[-?, +?, m]

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

Adds the string pointed to by s with length l to the buffer B (see luaL_Buffer). The string can contain embedded zeros.

​ 将由 s 指向的长度为 l 的字符串添加到缓冲区 B （参见 luaL_Buffer ）。该字符串可以包含嵌入的零。

luaL_addsize

[-?, +?, –]

void luaL_addsize (luaL_Buffer *B, size_t n);

Adds to the buffer B a string of length n previously copied to the buffer area (see luaL_prepbuffer).

​ 将长度为 n 的字符串添加到缓冲区 B ，该字符串之前已复制到缓冲区区域（参见 luaL_prepbuffer ）。

luaL_addstring

[-?, +?, m]

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

Adds the zero-terminated string pointed to by s to the buffer B (see luaL_Buffer).

​ 将以零结尾的字符串指向 s 添加到缓冲区 B （请参阅 luaL_Buffer ）。

luaL_addvalue

[-?, +?, m]

void luaL_addvalue (luaL_Buffer *B);

Adds the value on the top of the stack to the buffer B (see luaL_Buffer). Pops the value.

​ 将栈顶的值添加到缓冲区 B （请参阅 luaL_Buffer ）。弹出值。

This is the only function on string buffers that can (and must) be called with an extra element on the stack, which is the value to be added to the buffer.

​ 这是字符串缓冲区上唯一可以（并且必须）使用栈上的额外元素调用的函数，该元素是添加到缓冲区的值。

luaL_argcheck

[-0, +0, v]

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

Checks whether cond is true. If it is not, raises an error with a standard message (see luaL_argerror).

​ 检查 cond 是否为真。如果不是，则引发一个带有标准消息的错误（参见 luaL_argerror ）。

luaL_argerror

[-0, +0, v]

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

Raises an error reporting a problem with argument arg of the C function that called it, using a standard message that includes extramsg as a comment:

​ 引发一个错误，报告调用它的 C 函数的参数 arg 存在问题，使用包含 extramsg 作为注释的标准消息：

     bad argument #arg to 'funcname' (extramsg)

This function never returns.

​ 此函数从不返回。

luaL_argexpected

[-0, +0, v]

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

Checks whether cond is true. If it is not, raises an error about the type of the argument arg with a standard message (see luaL_typeerror).

​ 检查 cond 是否为真。如果不是，则引发有关参数 arg 类型错误的错误，并附有标准消息（请参阅 luaL_typeerror ）。

luaL_Buffer

typedef struct luaL_Buffer luaL_Buffer;

Type for a string buffer.

​ 字符串缓冲区的类型。

A string buffer allows C code to build Lua strings piecemeal. Its pattern of use is as follows:

​ 字符串缓冲区允许 C 代码分段构建 Lua 字符串。其使用模式如下：

• First declare a variable b of type luaL_Buffer. 首先声明类型为 luaL_Buffer 的变量 b 。
• Then initialize it with a call luaL_buffinit(L, &b). 然后使用调用 luaL_buffinit(L, &b) 对其进行初始化。
• Then add string pieces to the buffer calling any of the luaL_add* functions. 然后通过调用任意 luaL_add* 函数将字符串片段添加到缓冲区。
• Finish by calling luaL_pushresult(&b). This call leaves the final string on the top of the stack. 通过调用 luaL_pushresult(&b) 完成。此调用将最终字符串留在栈顶。

If you know beforehand the maximum size of the resulting string, you can use the buffer like this:

​ 如果您事先知道结果字符串的最大大小，则可以使用缓冲区，如下所示：

• First declare a variable b of type luaL_Buffer. 首先声明类型为 luaL_Buffer 的变量 b 。
• Then initialize it and preallocate a space of size sz with a call luaL_buffinitsize(L, &b, sz). 然后对其进行初始化，并通过调用 luaL_buffinitsize(L, &b, sz) 预先分配大小为 sz 的空间。
• Then produce the string into that space. 然后将字符串生成到该空间中。
• Finish by calling luaL_pushresultsize(&b, sz), where sz is the total size of the resulting string copied into that space (which may be less than or equal to the preallocated size). 通过调用 luaL_pushresultsize(&b, sz) 完成，其中 sz 是复制到该空间的结果字符串的总大小（可能小于或等于预先分配的大小）。

During its normal operation, a string buffer uses a variable number of stack slots. So, while using a buffer, you cannot assume that you know where the top of the stack is. You can use the stack between successive calls to buffer operations as long as that use is balanced; that is, when you call a buffer operation, the stack is at the same level it was immediately after the previous buffer operation. (The only exception to this rule is luaL_addvalue.) After calling luaL_pushresult, the stack is back to its level when the buffer was initialized, plus the final string on its top.

​ 在正常操作期间，字符串缓冲区使用可变数量的栈槽。因此，在使用缓冲区时，您不能假设您知道栈顶在哪里。只要这种使用是平衡的，您就可以在连续的缓冲区操作调用之间使用栈；也就是说，当您调用缓冲区操作时，栈处于与前一个缓冲区操作之后立即相同的级别。（此规则的唯一例外是 luaL_addvalue 。）在调用 luaL_pushresult 之后，栈会返回到缓冲区初始化时的级别，外加其顶部的最终字符串。

luaL_buffaddr

[-0, +0, –]

char *luaL_buffaddr (luaL_Buffer *B);

Returns the address of the current content of buffer B (see luaL_Buffer). Note that any addition to the buffer may invalidate this address.

​ 返回缓冲区 B 当前内容的地址（请参阅 luaL_Buffer ）。请注意，对缓冲区的任何添加都可能使此地址无效。

luaL_buffinit

[-0, +?, –]

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

Initializes a buffer B (see luaL_Buffer). This function does not allocate any space; the buffer must be declared as a variable.

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

luaL_bufflen

[-0, +0, –]

size_t luaL_bufflen (luaL_Buffer *B);

Returns the length of the current content of buffer B (see luaL_Buffer).

​ 返回缓冲区 B （参见 luaL_Buffer ）的当前内容的长度。

luaL_buffinitsize

[-?, +?, m]

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

Equivalent to the sequence luaL_buffinit, luaL_prepbuffsize.

​ 等同于序列 luaL_buffinit , luaL_prepbuffsize .

luaL_buffsub

[-?, +?, –]

void luaL_buffsub (luaL_Buffer *B, int n);

Removes n bytes from the buffer B (see luaL_Buffer). The buffer must have at least that many bytes.

​ 从缓冲区 B 中移除 n 字节（参见 luaL_Buffer ）。缓冲区必须至少有那么多字节。

luaL_callmeta

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

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

Calls a metamethod.

​ 调用元方法。

If the object at index obj has a metatable and this metatable has a field e, this function calls this field passing the object as its only argument. In this case this function returns true and pushes onto the stack the value returned by the call. If there is no metatable or no metamethod, this function returns false without pushing any value on the stack.

​ 如果索引 obj 处的对象具有元表，并且该元表具有字段 e ，则此函数调用该字段，并将该对象作为其唯一参数传递。在这种情况下，此函数返回 true，并将调用返回的值压入栈。如果没有元表或元方法，则此函数返回 false，而不会在栈上压入任何值。

luaL_checkany

[-0, +0, v]

void luaL_checkany (lua_State *L, int arg);

Checks whether the function has an argument of any type (including nil) at position arg.

​ 检查函数在位置 arg 是否具有任何类型的参数（包括 nil）。

luaL_checkinteger

[-0, +0, v]

lua_Integer luaL_checkinteger (lua_State *L, int arg);

Checks whether the function argument arg is an integer (or can be converted to an integer) and returns this integer.

​ 检查函数参数 arg 是否为整数（或可转换为整数），并返回此整数。

luaL_checklstring

[-0, +0, v]

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

Checks whether the function argument arg is a string and returns this string; if l is not NULL fills its referent with the string’s length.

​ 检查函数参数 arg 是否为字符串并返回此字符串；如果 l 不是 NULL ，则用字符串的长度填充其引用。

This function uses lua_tolstring to get its result, so all conversions and caveats of that function apply here.

​ 此函数使用 lua_tolstring 获取其结果，因此该函数的所有转换和注意事项在此处适用。

luaL_checknumber

[-0, +0, v]

lua_Number luaL_checknumber (lua_State *L, int arg);

Checks whether the function argument arg is a number and returns this number converted to a lua_Number.

​ 检查函数参数 arg 是否为数字，并将此数字转换为 lua_Number 并返回。

luaL_checkoption

[-0, +0, v]

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

Checks whether the function argument arg is a string and searches for this string in the array lst (which must be NULL-terminated). Returns the index in the array where the string was found. Raises an error if the argument is not a string or if the string cannot be found.

​ 检查函数参数 arg 是否为字符串，并在数组 lst （必须以 NULL 结尾）中搜索此字符串。返回在数组中找到字符串的索引。如果参数不是字符串或找不到字符串，则引发错误。

If def is not NULL, the function uses def as a default value when there is no argument arg or when this argument is nil.

​ 如果 def 不是 NULL ，则当没有参数 arg 或此参数为 nil 时，函数使用 def 作为默认值。

This is a useful function for mapping strings to C enums. (The usual convention in Lua libraries is to use strings instead of numbers to select options.)

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

luaL_checkstack

[-0, +0, v]

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

Grows the stack size to top + sz elements, raising an error if the stack cannot grow to that size. msg is an additional text to go into the error message (or NULL for no additional text).

​ 将栈大小增加到 top + sz 个元素，如果栈无法增长到该大小，则引发错误。 msg 是要放入错误消息中的附加文本（或 NULL 表示没有附加文本）。

luaL_checkstring

[-0, +0, v]

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

Checks whether the function argument arg is a string and returns this string.

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

This function uses lua_tolstring to get its result, so all conversions and caveats of that function apply here.

​ 此函数使用 lua_tolstring 来获取其结果，因此该函数的所有转换和注意事项在此处适用。

luaL_checktype

[-0, +0, v]

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

Checks whether the function argument arg has type t. See lua_type for the encoding of types for t.

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

luaL_checkudata

[-0, +0, v]

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

Checks whether the function argument arg is a userdata of the type tname (see luaL_newmetatable) and returns the userdata’s memory-block address (see lua_touserdata).

​ 检查函数参数 arg 是否是类型 tname 的用户数据（请参见 luaL_newmetatable ），并返回用户数据的内存块地址（请参见 lua_touserdata ）。

luaL_checkversion

[-0, +0, v]

void luaL_checkversion (lua_State *L);

Checks whether the code making the call and the Lua library being called are using the same version of Lua and the same numeric types.

​ 检查进行调用的代码和被调用的 Lua 库是否使用相同版本的 Lua 和相同的数字类型。

luaL_dofile

[-0, +?, m]

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

Loads and runs the given file. It is defined as the following macro:

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

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

It returns 0 (LUA_OK) if there are no errors, or 1 in case of errors.

​ 如果没有错误，则返回 0 ( LUA_OK )，如果有错误，则返回 1。

luaL_dostring

[-0, +?, –]

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

Loads and runs the given string. It is defined as the following macro:

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

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

It returns 0 (LUA_OK) if there are no errors, or 1 in case of errors.

​ 如果没有错误，则返回 0 ( LUA_OK )，如果有错误，则返回 1。

luaL_error

[-0, +0, v]

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

Raises an error. The error message format is given by fmt plus any extra arguments, following the same rules of lua_pushfstring. It also adds at the beginning of the message the file name and the line number where the error occurred, if this information is available.

​ 引发错误。错误消息格式由 fmt 加上任何额外的参数给出，遵循 lua_pushfstring 的相同规则。它还将在消息的开头添加错误发生的文件名和行号（如果此信息可用）。

This function never returns, but it is an idiom to use it in C functions as return luaL_error(*args*).

​ 此函数从不返回，但将其用作 C 函数中的 return luaL_error(*args*) 是一种惯用用法。

luaL_execresult

[-0, +3, m]

int luaL_execresult (lua_State *L, int stat);

This function produces the return values for process-related functions in the standard library (os.execute and io.close).

​ 此函数生成标准库中与进程相关的函数的返回值（ os.execute 和 io.close ）。

luaL_fileresult

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

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

This function produces the return values for file-related functions in the standard library (io.open, os.rename, file:seek, etc.).

​ 此函数生成标准库中与文件相关的函数的返回值（ io.open 、 os.rename 、 file:seek 等）。

luaL_getmetafield

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

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

Pushes onto the stack the field e from the metatable of the object at index obj and returns the type of the pushed value. If the object does not have a metatable, or if the metatable does not have this field, pushes nothing and returns LUA_TNIL.

​ 将索引 obj 处对象的元表的字段 e 压入栈，并返回压入值的类型。如果对象没有元表，或者元表没有此字段，则不压入任何内容并返回 LUA_TNIL 。

luaL_getmetatable

[-0, +1, m]

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

Pushes onto the stack the metatable associated with the name tname in the registry (see luaL_newmetatable), or nil if there is no metatable associated with that name. Returns the type of the pushed value.

​ 将与注册表中的名称 tname 关联的元表推送到栈（参见 luaL_newmetatable ），如果没有与该名称关联的元表，则推送 nil。返回所推送值的类型。

luaL_getsubtable

[-0, +1, e]

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

Ensures that the value t[fname], where t is the value at index idx, is a table, and pushes that table onto the stack. Returns true if it finds a previous table there and false if it creates a new table.

​ 确保值 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);const char *luaL_gsub (lua_State *L,
const char *s,
const char *p,
const char *r);

Creates a copy of string s, replacing any occurrence of the string p with the string r. Pushes the resulting string on the stack and returns it.

​ 创建字符串 s 的副本，用字符串 r 替换字符串 p 的任何出现。将结果字符串压入栈并返回它。

luaL_len

[-0, +0, e]

lua_Integer luaL_len (lua_State *L, int index);

Returns the “length” of the value at the given index as a number; it is equivalent to the ‘#’ operator in Lua (see §3.4.7). Raises an error if the result of the operation is not an integer. (This case can only happen through metamethods.)

​ 将给定索引处的值的“长度”作为数字返回；它等同于 Lua 中的 ’ # ’ 运算符（参见 §3.4.7）。如果操作结果不是整数，则引发错误。（这种情况只能通过元方法发生。）

luaL_loadbuffer

[-0, +1, –]

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

Equivalent to luaL_loadbufferx with mode equal to NULL.

​ 等价于 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);int luaL_loadbufferx (lua_State *L,
const char *buff,
size_t sz,
const char *name,
const char *mode);

Loads a buffer as a Lua chunk. This function uses lua_load to load the chunk in the buffer pointed to by buff with size sz.

​ 将缓冲区加载为 Lua 块。此函数使用 lua_load 加载由 buff 指向的缓冲区中的块，大小为 sz 。

This function returns the same results as lua_load. name is the chunk name, used for debug information and error messages. The string mode works as in the function lua_load.

​ 此函数返回与 lua_load 相同的结果。 name 是块名称，用于调试信息和错误消息。字符串 mode 的作用与函数 lua_load 中的作用相同。

luaL_loadfile

[-0, +1, m]

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

Equivalent to luaL_loadfilex with mode equal to NULL.

​ 等价于 luaL_loadfilex ，其中 mode 等于 NULL 。

luaL_loadfilex

[-0, +1, m]

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

Loads a file as a Lua chunk. This function uses lua_load to load the chunk in the file named filename. If filename is NULL, then it loads from the standard input. The first line in the file is ignored if it starts with a #.

​ 将文件作为 Lua 块加载。此函数使用 lua_load 加载名为 filename 的文件中的块。如果 filename 为 NULL ，则从标准输入加载。如果文件的第一行以 # 开头，则忽略该行。

The string mode works as in the function lua_load.

​ 字符串 mode 的作用与函数 lua_load 中的作用相同。

This function returns the same results as lua_load or LUA_ERRFILE for file-related errors.

​ 此函数返回与 lua_load 或 LUA_ERRFILE 相同的结果，以获取与文件相关的错误。

As lua_load, this function only loads the chunk; it does not run it.

​ 与 lua_load 一样，此函数仅加载块；不会运行它。

luaL_loadstring

[-0, +1, –]

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

Loads a string as a Lua chunk. This function uses lua_load to load the chunk in the zero-terminated string s.

​ 将字符串作为 Lua 块加载。此函数使用 lua_load 加载以零结尾的字符串 s 中的块。

This function returns the same results as lua_load.

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

Also as lua_load, this function only loads the chunk; it does not run it.

​ 同样，与 lua_load 一样，此函数仅加载块；不会运行它。

luaL_newlib

[-0, +1, m]

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

Creates a new table and registers there the functions in the list l.

​ 创建一个新表，并在列表 l 中注册函数。

It is implemented as the following macro:

​ 它作为以下宏实现：

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

The array l must be the actual array, not a pointer to it.

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

luaL_newlibtable

[-0, +1, m]

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

Creates a new table with a size optimized to store all entries in the array l (but does not actually store them). It is intended to be used in conjunction with luaL_setfuncs (see luaL_newlib).

​ 创建一个新表，其大小经过优化，可存储数组 l 中的所有条目（但实际上并不存储它们）。它旨在与 luaL_setfuncs 一起使用（请参阅 luaL_newlib ）。

It is implemented as a macro. The array l must be the actual array, not a pointer to it.

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

luaL_newmetatable

[-0, +1, m]

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

If the registry already has the key tname, returns 0. Otherwise, creates a new table to be used as a metatable for userdata, adds to this new table the pair __name = tname, adds to the registry the pair [tname] = new table, and returns 1.

​ 如果注册表中已有键 tname ，则返回 0。否则，创建一个新表用作用户数据元表，将对 __name = tname 添加到此新表中，将对 [tname] = new table 添加到注册表中，并返回 1。

In both cases, the function pushes onto the stack the final value associated with tname in the registry.

​ 在这两种情况下，该函数都会将与注册表中的 tname 关联的最终值压入栈。

luaL_newstate

[-0, +0, –]

lua_State *luaL_newstate (void);

Creates a new Lua state. It calls lua_newstate with an allocator based on the ISO C allocation functions and then sets a warning function and a panic function (see §4.4) that print messages to the standard error output.

​ 创建一个新的 Lua 状态。它使用基于 ISO C 分配函数的分配器调用 lua_newstate ，然后设置一个警告函数和一个恐慌函数（参见 §4.4）以将消息打印到标准错误输出。

Returns the new state, or NULL if there is a memory allocation error.

​ 返回新状态，如果存在内存分配错误，则返回 NULL 。

luaL_openlibs

[-0, +0, e]

void luaL_openlibs (lua_State *L);

Opens all standard Lua libraries into the given state.

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

luaL_opt

[-0, +0, –]

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

This macro is defined as follows:

​ 此宏定义如下：

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

In words, if the argument arg is nil or absent, the macro results in the default dflt. Otherwise, it results in the result of calling func with the state L and the argument index arg as arguments. Note that it evaluates the expression dflt only if needed.

​ 用文字来说，如果参数 arg 为 nil 或不存在，则宏的结果为默认值 dflt 。否则，结果为使用状态 L 和参数索引 arg 作为参数调用 func 的结果。请注意，它仅在需要时才计算表达式 dflt 。

luaL_optinteger

[-0, +0, v]

lua_Integer luaL_optinteger (lua_State *L,
                             int arg,
                             lua_Integer d);lua_Integer luaL_optinteger (lua_State *L,
int arg,
lua_Integer d);
 如果函数参数  为整数（或可转换为整数），则返回此整数。如果此参数不存在或为 nil，则返回  。否则，引发错误。

If the function argument arg is an integer (or it is convertible to an integer), returns this integer. If this argument is absent or is nil, returns d. Otherwise, raises an error.

​ [-0, +0, v]

luaL_optlstring

[-0, +0, v] const char *luaL_optlstring (lua_State *L,

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

If the function argument arg is a string, returns this string. If this argument is absent or is nil, returns d. Otherwise, raises an error.

​ 如果函数参数 arg 是字符串，则返回此字符串。如果此参数不存在或为 nil，则返回 d 。否则，引发错误。

If l is not NULL, fills its referent with the result’s length. If the result is NULL (only possible when returning d and d == NULL), its length is considered zero.

​ 如果 l 不是 NULL ，则用结果的长度填充其引用。如果结果为 NULL （仅在返回 d 和 d == NULL 时可能），则其长度被视为零。

This function uses lua_tolstring to get its result, so all conversions and caveats of that function apply here.

​ 此函数使用 lua_tolstring 获取其结果，因此该函数的所有转换和注意事项在此处适用。

luaL_optnumber

[-0, +0, v]

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

If the function argument arg is a number, returns this number as a lua_Number. If this argument is absent or is nil, returns d. Otherwise, raises an error.

​ 如果函数参数 arg 是数字，则以 lua_Number 的形式返回此数字。如果此参数不存在或为 nil，则返回 d 。否则，引发错误。

luaL_optstring

[-0, +0, v]

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

If the function argument arg is a string, returns this string. If this argument is absent or is nil, returns d. Otherwise, raises an error.

​ 如果函数参数 arg 是字符串，则返回此字符串。如果此参数不存在或为 nil，则返回 d 。否则，引发错误。

luaL_prepbuffer

[-?, +?, m]

char *luaL_prepbuffer (luaL_Buffer *B);

Equivalent to luaL_prepbuffsize with the predefined size LUAL_BUFFERSIZE.

​ 等同于具有预定义大小 LUAL_BUFFERSIZE 的 luaL_prepbuffsize 。

luaL_prepbuffsize

[-?, +?, m]

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

Returns an address to a space of size sz where you can copy a string to be added to buffer B (see luaL_Buffer). After copying the string into this space you must call luaL_addsize with the size of the string to actually add it to the buffer.

​ 返回大小为 sz 的空间的地址，您可以在其中复制要添加到缓冲区 B 的字符串（请参阅 luaL_Buffer ）。将字符串复制到此空间后，您必须使用字符串的大小调用 luaL_addsize 以便实际将其添加到缓冲区。

luaL_pushfail

[-0, +1, –]

void luaL_pushfail (lua_State *L);

Pushes the fail value onto the stack (see §6).

​ 将失败值推入栈（参见 §6）。

luaL_pushresult

[-?, +1, m]

void luaL_pushresult (luaL_Buffer *B);void luaL_pushresult (luaL_Buffer *B);
 完成缓冲区  的使用，将最终字符串留在栈顶部。

Finishes the use of buffer B leaving the final string on the top of the stack.

​ [-?, +1, m]

luaL_pushresultsize

[-?, +1, m] void luaL_pushresultsize (luaL_Buffer *B, size_t sz); 等同于序列 、。

void luaL_pushresultsize (luaL_Buffer *B, size_t sz);
[-1, +0, m]

Equivalent to the sequence luaL_addsize, luaL_pushresult.

​ int luaL_ref (lua_State *L, int t); 在索引 luaL_addsize 处的表中为栈顶部的对象创建一个引用并返回该引用（并弹出该对象）。

luaL_ref

[-1, +0, m]

int luaL_ref (lua_State *L, int t);

Creates and returns a reference, in the table at index t, for the object on the top of the stack (and pops the object).

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

​ 引用是一个唯一的整数键。只要您不手动将整数键添加到表 t 中， luaL_ref 就会确保它返回的键的唯一性。您可以通过调用 lua_rawgeti(L, t, r) 来检索由引用 r 引用的对象。函数 luaL_unref 释放引用。

If the object on the top of the stack is nil, luaL_ref returns the constant LUA_REFNIL. The constant LUA_NOREF is guaranteed to be different from any reference returned by luaL_ref.

​ 如果栈顶的对象为 nil， luaL_ref 返回常量 LUA_REFNIL 。常量 LUA_NOREF 保证与 luaL_ref 返回的任何引用不同。

luaL_Reg

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

Type for arrays of functions to be registered by luaL_setfuncs. name is the function name and func is a pointer to the function. Any array of luaL_Reg must end with a sentinel entry in which both name and func are NULL.

​ 要由 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);void luaL_requiref (lua_State *L, const char *modname,
lua_CFunction openf, int glb);

If package.loaded[modname] is not true, calls the function openf with the string modname as an argument and sets the call result to package.loaded[modname], as if that function has been called through require.

​ 如果 package.loaded[modname] 不为真，则使用字符串 modname 作为参数调用函数 openf ，并将调用结果设置为 package.loaded[modname] ，就像该函数已通过 require 调用一样。

If glb is true, also stores the module into the global modname.

​ 如果 glb 为真，则还将模块存储到全局 modname 中。

Leaves a copy of the module on the stack.

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

luaL_setfuncs

[-nup, +0, m]

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

Registers all functions in the array l (see luaL_Reg) into the table on the top of the stack (below optional upvalues, see next).

​ 将数组 l 中的所有函数（请参阅 luaL_Reg ）注册到栈顶部的表中（在可选的上值下方，请参阅下一个）。

When nup is not zero, all functions are created with nup upvalues, initialized with copies of the nup values previously pushed on the stack on top of the library table. These values are popped from the stack after the registration.

​ 当 nup 不为零时，所有函数都使用 nup 个上值创建，这些上值使用先前推送到栈顶部的库表上方的 nup 值的副本进行初始化。注册后，这些值从栈中弹出。

A function with a NULL value represents a placeholder, which is filled with false.

​ 具有 NULL 值的函数表示占位符，该占位符用 false 填充。

luaL_setmetatable

[-0, +0, –]

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

Sets the metatable of the object on the top of the stack as the metatable associated with name tname in the registry (see luaL_newmetatable).

​ 将栈顶对象的元表设置为注册表中与名称 tname 关联的元表（请参阅 luaL_newmetatable ）。

luaL_Stream

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

The standard representation for file handles used by the standard I/O library.

​ 标准 I/O 库使用的文件句柄的标准表示形式。

A file handle is implemented as a full userdata, with a metatable called LUA_FILEHANDLE (where LUA_FILEHANDLE is a macro with the actual metatable’s name). The metatable is created by the I/O library (see luaL_newmetatable).

​ 文件句柄实现为一个完整用户数据，其元表称为 LUA_FILEHANDLE （其中 LUA_FILEHANDLE 是一个宏，其名称为实际元表）。元表由 I/O 库创建（请参阅 luaL_newmetatable ）。

This userdata must start with the structure luaL_Stream; it can contain other data after this initial structure. The field f points to the corresponding C stream (or it can be NULL to indicate an incompletely created handle). The field closef points to a Lua function that will be called to close the stream when the handle is closed or collected; this function receives the file handle as its sole argument and must return either a true value, in case of success, or a false value plus an error message, in case of error. Once Lua calls this field, it changes the field value to NULL to signal that the handle is closed.

​ 此用户数据必须以结构 luaL_Stream 开头；它可以在此初始结构之后包含其他数据。字段 f 指向相应的 C 流（或者它可以是 NULL ，以指示一个不完整创建的句柄）。字段 closef 指向一个 Lua 函数，该函数将在句柄关闭或收集时被调用以关闭流；此函数接收文件句柄作为其唯一参数，并且必须在成功时返回一个 true 值，或在出错时返回一个 false 值和一个错误消息。一旦 Lua 调用此字段，它会将字段值更改为 NULL 以表示句柄已关闭。

luaL_testudata

[-0, +0, m]

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

This function works like luaL_checkudata, except that, when the test fails, it returns NULL instead of raising an error.

​ 此函数的工作方式类似于 luaL_checkudata ，不同之处在于，当测试失败时，它返回 NULL 而不是引发错误。

luaL_tolstring

[-0, +1, e]

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

Converts any Lua value at the given index to a C string in a reasonable format. The resulting string is pushed onto the stack and also returned by the function (see §4.1.3). If len is not NULL, the function also sets *len with the string length.

​ 将给定索引处的任何 Lua 值转换为合理格式的 C 字符串。结果字符串被推入栈，并由函数返回（请参阅 §4.1.3）。如果 len 不是 NULL ，函数还会使用字符串长度设置 *len 。

If the value has a metatable with a __tostring field, then luaL_tolstring calls the corresponding metamethod with the value as argument, and uses the result of the call as its result.

​ 如果该值具有带有 __tostring 字段的元表，则 luaL_tolstring 将使用该值作为参数调用相应的元方法，并将调用的结果用作其结果。

luaL_traceback

[-0, +1, m]

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

Creates and pushes a traceback of the stack L1. If msg is not NULL, it is appended at the beginning of the traceback. The level parameter tells at which level to start the traceback.

​ 创建并推送栈 L1 的回溯。如果 msg 不是 NULL ，则将其追加到回溯的开头。 level 参数告诉从哪个级别开始回溯。

luaL_typeerror

[-0, +0, v]

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

Raises a type error for the argument arg of the C function that called it, using a standard message; tname is a “name” for the expected type. This function never returns.

​ 使用标准消息为调用它的 C 函数的参数 arg 引发类型错误； tname 是预期类型的“名称”。此函数从不返回。

luaL_typename

[-0, +0, –]

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

Returns the name of the type of the value at the given index.

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

luaL_unref

[-0, +0, –]

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

Releases the reference ref from the table at index t (see luaL_ref). The entry is removed from the table, so that the referred object can be collected. The reference ref is also freed to be used again.

​ 从索引 t 处的表中释放引用 ref （请参见 luaL_ref ）。从表中删除该条目，以便可以收集引用的对象。引用 ref 也被释放以再次使用。

If ref is LUA_NOREF or LUA_REFNIL, luaL_unref does nothing.

​ 如果 ref 是 LUA_NOREF 或 LUA_REFNIL ， luaL_unref 不执行任何操作。

luaL_where

[-0, +1, m]

void luaL_where (lua_State *L, int lvl);

Pushes onto the stack a string identifying the current position of the control at level lvl in the call stack. Typically this string has the following format:

​ 将一个字符串推送到栈上，该字符串标识调用栈中 lvl 级别的当前控制位置。通常，此字符串具有以下格式：

     chunkname:currentline:

Level 0 is the running function, level 1 is the function that called the running function, etc.

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

This function is used to build a prefix for error messages.

​ 此函数用于构建错误消息的前缀。