LuaWrapper is a library designed to help bridge the gap between Lua and C++. It is designed to be small (a single header file), simple, fast, and typesafe. It has no external dependencies other than the lua library itself, and does not need to be precompiled; the header can simply be dropped into a project and used immediately. It even supports class inheritance to a certain degree. Objects can be created in either Lua or C++, and passed back and forth.

In Lua, the objects are userdata, but through tricky use of metatables, they can be treated almost identically to tables. Each userdata has a __index and __newindex function that maps to a table hidden storage table in the registry.

The main functions of interest are the following:

luaW_is<T>
luaW_to<T>
luaW_check<T>
luaW_push<T>
luaW_register<T>
luaW_extend<T, U>
luaW_hold<T>
luaW_release<T>

The first four functions allow you to manipulate arbitrary classes just like you would the primitive types (e.g. numbers or strings). luaW_is<T> allows you to check if the object is what you think it is, and will take the is-a relationship into account unless the optional strict argument is set. luaW_to<T> will return a pointer of type T to your object (unless it is of the wrong type, in which case it will return NULL).

Registering a class

Run luaW_register to create a table and metatable for your class. This creates a table with the name you specify filled with the function from the table argument in addition to the function new. This is generally for things you think of as static methods in C++. The metatable becomes a metatable for each object if your class. These can be thought of as member functions or methods.

You may also supply constructors and destructors for classes that do not have a default constructor or that require special set up or tear down. You may specify NULL as the constructor, which means that you will not be able to call the new function on your class table. You will need to manually push objects from C++. By default, the default constructor is used to create objects and a simple call to delete is used to destroy them. When using the constructor, you do not have access to the userdata's storage table. If you want to add or adjust values to the storage table you can use the special post constructor metamethod ("__postctor" or LUAW_POSTCTOR_KEY).

By default, LuaWrapper uses the address of C++ object to identify unique objects. In some cases this is not desired, such as in the case of shared_ptrs. Two shared_ptrs may themselves have unique locations in memory but still represent the same object. For cases like that, you may specify an identifier function which is responsible for pushing a key representing your object on to the stack.

Extending a class

To extend a class use the function luaW_extend<T, U>, where T is a class that extends U. All functions in the base class will be available to the derived class (except when they share a function name, in which case the derived class's function wins).

Pointer Ownership

Objects created from within Lua scripts (or that are created through luaW_new) are considered to be owned by Lua. Ownership merely means that when all references to it are removed, the garbage collector will delete the object. An object created in C++ and pushed to Lua is not considered owned unless luaW_hold is run on it. LuaWrapper uses a weak table to cache objects in order to prevent the __gc metamethod from deleting pointers to objects that are still in use. If an object is created in Lua and you do not want it to be owned by Lua, you may call luaW_release on it.

Lua Wrapper Utilities

A second file, called LuaWrapperUtil.hpp includes a number of additional functions that may be useful, which build upon the core LuaWrapper API. The main features are some functions which automatically cast integer types to enum types and templated getters and setters for primitives an pointers to objects. All functions in LuaWrapperUtil.hpp are prefixed with luaU_. Documentation and some examples are provided in the comments of the file.