Lua教程（十七）：C API簡介

更新時間：2015年04月30日 09:57:57 投稿：junjie

這篇文章主要介紹了Lua教程（十七）：C API簡介,本文講解了基礎(chǔ)知識、棧、C API中的錯誤處理、Lua調(diào)用C程序、C程序調(diào)用Lua代碼的錯誤處理等內(nèi)容,需要的朋友可以參考下

Lua是一種嵌入式腳本語言，即Lua不是可以單獨運行的程序，在實際應(yīng)用中，主要存在兩種應(yīng)用形式。第一種形式是，C/C++作為主程序，調(diào)用Lua代碼，此時可以將Lua看做“可擴展的語言”，我們將這種應(yīng)用稱為“應(yīng)用程序代碼”。第二種形式是Lua具有控制權(quán)，而C/C++代碼則作為Lua的“庫代碼”。在這兩種形式中，都是通過Lua提供的C API完成兩種語言之間的通信的。

1. 基礎(chǔ)知識：

C API是一組能使C/C++代碼與Lua交互的函數(shù)。其中包括讀寫Lua全局變量、調(diào)用Lua函數(shù)、運行一段Lua代碼，以及注冊C函數(shù)以供Lua代碼調(diào)用等。這里先給出一個簡單的示例代碼：

復(fù)制代碼代碼如下:

#include <stdio.h>
#include <string.h>
#include <lua.hpp>
#include <lauxlib.h>
#include <lualib.h>

int main(void)
{
    const char* buff = "print(\"hello\")";
    int error;
    lua_State* L = luaL_newstate();
    luaL_openlibs(L);

    error = luaL_loadbuffer(L,buff,strlen(buff),"line") || lua_pcall(L,0,0,0);
    int s = lua_gettop(L);
    if (error) {
        fprintf(stderr,"%s",lua_tostring(L,-1));
        lua_pop(L,1);
    }
    lua_close(L);
    return 0;
}

下面是針對以上代碼給出的具體解釋：

    1). 上面的代碼是基于我的C++工程，而非C工程，因此包含的頭文件是lua.hpp，如果是C工程，可以直接包含lua.h。
    2). Lua庫中沒有定義任何全局變量，而是將所有的狀態(tài)都保存在動態(tài)結(jié)構(gòu)lua_State中，后面所有的C API都需要該指針作為第一個參數(shù)。
    3). luaL_openlibs函數(shù)是用于打開Lua中的所有標準庫，如io庫、string庫等。
    4). luaL_loadbuffer編譯了buff中的Lua代碼，如果沒有錯誤，則返回0，同時將編譯后的程序塊壓入虛擬棧中。
    5). lua_pcall函數(shù)會將程序塊從棧中彈出，并在保護模式下運行該程序塊。執(zhí)行成功返回0，否則將錯誤信息壓入棧中。
    6). lua_tostring函數(shù)中的-1，表示棧頂?shù)乃饕?，棧底的索引值?，以此類推。該函數(shù)將返回棧頂?shù)腻e誤信息，但是不會將其從棧中彈出。
    7). lua_pop是一個宏，用于從虛擬棧中彈出指定數(shù)量的元素，這里的1表示僅彈出棧頂?shù)脑亍?br />     8). lua_close用于釋放狀態(tài)指針所引用的資源。

2. 棧：

在Lua和C語言之間進行數(shù)據(jù)交換時，由于兩種語言之間有著較大的差異，比如Lua是動態(tài)類型，C語言是靜態(tài)類型，Lua是自動內(nèi)存管理，而C語言則是手動內(nèi)存管理。為了解決這些問題，Lua的設(shè)計者使用了虛擬棧作為二者之間數(shù)據(jù)交互的介質(zhì)。在C/C++程序中，如果要獲取Lua的值，只需調(diào)用Lua的C API函數(shù)，Lua就會將指定的值壓入棧中。要將一個值傳給Lua時，需要先將該值壓入棧，然后調(diào)用Lua的C API，Lua就會獲取該值并將其從棧中彈出。為了可以將不同類型的值壓入棧，以及從棧中取出不同類型的值，Lua為每種類型均設(shè)定了一個特定函數(shù)。

1). 壓入元素：

Lua針對每種C類型，都有一個C API函數(shù)與之對應(yīng)，如：

復(fù)制代碼代碼如下:

    void lua_pushnil(lua_State* L);  --nil值

    void lua_pushboolean(lua_State* L, int b); --布爾值

    void lua_pushnumber(lua_State* L, lua_Number n); --浮點數(shù)

    void lua_pushinteger(lua_State* L, lua_Integer n);  --整型

    void lua_pushlstring(lua_State* L, const char* s, size_t len); --指定長度的內(nèi)存數(shù)據(jù)

    void lua_pushstring(lua_State* L, const char* s);  --以零結(jié)尾的字符串，其長度可由strlen得出。

    對于字符串數(shù)據(jù)，Lua不會持有他們的指針，而是調(diào)用在API時生成一個內(nèi)部副本，因此，即使在這些函數(shù)返回后立刻釋放或修改這些字符串指針，也不會有任何問題。
    在向棧中壓入數(shù)據(jù)時，可以通過調(diào)用下面的函數(shù)判斷是否有足夠的棧空間可用，一般而言，Lua會預(yù)留20個槽位，對于普通應(yīng)用來說已經(jīng)足夠了，除非是遇到有很多參數(shù)的函數(shù)。
    int lua_checkstack(lua_State* L, int extra) --期望得到extra數(shù)量的空閑槽位，如果不能擴展并獲得，返回false。

    2). 查詢元素：

API使用“索引”來引用棧中的元素，第一個壓入棧的為1，第二個為2，依此類推。我們也可以使用負數(shù)作為索引值，其中-1表示為棧頂元素，-2為棧頂下面的元素，同樣依此類推。

Lua提供了一組特定的函數(shù)用于檢查返回元素的類型，如：

復(fù)制代碼代碼如下:

    int lua_isboolean (lua_State *L, int index);

    int lua_iscfunction (lua_State *L, int index);

    int lua_isfunction (lua_State *L, int index);

    int lua_isnil (lua_State *L, int index);

    int lua_islightuserdata (lua_State *L, int index);

    int lua_isnumber (lua_State *L, int index);

    int lua_isstring (lua_State *L, int index);

    int lua_istable (lua_State *L, int index);

    int lua_isuserdata (lua_State *L, int index);

以上函數(shù)，成功返回1，否則返回0。需要特別指出的是，對于lua_isnumber而言，不會檢查值是否為數(shù)字類型，而是檢查值是否能轉(zhuǎn)換為數(shù)字類型。
Lua還提供了一個函數(shù)lua_type，用于獲取元素的類型，函數(shù)原型如下：

復(fù)制代碼代碼如下:

int lua_type (lua_State *L, int index);

該函數(shù)的返回值為一組常量值，分別是：LUA_TNIL、LUA_TNUMBER、LUA_TBOOLEAN、LUA_TSTRING、LUA_TTABLE、LUA_TFUNCTION、LUA_TUSERDATA、LUA_TTHREAD和LUA_TLIGHTUSERDATA。這些常量通常用于switch語句中。
除了上述函數(shù)之外，Lua還提供了一組轉(zhuǎn)換函數(shù)，如：

復(fù)制代碼代碼如下:

    int lua_toboolean (lua_State *L, int index);

    lua_CFunction lua_tocfunction (lua_State *L, int index);

    lua_Integer lua_tointeger (lua_State *L, int index);    

    const char *lua_tolstring (lua_State *L, int index, size_t *len);

    lua_Number lua_tonumber (lua_State *L, int index);

    const void *lua_topointer (lua_State *L, int index);

    const char *lua_tostring (lua_State *L, int index);

    void *lua_touserdata (lua_State *L, int index);

    --string類型返回字符串長度，table類型返回操作符'#'等同的結(jié)果，userdata類型返回分配的內(nèi)存塊長度。

    size_t lua_objlen (lua_State *L, int index);

    對于上述函數(shù)，如果調(diào)用失敗，lua_toboolean、lua_tonumber、lua_tointeger和lua_objlen均返回0，而其他函數(shù)則返回NULL。在很多時候0不是一個很有效的用于判斷錯誤的值，但是ANSI C沒有提供其他可以表示錯誤的值。因此對于這些函數(shù)，在有些情況下需要先使用lua_is*系列函數(shù)判斷是否類型正確，而對于剩下的函數(shù)，則可以直接通過判斷返回值是否為NULL即可。
    對于lua_tolstring函數(shù)返回的指向內(nèi)部字符串的指針，在該索引指向的元素被彈出之后，將無法保證仍然有效。該函數(shù)返回的字符串末尾均會有一個尾部0。
    下面將給出一個工具函數(shù)，可用于演示上面提到的部分函數(shù)，如：

復(fù)制代碼代碼如下:

static void stackDump(lua_State* L) 

{

    int top = lua_gettop(L);

    for (int i = 1; i <= top; ++i) {

        int t = lua_type(L,i);

        switch(t) {

        case LUA_TSTRING:

            printf("'%s'",lua_tostring(L,i));

            break;

        case LUA_TBOOLEAN:

            printf(lua_toboolean(L,i) ? "true" : "false");

            break;

        case LUA_TNUMBER:

            printf("%g",lua_tonumber(L,i));

            break;

        default:

            printf("%s",lua_typename(L,t));

            break;

        }

        printf("");

    }

    printf("\n");

}

3). 其它棧操作函數(shù)：

除了上面給出的數(shù)據(jù)交換函數(shù)之外，Lua的C API還提供了一組用于操作虛擬棧的普通函數(shù)，如：

復(fù)制代碼代碼如下:

    int lua_gettop(lua_State* L); --返回棧中元素的個數(shù)。

    void lua_settop(lua_State* L, int index); --將棧頂設(shè)置為指定的索引值。

    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); --彈出棧頂元素，并將該值設(shè)置到指定索引上。

Lua還提供了一個宏用于彈出指定數(shù)量的元素：

復(fù)制代碼代碼如下:

#define lua_pop(L,n) lua_settop(L, -(n) - 1)

見如下示例代碼：

復(fù)制代碼代碼如下:

int main()
{
    lua_State* L = luaL_newstate();
    lua_pushboolean(L,1);
    lua_pushnumber(L,10);
    lua_pushnil(L);
    lua_pushstring(L,"hello");
    stackDump(L); //true 10 nil 'hello'

lua_pushvalue(L,-4);
stackDump(L); //true 10 nil 'hello' true

lua_replace(L,3);
stackDump(L); //true 10 true 'hello'

lua_settop(L,6);
stackDump(L); //true 10 true 'hello' nil nil

lua_remove(L,-3);
stackDump(L); //true 10 true nil nil

lua_settop(L,-5);
stackDump(L); //true

lua_close(L);
return 0;
}

3. C API中的錯誤處理：

1). C程序調(diào)用Lua代碼的錯誤處理：

    通常情況下，應(yīng)用程序代碼是以“無保護”模式運行的。因此，當Lua發(fā)現(xiàn)“內(nèi)存不足”這類錯誤時，只能通過調(diào)用“緊急”函數(shù)來通知C語言程序，之后在結(jié)束應(yīng)用程序。用戶可通過lua_atpanic來設(shè)置自己的“緊急”函數(shù)。如果希望應(yīng)用程序代碼在發(fā)生Lua錯誤時不會退出，可通過調(diào)用lua_pcall函數(shù)以保護模式運行Lua代碼。這樣再發(fā)生內(nèi)存錯誤時，lua_pcall會返回一個錯誤代碼，并將解釋器重置為一致的狀態(tài)。如果要保護與Lua的C代碼，可以使用lua_cpall函數(shù)，它將接受一個C函數(shù)作為參數(shù)，然后調(diào)用這個C函數(shù)。

    2). Lua調(diào)用C程序：

通常而言，當一個被Lua調(diào)用的C函數(shù)檢測到錯誤時，它就應(yīng)該調(diào)用lua_error，該函數(shù)會清理Lua中所有需要清理的資源，然后跳轉(zhuǎn)回發(fā)起執(zhí)行的那個lua_pcall，并附上一條錯誤信息。

您可能感興趣的文章: