Lua_icxx  1.02 (Aug 2011)
Lua_icxx docs

Lua-icxx (pronounced "*lua'ix*") is a small C++ library that simplifies *embedding* a Lua interpreter in a C++ application. Embedding the Lua interpreter in a C++ application allows it to evaluate Lua expressions, put data in the interpreter's global environment, and run Lua scripts. Conversely, the interpreter can be *extended* via dynamically loaded libraries (DLL files on Windows, SO files on most popular Nix flavors) that define new functions, classes, and constants for scripts to use.

There are many C++ bindings that provide an OO API to *extend* Lua, but there are few OO libraries that do so for *embedding* Lua in C++. For instance you could use SWIG to export some classes and functions of a C++ application to Lua, so that Lua scripts run from the application could make use of those classes and functions. But making the interpreter run those scripts, or run interpreted Lua "chunks", or making it evaluate Lua expressions, requires way too much repetetive work for my liking; calling pcall, checking errors via the stack, making sure I don't remove too few or too many items from stack, bla bla bla, repeat this in every application... Why?

Lua-icxx provides an OO API to the Lua interpreter to make it easy to

  • load Lua extension libraries (such as generated by SWIG or some other C++ binding library),
  • evaluate Lua expressions and scripts,
  • call Lua functions, access data in tables, etc
  • exchange values (numbers, strings) between the interpreter and application
  • use user data types (exported to Lua via SWIG or other C++ binding library),
  • create sandboxes for scripts
  • and more.

The best thing is, Lua-icxx makes simple things simple, replacing many lines of Lua C API calls and error checking code with a couple lines of OO code. No need to worry about the Lua stack. Leave that up to the Lua extension libraries like SWIG, lua-icxx does the front end part.

Lua-icxx is being used by a couple commercial projects and the unit testing is fairly extensive. However, it is still alpha in terms of "completeness":

  • it has only been built on Windows; volunteer needed to do this on Linux!
  • the interface is still fairly young, based one set of projects by one person (author); as others use it, shortcomings will be identified

Contributions from others are not only welcome but encouraged. Even feedback about the API or documentation is useful.

Most important classes:

  • LuaInterpreter: an instance of a Lua interpreter, with its own space for variables etc
  • LuaTempResult: the result of evaluating Lua expressions, getting any data from the interpreter, etc
  • LuaObjRef: reference to a Lua "object" (number, string, function, table, etc)
  • LuaFuncRef: a reference to a Lua object that is a function
  • LuaTableRef: a reference to a Lua object that is a table

Example: 

LuaInterpreter lua;

// print using Lua's print():
LuaFuncRef luaPrint = lua.eval("print");
luaPrint("Hello World!");                

// create a table, "a", containing an object of class Foo, 
// exported to Lua (via SWIG or other), and a method name
lua.doScript("a={b=getFooExported(), c='bar'}");

// get 3 items from Lua, assumed to have been created already:
LuaTempResult res = lua.eval("a, a.b, a['c']"); 
assert(res.ok());
LuaTableRef a      = res[0]; 
LuaClassObjRef udt = res[1];      // assume a.b is user data type
string method      = res[2];      // assume method name
udt.callMethod(method, 1, 2, 3);  // call a.b:bar(1,2,3)

Thanks go to SourceForge.net for hosting this project (http://www.sf.net/projects/lua-icxx).

Enjoy!