Lua 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