Lua参考手册下半部分

3.2k 词

当前大部分来源是5.1的标准

lua_Reader

typedef const char * (*lua_Reader) (lua_State *L, void *data, size_t *size);

lua_load 用到的读取器函数, 每次它需要一块新的 chunk 的时候, lua_load 就调用读取器, 每次都会传入一个参数 data 。 读取器需要返回含有新的 chunk 的一块内存的指针, 并把 size 设为这块内存的大小。 内存块必须在下一次函数被调用之前一直存在。 读取器可以通过返回一个 NULL 来指示 chunk 结束。 读取器可能返回多个块,每个块可以有任意的大于零的尺寸。

lua_register

void lua_register (lua_State *L, const char *name, lua_CFunction f);

把 C 函数 f 设到全局变量 name 中。 它通过一个宏定义:

 #define lua_register(L,n,f) 
        (lua_pushcfunction(L, f), lua_setglobal(L, n))

lua_remove

void lua_remove (lua_State *L, int index);

从给定有效索引处移除一个元素, 把这个索引之上的所有元素移下来填补上这个空隙。 不能用伪索引来调用这个函数, 因为伪索引并不指向真实的栈上的位置。

lua_replace

void lua_replace (lua_State *L, int index);

把栈顶元素移动到给定位置(并且把这个栈顶元素弹出), 不移动任何元素(因此在那个位置处的值被覆盖掉)。

lua_resume

int lua_resume (lua_State *L, int narg);

在给定线程中启动或继续一个 coroutine 。
要启动一个 coroutine 的话,首先你要创建一个新线程 (参见 lua_newthread ); 然后把主函数和若干参数压到新线程的堆栈上; 最后调用 lua_resume , 把 narg 设为参数的个数。 这次调用会在 coroutine 挂起时或是结束运行后返回。 当函数返回时,堆栈中会有传给 lua_yield 的所有值, 或是主函数的所有返回值。 如果 coroutine 切换时,lua_resume 返回 LUA_YIELD , 而当 coroutine 结束运行且没有任何错误时,返回 0 。 如果有错则返回错误代码(参见 lua_pcall)。 在发生错误的情况下, 堆栈没有展开, 因此你可以使用 debug API 来处理它。 出错信息放在栈顶。 要继续运行一个 coroutine 的话,你把需要传给 yield 作结果的返回值压入堆栈,然后调用 lua_resume 。

lua_setallocf

void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);

把指定状态机的分配器函数换成带上指针 ud 的 f 。

lua_setfenv

int lua_setfenv (lua_State *L, int index);

从堆栈上弹出一个 table 并把它设为指定索引处值的新环境。 如果指定索引处的值即不是函数又不是线程或是 userdata , lua_setfenv 会返回 0 , 否则返回 1 。

lua_setfield

void lua_setfield(lua_State *L, int index, const char *k);

等价于t[k] = v的操作,这里t是给出的有效索引index处的值,而v是栈顶的那个值。这个函数将把这个值弹出堆栈。 跟在Lua中一样,这个函数可能触发一个newindex事件的元方法。

lua_setglobal

void lua_setglobal (lua_State *L, const char *name);

从堆栈上弹出一个值,并将其设到全局变量 name 中。 它由一个宏定义出来:

#define lua_setglobal(L,s)   lua_setfield(L, LUA_GLOBALSINDEX, s)

lua_setmetatable

int lua_setmetatable(lua_State *L, int index);

把一个table 弹出堆栈,并将其设为给定索引处的值的 metatable 。

lua_settable

void lua_settable(lua_State *L, int index);

作一个等价于 t[k] = v的操作,这里t是一个给定有效索引 index 处的值, v 指栈顶的值, 而 k 是栈顶之下的那个值。这个函数会把键和值都从堆栈中弹出。 和在 Lua 中一样,这个函数可能触发 “newindex” 事件的元方法。

lua_settop

void lua_settop(lua_State *L, int index);

参数允许传入任何可接受的索引以及0。它将把堆栈的栈顶设为这个索引。如果新的栈顶比原来的大,超出部分的新元素将被填为nil。如果index为0,把栈上所有元素移除。

lua_State

typedef struct lua_State lua_State;
一个不透明的结构,它保存了整个 Lua 解释器的状态。 Lua 库是完全可重入的: 它没有任何全局变量。 (译注:从 C 语法上来说,也不尽然。例如,在 table 的实现中 用了一个静态全局变量 dummynode_ ,但这在正确使用时并不影响可重入性。 只是万一你错误链接了 lua 库,不小心在同一进程空间中存在两份 lua 库实现的代码的话, 多份 dummynode_ 不同的地址会导致一些问题。) 所有的信息都保存在这个结构中。

这个状态机的指针必须作为第一个参数传递给每一个库函数。 lua_newstate 是一个例外, 这个函数会从头创建一个 Lua 状态机。

lua_status

int lua_status (lua_State *L);

返回线程 L 的状态。
正常的线程状态是 0 。 当线程执行完毕或发生一个错误时,状态值是错误码。 如果线程被挂起,状态为 LUA_YIELD 。

lua_toboolean

int lua_toboolean (lua_State *L, int index);

把指定的索引处的的Lua值转换为一个C中的boolean值(0或是1)。和Lua中做的所有测试一样,lua_toboolean会把任何不同于false和nil的值当作1返回; 否则就返回0。 如果用一个无效索引去调用也会返回0。 (如果你想只接收真正的boolean值,就需要使用lua_isboolean来测试值的类型。)

lua_tocfunction

lua_CFunction lua_tocfunction (lua_State *L, int index);

把给定索引处的 Lua 值转换为一个 C 函数。 这个值必须是一个 C 函数;如果不是就返回 NULL 。

lua_tointeger

lua_Integer lua_tointeger (lua_State *L, int idx);

把给定索引处的 Lua 值转换为 lua_Integer 这样一个有符号整数类型。 这个 Lua 值必须是一个数字或是一个可以转换为数字的字符串 (参见 §2.2.1); 否则,lua_tointeger 返回 0 。
如果数字不是一个整数, 截断小数部分的方式没有被明确定义。

lua_tolstring

const char *lua_tolstring (lua_State *L, int index, size_t *len);

把给定索引处的 Lua 值转换为一个 C 字符串。 如果 len 不为 NULL , 它还把字符串长度设到 *len 中。 这个 Lua 值必须是一个字符串或是一个数字; 否则返回返回 NULL 。 如果值是一个数字,lua_tolstring 还会把堆栈中的那个值的实际类型转换为一个字符串。 (当遍历一个表的时候,把 lua_tolstring 作用在键上,这个转换有可能导致 lua_next 弄错。)

lua_tolstring 返回 Lua 状态机中 字符串的以对齐指针。 这个字符串总能保证 ( C 要求的)最后一个字符为零 (‘