使用Lua来扩展C++程序的方法

让软件有更高的可塑性，让用户能通过脚本定制行为，这是很多应用走向成熟的关键一步。从 Microsoft Office 的 VBA 到《魔兽世界》里的 Lua，脚本引擎把应用变成了一个平台，终端用户可以在上面自由施展。而嵌入脚本语言，可选方案其实不少：开源的、商业的，甚至自己从头写一个。Ja vaScript、Lua、Python 是当下最主流的几个选择。在 Windows 平台上，常规做法就是把脚本引擎打包成 DLL，然后通过 API 调用它。

接下来，我们就以 Lua 5.2 为例，看看如何把它嵌入到 C++ 代码中。开发环境是 Visual Studio 2005，但思路对后续版本同样适用。动手之前，需要先从 Lua 官网下载必要的组件，包括编译好的 DLL、头文件和导入库。有一点得提醒一下：最终生成的可执行文件必须带上 Lua 的 DLL，否则运行时就会提示缺少文件。文章中提供的测试代码都是用 VS 2005 写的，但向后兼容性很好。

这篇文章不是 Lua 的全面文档，而是通过一个具体实现，带你快速上手。Lua 官网（lua.org）和很多网站都有更深入的资料，这里只是提供一个“起手式”，帮你迈出第一步。

产品开发中，把一个完整应用做成平台，和做一个单体应用，策略完全不同。平台需要给用户提供丰富的插件工具和服务，让他们自己搞定特定的需求。这个思路在微软 Office、Visual Studio、Eclipse、Photoshop 甚至《魔兽世界》的世界里都屡见不鲜。作为一款商业 POS 应用程序，GenPOS 也具备一些类似的平台特性：布局管理器允许用户调整窗口、按钮的位置和文字；字符控制功能可以自动化工作流；丰富的参数化设计能改软件功能；数据库助记符让多语言显示更容易；远程接口可以动态改变参数；甚至还提供接口获取财物的运行状态数据。

不过，总有一些模块是直接由源代码控制的——比如打印收据（虽然显示内容部分来自参数）。这些模块的修改依赖开发团队。简单列举一下现有机制的局限：字符控制功能缺少状态测试和跳转；无法根据当前状态动态修改显示信息。

与其在一个简陋的字符控制功能上打补丁，不如找一种更灵活的方案——不折腾、不伤筋动骨，还能提供更多扩展能力。就像我们之前引入布局管理器让客户自己设计界面一样，我们也希望经销商能通过脚本为他们的客户提供增值服务。更进一步，我们希望开放足够的应用服务访问权限，让经销商甚至最终用户都能修改应用行为。而且，最好选用一个社区活跃、资源丰富的语言。

我们用 Lua 5.2 脚本引擎在 POS 源代码上做了些简单实验，看看往程序里加功能到底有多难。实验结果令人欣慰：我们想呈现的功能基本都能实现，只要对 Lua 脚本引擎做点小调整就能用起来。

使用 Lua 5.2 脚本引擎

Lua 脚本引擎本身是用 C 写的，在 C++ 里使用它也非常直接。网上能找到大量集成 Lua 5.2 的代码片段。Lua 5.2 的 API 跟旧版相比，只有初始化和启动等少数接口有变化，所以老脚本基本不用改，或只做微小调整就能迁移过来。

基本的初始化步骤就两步：

• 调用 lua_newstate() 创建一个新的 Lua 状态机。
• 有需要的话，调用 luaL_openlibs() 加载 Lua 标准库。

初始化之后，要执行一段 Lua 脚本也简单：先用 luaL_loadfile 把脚本加载到引擎，再调用 lua_pcall 执行它。

关键点来了：如果你想在应用里加载 Lua 脚本并调用其中的函数，必须执行被加载的 Lua 程序块（chunk）。刚加载的程序块只是编译后的二进制数据，还没跑起来。只有在 lua_pcall 之后，Lua 里的全局变量和函数才会被创建，在此之前应用是看不见它们的。反过来，应用想给 Lua 提供全局变量或函数，也得先创建它们，然后用 lua_setglobal() 把值注册进 Lua 环境。文件 UtilityFunctions.cpp 里的函数 int LuaSimpleWrapper::TriggerGlobalCall() 就是一个例子——它在 Lua 虚拟栈上动态构造一个函数调用，再用 lua_pcall() 带着参数执行它。

所有 Lua API 都需要一个会话句柄：lua_State* 指针。每次成功调用 lua_newstate() 都会返回一个 lua_State*，失败则返回 NULL。这个结构体标识了特定的 Lua 会话，允许同时运行多个并行会话。当应用调用 Lua 函数，或者 Lua 调用应用提供的服务函数时，这个 lua_State 用来区分是哪个会话。这意味着，应用提供给 Lua 的服务函数必须是完全可重入的，或者通过信号量、临界区来保证线程安全。

使用代码

Visual Studio 2005 工程目录下包含了三个 C++ 文件和一个测试用的 Lua 脚本。主文件 Parser01.cpp 负责加载 Lua 文件并调用某些函数。UtilityFunctions.cpp 实现了 LuaSimpleWrapper 类的方法。InitEnviron.cpp 则包含了我们希望提供给 Lua 环境的函数。

我们设想的方案是这样的：POS 启动时，会指定一个 Lua 脚本文件路径。然后启动一个初始化 Lua 引擎并加载该脚本的线程。Lua 块会一直驻留在内存中，后续 POS 中的事件会派发给 Lua 脚本处理。这个示例程序的测试工具，就是对这种方案的一个初步探索。

在下面的 Lua 函数中，我们使用了 InitEnviron.cpp 里提供的几个函数，专门用来处理非标准 Lua 字符串的“宽字符串”。标准 Lua 字符串是单字节 char 类型的。这些附加函数提供了宽字符串的连接、比较等方法。

下面展示一个 Lua 函数 xxfunc，它接收三个参数并执行一系列操作。这是一个全局函数，应用可以通过 lua_getglobal() 从 Lua 全局字典中检索到它，然后像 lua_pushstring() 把参数压入堆栈，最后调用 lua_pcall() 执行。

-- a sample Lua global function that can be invoked from the application or from Lua
function xxfunc (myMessage, wide1, wide2)
    trace("## xxfunc() called.")
    trace("  "..myMessage)
    trace ("  myFrame index "..myFrame.FrameIndex)
    trace ("  myFrame2 index "..myFrame2.FrameIndex)
    trace ("  myFrame3 index "..myFrame3.FrameIndex)
    
    -- compare two wide char strings that were passed in as arguments
    trace ("  compare wide "..wcscmp(wide1, wide2))
    
    -- generate a wide char string from a Lua string
    local widestring = wcscre("WIDE1")
    trace ("  compare with generated "..wcscmp (wide1, widestring))
    
    -- try out the wcscat and the wcscre functions to generate a string
    traceW (wcscat (wcscre("  concat two "), wcscat(wide1, wide2)))
    
    traceW (wcscat (wcscre("  concat multi "), wide1, wcscre(" "), wide2))
    
    -- tryout wcscat with a non-string argument which should be skipped.
    traceW (wcscat (wcscre("  concat multi "), 2, wcscre(" "), wide2))
  
    local myMemEntry = GetMnemonic (15)
    if (myMessage) then
        if (myMessage.Type == "FRAMEWORK") then
            local myNem = GetMnemonic (20)
        end
    end
end

这个已被加载的 Lua 函数可以由应用程序调用。借助 LuaSimpleWrapper 类的辅助函数 TriggerGlobalCall()，我们可以用一行 C++ 代码来调用它。这个函数需要一个描述性字符串来标识要调用的全局 Lua 函数（函数名、变量或表实例的方法），并跟着实际参数。这种可变参数调用很容易成为运行时错误的根源——因为它涉及三个必须匹配的源：TriggerGlobalCall() 中的描述字符串、提供的实际参数、被调用的 Lua 函数。

if (myLua.TriggerGlobalCall ("xxfunc:s,w,w", "TriggerGlobalCall", L"WIDE1", L"WIDE2") < 0) {
    cout << "%% " << myLua.GetLastErrorString() << endl ;
}

描述字符串用逗号分隔参数类型，每个字母代表一种类型：s 表示 ANSI 字符串，w 表示宽字符串，f 表示浮点型，i 表示整型，p 表示函数指针。逗号只是为了可读性，实际在解析时被忽略。

上面的调用会产生如下输出，由 Lua 函数加工参数后打印出来：

## xxfunc() called.
  TriggerGlobalCall
  myFrame index 0
  myFrame2 index 1
  myFrame3 index 2
  compare wide -1
  compare with generated 0
  concat two WIDE1WIDE2
  concat multi WIDE1 WIDE2
  concat multi  WIDE2
  getTransactionMnemonic() 15

此外，TriggerGlobalCall() 还支持指定一个表里的函数：描述字符串格式为 tablename.key，其中 tablename 是 Lua 全局的表名，key 是访问函数的键值。

// specify a function to be invoked by the OnEvent() handler
// specify a different event type which is not in the Lua script
if (myLua.TriggerGlobalCall ("myFrame2.OnEvent:s,f", "EVENT_TYPE_J2", SimpleFunc) < 0) {
    cout << "%% " << myLua.GetLastErrorString() << endl;
}

将C/C++函数导出到Lua引擎中

要在 Lua 脚本里使用 C/C++ 辅助函数，应用程序需要提供函数体，并用合适的 Lua API 把它注册到 Lua 环境中。基本流程是：将若干值压入 Lua 虚拟堆栈，然后调用 lua_setglobal() 将其设置为全局变量。

lua_pushcclosure (lua, concatMultiWideStrings, 0);
lua_setglobal (lua, "wcscat");

Lua 支持闭包。当 Lua 脚本调用应用函数时，闭包允许应用向该函数传递一些额外的值（上值）。这些值可以被函数更新——比如用一个计数器来生成唯一 ID。在 LuaSimpleWrapper::InitLuaEnvironment() 方法中，就有一个为 Lua 提供 CreateFrame() 函数的例子，使用了闭包来存储帧索引和对象计数：

// CreateFrame() function that will create a frame with an index
lua_pushnumber(m_luaState, 0);                 // frameindex, count of frames for this Lua state object, init to zero
lua_pushnumber(m_luaState, m_MyObjectCount);   // objectindex, which Lua state object am I?

// create the C closure with the above two arguments
lua_pushcclosure (m_luaState, ParserLuaCreateGlobalFrame, 2);
lua_setglobal (m_luaState, "CreateFrame");

要导出的 C++ 函数原型必须符合 static int func(lua_State *L) 的形式。下面这个 concatMultiWideStrings 函数演示了如何从 Lua 虚拟栈读取参数并返回结果。它利用 lua_gettop() 获取参数个数，用 lua_type() 检查类型，跳过非字符串类型的参数。

注意，如果我们在只需要字符串类型的地方传入了其他类型，Lua 会尝试自动转换——但默认转换的结果是单字节 char 字符串，而不是我们期望的双字节宽字符串，所以必须显式处理。

// concatenate multiple wide strings
//  const wchar_t *wcscat(wchar_t *wcharSt1, const wchar_t *wcharSt2, const wchar_t *wcharSt3, ...)
static int concatMultiWideStrings (lua_State *lua)
{
    int  nPushCount = 0;
    int  nArgIndex = 1;
    int argc = lua_gettop(lua);
    wchar_t  tempBuffer[2048];
  
    if (argc > 0) {
        wchar_t    *pWideString = &tempBuffer[0];
        size_t      iLen = 1;
  
        while (nArgIndex <= argc) {
            if (lua_type(lua, nArgIndex) == LUA_TSTRING) {
                const wchar_t *msgX = (wchar_t *) lua_tostring (lua, nArgIndex);
                while (*msgX) {*pWideString++ = *msgX++; iLen++; }
            }
            nArgIndex++;
        }
        *pWideString = 0;  // final zero terminator
        lua_pushlstring (lua, (char *)(&tempBuffer), iLen * sizeof(wchar_t));
        nPushCount++;
    }
  
    return nPushCount;
}

关注点

这个测试工具的第一个版本非常简陋——只是加载一个简单 Lua 脚本，然后输出一行 "Hello World"。但随着对 Lua 嵌入潜力的深入探索，脚本和测试工具变得越来越复杂，很快就发现需要一个能打印 Lua 虚拟栈全貌的函数，才能搞懂引擎和应用之间到底在怎么通信。有好几次，程序突然崩掉，不得不单步调试 C++ 代码，同时借助栈内容输出函数来还原现场，才找到问题并修复。

Lua 的动态特性——跟 Ja vaScript 这类松散类型语言一样——既能写出很精彩的代码，也能带来难以调试的坑。核心难点在于同时使用两种语言，而 Visual Studio 又缺少对 Lua 的原生调试支持。

在实现 LuaSimpleWrapper::TriggerGlobalCall() 时，我们在 Visual Studio 调试器里遇到过测试用例导致 Lua 脚本引擎弹 Windows 错误对话框，甚至要求关闭应用程序。分析下来，是错误发生时某些值被压入 Lua 虚拟栈但未被正确处理。解决方案很简单：一旦发现错误，就用 lua_settop(m_luaState, 0) 清理栈，然后再返回。下面这段代码演示了如何检查全局变量是否存在，如果不存在或不是表，就清栈并返回错误：

lua_getglobal (m_luaState, globalName);
if (lua_type(m_luaState, lua_gettop(m_luaState)) == LUA_TNIL) {
    // if the global variable does not exist then we will bail out with an error.
    strcpy_s (m_lastLuaError, sizeof(m_lastLuaError), "Global variable not found: ");
    strcat_s (m_lastLuaError, sizeof(m_lastLuaError), globalName);
    m_lastState = LuaDescripParse;
    // error so we will just clear the Lua virtual stack and then return
    // if we do not clear the Lua stack, we lea ve garbage that will cause
    // problems with later function calls from the application.
    // we do this rather than use lua_error() because this function is called
    // from the application and not through Lua.
    lua_settop (m_luaState, 0);
    return -1;
}