lua API函數大全

Lua5.1中的API函數

lua_State* luaL_newstate()
Lua腳本的編譯執行是相互獨立的，在不一樣的線程上執行。經過luaL_newstate()函數能夠申請一個虛擬機，返回指針類型 lua_State。從此其餘全部Lua Api函數的調用都須要此指針做爲第一參數，用來指定某個虛擬機。
lua_State* L = luaL_newstate();
---------------------------------------------------------------------------------------
void  lua_close(lua_State *L)
銷
毀指定 Lua 狀態機中的全部對象（若是有垃圾收集相關的元方法的話，會調用它們），而且釋放狀態機中使用的全部動態內存。在一些平臺上，你能夠沒必要調
用這個函數，由於當宿主程序結束的時候，全部的資源就天然被釋放掉了。另外一方面，長期運行的程序，好比一個後臺程序或是一個 web 服務器，當再也不須要
它們的時候就應該釋放掉相關狀態機。這樣能夠避免狀態機擴張的過大。
lua_close(L);
---------------------------------------------------------------------------------------
lua_State* lua_newthread(lua_State *L)

---------------------------------------------------------------------------------------
int   lua_gettop(lua_State *L)
取得棧的高度
for (int i = 0; i < 10; ++i)
      lua_pushnumber(L, i);
printf("%d", lua_gettop(L));
--> 10
---------------------------------------------------------------------------------------
void  lua_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
---------------------------------------------------------------------------------------
void  lua_pushvalue(lua_State *L, int idx)
將指定索引上值的副本壓入棧
for (int i = 1; i <= 3; ++i)
      lua_pushnumber(i);
棧中元素：（從下往上） 1 2 3
lua_pushvalue(L, 2)
棧中元素：（從下往上） 1 2 3 2
---------------------------------------------------------------------------------------
void  lua_remove(lua_State *L, int idx)
刪除指定索引上的元素，並將該位置之上的全部元素下移以補空缺
for (int i = 1; i <= 3; ++i)
      lua_pushnumber(i);
棧中元素：（從下往上） 1 2 3
lua_remove(L, 2)
棧中元素：（從下往上） 1 3
---------------------------------------------------------------------------------------
void  lua_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
---------------------------------------------------------------------------------------
void  lua_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
---------------------------------------------------------------------------------------
int   lua_checkstack(lua_State *L, int sz)
擴大棧的可用尺寸，棧的默認尺寸是20，此函數會確保堆棧上至少有 sz 個空位。若是不能把堆棧擴展到相應的尺寸，函數返回 false 。這個函數永遠不會縮小堆棧；若是堆棧已經比須要的大了，那麼就放在那裏不會產生變化。
lua_checkstack(L, 100)
---------------------------------------------------------------------------------------
void  lua_xmove(lua_State* from, lua_State* to, int n)

//access functions (stack -> C)
int   lua_isnumber(lua_State *L, int idx)
int   lua_isstring(lua_State *L, int idx)
int   lua_iscfunction(lua_State *L, int idx)
int   lua_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
......
---------------------------------------------------------------------------------------
int   lua_type(lua_State *L, int idx)
獲得一個元素的類型，返回整型，返回值是以下列表之一：

#define LUA_TNONE  (-1)

#define LUA_TNIL  0
#define LUA_TBOOLEAN  1
#define LUA_TLIGHTUSERDATA 2
#define LUA_TNUMBER  3
#define LUA_TSTRING  4
#define LUA_TTABLE  5
#define LUA_TFUNCTION  6
#define LUA_TUSERDATA  7
#define LUA_TTHREAD  8

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
---------------------------------------------------------------------------------------

int   lua_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
---------------------------------------------------------------------------------------
int   lua_rawequal(lua_State *L, int idx1, int idx2)
int   lua_lessthan(lua_State *L, int idx1, int idx2)

---------------------------------------------------------------------------------------
lua_Number lua_tonumber(lua_State *L, int idx)
lua_Integer lua_tointeger(lua_State *L, int idx)
int   lua_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_t  lua_objlen(lua_State *L, int idx)
返回值的長度，若是類型不正確，返回0
lua_pushstring(L, "hello,lua")
lua_objlen(L, 1)-->9
---------------------------------------------------------------------------------------
lua_CFunction lua_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)
void  lua_pushnil(lua_State *L)
void  lua_pushnumber(lua_State *L, lua_Number n)
void  lua_pushinteger(lua_State *L, lua_Integer n)
void  lua_pushlstring(lua_State *L, const char* s, size_t l)
void  lua_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, ...)
void  lua_pushcclosure(lua_State *L, lua_CFunction fn, int n)
void  lua_pushboolean(lua_State *L, void *b)
void  lua_pushlightuserdata(lua_State *L, void *p)
int   lua_pushthread(lua_State *L)

void  lua_gettable(lua_State *L, int idx)
---------------------------------------------------------------------------------------
void  lua_getfield(lua_State *L, int idx, const char *k)
把 t[k] 值壓入堆棧，這裏的 t 是指有效索引 index 指向的值。在 Lua 中，這個函數可能觸發對應 "index" 事件的元方法
---------------------------------------------------------------------------------------
void  lua_rawget(lua_State *L, int idx)
void  lua_rawgeti(lua_State *L, int idx, int n)
---------------------------------------------------------------------------------------
void  lua_createtable(lua_State *L, int narr, int nrec)
建立一個新的空 table 壓入堆棧。這個新 table 將被預分配 narr 個元素的數組空間以及 nrec 個元素的非數組空間。當你明確知道表中須要多少個元素時，預分配就很是有用。若是你不知道，可使用函數 lua_newtable。
舉例暫缺
---------------------------------------------------------------------------------------
void*  lua_newuserdata(lua_State *L, size_t sz)
int   lua_getmetatable(lua_State *L, int objindex)
---------------------------------------------------------------------------------------
void  lua_getfenv(lua_State *L, int idx)

把索引處值的環境表壓入堆棧
---------------------------------------------------------------------------------------
void  lua_settable(lua_State *L, int idx);
void  lua_setfield(lua_State *L, int idx, const char *k)
void  lua_rawset(lua_State *L, int idx)
void  lua_rawseti(lua_State *L, int idx, int n)
int   lua_setmetatable(lua_State *L, int objindex)
int   lua_setfenv(lua_State *L, int idx)

//'load' and 'call' functions (load and run lua code)
void  lua_call(lua_State *L, int nargs, int nresults);
int   lua_pcall(lua_State *L, int nargs, int nresults, int errfunc)
---------------------------------------------------------------------------------------
int   lua_cpcall(lua_State *L, lua_CFunction func, void *ud)
以
保護模式調用 C 函數 func 。 func 只有能從堆棧上拿到一個參數，就是包含有 ud 的 light userdata。當有錯誤
時， lua_cpcall 返回和 lua_pcall 相同的錯誤代碼，並在棧頂留下錯誤對象；不然它返回零，並不會修改堆棧。全部從 func 內
返回的值都會被扔掉。
舉例暫缺
---------------------------------------------------------------------------------------
int   lua_load(lua_State *L, lua_Reader reader, void *dt, const char *chunkname);
---------------------------------------------------------------------------------------
int   lua_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 返回彈出堆棧。
舉例暫缺
---------------------------------------------------------------------------------------
int   lua_yield(lua_State *L, int nresults)
int   lua_resume(lua_State *L, int narg)
int   lua_status(lua_State *L)

---------------------------------------------------------------------------------------
int   lua_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-collector pause 的新值。函數返回之前的值。
 * LUA_GCSETSTEPMUL: 把 arg/100 設置成 step multiplier 。函數返回之前的值。
---------------------------------------------------------------------------------------
int   lua_error(lua_State *L)
產生一個 Lua 錯誤。錯誤信息（實際上能夠是任何類型的 Lua 值）必須被置入棧頂。這個函數會作一次長跳轉，所以它不會再返回。（參見 luaL_error）。
lua_pushstring(L, "one error");
lua_error(L);
printf("%s", "本行已經執行不到了");
---------------------------------------------------------------------------------------
int   lua_next(lua_State *L, int idx)
---------------------------------------------------------------------------------------
void  lua_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_Alloc lua_getallocf(lua_State *L, void **ud)
返回給定狀態機的內存分配器函數。若是 ud 不是 NULL ，Lua 把調用 lua_newstate 時傳入的那個指針放入 *ud 。
---------------------------------------------------------------------------------------
void  lua_setallocf(lua_State *L, lua_Alloc f, void *ud)

//Functions to be called by the debuger in specific events
int   lua_getstack(lua_State *L, int level, lua_Debug *ar)
int   lua_getinfo(lua_State *L, const char *what, lua_Debug *ar)
const char* lua_getlocal(lua_State *L, const lua_Debug *ar, int n)
const char* lua_setlocal(lua_State *L, const lua_Debug *ar, int n)
const char* lua_getupvalue(lua_State *L, int funcindex, int n)
const char* lua_setupvalue(lua_State *L, int funcindex, int n)
int   lua_sethook(lua_State *L, lua_Hook func, int mask, int count);
lua_Hook lua_gethook(lua_State *L)
int   lua_gethookmask(lua_State *L)
int   lua_gethookcount(lua_State *L)