Lua与C交互API接口总结

1. 常见Lua相关的C API

压入元素

// cpp
void lua_pushnil(lua_State *L);
void lua_pushboolean(lua_State *L, int bool);
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);
void lua_pushfunction(lua_State *L, lua_CFunction fn);

查询元素

// cpp
int lua_is***(lua_State *L, int index); // 检查lua数据类型 nil number string table等// lua_type 函数是 Lua C API 中用于获取指定索引处的值的类型的函数。它返回一个表示值类型的整数，并且不会改变堆栈上的内容。
/* 如果索引处的值存在，则返回该值的类型，以整数形式表示。返回值为以下预定义的常量之一：
LUA_TNIL：空值。
LUA_TBOOLEAN：布尔值。
LUA_TLIGHTUSERDATA：轻量用户数据。
LUA_TNUMBER：数字。
LUA_TSTRING：字符串。
LUA_TTABLE：表。
LUA_TFUNCTION：函数。
LUA_TUSERDATA：用户数据。
LUA_TTHREAD：线程（协程）。
如果索引处的值不存在，则返回 LUA_TNONE。
*/
int lua_type(lua_State *L, int index);

获取元素

// cpp
// to* 相关操作并不会改变lua栈，只是从栈中index出取值并转成c变量类型int lua_toboolean(lua_State *L, int index); // 从栈中获取bool值const char *lua_tostring(lua_State *L, int index);// len：用于存储字符串长度的指针（可选参数）。如果为 NULL，则不返回字符串长度
const char *lua_tolstring(lua_State *L, int index, size_t *len);// lua_Integer 通常在 Lua 的头文件（如 lua.h 或 luaconf.h）中定义
// typedef long long lua_Integer
lua_Integer lua_tointeger(lua_State *L, int index);// lua_Number 通常在 Lua 的头文件（如 lua.h 或 luaconf.h）中定义
// typedef double lua_Number;
lua_Number lua_tonumber(lua_State *L, int index);int lua_toboolean(lua_State *L, int index);

检查元素

// cpp
int luaL_checkinteger(lua_State *L, int arg); lua_Number luaL_checknumber(lua_State *L, int arg);const char* luaL_checkstring(lua_State *L, int arg);int luaL_checkboolean(lua_State *L, int arg);// t：要检查的类型，在 Lua 中表示为预定义的宏，例如 LUA_TNUMBER、LUA_TSTRING 等。
void luaL_checktype(lua_State *L, int arg, int t);

栈的相关数据操作

// cpp
lua_pop(lua_State *L, int n); // 弹出栈顶的 n 个值。lua_gettop(lua_State *L); // 返回堆栈的栈顶索引（但不修改堆栈）。lua_settop(lua_State *L, int index);// 修改栈元素数量，减小栈则会丢弃多余部分元素，增大会push nil值lua_remove(lua_State *L, int index); // 移除指定索引处的值，并将上面的所有值下移。// 用于将指定索引处的值复制到堆栈顶部。它不会删除原始值，而是将其复制一份并推入堆栈。
void lua_pushvalue(lua_State *L, int index);// 用于将栈顶的值弹出，并将其设置为lua的全局变量
void lua_setglobal(lua_State *L, const char *name);// 用于将lua全局变量的值推入堆栈
void lua_getglobal(lua_State *L, const char *name);// 用于将栈顶的值弹出，并将其设置为index处的表中指定字段的值
/* lua_setfield 从栈顶弹出一个值，并将其设置为表中指定字段的值。
这个操作相当于在 Lua 中执行 t[k] = value，其中 t 是栈中索引为 index 的表，k 是字段名，value 是栈顶的值。*/
void lua_setfield(lua_State *L, int index, const char *k);// 用于从指定索引处的表中获取一个字段的值，并将其推入堆栈
void lua_getfield(lua_State *L, int index, const char *k);

2. C调用Lua

核心调用函数

void lua_call(lua_State *L, int nargs, int nresults); // 相对lua_pcall来说至少了错误处理函数int lua_pcall(lua_State *L, int nargs, int nresults, int errfunc);
/* lua_State *L：指向 Lua 状态的指针。
int nargs：要传递给 Lua 函数的参数数量。
int nresults：Lua 函数预期返回的结果数量。
int errfunc：错误处理函数在堆栈中的索引。通常为 0，表示没有错误处理函数。0：调用成功。
非零值：调用失败，对应于不同的错误代码，例如 LUA_ERRRUN、LUA_ERRMEM、LUA_ERRERR 等。lua_call和lua_pcall 执行时在堆栈上进行以下操作：
从栈顶开始，依次向下计算 nargs 个元素，这些元素表示传递给函数的参数，会依次弹出这几个参数。
在参数之后的那个元素应该是要调用的函数。
弹出函数本身，调用函数，并期望 nresults 个返回值，压入 nresults 个返回值。
*/

示例

-- Lua
function add(a, b)return a + b
end

// cpp
#include <lua.h>
#include <lualib.h>
#include <lauxlib.h>
#include <stdio.h>int main() {lua_State *L = luaL_newstate();  // 创建新的 Lua 状态luaL_openlibs(L);                // 打开标准库if (luaL_dofile(L, "script.lua")) {  // 加载并执行 Lua 脚本fprintf(stderr, "Failed to load script: %s\n", lua_tostring(L, -1));return 1;}lua_getglobal(L, "add");  // 将全局函数 "add" 压入堆栈if (!lua_isfunction(L, -1)) {fprintf(stderr, "'add' is not a function\n");return 1;}lua_pushnumber(L, 10);  // 压入第一个参数lua_pushnumber(L, 20);  // 压入第二个参数// lua_call(L, 2, 1);  // 调用函数，传递 2 个参数，期望 1 个结果if (lua_pcall(L, 2, 1, 0) != 0) {  // 调用函数，传递 2 个参数，期望 1 个结果fprintf(stderr, "Error calling 'add': %s\n", lua_tostring(L, -1));return 1;}if (lua_isnumber(L, -1)) {double result = lua_tonumber(L, -1);printf("Result: %f\n", result);  // 打印结果} else {fprintf(stderr, "Function 'add' did not return a number\n");}lua_pop(L, 1);  // 从堆栈中移除结果lua_close(L);   // 关闭 Lua 状态return 0;
}

3. Lua调用C

Lua调用C函数时，必须遵守int FunctionName(lua_State *L)类型去定义并实现，其中int返回值表示参数个数。当每个Lua调用C函数时，会自动在内部维护一个私有局部栈，因此我们去参数时直接从1取就可以，且在调用时与结束调用时无需考虑栈的清理问题。

1. C函数注册到Lua（lua_register）

// lua_register 是 Lua C API 中的一个宏，用于将 C 函数注册为 Lua 全局函数/* 这个宏实际上是 lua_pushcfunction 和 lua_setglobal 两个函数的组合：
lua_pushcfunction(L, f)：将 C 函数 f 压入 Lua 堆栈。
lua_setglobal(L, n)：将堆栈顶部的值（即刚刚压入的 C 函数 f）设置为全局变量 n。*/#define lua_register(L, n, f) \(lua_pushcfunction(L, (f)), lua_setglobal(L, (n)))

示例

-- script.lua
local result = add(10, 20)
print("Result of add(10, 20):", result)

// cpp
#include <iostream>
#include <lua.hpp>// C++ 函数
int add(lua_State* L) {int a = luaL_checkinteger(L, 1);int b = luaL_checkinteger(L, 2);lua_pushinteger(L, a + b);return 1;
}// 将 C++ 函数注册到 Lua
void register_functions(lua_State* L) {lua_register(L, "add", add);
}int main() {lua_State* L = luaL_newstate();  // 创建新的 Lua 状态luaL_openlibs(L);                // 打开标准库register_functions(L);  // 注册 C++ 函数if (luaL_dofile(L, "script.lua")) {  // 执行 Lua 脚本std::cerr << "Failed to load script: " << lua_tostring(L, -1) << std::endl;lua_pop(L, 1);  // 从堆栈中移除错误消息}lua_close(L);  // 关闭 Lua 状态return 0;
}

2. 批量注册（luaL_Reg）

// cpp
typedef struct luaL_Reg {const char *name; // 函数的名字lua_CFunction func; // 对应的 C 函数
} luaL_Reg;void luaL_newlib (lua_State *L, const luaL_Reg l[]);
/*这个实际上是 luaL_newlibtable 和 luaL_setfuncs两个函数的组合：void luaL_newlibtable(lua_State *L, const luaL_Reg l[]); 
其中l为指向 luaL_Reg 结构体数组的指针，该数组定义了库中的函数。
luaL_newlibtable 是 Lua C API 提供的一个函数，用于创建一个新的空表，
这个表的大小预分配为注册表中定义的库函数数量。
这在创建一个新的 Lua 库时特别有用，因为它可以预先分配合适的空间以容纳所有的库函数，避免动态扩展表的开销。void luaL_setfuncs(lua_State *L, const luaL_Reg *l, int nup);
l：指向 luaL_Reg 结构体数组的指针，该数组定义了库中的函数。
nup：传递给每个函数的 upvalue 数量。通常为 0。
luaL_setfuncs用于将 C 函数数组注册到一个 Lua 表中。
*/

示例

// cpp
#include <lua.hpp>
#include <iostream>// C 函数：加法
int add(lua_State* L) {int a = luaL_checkinteger(L, 1);int b = luaL_checkinteger(L, 2);lua_pushinteger(L, a + b);return 1;
}// C 函数：减法
int sub(lua_State* L) {int a = luaL_checkinteger(L, 1);int b = luaL_checkinteger(L, 2);lua_pushinteger(L, a - b);return 1;
}// 创建 Lua 库
extern "C" int luaopen_mylib(lua_State* L) {luaL_Reg mylib[] = {{"add", add},{"sub", sub},{NULL, NULL}};luaL_newlib(L, mylib);return 1;
}int main() {lua_State* L = luaL_newstate();luaL_openlibs(L);luaopen_mylib(L);  // 手动打开库（如果需要）if (luaL_dofile(L, "script.lua")) {std::cerr << "Failed to load script: " << lua_tostring(L, -1) << std::endl;lua_pop(L, 1);}lua_close(L);return 0;
}

-- script.lua
local mylib = require("mylib")local result_add = mylib.add(10, 20)
print("Result of add(10, 20):", result_add)local result_sub = mylib.sub(20, 10)
print("Result of sub(20, 10):", result_sub)