?
本文檔使用 PHP中文網(wǎng)手冊 發(fā)布
所述輔助庫提供了幾個方便的功能的接口下用的Lua。盡管基本API為C和Lua之間的所有交互提供了原始函數(shù)，但輔助庫為一些常見任務(wù)提供了更高級的函數(shù)。
輔助庫中的所有函數(shù)和類型都在頭文件中定義lauxlib.h并具有前綴luaL_。
輔助庫中的所有功能都建立在基本API之上，因此它們不提供任何使用該API無法完成的功能。盡管如此，使用輔助庫確保了代碼的更一致性。
輔助庫中的幾個函數(shù)在內(nèi)部使用一些額外的堆棧槽。當(dāng)輔助庫中的函數(shù)使用少于5個插槽時，它不檢查堆棧大小; 它只是假設(shè)有足夠的插槽。
輔助庫中的幾個函數(shù)用于檢查C函數(shù)參數(shù)。由于錯誤消息的格式為參數(shù)（例如，“ bad argument #1”），因此不應(yīng)將這些函數(shù)用于其他堆棧值。
luaL_check*如果檢查不滿足，稱為函數(shù)總是會引發(fā)錯誤。
5.1 – Functions and Types
這里我們按字母順序列出輔助庫中的所有函數(shù)和類型。
luaL_addchar-?, +?, m
void luaL_addchar (luaL_Buffer *B, char c);
將該字節(jié)添加c到緩沖區(qū)B（請參閱luaL_Buffer）。
luaL_addlstring-?, +?, m
void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);
將s長度指向的字符串添加l到緩沖區(qū)中B（請參閱luaL_Buffer）。該字符串可以包含嵌入的零。
luaL_addsize-?, +?, –
void luaL_addsize (luaL_Buffer *B, size_t n);
添加到緩沖區(qū)B（請參閱luaL_Buffer）n以前復(fù)制到緩沖區(qū)的長度的字符串（請參閱參考資料luaL_prepbuffer）。
luaL_addstring-?, +?, m
void luaL_addstring (luaL_Buffer *B, const char *s);
將指向的由零結(jié)尾的字符串添加s到緩沖區(qū)B（請參閱luaL_Buffer）。
luaL_addvalue-1, +?, m
void luaL_addvalue (luaL_Buffer *B);
將堆棧頂部的值添加到緩沖區(qū)B（請參閱luaL_Buffer）。彈出該值。
這是字符串緩沖區(qū)中唯一可以（并且必須）用堆棧上的額外元素調(diào)用的函數(shù)，這是要添加到緩沖區(qū)的值。
luaL_argcheck-0, +0, v
void luaL_argcheck (lua_State *L, int cond, int arg, const char *extramsg);
檢查是否cond為真。如果不是，則用標(biāo)準(zhǔn)消息引發(fā)錯誤（請參閱參考資料luaL_argerror）。
luaL_argerror-0, +0, v
int luaL_argerror (lua_State *L, int arg, const char *extramsg);
arg使用包含extramsg以下注釋的標(biāo)準(zhǔn)消息引發(fā)一個報告問題的錯誤：調(diào)用它的C函數(shù)的參數(shù)：
bad argument #arg to 'funcname' (extramsg)
這個函數(shù)不會返回。
luaL_Buffer
typedef struct luaL_Buffer luaL_Buffer;
鍵入字符串緩沖區(qū)。
字符串緩沖區(qū)允許C代碼零碎地構(gòu)建Lua字符串。其使用模式如下：
首先聲明一個
b類型的變量luaL_Buffer。然后用一個調(diào)用初始化它
luaL_buffinit(L, &b)。然后將字符串片段添加到調(diào)用任何
luaL_add*函數(shù)的緩沖區(qū)中。通過呼叫完成
luaL_pushresult(&b)。這個調(diào)用將最后一個字符串留在棧頂。
如果你事先知道結(jié)果字符串的總大小，你可以像這樣使用緩沖區(qū)：
首先聲明一個
b類型的變量luaL_Buffer。然后初始化它并
sz通過調(diào)用預(yù)先分配大小的空間luaL_buffinitsize(L, &b, sz)。然后將該字符串復(fù)制到該空間中。
通過調(diào)用完成
luaL_pushresultsize(&b, sz)，其中sz是復(fù)制到該空間的結(jié)果字符串的總大小。
在正常操作期間，字符串緩沖區(qū)使用可變數(shù)量的堆棧槽。所以，在使用緩沖區(qū)的時候，你不能假設(shè)你知道堆棧的頂端在哪里。只要使用平衡，您可以在連續(xù)調(diào)用之間使用堆棧來緩沖操作; 也就是說，當(dāng)你調(diào)用一個緩沖區(qū)操作時，堆棧與前一個緩沖區(qū)操作之后的堆棧位于同一層。（這條規(guī)則的唯一例外是）luaL_addvalue。在luaL_pushresult初始化緩沖區(qū)時，調(diào)用堆棧后返回其級別，并在其頂部添加最后一個字符串。
luaL_buffinit-0, +0, –
void luaL_buffinit (lua_State *L, luaL_Buffer *B);
初始化一個緩沖區(qū)B。此功能不分配任何空間; 必須將緩沖區(qū)聲明為變量（請參閱luaL_Buffer）。
luaL_buffinitsize-?, +?, m
char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);
相當(dāng)于序列luaL_buffinit，luaL_prepbuffsize。
luaL_callmeta-0, +(0|1), e
int luaL_callmeta (lua_State *L, int obj, const char *e);
Calls a metamethod.
如果索引處的對象obj具有metatable，并且此metatable具有一個字段e，則此函數(shù)將調(diào)用此字段作為其唯一參數(shù)傳遞該對象。在這種情況下，該函數(shù)返回true，并將該調(diào)用返回的值壓入堆棧。如果沒有metatable或者沒有metamethod，這個函數(shù)返回false（沒有在棧上壓入任何值）。
luaL_checkany-0, +0, v
void luaL_checkany (lua_State *L, int arg);
檢查函數(shù)是否有任何類型的參數(shù)（包括零）arg。
luaL_checkinteger-0, +0, v
lua_Integer luaL_checkinteger (lua_State *L, int arg);
檢查函數(shù)參數(shù)arg是否為整數(shù)（或可以轉(zhuǎn)換為整數(shù)）并將此整型轉(zhuǎn)換為一個lua_Integer。
luaL_checklstring-0, +0, v
const char *luaL_checklstring (lua_State *L, int arg, size_t *l);
檢查函數(shù)參數(shù)arg是否是字符串并返回此字符串; 如果l不NULL填充*l字符串的長度。
此功能用于lua_tolstring獲取其結(jié)果，因此此功能的所有轉(zhuǎn)換和注意事項均適用于此。
luaL_checknumber-0, +0, v
lua_Number luaL_checknumber (lua_State *L, int arg);
檢查函數(shù)參數(shù)arg是否是數(shù)字并返回此數(shù)字。
luaL_checkoption-0, +0, v
int luaL_checkoption (lua_State *L, int arg, const char *def, const char *const lst[]);
檢查函數(shù)參數(shù)arg是否為字符串，并在數(shù)組中搜索此字符串lst（必須以NULL結(jié)尾）。返回找到字符串的數(shù)組中的索引。如果參數(shù)不是字符串或者找不到字符串，則引發(fā)錯誤。
如果def不是NULL，則def當(dāng)沒有參數(shù)arg或此參數(shù)為零時，該函數(shù)將用作默認(rèn)值。
這是一個將字符串映射到C枚舉的有用函數(shù)。（Lua庫中的常規(guī)約定是使用字符串而不是數(shù)字來選擇選項。）
luaL_checkstack-0, +0, v
void luaL_checkstack (lua_State *L, int sz, const char *msg);
將堆棧大小增加到top + sz元素，如果堆棧無法增長到該大小，則會引發(fā)錯誤。msg是進入錯誤消息（或NULL沒有其他文本）的附加文本。
luaL_checkstring-0, +0, v
const char *luaL_checkstring (lua_State *L, int arg);
檢查函數(shù)參數(shù)arg是否為字符串并返回此字符串。
此功能用于lua_tolstring獲取其結(jié)果，因此此功能的所有轉(zhuǎn)換和注意事項均適用于此。
luaL_checktype-0, +0, v
void luaL_checktype (lua_State *L, int arg, int t);
檢查函數(shù)參數(shù)是否arg具有類型t。請參閱有關(guān)lua_type類型的編碼t。
luaL_checkudata-0, +0, v
void *luaL_checkudata (lua_State *L, int arg, const char *tname);
檢查函數(shù)參數(shù)是否arg是該類型的用戶數(shù)據(jù)tname（請參閱luaL_newmetatable）并返回用戶數(shù)據(jù)地址（請參閱參考資料lua_touserdata）。
luaL_checkversion-0, +0, v
void luaL_checkversion (lua_State *L);
檢查運行呼叫的核心，創(chuàng)建Lua狀態(tài)的核心以及發(fā)起呼叫的代碼是否都使用相同版本的Lua。還檢查運行調(diào)用的內(nèi)核和創(chuàng)建Lua狀態(tài)的內(nèi)核是否使用相同的地址空間。
luaL_dofile-0, +?, e
int luaL_dofile (lua_State *L, const char *filename);
加載并運行給定的文件。它被定義為以下宏：
(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
如果沒有錯誤，則返回false，如果發(fā)生錯誤，則返回true。
luaL_dostring-0, +?, –
int luaL_dostring (lua_State *L, const char *str);
加載并運行給定的字符串。它被定義為以下宏：
(luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
如果沒有錯誤，則返回false，如果發(fā)生錯誤，則返回true。
luaL_error-0, +0, v
int luaL_error (lua_State *L, const char *fmt, ...);
引發(fā)錯誤。錯誤消息格式由fmt加上任何額外的參數(shù)給出，遵循相同的規(guī)則lua_pushfstring。如果該信息可用，它還會在消息的開始處添加文件名和發(fā)生錯誤的行號。
這個函數(shù)永遠不會返回，但它是一個在C函數(shù)中使用它的習(xí)慣用法。return luaL_error(args)
luaL_execresult-0, +3, m
int luaL_execresult (lua_State *L, int stat);
該函數(shù)為標(biāo)準(zhǔn)庫（os.execute和io.close）中與進程相關(guān)的函數(shù)生成返回值。
luaL_fileresult-0, +(1|3), m
int luaL_fileresult (lua_State *L, int stat, const char *fname);
該功能用于在標(biāo)準(zhǔn)庫文件有關(guān)的功能（生成的返回值io.open，os.rename，file:seek等等）。
luaL_getmetafield-0, +(0|1), m
int luaL_getmetafield (lua_State *L, int obj, const char *e);
e從索引處的對象的元表單中將字段推入堆棧，obj并返回推送值的類型。如果對象沒有metatable，或者如果metatable沒有這個字段，則不會推送并返回LUA_TNIL。
luaL_getmetatable-0, +1, m
int luaL_getmetatable (lua_State *L, const char *tname);
將與名稱相關(guān)聯(lián)的元數(shù)據(jù)存入堆棧tname（請參閱參考資料luaL_newmetatable）（如果沒有與該名稱相關(guān)的元數(shù)據(jù)，則為零）。返回推送值的類型。
luaL_getsubtable-0, +1, e
int luaL_getsubtable (lua_State *L, int idx, const char *fname);
確保 index 的值在t[fname]哪里t是idx一個表，并將該表推入堆棧。如果它發(fā)現(xiàn)上一個表，則返回true;如果它創(chuàng)建一個新表，則返回false。
luaL_gsub-0, +1, m
const char *luaL_gsub (lua_State *L, const char *s, const char *p, const char *r);
創(chuàng)建字符串的副本s替換字符串出現(xiàn)的任何p以字符串r。將結(jié)果字符串推入堆棧并返回。
luaL_len-0, +0, e
lua_Integer luaL_len (lua_State *L, int index);
將給定索引處的值的“長度”作為數(shù)字返回; 它相當(dāng)于#Lua中的' '運算符（參見§3.4.7）。如果操作的結(jié)果不是整數(shù)，則引發(fā)錯誤。（這種情況只能通過metamethods發(fā)生。）
luaL_loadbuffer-0, +1, –
int luaL_loadbuffer (lua_State *L, const char *buff, size_t sz, const char *name);
相當(dāng)于luaL_loadbufferx用mode等于NULL。
luaL_loadbufferx-0, +1, –
int luaL_loadbufferx (lua_State *L, const char *buff, size_t sz, const char *name, const char *mode);
將一個緩沖區(qū)加載為Lua塊。此函數(shù)用于lua_load將大塊加載到buff大小指向的緩沖區(qū)中sz。
該函數(shù)返回與。相同的結(jié)果lua_load。name是塊名稱，用于調(diào)試信息和錯誤消息。該字符串mode在函數(shù)中起作用lua_load。
luaL_loadfile-0, +1, m
int luaL_loadfile (lua_State *L, const char *filename);
相當(dāng)于luaL_loadfilex用mode等于NULL。
luaL_loadfilex-0, +1, m
int luaL_loadfilex (lua_State *L, const char *filename, const char *mode);
將文件加載為Lua塊。此函數(shù)用于lua_load將文件加載到名為的文件中filename。如果filename是NULL，則從標(biāo)準(zhǔn)輸入加載。如果以a開頭，文件中的第一行將被忽略#。
該字符串mode在函數(shù)中起作用lua_load。
該函數(shù)返回lua_load與之相同的結(jié)果，但是它具有LUA_ERRFILE與文件相關(guān)的錯誤的額外錯誤代碼（例如，它無法打開或讀取文件）。
因為lua_load這個函數(shù)只加載塊; 它不會運行它。
luaL_loadstring-0, +1, –
int luaL_loadstring (lua_State *L, const char *s);
將一個字符串加載為 Lua 塊。該函數(shù)用于lua_load加載零終止字符串中的塊s。
該函數(shù)返回與。相同的結(jié)果lua_load。
另外lua_load，這個函數(shù)只加載塊; 它不會運行它。
luaL_newlib-0, +1, m
void luaL_newlib (lua_State *L, const luaL_Reg l[]);
創(chuàng)建一個新表并在列表中注冊該功能l。
它被實現(xiàn)為以下宏：
(luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
數(shù)組l必須是實際的數(shù)組，而不是指向它的指針。
luaL_newlibtable-0, +1, m
void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);
創(chuàng)建一個具有優(yōu)化大小的新表，以存儲數(shù)組中的所有條目l（但不實際存儲它們）。它旨在與luaL_setfuncs（參見luaL_newlib）結(jié)合使用。
它是作為一個宏實現(xiàn)的。數(shù)組l必須是實際的數(shù)組，而不是指向它的指針。
luaL_newmetatable-0, +1, m
int luaL_newmetatable (lua_State *L, const char *tname);
如果注冊表已經(jīng)有密鑰tname，則返回0.否則，創(chuàng)建一個新表作為用戶數(shù)據(jù)的元數(shù)據(jù)，向該新表__name = tname添加該對，向注冊表添加該對[tname] = new table，并返回1.（該條目__name用于通過一些錯誤報告功能）。
在這兩種情況下，將與tname注冊表中相關(guān)的最終值推入堆棧。
luaL_newstate-0, +0, –
lua_State *luaL_newstate (void);
創(chuàng)建一個新的 Lua 狀態(tài)。它lua_newstate使用基于標(biāo)準(zhǔn) C realloc函數(shù)的分配器進行調(diào)用，然后設(shè)置一個恐慌函數(shù)（請參閱第4.6節(jié)），在出現(xiàn)嚴(yán)重錯誤時將錯誤消息輸出到標(biāo)準(zhǔn)錯誤輸出。
返回新的狀態(tài)，或者NULL是否有內(nèi)存分配錯誤。
luaL_openlibs-0, +0, e
void luaL_openlibs (lua_State *L);
將所有標(biāo)準(zhǔn) Lua 庫打開到給定狀態(tài)。
luaL_opt-0, +0, e
T luaL_opt (L, func, arg, dflt);
This macro is defined as follows:
(lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))
換言之，如果參數(shù)arg為零或不存在，宏將導(dǎo)致默認(rèn)值dflt。否則，它將導(dǎo)致以func狀態(tài)L和參數(shù)索引arg作為參數(shù)調(diào)用的結(jié)果。請注意，dflt它只在需要時評估表達式。
luaL_optinteger-0, +0, v
lua_Integer luaL_optinteger (lua_State *L, int arg, lua_Integer d);
如果函數(shù)參數(shù)arg是一個整數(shù)（或可轉(zhuǎn)換為整數(shù)），則返回此整數(shù)。如果這個論點不存在或者為零，則返回d。否則，會引發(fā)錯誤。
luaL_optlstring-0, +0, v
const char *luaL_optlstring (lua_State *L, int arg, const char *d, size_t *l);
如果函數(shù)參數(shù)arg是一個字符串，則返回此字符串。如果這個論點不存在或者為零，則返回d。否則，會引發(fā)錯誤。
如果l不是NULL，則填充*l結(jié)果長度的位置。如果結(jié)果是NULL（僅返回時可能d和d == NULL），它的長度被認(rèn)為是零。
此功能用于lua_tolstring獲取其結(jié)果，因此此功能的所有轉(zhuǎn)換和注意事項均適用于此。
luaL_optnumber-0, +0, v
lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);
如果函數(shù)參數(shù)arg是一個數(shù)字，則返回該數(shù)字。如果這個論點不存在或者為零，則返回d。否則，會引發(fā)錯誤。
luaL_optstring-0, +0, v
const char *luaL_optstring (lua_State *L, int arg, const char *d);
如果函數(shù)參數(shù)arg是一個字符串，則返回此字符串。如果這個論點不存在或者為零，則返回d。否則，會引發(fā)錯誤。
luaL_prepbuffer-?, +?, m
char *luaL_prepbuffer (luaL_Buffer *B);
等同于luaL_prepbuffsize預(yù)定義的大小LUAL_BUFFERSIZE。
luaL_prepbuffsize-?, +?, m
char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);
將地址返回到大小sz可以復(fù)制要添加到緩沖區(qū)的字符串的空間B（請參閱參考資料luaL_Buffer）。將字符串復(fù)制到此空間后，必須調(diào)用luaL_addsize字符串的大小才能將其實際添加到緩沖區(qū)中。
luaL_pushresult-?, +1, m
void luaL_pushresult (luaL_Buffer *B);
完成緩沖區(qū)的使用，B將最后一個字符串留在棧頂。
luaL_pushresultsize-?, +1, m
void luaL_pushresultsize (luaL_Buffer *B, size_t sz);
相當(dāng)于序列luaL_addsize，luaL_pushresult。
luaL_ref-1, +0, m
int luaL_ref (lua_State *L, int t);
在索引表中創(chuàng)建并返回一個引用，t用于堆棧頂部的對象（并彈出對象）。
A reference is a unique integer key. As long as you do not manually add integer keys into table t, luaL_ref ensures the uniqueness of the key it returns. You can retrieve an object referred by reference r by calling lua_rawgeti(L, t, r). Function luaL_unref frees a reference and its associated object.
如果堆棧頂部的對象為零，則luaL_ref返回常量LUA_REFNIL。常數(shù)LUA_NOREF保證與任何返回的引用不同luaL_ref。
luaL_Reg
typedef struct luaL_Reg { const char *name;
lua_CFunction func;} luaL_Reg;鍵入要注冊的函數(shù)數(shù)組luaL_setfuncs。name是函數(shù)名稱，func是一個指向函數(shù)的指針。任何數(shù)組都luaL_Reg必須以兩個name和兩個func都是的哨兵條目結(jié)束NULL。
luaL_requiref-0, +1, e
void luaL_requiref (lua_State *L, const char *modname, lua_CFunction openf, int glb);
如果modname尚未存在package.loaded，則openf使用字符串modname作為參數(shù)調(diào)用函數(shù)，并將調(diào)用結(jié)果設(shè)置為package.loaded[modname]，就好像該函數(shù)已被調(diào)用一樣require。
如果glb是，則也將該模塊存儲到全局中modname。
將模塊的副本留在堆棧上。
luaL_setfuncs-nup, +0, m
void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);
將數(shù)組中的所有函數(shù)注冊到堆棧頂部的表中l（請參閱luaL_Reg下面的可選upvalues）。
當(dāng)nup不為零時，所有函數(shù)都將創(chuàng)建共享nup值，這些值必須事先在堆棧頂部的堆棧上進行推送。這些值在注冊后從堆棧彈出。
luaL_setmetatable-0, +0, –
void luaL_setmetatable (lua_State *L, const char *tname);
將堆棧頂部的對象的元表單設(shè)置為與tname注冊表中的名稱關(guān)聯(lián)的元表單（請參閱參考資料luaL_newmetatable）。
luaL_Stream
typedef struct luaL_Stream {
FILE *f;
lua_CFunction closef;} luaL_Stream;文件句柄的標(biāo)準(zhǔn)表示，由標(biāo)準(zhǔn)I / O庫使用。
一個文件句柄被實現(xiàn)為一個完整的用戶數(shù)據(jù)，帶有一個名為metatable LUA_FILEHANDLE（其中LUA_FILEHANDLE是一個具有實際metatable名稱的宏）。該metatable由I / O庫創(chuàng)建（請參閱參考資料luaL_newmetatable）。
這個用戶數(shù)據(jù)必須以結(jié)構(gòu)開始luaL_Stream; 它可以包含此初始結(jié)構(gòu)之后的其他數(shù)據(jù)。Field f指向相應(yīng)的C流（或者它可以NULL指示一個不完全創(chuàng)建的句柄）。Field closef指向一個Lua函數(shù)，當(dāng)句柄關(guān)閉或收集時，Lua函數(shù)將被調(diào)用來關(guān)閉流; 該函數(shù)接收文件句柄作為唯一參數(shù)，并且必須返回true（成功的情況下）或nil加上錯誤消息（如果有錯誤）。一旦Lua調(diào)用此字段，它將字段值更改為NULL表示句柄已關(guān)閉。
luaL_testudata-0, +0, m
void *luaL_testudata (lua_State *L, int arg, const char *tname);
這個函數(shù)的作用就像luaL_checkudata，除了當(dāng)測試失敗時，它返回NULL而不是引發(fā)錯誤。
luaL_tolstring-0, +1, e
const char *luaL_tolstring (lua_State *L, int idx, size_t *len);
將給定索引處的任何Lua值轉(zhuǎn)換為合理格式的C字符串。生成的字符串被壓入堆棧，并由函數(shù)返回。如果len不是NULL，該函數(shù)也會設(shè)置*len字符串長度。
如果該值具有__tostring字段的metatable ，則將luaL_tolstring值作為參數(shù)調(diào)用相應(yīng)的metamethod，并將調(diào)用的結(jié)果作為結(jié)果。
luaL_traceback-0, +1, m
void luaL_traceback (lua_State *L, lua_State *L1, const char *msg, int level);
創(chuàng)建并推送堆棧的回溯L1。如果msg不是，NULL它會追溯到回溯開始時。該level參數(shù)告訴在哪個級別開始回溯。
luaL_typename-0, +0, –
const char *luaL_typename (lua_State *L, int index);
返回給定索引處的值的類型的名稱。
luaL_unref-0, +0, –
void luaL_unref (lua_State *L, int t, int ref);
ref從索引處的表中釋放引用t（請參閱luaL_ref）。該條目從表中刪除，以便可以收集被引用的對象。該參考ref也被釋放以再次使用。
如果ref是LUA_NOREF或者LUA_REFNIL，luaL_unref什么也不做。
luaL_where-0, +1, m
void luaL_where (lua_State *L, int lvl);
將一個字符串推入堆棧，標(biāo)識lvl調(diào)用堆棧中級別控件的當(dāng)前位置。通常這個字符串具有以下格式：
chunkname:currentline:
0級是運行功能，1級是調(diào)用運行功能的功能等。
該函數(shù)用于為錯誤消息構(gòu)建前綴。