C API
- 云风Blog：Lua C API 的正确用法
- C读取和调用Lua文件的库：
lua.h, lauxlib.h, lualib.h - 包括：读写Lua全局变量的函数、调用Lua函数的函数、运行Lua代码片段的函数、注册C函数然后可以在Lua中被调用的函数
- C和Lua之间的数据交换，通过对栈上的值进行操作。栈的使用解决：Lua会自动进行垃圾回收，而C要求显示的分配内存单元；Lua中的动态类型和C的静态类型。
- 压入元素：
void lua_pushnil(lua_State *L); //插入空值
void lua_pushboolean(lua_State *L, int bool); //插入布尔值
void lua_pushnumber(lua_State *L, double n); //插入double
void lua_pushlstring(lua_State *L, const char* s, size_t length); //插入任意字符串
void lua_pushstring(lua_State *L, const char* s); //插入带'\0'的字符串
-
查询元素
1表示第一个被压栈的元素；-1表示栈顶元素；当一个C函数返回后，Lua会清理他的栈，所以，有一个原则：永远不要将指向Lua字符串的指针保存到访问他们的外部函数中。
int lua_is*(lua_State *L, int index); //检查一个元素是否指定类型(number,string,boolean,table)
int lua_toboolean(lua_State *L, int index);
double lua_tonumber(lua_State *L, int index);
const char* lua_tostring(lua_State *L, int index);
size_t lua_strlen(lua_State *L, int index);
- 其他堆栈操作
int lua_gettop(lua_State *L); //返回堆栈中的元素个数
void lua_settop(lua_State *L, int index); //设置栈顶为一个指定的值，多余值被抛弃，否则压入nil值
void lua_pop(lua_State *L, int n); //lua_settop(L, -n - 1),从堆栈中弹出n个元素
void lua_pushvalue(lua_State *L, int index); //压入堆栈上指定一个索引的拷贝到栈顶
void lua_remove(lua_State *L, int index); //移除指定索引位置的元素
void lua_insert(lua_State *L, int index); //移动栈顶元素到指定索引的位置
void lua_replace(lua_State *L, int index); //从栈顶中弹出元素并将其设置到指定索引位置
-
错误处理
应用程序中(调用Lua的C代码)的错误处理：当Lua遇到类似内存分配失败的情况，大部分会抛出异常，调用panic函数退出应用；其余情况会忽略异常，在保护模式下运行代码(Lua通过调用lua_pcall来运行)。
类库(被Lua调用的C函数)中的错误处理：C函数发现错误只要调用luaL_error函数，清理所有在Lua中需要被清理的，然后和错误信息一起回到最初执行lua_pcall的地方。 - 表操作
void lua_gettable(lua_State *L, int idx); //以栈顶元素为key值，获取指定索引的表的值到栈顶
void lua_getfield(lua_State *L, int idx, const char *k); //获取指定索引的表对应key的值到栈顶
void lua_getglobal(lua_State *L, const char *name); //等于lua_getfield(L, LUA_GLOBALSINDEX, (name))。获取全局表的变量到栈顶
void lua_settable(lua_State *L, int idx); //以栈顶元素为value，栈顶下一元素为key，设置指定索引的表的值
void lua_setfield(lua_State *L, int idx, const char *k); //弹出栈顶元素，并设置为指定索引的表对应key的值
void lua_setglobal(lua_State *L, const char *name); //等于lua_setfield(L, LUA_GLOBALSINDEX, (name))。设置全局变量的值
void lua_rawgeti(lua_State *L, int idx, int n); //获得idx索引的表以n为key的值
void lua_rawget(lua_State *L, int idx); //获得idx索引的表以栈顶为key的值
void lua_rawseti(lua_State *L, int idx, int n); //设置idx索引的表以n为key的值
void lua_rawset(lua_State *L, int idx); //设置idx索引的表以栈顶下一个元素为key的值
-
调用函数
使用API调用函数的方法是很简单的：首先，将被调用的函数入栈；第二，依次将所有参数入栈；第三，使用lua_pcall调用函数；最后，从栈中获取函数执行返回的结果。
在将结果入栈之前，lua_pcall会将栈内的函数和参数移除。如果lua_pcall运行时出现错误，lua_pcall会返回一个非0的结果，并将错误信息入栈(依然会先移除栈内函数和参数)
错误处理函数需要在被调用函数和参数之前入栈，参数errfunc为错误函数在栈中的索引。一般错误返回LUA_ERRRUN。内存分配错误返回LUA_ERRMEM；在错误处理函数中出错返回LUA_ERRERR，这两种情况并不会调用错误处理函数。
int lua_pcall(lua_State *L, int nargs, int nresults, int errfunc); //调用栈顶函数，指定参数格式nargs，返回结果个数，nresults，和错误函数
-
调用C函数
Lua调用C函数，使用栈进行交互，用来交互的栈不是全局变量，每一个函数都有他自己的私有栈，第一个参数总是在这个私有栈的index = 1的位置。
一个Lua库实际上是一个定义了一系列Lua函数的chunk，并将这些函数保存在适当的地方，通常作为table的域来保存。Lua的C库就是这样实现的。
在宿主程序中调用C函数
//注册被Lua调用的C函数的格式，以a+b为例
static int func(lua_State *L)
{
//从栈中获取函数参数并检查合法性，1表示Lua调用时的第一个参数，以此类推
double arg1 = luaL_checknumber(L, 1);
double arg2 = luaL_checknumber(L, 2);
//将函数结果入栈，如果有多个返回值，可以多次入栈
lua_pushnumber(L, arg1 + arg2);
//返回值表示该函数的返回值的数量
return 1;
}
int main()
{
lua_State* L = luaL_newstate();
luaL_openlibs(L);
//注册被Lua调用的C函数，参数"add"表示Lua调用时使用的全局函数名，func为被调用的C函数
lua_register(L, "add", func);
luaL_dostring("print(add(1, 2))");
lua_close(L);
return 0;
}
C函数库
//注册被Lua调用的C函数的格式，以a+b为例，函数必须以C的形式被导出
extern "C" int func(lua_State *L)
{
//从栈中获取函数参数并检查合法性，1表示Lua调用时的第一个参数，以此类推
double arg1 = luaL_checknumber(L, 1);
double arg2 = luaL_checknumber(L, 2);
//将函数结果入栈，如果有多个返回值，可以多次入栈
lua_pushnumber(L, arg1 + arg2);
//返回值表示该函数的返回值的数量
return 1;
}
static luaL_Reg mylibs[] =
{
{"add", func},
{NULLL, NULL},
};
//注册mylibs库，Lua中使用该库的用法：testlibs.add(1, 2)
extern "C" __declspec(dllexport)
int luaopen_testlibs(lua_State* L)
{
luaL_newlib(L, mylibs);
return 1;
}
-
字符串处理
当C函数接受一个来自lua的字符串作为参数时，有两个规则必须遵守：当字符串正在被访问的时候不要将其出栈；永远不要修改字符串。
当C函数需要创建一个字符串返回给lua的时候，C代码负责缓冲区的分配和释放，负责处理缓冲溢出等情况。
void lua_concat(lua_State *L, int n); //连接栈顶开始的n个字符串，弹出这n个字符串并压栈结果
const char *lua_pushfstring(lua_State *L, const char *fmt, ...); //根据格式串fmt的要求创建一个新的字符串。
-
注册表
使用LUA_REGISTRYINDEX索引来保存注册表中的Lua值。任何C库都可以在这张表里保存数据， 为了防止冲突，可以使用保护库名前缀的名字作为key值。注册表中的整数key用于应用机制luaL_ref。 -
闭包
一个C函数和它的upvalues的组合称为闭包。upvalues为函数能访问的外部局部变量。
static int counter(lua_State *L)
{
double val = lua_tonumber(L, lua_upvalveindex(1));
lua_pushnumber(L, ++val);
lua_pushvalue(L, -1);
lua_replace(L, lua_upvalueindex(1));
return 1;
}
int newCounter(lua_State *L)
{
lua_pushnumber(L, 0);
//第二个参数为基本函数，第三个参数是upvalues的个数
lua_pushcclosure(L, &counter, 1);
return 1;
}
- Userdata
void *lua_newuserdata(lua_State *L, size_t size); //按照指定size的大小分配一段内存放入栈内，并返回这个地址
- Metatable
int luaL_newmetatable(lua_State *L, const char* tname); //栈顶创建metatable，建立表和registry中类型名的双向关系(分别以tname为表的key和以表为tname的key)
void luaL_getmetatable(lua_State *L, const char* tname); //获取registry中tname对应的表
void* luaL_checkudata(lua_State *L, int index, const char* tname); //检查指定索引的元素是否为带有给定tname的metatable的useratum，如果是，返回useratum的地址，否则返回NULL
