14.3 嵌入 Lua

14.3 嵌入 Lua

深入探索 Lua 嵌入 C：代码实践与详解

Lua 以其轻量、快速和可嵌入性而闻名，使其成为许多应用场景中的理想脚本语言。而 Lua 最强大的特性之一，便是其与 C 语言的无缝集成能力。通过 Lua C API，C 语言程序可以将 Lua 虚拟机嵌入自身，从而利用 Lua 的灵活性和动态性，同时保持 C 语言的性能和底层控制力。

1. 嵌入 Lua 的优势与应用场景

在深入代码之前，先理解嵌入 Lua 的价值至关重要。将 Lua 嵌入 C 程序，可以带来以下显著优势：

• 脚本化能力: 为 C 程序添加脚本语言支持，允许用户通过 Lua 脚本自定义程序行为、扩展功能，而无需重新编译 C 代码。

• 配置灵活性: 使用 Lua 脚本作为配置文件，可以方便地修改程序参数、调整运行逻辑，实现更灵活的配置管理。

• 热更新与动态加载: Lua 脚本可以动态加载和更新，这意味着可以在不重启 C 程序的情况下，修改程序的功能和逻辑，实现热更新。

• 胶水语言: Lua 可以作为 C 和其他语言（如 C++、Java 等）之间的桥梁，方便不同语言组件之间的集成和交互。

• 游戏开发: Lua 在游戏开发领域应用广泛，常用于游戏逻辑、UI 脚本、AI 脚本等，实现快速迭代和灵活的游戏设计。

常见的嵌入 Lua 的应用场景包括：

• 游戏引擎: 如 Cocos2d-x、Unity 等，使用 Lua 作为脚本语言。

• 应用程序框架: 许多应用程序框架允许用户使用 Lua 脚本扩展功能。

• 网络服务器: 使用 Lua 处理请求路由、业务逻辑等。

• 嵌入式系统: 在资源受限的嵌入式系统中，Lua 的轻量级特性使其成为理想的脚本语言选择。

2. Lua C API 基础概念

Lua C API 是一组 C 函数、数据类型和宏定义，用于在 C 代码中与 Lua 虚拟机进行交互。理解以下核心概念是掌握 Lua C API 的关键：

• Lua 状态 (Lua State): lua_State: Lua 状态是 Lua 运行环境的核心，每个 Lua 状态都是一个独立的虚拟机实例。C 程序需要创建一个或多个 Lua 状态才能执行 Lua 代码。

• Lua 堆栈 (Lua Stack):: Lua 与 C 之间的数据交换主要通过一个虚拟的堆栈完成。堆栈是一个 LIFO (后进先出) 的数据结构，用于传递参数、返回值等。

• 索引 (Index):: 堆栈中的每个元素都有一个索引，用于访问和操作堆栈中的数据。索引可以是正数（从栈底向上计数，1 代表栈底）或负数（从栈顶向下计数，-1 代表栈顶）。

• 数据类型 (Types):: Lua C API 定义了一系列常量，用于表示 Lua 中的数据类型，例如 LUA_TNUMBER (数字)、LUA_TSTRING (字符串)、LUA_TBOOLEAN (布尔值)、LUA_TFUNCTION (函数)、LUA_TTABLE (表) 等。

• API 函数: Lua C API 提供了一系列函数，用于：

  • 创建和销毁 Lua 状态 (lua_newstate, lua_close).

  • 加载和执行 Lua 代码 (luaL_loadstring, luaL_loadfile, lua_pcall).

  • 在堆栈上压入和弹出数据 (lua_pushnumber, lua_pushstring, lua_pop).

  • 从堆栈中获取数据 (lua_tonumberx, lua_tostringx, lua_toboolean).

  • 调用 Lua 函数 (lua_getglobal, lua_pcall).

  • 注册 C 函数到 Lua (lua_register, lua_pushcfunction, lua_setglobal).

  • 操作 Lua 表 (lua_createtable, lua_gettable, lua_settable).

  • 错误处理 (lua_pcall).

3. 嵌入 Lua 的基本步骤

嵌入 Lua 的基本步骤通常包括：

1. 创建 Lua 状态: 使用 luaL_newstate() 函数创建一个新的 Lua 状态。

2. 加载 Lua 标准库: 使用 luaL_openlibs() 函数加载 Lua 的标准库，例如 base、math、string、table 等。

3. 加载和执行 Lua 代码: 可以使用 luaL_loadstring() 加载 Lua 代码字符串，或使用 luaL_loadfile() 加载 Lua 代码文件。然后使用 lua_pcall() 函数执行加载的代码。

4. 与 Lua 交互: 通过 Lua C API 函数，在 C 代码和 Lua 代码之间进行数据交换和功能调用。

5. 关闭 Lua 状态: 在程序结束时，使用 lua_close() 函数关闭 Lua 状态，释放资源。

4. 代码实践：Lua 嵌入 C 的示例详解

下面通过一系列代码示例，逐步深入 Lua 嵌入 C 的实践。

4.1. 第一个 Lua 嵌入程序：执行简单的 Lua 代码

#include <lua.h>
#include <lualib.h>
#include <lauxlib.h>
int main() {
    // 1. 创建 Lua 状态
    lua_State *L = luaL_newstate();
    if (L == NULL) {
        fprintf(stderr, "luaL_newstate failed\n");
        return 1;
    }
    // 2. 加载 Lua 标准库
    luaL_openlibs(L);
    // 3. 加载和执行 Lua 代码字符串
    const char *lua_code = "print('Hello from Lua!')";
    if (luaL_loadstring(L, lua_code) || lua_pcall(L, 0, 0, 0)) {
        fprintf(stderr, "Error executing Lua code: %s\n", lua_tostring(L, -1));
        lua_close(L);
        return 1;
    }
    // 4. 关闭 Lua 状态
    lua_close(L);
    return 0;
}
​

代码详解：

• #include <lua.h>, #include <lualib.h>, #include <lauxlib.h>: 引入 Lua C API 的头文件。

  • lua.h: 核心 Lua API 头文件。

  • lualib.h: 定义了 luaL_openlibs 等函数，用于加载标准库。

  • lauxlib.h: 定义了辅助库函数，例如 luaL_newstate, luaL_loadstring 等。

• lua_State *L = luaL_newstate();: 创建一个新的 Lua 状态 L。luaL_newstate() 是辅助库提供的函数，它创建了一个新的 Lua 状态，并初始化了一些基本设置。

• luaL_openlibs(L);: 加载 Lua 的标准库到 Lua 状态 L 中。这使得 Lua 脚本可以使用 print, math.sin, string.gsub 等标准库函数。

• const char *lua_code = "print('Hello from Lua!')";: 定义一个 C 字符串 lua_code，包含要执行的 Lua 代码。

• luaL_loadstring(L, lua_code): 将 Lua 代码字符串 lua_code 加载到 Lua 状态 L 中。luaL_loadstring 会编译 Lua 代码，但不会立即执行。它会将编译后的代码作为一个 Lua 函数压入堆栈。

• lua_pcall(L, 0, 0, 0): 执行堆栈顶部的 Lua 函数（即 luaL_loadstring 加载的代码）。

  • 第一个参数 L 是 Lua 状态。

  • 第二个参数 0 是参数数量。这里 Lua 代码没有参数，所以为 0。

  • 第三个参数 0 是返回值数量。这里 Lua 代码没有返回值，所以为 0。

  • 第四个参数 0 是错误处理函数索引。这里不使用自定义错误处理，所以为 0。

  • lua_pcall 返回 0 表示执行成功，非 0 表示执行失败。

• lua_tostring(L, -1): 当 lua_pcall 执行失败时，错误信息会被压入堆栈顶部。lua_tostring(L, -1) 从堆栈顶部取出错误信息，并转换为 C 字符串。-1 表示栈顶索引。

• lua_close(L);: 关闭 Lua 状态 L，释放相关资源。

编译和运行：

假设你已经安装了 Lua 开发库（例如在 Debian/Ubuntu 上安装 liblua5.3-dev），可以使用以下命令编译代码：

gcc -o embed_lua embed_lua.c -llua5.3 -lm -ldl
​

• -llua5.3: 链接 Lua 库 (根据你的 Lua 版本可能需要调整，例如 -llua5.4 或 -llua).

• -lm: 链接数学库 (Lua 标准库中 math 库需要).

• -ldl: 链接动态链接库库 (某些 Lua 版本可能需要).

运行编译后的可执行文件 embed_lua:

./embed_lua
​

程序将输出：

Hello from Lua!
​

4.2. C 调用 Lua 函数

#include <lua.h>
#include <lualib.h>
#include <lauxlib.h>
int main() {
    lua_State *L = luaL_newstate();
    luaL_openlibs(L);
    const char *lua_code =
        "function add(a, b) "
        "  return a + b "
        "end";
    if (luaL_loadstring(L, lua_code) || lua_pcall(L, 0, 0, 0)) {
        fprintf(stderr, "Error loading Lua function: %s\n", lua_tostring(L, -1));
        lua_close(L);
        return 1;
    }
    // 1. 获取 Lua 全局函数 'add'
    lua_getglobal(L, "add");
    if (!lua_isfunction(L, -1)) {
        fprintf(stderr, "'add' is not a function\n");
        lua_close(L);
        return 1;
    }
    // 2. 压入参数
    lua_pushnumber(L, 5);
    lua_pushnumber(L, 3);
    // 3. 调用函数 (2个参数, 1个返回值)
    if (lua_pcall(L, 2, 1, 0)) {
        fprintf(stderr, "Error calling 'add': %s\n", lua_tostring(L, -1));
        lua_close(L);
        return 1;
    }
    // 4. 获取返回值
    if (lua_isnumber(L, -1)) {
        double result = lua_tonumberx(L, -1, NULL);
        printf("Lua function 'add' returned: %.0f\n", result);
    } else {
        fprintf(stderr, "Lua function 'add' did not return a number\n");
    }
    // 5. 清理堆栈 (弹出返回值)
    lua_pop(L, 1);
    lua_close(L);
    return 0;
}
​

代码详解：

• Lua 代码定义 add 函数: Lua 代码字符串中定义了一个名为 add 的函数，接受两个参数 a 和 b，并返回它们的和。

• lua_getglobal(L, "add");: 从 Lua 全局环境中获取名为 "add" 的变量，并将其压入堆栈。由于 "add" 是一个函数，所以堆栈顶部现在是 add 函数对象。

• lua_isfunction(L, -1): 检查堆栈顶部是否为函数类型。

• lua_pushnumber(L, 5);, lua_pushnumber(L, 3);: 将数字 5 和 3 作为参数压入堆栈。参数会按照压入的顺序传递给 Lua 函数。

• lua_pcall(L, 2, 1, 0): 调用堆栈顶部的函数（即 add 函数）。

  • 第二个参数 2 表示传递给 Lua 函数的参数数量（5 和 3 共两个参数）。

  • 第三个参数 1 表示期望 Lua 函数返回的返回值数量（add 函数返回一个值）。

• lua_isnumber(L, -1): 检查堆栈顶部是否为数字类型（即 Lua 函数的返回值）。

• double result = lua_tonumberx(L, -1, NULL);: 从堆栈顶部获取数字值，并转换为 C 的 double 类型。

• lua_pop(L, 1);: 从堆栈中弹出 1 个元素，即 Lua 函数的返回值。在 C 代码中处理完返回值后，通常需要将其从堆栈中弹出，以保持堆栈的整洁。

运行结果：

Lua function 'add' returned: 8
​

4.3. Lua 调用 C 函数 (注册 C 函数到 Lua)

#include <lua.h>
#include <lualib.h>
#include <lauxlib.h>
// C 函数：计算平方
static int l_square(lua_State *L) {
    // 1. 检查参数数量
    if (lua_gettop(L) != 1) {
        return luaL_error(L, "Usage: square(number)");
    }
    // 2. 检查参数类型
    if (!lua_isnumber(L, 1)) {
        return luaL_error(L, "Argument must be a number");
    }
    // 3. 获取参数
    double num = lua_tonumberx(L, 1, NULL);
    // 4. 计算平方
    double result = num * num;
    // 5. 将结果压入堆栈 (作为返回值)
    lua_pushnumber(L, result);
    // 6. 返回值数量 (1个)
    return 1;
}
int main() {
    lua_State *L = luaL_newstate();
    luaL_openlibs(L);
    // 注册 C 函数 'l_square' 到 Lua 全局环境，命名为 'square'
    lua_register(L, "square", l_square);
    const char *lua_code =
        "print('Square of 5 is:', square(5)) "
        "print('Square of 10 is:', square(10))";
    if (luaL_loadstring(L, lua_code) || lua_pcall(L, 0, 0, 0)) {
        fprintf(stderr, "Error executing Lua code: %s\n", lua_tostring(L, -1));
        lua_close(L);
        return 1;
    }
    lua_close(L);
    return 0;
}
​

代码详解：

• C 函数 l_square(lua_State *L): 这是一个 C 函数，它将被注册到 Lua 中，并可以从 Lua 代码中调用。

  • static int l_square(lua_State *L): C 函数必须是 static int 类型，并接受一个 lua_State *L 参数。L 是当前 Lua 状态的指针，C 函数需要通过 L 与 Lua 虚拟机交互。

  • lua_gettop(L): 获取堆栈中的元素数量，用于检查 Lua 传递给 C 函数的参数数量。

  • luaL_error(L, "错误信息"): Lua 辅助库提供的错误处理函数。它会创建一个错误对象，并将错误信息压入堆栈，然后返回 LUA_ERRRUN，表示函数执行失败。

  • lua_isnumber(L, 1): 检查堆栈索引 1 处的元素是否为数字类型（即 Lua 传递的第一个参数）。

  • lua_tonumberx(L, 1, NULL): 从堆栈索引 1 处获取数字值。

  • lua_pushnumber(L, result): 将计算结果 result 压入堆栈。C 函数的返回值通过将值压入堆栈来传递给 Lua。

  • return 1;: C 函数返回 1，表示它向 Lua 返回了一个返回值（即堆栈上的 result）。

• lua_register(L, "square", l_square);: 将 C 函数 l_square 注册到 Lua 全局环境中，命名为 "square"。之后，Lua 代码就可以像调用普通 Lua 函数一样调用 "square"。

  • 第一个参数 L 是 Lua 状态。

  • 第二个参数 "square" 是 Lua 中使用的函数名。

  • 第三个参数 l_square 是 C 函数的指针。

运行结果：

Square of 5 is: 25
Square of 10 is: 100
​

4.4. C 与 Lua 之间的数据交换：字符串、布尔值、表

字符串交互：

• C to Lua: 使用 lua_pushstring(L, "hello Lua") 将 C 字符串压入堆栈。

• Lua to C: 使用 lua_tostringx(L, index, NULL) 从堆栈中获取 Lua 字符串，并转换为 C 字符串。

布尔值交互：

• C to Lua: 使用 lua_pushboolean(L, 1) (true) 或 lua_pushboolean(L, 0) (false) 将 C 布尔值压入堆栈。

• Lua to C: 使用 lua_toboolean(L, index) 从堆栈中获取 Lua 布尔值 (返回 1 或 0)。

表 (Table) 交互：

Lua 的表是一种非常强大的数据结构，C 代码可以通过 Lua C API 操作 Lua 表。

• 创建表: lua_createtable(L, narr, nrec) 创建一个新的空表，并压入堆栈。narr 是预分配的数组部分大小，nrec 是预分配的哈希部分大小 (可以都设为 0)。

• 设置表元素:

  1. 将表压入堆栈 (如果表不在栈顶)。

  2. 将键 (key) 压入堆栈。

  3. 将值 (value) 压入堆栈。

  4. 使用 lua_settable(L, index) 将键值对设置到表 index 中。index 是表在堆栈中的索引。

• 获取表元素:

  1. 将表压入堆栈 (如果表不在栈顶)。

  2. 将键 (key) 压入堆栈。

  3. 使用 lua_gettable(L, index) 获取表 index 中键对应的值，并将值压入堆栈。

示例代码 (表交互)：

#include <lua.h>
#include <lualib.h>
#include <lauxlib.h>
int main() {
    lua_State *L = luaL_newstate();
    luaL_openlibs(L);
    // 1. 创建一个 Lua 表
    lua_createtable(L, 0, 0); // 创建空表
    // 2. 设置表元素: table["name"] = "Lua"
    lua_pushstring(L, "name"); // 键 "name"
    lua_pushstring(L, "Lua");  // 值 "Lua"
    lua_settable(L, -3);      // 设置 table[-3][key] = value. -3 是表的索引 (相对于栈顶)
    // 3. 设置表元素: table["version"] = 5.4
    lua_pushstring(L, "version"); // 键 "version"
    lua_pushnumber(L, 5.4);     // 值 5.4
    lua_settable(L, -3);      // 设置 table[-3][key] = value
    // 4. 获取表元素: value = table["name"]
    lua_pushstring(L, "name"); // 键 "name"
    lua_gettable(L, -2);      // 获取 table[-2][key], 并将 value 压入栈顶. -2 是表的索引
    // 5. 打印表元素值
    if (lua_isstring(L, -1)) {
        const char *name = lua_tostringx(L, -1, NULL);
        printf("Table[\"name\"] = %s\n", name);
    }
    lua_pop(L, 1); // 弹出获取到的值
    // 6. 执行 Lua 代码访问表
    const char *lua_code = "print('Table content:') for k, v in pairs(mytable) do print(k, v) end";
    // 将 C 中创建的表设置为 Lua 全局变量 'mytable'
    lua_setglobal(L, "mytable"); // table[-2] 设置为全局变量 'mytable'
    if (luaL_loadstring(L, lua_code) || lua_pcall(L, 0, 0, 0)) {
        fprintf(stderr, "Error executing Lua code: %s\n", lua_tostring(L, -1));
        lua_close(L);
        return 1;
    }
    lua_close(L);
    return 0;
}
​

运行结果：

Table["name"] = Lua
Table content:
name	Lua
version	5.4
​

5. 错误处理

在嵌入 Lua 的过程中，错误处理至关重要。Lua C API 提供了机制来捕获和处理 Lua 代码执行时发生的错误。

• lua_pcall 的错误处理: lua_pcall 函数的返回值可以指示函数调用是否成功。如果返回非 0 值，则表示执行过程中发生了错误。错误信息通常会被压入堆栈顶部。可以使用 lua_tostring(L, -1) 获取错误信息。

• luaL_error: C 函数可以使用 luaL_error(L, "错误信息") 函数来抛出 Lua 错误。这会将错误信息压入堆栈，并返回 LUA_ERRRUN。Lua 代码可以使用 pcall 函数捕获 C 函数抛出的错误。