LUA C API接口

转载自：http://www.cnblogs.com/stephen-liu74/archive/2012/07/18/2433428.html
lua手册：http://cloudwu.github.io/lua53doc/contents.html

Lua是一种嵌入式脚本语言，即Lua不是可以单独运行的程序，在实际应用中，主要存在两种应用形式。第一种形式是，C/C++作为主程序，调用Lua代码，此时可以将Lua看做“可扩展的语言”，我们将这种应用称为“应用程序代码”。第二种形式是Lua具有控制权，而C/C++代码则作为Lua的“库代码”。在这两种形式中，都是通过Lua提供的C API完成两种语言之间的通信的。

1. 基础知识：

C API是一组能使C/C++代码与Lua交互的函数。其中包括读写Lua全局变量、调用Lua函数、运行一段Lua代码，以及注册C函数以供Lua代码调用等。这里先给出一个简单的示例代码：

1 #include <stdio.h>
2 #include <string.h>
3 #include <lua.hpp>
4 #include <lauxlib.h>
5 #include <lualib.h>
6 
7 int main(void) 
8 {
9       const char* buff = "print(\"hello\")";
10      int error;
11      lua_State* L = luaL_newstate();
12      luaL_openlibs(L);
13 
14      error = luaL_loadbuffer(L,buff,strlen(buff),"line") || lua_pcall(L,0,0,0);
15      int s = lua_gettop(L);
16      if (error) {
17                fprintf(stderr,"%s",lua_tostring(L,-1));
18          lua_pop(L,1);
19      }
20      lua_close(L);
21      return 0;
22 }

下面是针对以上代码给出的具体解释：
1). 上面的代码是基于我的C++工程，而非C工程，因此包含的头文件是lua.hpp，如果是C工程，可以直接包含lua.h。
2). Lua库中没有定义任何全局变量，而是将所有的状态都保存在动态结构lua_State中，后面所有的C API都需要该指针作为第一个参数。
3). luaL_openlibs函数是用于打开Lua中的所有标准库，如io库、string库等。
4). luaL_loadbuffer编译了buff中的Lua代码，如果没有错误，则返回0，同时将编译后的程序块压入虚拟栈中。
5). lua_pcall函数会将程序块从栈中弹出，并在保护模式下运行该程序块。执行成功返回0，否则将错误信息压入栈中。
6). lua_tostring函数中的-1，表示栈顶的索引值，栈底的索引值为1，以此类推。该函数将返回栈顶的错误信息，但是不会将其从栈中弹出。
7). lua_pop是一个宏，用于从虚拟栈中弹出指定数量的元素，这里的1表示仅弹出栈顶的元素。
8). lua_close用于释放状态指针所引用的资源。

2.栈：

在Lua和C语言之间进行数据交换时，由于两种语言之间有着较大的差异，比如Lua是动态类型，C语言是静态类型，Lua是自动内存管理，而C语言则是手动内存管理。为了解决这些问题，Lua的设计者使用了虚拟栈作为二者之间数据交互的介质。在C/C++程序中，如果要获取Lua的值，只需调用Lua的C API函数，Lua就会将指定的值压入栈中。要将一个值传给Lua时，需要先将该值压入栈，然后调用Lua的C API，Lua就会获取该值并将其从栈中弹出。为了可以将不同类型的值压入栈，以及从栈中取出不同类型的值，Lua为每种类型均设定了一个特定函数。
1). 压入元素：

    Lua针对每种C类型，都有一个C API函数与之对应，如：
    void lua_pushnil(lua_State* L);  --nil值
    void lua_pushboolean(lua_State* L, int b); --布尔值
    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 len); --指定长度的内存数据
    void lua_pushstring(lua_State* L, const char* s);  --以零结尾的字符串，其长度可由strlen得出。

   //对于字符串数据，Lua不会持有他们的指针，而是调用在API时生成一个内部副本，因此，即使在这些函
   //数返回后立刻释放或修改这些字符串指针，也不会有任何问题。
   //在向栈中压入数据时，可以通过调用下面的函数判断是否有足够的栈空间可用，一般而言，Lua会预留20
   //个槽位，对于普通应用来说已经足够了，除非是遇到有很多参数的函数。
   //int lua_checkstack(lua_State* L, int extra) --期望得到extra数量的空闲槽位，如果不
   //能扩展并获得，返回false。

2). 查询元素：

    //API使用“索引”来引用栈中的元素，第一个压入栈的为1，第二个为2，依此类推。我们也可以使用为索引值，其中-1表示为栈顶元素，-2为栈顶下面的元素，同样依此类推。

    Lua提供了一组特定的函数用于检查返回元素的类型，如： 
    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);

以上函数，成功返回1，否则返回0。需要特别指出的是，对于lua_isnumber而言，不会检查值是否为数字类型，而是检查值是否能转换为数字类型。
Lua还提供了一个函数lua_type，用于获取元素的类型，函数原型如下：

int lua_type (lua_State *L, int index);
LUA_TTABLE、LUA_TFUNCTION、LUA_TUSERDATA、LUA_TTHREAD和LUA_TLIGHTUSERDATA。这些常量通常
用于switch语句中

    除了上述函数之外，Lua还提供了一组转换函数，如：
    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类型返回操作符’#’等同的结果，userdata类型返回分配的内存块长度。

    size_t lua_objlen (lua_State *L, int index);　

对于上述函数，如果调用失败，lua_toboolean、lua_tonumber、lua_tointeger和lua_objlen均返回0，错误的通过判断返回值是否为NULL即可。
对于lua_tolstring函数返回的指向内部字符串的指针，在该索引指向的元素被弹出之后，将无法保证仍然有效。该函数返回的字符串末尾均会有一个尾部0。
下面将给出一个工具函数，可用于演示上面提到的部分函数，如：

 1 static void stackDump(lua_State* L) //打印整个栈的内容，由下而上，根据元素类型打印
 2 {
 3     int top = lua_gettop(L);//返回栈顶元素的索引。 因为索引是从 1 开始编号的， 
                            //所以这个结果等于栈上的元素个数； 特别指出，0 表示栈为空
 4     for (int i = 1; i <= top; ++i) {
 5         int t = lua_type(L,i);//返回给定有效索引处值的类型， 
                              //当索引无效（或无法访问）时则返回 LUA_TNONE
 6         switch(t) {
 7         case LUA_TSTRING:
 8             printf("'%s'",lua_tostring(L,i));
 9             break;
10         case LUA_TBOOLEAN:
11             printf(lua_toboolean(L,i) ? "true" : "false");
12             break;
13         case LUA_TNUMBER:
14             printf("%g",lua_tonumber(L,i));
15             break;
16         default:
17             printf("%s",lua_typename(L,t));//返回 t 表示的类型名， 
                                    //这个 tp 必须是 lua_type 可能返回的值中之一。 
18             break;
19         }
20         printf("");
21     }
22     printf("\n");
23 }

3). 其它栈操作函数

    //除了上面给出的数据交换函数之外，Lua的C API还提供了一组用于操作虚拟栈的普通函数，如：
    int lua_gettop(lua_State* L); //返回栈中元素的个数。
    void lua_settop(lua_State* L, int index); //将栈顶设置为指定的索引值。
    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还提供了一个宏用于弹出指定数量的元素：#define lua_pop(L,n)  lua_settop(L, -(n) - 1)    
    见如下示例代码：

 1 int main()
 2 {
 3     lua_State* L = luaL_newstate();
 4     lua_pushboolean(L,1);
 5     lua_pushnumber(L,10);
 6     lua_pushnil(L);
 7     lua_pushstring(L,"hello");
 8     stackDump(L); //true 10 nil 'hello'
 9 
10     lua_pushvalue(L,-4);--把栈上给定索引处的处的元素作为一个副本压栈
11     stackDump(L); //true 10 nil 'hello' true
12 
13     lua_replace(L,3);--把栈顶元素放置到给定位置而不移动其它元素 
                    --（因此覆盖了那个位置处的值），然后将栈顶元素弹出
14     stackDump(L); //true 10 true 'hello'
15 
16     lua_settop(L,6);--参数允许传入任何索引以及 0 。 它将把堆栈的栈顶设为这个索引。 如果新的栈顶比原来的
                    --大， 超出部分的新元素将被填为 nil 。 如果 index 为 0 ， 把栈上所有元素移除
17     stackDump(L); //true 10 true 'hello' nil nil
18 
19     lua_remove(L,-3);--从给定有效索引处移除一个元素， 把这个索引之上的所有元素移下来填补上这个空隙。 
                    --不能用伪索引来调用这个函数，因为伪索引并不指向真实的栈上的位置。
20     stackDump(L); //true 10 true nil nil
21 
22     lua_settop(L,-5);---5为栈顶，-1到-4被移除
23     stackDump(L); //true
24 
25     lua_close(L);
26     return 0;
27 }

3. C API中的错误处理：
1). C程序调用Lua代码的错误处理：
通常情况下，应用程序代码是以“无保护”模式运行的。因此，当Lua发现“内存不足”这类错误时，只能通过调用“紧急”函数来通知C语言程序，之后在结束应用程序。用户可通过lua_atpanic来设置自己的“紧急”函数。如果希望应用程序代码在发生Lua错误时不会退出，可通过调用lua_pcall函数以保护模式运行Lua代码。这样再发生内存错误时，lua_pcall会返回一个错误代码，并将解释器重置为一致的状态。如果要保护与Lua的C代码，可以使用lua_cpall函数，它将接受一个C函数作为参数，然后调用这个C函数。

2). Lua调用C程序：
通常而言，当一个被Lua调用的C函数检测到错误时，它就应该调用lua_error，该函数会清理Lua中所有需要清理的资源，然后跳转回发起执行的那个lua_pcall，并附上一条错误信息。”