OOLua  2.0.1
C++ and Lua binding
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Lua Types in OOLua

OOLua provides three types to help store and interact with Lua types, these are Lua_ref, Lua_function and Table.


The Lua_ref templated class stores a reference using Lua's reference system luaL_ref and luaL_unref, along with a lua_State. The reason this class stores the lua_State is to make it difficult to use the reference with another universe. A reference from the same Lua universe, even if it is from a different lua_State, is valid to be used in the universe.

The class takes ownership of any reference passed either to the two argument constructor or the set_ref function. On going out of scope a valid reference is guaranteed to be released, you may also force a release by passing an instance to swap for which valid returns false.

There are two special values for the reference which Lua provides, both of which OOLua will treat as an invalid reference:

  • LUA_REFNIL luaL_ref return value to indicate it encountered a nil object at the location the ref was asked for
  • LUA_NOREF guaranteed to be different from any reference return by luaL_ref
    Template Parameters
    IDLua type as returned by lua_type
  • Universe: A call to luaL_newstate or lua_newstate creates a Lua universe and a universe is completely independent of any other universe. lua_newthread and coroutine.create, create a lua_State in an already existing universe.
    Term first heard in a Lua mailing list post by Mark Hamburg.

For your convenience there are two predefined typedefs:


Calling a Lua function, from C++ code using OOLua's API, can be achieved using a Lua_function object. This is a state bound caller, and the state in which the callee will be invoked is specified either in the constructor or via the bind_script member function.

To invoke a callee, the OOLUA::Lua_function type uses a call operator. The operator's first parameter must be the callee and it can be specified using one of the following types:

  • std::string A function in the bound state's global table
  • OOLUA::Lua_func_ref A reference to a function
  • int A valid stack index If the callee is identified via a valid stack index, then this index will remain on the stack at same absolute location after the caller has returned.

The call operator is also overloaded to enable the passing of parameters to the callee; the maximum number of parameters is defined by the configurable value "lua_params".

Calling a Lua function

When using the Script class, a Lua_function instance is initialised in the Script's constructor and is made available as a public member using the name call. A Lua_function can also be used directly either by constructing it specifically for the call or reusing a previous instance.

Global function identified by a string name:

void stringFunc_callsFunctionInGlobalScope_returnsTrue()
m_lua->run_chunk("_G['global_name'] = function() end");
OOLUA::Lua_function caller(*m_lua);
CPPUNIT_ASSERT_EQUAL(true , caller("global_name"));

Lua_func_ref from a child state that is called using the Script's public member:

void functionRef_functionRefIsFromAChildState_returnsTrue()
OOLUA::Lua_func_ref func_from_child = create_func_ref_with_child_state();
CPPUNIT_ASSERT_EQUAL(true, m_lua->call(func_from_child) );

Valid stack index that is a function:

void indexFunc_passedFunctionIndex_returnsTrue()
OOLUA::Lua_function caller(*m_lua);
CPPUNIT_ASSERT_EQUAL(true, caller(1));


Table provides a simple typed C++ interface for the Lua unordered and ordered associative container of the same name. Operations which use the Lua stack ensure that the stack is the same on exit as it was on entry, OOLua tries to force a clean stack(OOLua and the Lua stack).

Any value can be retrieved or set from the table via the use of the template member functions set, at or safe_at. If the value asked for is not the correct type located in the position an error can be reported, the type of which depends on Error Reporting and the function which was called. See individual member function documentation for details.

The member function try_at is only defined when exceptions are enabled for the library.

There are two helper functions for creating a OOLUA::Table both of which are named OOLUA::new_table.

void setValue_valueSetInLua_cppSideRepresentationHasChange()
OOLUA::new_table(*m_lua, t);
m_lua->run_chunk("func = function(t) t['a'] = 1; end");
m_lua->call("func", t);
int storedValue(0);
t.at("a", storedValue);