Lua5.1中的API函数

lua_State*luaL_newstate()
Lua脚本的编译执行是相互独立的，在不同的线程上执行。通过luaL_newstate()函数可以申请一个虚拟机，返回指针类型 lua_State。今后其他所有Lua Api函数的调用都需要此指针作为第一参数，用来指定某个虚拟机。
lua_State* L = luaL_newstate();
---------------------------------------------------------------------------------------
voidlua_close(lua_State *L)
销
毁指定Lua状态机中的所有对象（如果有垃圾收集相关的元方法的话，会调用它们），并且释放状态机中使用的所有动态内存。在一些平台上，你可以不必调
用这个函数，因为当宿主程序结束的时候，所有的资源就自然被释放掉了。另一方面，长期运行的程序，比如一个后台程序或是一个web服务器，当不再需要
它们的时候就应该释放掉相关状态机。这样可以避免状态机扩张的过大。
lua_close(L);
---------------------------------------------------------------------------------------
lua_State*lua_newthread(lua_State *L)
---------------------------------------------------------------------------------------
intlua_gettop(lua_State *L)
取得栈的高度
for (int i = 0; i < 10; ++i)
lua_pushnumber(L, i);
printf("%d", lua_gettop(L));
-->10
---------------------------------------------------------------------------------------
voidlua_settop(lua_State *L, int idx)
设置栈的高度，如果之前的栈顶比新设置的更高，那么高出来的元素会被丢弃，反之压入nil来补足大小。
另外，Lua提供了一个宏，用来从栈中弹出n个元素：#define lua_pop(L, n) lua_settop(L, -(n)-1)
for (int i = 0; i < 10; ++i)
lua_pushnumber(L, i);
lua_settop(L, 5)
printf("%d", lua_gettop(L));
-->5
---------------------------------------------------------------------------------------
voidlua_pushvalue(lua_State *L, int idx)
将指定索引上值的副本压入栈
for (int i = 1; i <= 3; ++i)
lua_pushnumber(i);
栈中元素：（从下往上）12 3
lua_pushvalue(L, 2)
栈中元素：（从下往上）123 2
---------------------------------------------------------------------------------------
voidlua_remove(lua_State *L, int idx)
删除指定索引上的元素，并将该位置之上的所有元素下移以补空缺
for (int i = 1; i <= 3; ++i)
lua_pushnumber(i);
栈中元素：（从下往上）12 3
lua_remove(L, 2)
栈中元素：（从下往上）1 3
---------------------------------------------------------------------------------------
voidlua_insert(lua_State *L, int idx)
移指定位置上的所有元素以开辟一个空间槽的空间，然后将栈顶元素移到该位置
for (int i = 1; i <= 5; ++i)
lua_pushnumber(i);
栈中元素：（从下往上） 1 2 3 4 5
lua_insert(L, 3)
栈中元素：（从下往上）1 2 5 4 3
---------------------------------------------------------------------------------------
voidlua_replace(lua_State *L, int idx)
弹出栈顶的值，并将该值设置到指定索引上，但它不会移动任何东西
for (int i = 1; i <= 5; ++i)
lua_pushnumber(i);
栈中元素：（从下往上） 1 2 3 4 5
lua_replace(L, 3)
栈中元素：（从下往上）1 2 5 4
---------------------------------------------------------------------------------------
intlua_checkstack(lua_State *L, int sz)
扩大栈的可用尺寸，栈的默认尺寸是20，此函数会确保堆栈上至少有sz个空位。如果不能把堆栈扩展到相应的尺寸，函数返回false。这个函数永远不会缩小堆栈；如果堆栈已经比需要的大了，那么就放在那里不会产生变化。
lua_checkstack(L, 100)
---------------------------------------------------------------------------------------
voidlua_xmove(lua_State* from, lua_State* to, int n)

//access functions (stack -> C)
intlua_isnumber(lua_State *L, int idx)
intlua_isstring(lua_State *L, int idx)
intlua_iscfunction(lua_State *L, int idx)
intlua_isuserdata(lua_State *L, int idx)

int lua_isnil(lua_State *L, int idx);
int lua_isboolean(lua_State *L, int idx);
int lua_istable(lua_State *L, int idx);
int lua_isfunction(lua_State *L, int idx);
int lua_islightuserdata (lua_State *L, int idx);
上面四个函数都有一个同样的原型int lua_is*(lua_State *L, int index)，用来查询某值是否能转换成某个类型的值。对于任意数字，lua_isstring都返回真。
lua_pushnumber(L, 994);
lua_pushstring(L, "hello,lua");
lua_isnumber(L, 1)-->true
lua_isnumber(L, 2)-->false
lua_isstring(L,1)-->true
......
---------------------------------------------------------------------------------------
intlua_type(lua_State *L, int idx)
得到一个元素的类型，返回整型，返回值是如下列表之一：

#define LUA_TNONE(-1)

#define LUA_TNIL0
#define LUA_TBOOLEAN1
#define LUA_TLIGHTUSERDATA2
#define LUA_TNUMBER3
#define LUA_TSTRING4
#define LUA_TTABLE5
#define LUA_TFUNCTION6
#define LUA_TUSERDATA7
#define LUA_TTHREAD8

lua_pushnumber(L, 55);
lua_type(L, 1)-->LUA_TNUMBER
---------------------------------------------------------------------------------------
const char*lua_typename(lua_State *L, int tp)
将一个类型编码转换成类型名
lua_typename(L, 1)-->boolean
lua_typename(L, 3)-->number
---------------------------------------------------------------------------------------

intlua_equal(lua_State *L, int idx1, int idx2)
如果依照Lua中==操作符语义，索引index1和index2中的值相同的话，返回1。否则返回0。如果任何一个索引无效也会返回0。
lua_pushstring(L, "this");
lua_pushboolean(L, 1);
lua_pushboolean(L, 1);
lua_equal(L, -2, -3)
-->0
lua_equal(L, -1, -2)
-->1
lua_equal(L, -1, -10)
-->0
---------------------------------------------------------------------------------------
intlua_rawequal(lua_State *L, int idx1, int idx2)
intlua_lessthan(lua_State *L, int idx1, int idx2)

---------------------------------------------------------------------------------------
lua_Numberlua_tonumber(lua_State *L, int idx)
lua_Integerlua_tointeger(lua_State *L, int idx)
intlua_toboolean(lua_State *L, int idx)
const char* lua_tolstring(lua_State *L, int idx, size_t *len)
以上四个函数都有一个原型lua_to*(lua_State *L, int idx)，用于从栈中取一个值。如果指定的元素不具有正确的类型，调用这些函数也不会有问题，
在这种情况下，调用lua_toboolean，lua_tonumber，lua_tointeger会返回0，其它函数会返回NULL。通常不使用lua_is*函数，只需在调用它们之
后测试返回结果是否为NULL就可以了。
lua_pushnumber(L, 100)
lua_tonumber(L, 1)-->100
lua_pushinteger(L, 200)
lua_tointeger(L, -1)-->200
lua_pushboolean(L, 0)
lua_toboolean(L, -1)-->false
lua_pushstring(L, "hello,lua")
lua_tolstring(L, -1, &len)-->hello,lua
注：len是传出参数，表示字符串的长度，如果想忽略此参数，传入NULL
---------------------------------------------------------------------------------------
size_tlua_objlen(lua_State *L, int idx)
返回值的长度，如果类型不正确，返回0
lua_pushstring(L, "hello,lua")
lua_objlen(L, 1)-->9
---------------------------------------------------------------------------------------
lua_CFunctionlua_tocfunction(lua_State *L, int idx)
void*lua_touserdata(lua_State *L, int idx)
lua_State*lua_tothread(lua_State *L, int idx)
const void*lua_topointer(lua_State *L, int idx)

//push functions (C -> stack)
voidlua_pushnil(lua_State *L)
voidlua_pushnumber(lua_State *L, lua_Number n)
voidlua_pushinteger(lua_State *L, lua_Integer n)
voidlua_pushlstring(lua_State *L, const char* s, size_t l)
voidlua_pushstring(lua_State *L, const char *s)
const char*lua_pushvfstring(lua_State *L, const char *fmt, va_list argp)
const char*lua_pushfstring(lua_State *L, const char *fmt, ...)
voidlua_pushcclosure(lua_State *L, lua_CFunction fn, int n)
voidlua_pushboolean(lua_State *L, void *b)
voidlua_pushlightuserdata(lua_State *L, void *p)
intlua_pushthread(lua_State *L)

voidlua_gettable(lua_State *L, int idx)
---------------------------------------------------------------------------------------
voidlua_getfield(lua_State *L, int idx, const char *k)
把t[k]值压入堆栈，这里的t是指有效索引index指向的值。在Lua中，这个函数可能触发对应"index"事件的元方法
---------------------------------------------------------------------------------------
voidlua_rawget(lua_State *L, int idx)
voidlua_rawgeti(lua_State *L, int idx, int n)
---------------------------------------------------------------------------------------
voidlua_createtable(lua_State *L, int narr, int nrec)
创建一个新的空table压入堆栈。这个新table将被预分配narr个元素的数组空间以及nrec个元素的非数组空间。当你明确知道表中需要多少个元素时，预分配就非常有用。如果你不知道，可以使用函数lua_newtable。
举例暂缺
---------------------------------------------------------------------------------------
void*lua_newuserdata(lua_State *L, size_t sz)
intlua_getmetatable(lua_State *L, int objindex)
---------------------------------------------------------------------------------------
voidlua_getfenv(lua_State *L, int idx)

把索引处值的环境表压入堆栈
---------------------------------------------------------------------------------------
voidlua_settable(lua_State *L, int idx);
voidlua_setfield(lua_State *L, int idx, const char *k)
voidlua_rawset(lua_State *L, int idx)
voidlua_rawseti(lua_State *L, int idx, int n)
intlua_setmetatable(lua_State *L, int objindex)
intlua_setfenv(lua_State *L, int idx)

//'load' and 'call' functions (load and run lua code)
voidlua_call(lua_State *L, int nargs, int nresults);
intlua_pcall(lua_State *L, int nargs, int nresults, int errfunc)
---------------------------------------------------------------------------------------
intlua_cpcall(lua_State *L, lua_CFunction func, void *ud)
以
保护模式调用C函数func。func只有能从堆栈上拿到一个参数，就是包含有ud的lightuserdata。当有错误
时，lua_cpcall返回和lua_pcall相同的错误代码，并在栈顶留下错误对象；否则它返回零，并不会修改堆栈。所有从func内
返回的值都会被扔掉。
举例暂缺
---------------------------------------------------------------------------------------
intlua_load(lua_State *L, lua_Reader reader, void *dt, const char *chunkname);
---------------------------------------------------------------------------------------
intlua_dump(lua_State *L, lua_Writer writer, void *data);
把
函数dump成二进制chunk。函数接收栈顶的Lua函数做参数，然后生成它的二进制chunk。若被dump出来的东西被再次加
载，加载的结果就相当于原来的函数。当它在产生chunk的时候，lua_dump通过调用函数writer（参见lua_Writer）来
写入数据，后面的data参数会被传入writer。
最后一次由写入器(writer)返回值将作为这个函数的返回值返回；0表示没有错误。 这个函数不会把Lua返回弹出堆栈。
举例暂缺
---------------------------------------------------------------------------------------
intlua_yield(lua_State *L, int nresults)
intlua_resume(lua_State *L, int narg)
intlua_status(lua_State *L)

---------------------------------------------------------------------------------------
intlua_gc(lua_State *L, int what, int data)

控制垃圾收集器。 这个函数根据其参数what发起几种不同的任务：
*LUA_GCSTOP:停止垃圾收集器。
*LUA_GCRESTART:重启垃圾收集器。
*LUA_GCCOLLECT:发起一次完整的垃圾收集循环。
*LUA_GCCOUNT:返回Lua使用的内存总量（以K字节为单位）。
*LUA_GCCOUNTB:返回当前内存使用量除以1024的余数。
*LUA_GCSTEP:发起一步增量垃圾收集。步数由data控制（越大的值意味着越多步），而其具体含义（具体数字表示了多少）并未标准化。如果你想控制这个步数，必须实验性的测试data的值。如果这一步结束了一个垃圾收集周期，返回返回1。
*LUA_GCSETPAUSE:把data/100设置为garbage-collectorpause的新值。函数返回以前的值。
*LUA_GCSETSTEPMUL:把arg/100设置成stepmultiplier。函数返回以前的值。
---------------------------------------------------------------------------------------
intlua_error(lua_State *L)
产生一个Lua错误。错误信息（实际上可以是任何类型的Lua值）必须被置入栈顶。这个函数会做一次长跳转，因此它不会再返回。（参见luaL_error）。
lua_pushstring(L, "one error");
lua_error(L);
printf("%s", "本行已经执行不到了");
---------------------------------------------------------------------------------------
intlua_next(lua_State *L, int idx)
---------------------------------------------------------------------------------------
voidlua_concat(lua_State *L, int n)
连接栈顶的n个值，然后将这些值出栈，并把结果放在栈顶。如果n为1，结果就是一个字符串放在栈上（即，函数什么都不做）；如果n为0，结果是一个空串。连接依照Lua中创建语义完成，如果尝试把两个不能连接的类型连接，程序会给出错误提示。
lua_pushstring(L, "this");
lua_pushboolean(L, 1);
lua_pushnumber(L, 9989);
lua_pushnumber(L, 1111);
lua_pushboolean(L, 0);
lua_pushstring(L, "满天都是小星星");
lua_pushnumber(L, 1986);
lua_pushstring(L, "onebyone");
-->'this' 'true' '9989' '1111' 'false' '满天都是小星星' '1986' 'onebyone'
lua_concat(L, 3);
-->'this' 'true' '9989' '1111' 'false' '满天都是小星星1986onebyone'
---------------------------------------------------------------------------------------
lua_Alloclua_getallocf(lua_State *L, void **ud)
返回给定状态机的内存分配器函数。如果ud不是NULL，Lua把调用lua_newstate时传入的那个指针放入*ud。
---------------------------------------------------------------------------------------
voidlua_setallocf(lua_State *L, lua_Alloc f, void *ud)