LuaWrappers.hpp File Reference

#include <algorithm>
#include <string>
#include <boost/bind.hpp>
#include <Diluculum/CppObject.hpp>
#include <Diluculum/LuaExceptions.hpp>
#include <Diluculum/LuaState.hpp>
#include <Diluculum/LuaUtils.hpp>

Include dependency graph for LuaWrappers.hpp:

Go to the source code of this file.

Classes

class Diluculum::Impl::ClassTableFiller

Namespaces

namespace Diluculum

Everything in Diluculum is declared in this namespace.

namespace Diluculum::Impl

Implementation details of Diluculum.

Defines

#define DILUCULUM_WRAPPER_FUNCTION(FUNC)   Diluculum__ ## FUNC ## __Wrapper_Function

#define DILUCULUM_WRAP_FUNCTION(FUNC)

#define DILUCULUM_CLASS_TABLE(CLASS)   Diluculum__Class_Table__ ## CLASS

#define DILUCULUM_BEGIN_CLASS(CLASS)

#define DILUCULUM_METHOD_WRAPPER(CLASS, METHOD)   Diluculum__ ## CLASS ## __ ## METHOD ## __Method_Wrapper_Function

#define DILUCULUM_CLASS_METHOD(CLASS, METHOD)

#define DILUCULUM_END_CLASS(CLASS)

#define DILUCULUM_REGISTER_CLASS(LUA_VARIABLE, CLASS)   Diluculum_Register_Class__ ## CLASS (LUA_VARIABLE);

#define DILUCULUM_REGISTER_OBJECT(LUA_VARIABLE, CLASS, OBJECT)

#define DILUCULUM_BEGIN_MODULE(MODNAME)

#define DILUCULUM_MODULE_ADD_CLASS(CLASS, LUACLASS)   DILUCULUM_REGISTER_CLASS(theModule[LUACLASS], CLASS);

#define DILUCULUM_MODULE_ADD_FUNCTION(CFUNC, LUAFUNC)   theModule[LUAFUNC] = CFUNC;

#define DILUCULUM_END_MODULE()

Functions

void Diluculum::Impl::ReportErrorFromCFunction (lua_State *ls, const ::std::string &what)

Define Documentation

#define DILUCULUM_BEGIN_CLASS ( CLASS )

Starts a block of class wrapping macro calls. This must be followed by calls to DILUCULUM_CLASS_METHOD() for each method to be exported to Lua and a final call to DILUCULUM_END_CLASS().

Parameters:

CLASS

The class being exported.

Definition at line 164 of file LuaWrappers.hpp.

#define DILUCULUM_BEGIN_MODULE ( MODNAME )

Value:

extern "C" int luaopen_ ## MODNAME (lua_State *luaState) \
{                                                        \
   using Diluculum::LuaState;                            \
   using Diluculum::LuaVariable;                         \
   using Diluculum::EmptyLuaValueMap;                    \
   LuaState ls (luaState);                               \
                                                         \
   ls[#MODNAME] = EmptyLuaValueMap;                      \
   LuaVariable theModule = ls[#MODNAME];

Starts a block declaring a dynamically loadable module, that is, a module that is expected to be compiled as a shared library. The block must be closed by a call to DILUCULUM_END_MODULE() and contain some calls to macros like DILUCULUM_MODULE_ADD_CLASS() and DILUCULUM_MODULE_ADD_FUNCTION() in its body.

For those who know the way things happen in Lua, this block will provide a luaopen_MyModule() function, which initializes the module when loaded.

Parameters:

MODNAME The module name. This is how the module will be called in Lua. Also, the dynamic library to which the model will be compiled should be named like this (plus an extension like .so or .dll). Well, actually the rules for naming the module file are more complex than this. Check the Lua manual for the dirty details.

Definition at line 406 of file LuaWrappers.hpp.

#define DILUCULUM_CLASS_METHOD	(	CLASS,
		METHOD		)

Exports a given class' method. This macro must be called between calls to DILUCULUM_BEGIN_CLASS() and DILUCULUM_END_CLASS().

Parameters:

	CLASS	The class whose method is being exported.
	METHOD	The method being exported.

Definition at line 246 of file LuaWrappers.hpp.

#define DILUCULUM_CLASS_TABLE ( CLASS ) Diluculum__Class_Table__ ## CLASS

Returns the name of the table that represent the class CLASS.

Note:: This is used internally. Users can ignore this macro.

Definition at line 154 of file LuaWrappers.hpp.

#define DILUCULUM_END_CLASS ( CLASS )

Value:

\
/* The function used to register the class in a 'LuaState' */                 \
void Diluculum_Register_Class__ ## CLASS (Diluculum::LuaVariable className)   \
{                                                                             \
   Diluculum::LuaState ls (className.getState());                             \
                                                                              \
   if (ls["__Diluculum__Class_Metatables"].value().type() == LUA_TNIL)        \
     ls["__Diluculum__Class_Metatables"] = Diluculum::EmptyLuaValueMap;       \
                                                                              \
   DILUCULUM_CLASS_TABLE(CLASS)["classname"] = #CLASS;                        \
                                                                              \
   DILUCULUM_CLASS_TABLE(CLASS)["new"] =                                      \
      Diluculum__ ## CLASS ## __Constructor_Wrapper_Function;                 \
                                                                              \
   DILUCULUM_CLASS_TABLE(CLASS)["delete"] =                                   \
      Diluculum__ ## CLASS ## __Destructor_Wrapper_Function;                  \
                                                                              \
   DILUCULUM_CLASS_TABLE(CLASS)["__gc"] =                                     \
      Diluculum__ ## CLASS ## __Destructor_Wrapper_Function;                  \
                                                                              \
   DILUCULUM_CLASS_TABLE(CLASS)["__index"] = DILUCULUM_CLASS_TABLE(CLASS);    \
                                                                              \
   className = DILUCULUM_CLASS_TABLE(CLASS);                                  \
                                                                              \
   ls["__Diluculum__Class_Metatables"][#CLASS] =                              \
      DILUCULUM_CLASS_TABLE(CLASS);                                           \
}

Ends a block of class wrapping macro calls (which was opened by a call to DILUCULUM_BEGIN_CLASS()).

Parameters:

CLASS

The class being exported.

Definition at line 304 of file LuaWrappers.hpp.

#define DILUCULUM_END_MODULE ( )

Value:

return 1;                   \
}

Closes a block (started by DILUCULUM_BEGIN_MODULE()) that defines a dynamically loadable Lua module.

Bug:: In principle, this function should return one parameter: the table containing the module (this is more or less a convention). The current implementation not only ignores the convention: it also seems to return something invalid (function looks to be returning 1 without anything on the stack).

Definition at line 449 of file LuaWrappers.hpp.

#define DILUCULUM_METHOD_WRAPPER	(	CLASS,
		METHOD		)	Diluculum__ ## CLASS ## __ ## METHOD ## __Method_Wrapper_Function

Returns the name of the function used to wrap a method METHOD of the class CLASS.

Note:: This is used internally. Users can ignore this macro.

Definition at line 236 of file LuaWrappers.hpp.

#define DILUCULUM_MODULE_ADD_CLASS	(	CLASS,
		LUACLASS		)	DILUCULUM_REGISTER_CLASS(theModule[LUACLASS], CLASS);

Adds a class to the module. Must be called between calls to DILUCULUM_BEGIN_MODULE() and DILUCULUM_END_MODULE().

Parameters:

	CLASS	The name of the class being added, as it is known in the C++ side.
	LUACLASS	The name by which the class will be known in the Lua side.

Definition at line 425 of file LuaWrappers.hpp.

#define DILUCULUM_MODULE_ADD_FUNCTION	(	CFUNC,
		LUAFUNC		)	theModule[LUAFUNC] = CFUNC;

Adds a function to the module. Must be called between calls to DILUCULUM_BEGIN_MODULE() and DILUCULUM_END_MODULE().

Parameters:

	CFUNC	The name of the function being added, as it is known in the C++ side.
	LUAFUNC	The name by which the function will be known in the Lua side.

Definition at line 436 of file LuaWrappers.hpp.

#define DILUCULUM_REGISTER_CLASS	(	LUA_VARIABLE,
		CLASS		)	Diluculum_Register_Class__ ## CLASS (LUA_VARIABLE);

Registers a class in a given Diluculum::LuaState. The class must have been previously exported by calls to DILUCULUM_BEGIN_CLASS(), DILUCULUM_END_CLASS() and probably DILUCULUM_CLASS_METHOD().

Parameters:

	LUA_VARIABLE	The `Diluculum::LuaVariable` that will store the class after this call.
	CLASS	The class being registered.

Definition at line 342 of file LuaWrappers.hpp.

#define DILUCULUM_REGISTER_OBJECT	(	LUA_VARIABLE,
		CLASS,
		OBJECT	)

Value:

{                                                                             \
   /* leave the table where 'OBJECT' is to be stored at the stack top */      \
   LUA_VARIABLE.pushLastTable();                                              \
                                                                              \
   /* push the field where the object will be stored */                       \
   Diluculum::PushLuaValue (LUA_VARIABLE.getState(),                          \
                            LUA_VARIABLE.getKeys().back());                   \
                                                                              \
   /* create the userdata, set its metatable */                               \
   void* ud = lua_newuserdata (LUA_VARIABLE.getState(),                       \
                               sizeof(Diluculum::Impl::CppObject));           \
                                                                              \
   Diluculum::Impl::CppObject* cppObj =                                       \
      reinterpret_cast<Diluculum::Impl::CppObject*>(ud);                      \
                                                                              \
   cppObj->ptr = &OBJECT;                                                     \
   cppObj->deleteMe = false;                                                  \
                                                                              \
   lua_getglobal (LUA_VARIABLE.getState(), "__Diluculum__Class_Metatables");  \
   lua_getfield (LUA_VARIABLE.getState(), -1, #CLASS);                        \
   lua_setmetatable (LUA_VARIABLE.getState(), -3);                            \
                                                                              \
   lua_pop (LUA_VARIABLE.getState(), 1); /* pop the table of metatables */    \
                                                                              \
   /* store the userdata */                                                   \
   lua_settable (LUA_VARIABLE.getState(), -3);                                \
}

Registers an object instantiated in C++ into a Lua state. This way, this object's methods can be called from Lua. The registered C++ object will not be destroyed when the corresponding Lua object is garbage-collected. Destroying it is responsibility of the programmer on the C++ side.

Parameters:

	LUA_VARIABLE	The `Diluculum::LuaVariable` where the object will be stored. Notice that a `Diluculum::LuaVariable` contains a reference to a `lua_State*`, so the Lua state in which the object will be stored is passed here, too, albeit indirectly.
	CLASS	The class of the object being registered. This class must have been previously registered in the target Lua state with a call to the `DILUCULUM_REGISTER_CLASS()` macro.
	OBJECT	The object to be registered to the Lua state.

Definition at line 360 of file LuaWrappers.hpp.

#define DILUCULUM_WRAP_FUNCTION ( FUNC )

Creates a lua_CFunction that wraps a function with the signature like the following one:

Diluculum::LuaValueList Func (const Diluculum::LuaValueList& params)

Notice that, thanks to the use of Diluculum::LuaValueLists, the wrapped function can effectively take and return an arbitrary number of values.

Note:: The name of the created wrapper function is a decorated version of the FUNC parameter. The decoration scheme can be quite complicated and is subject to change in future releases of Diluculum, so don't try to use it directly. Use the DILUCULUM_WRAPPER_FUNCTION() macro to obtain it instead.
The proper way to report errors from the function being wrapped is by throwing a Diluculum::LuaError. The created wrapper function will handle these exceptions and "translate" them to a call to lua_error().

See also:: DILUCULUM_WRAPPER_FUNCTION() To find out the name of the created wrapper function.

Parameters:

FUNC

The function to be wrapped.

Definition at line 112 of file LuaWrappers.hpp.

#define DILUCULUM_WRAPPER_FUNCTION ( FUNC ) Diluculum__ ## FUNC ## __Wrapper_Function

Returns the name of the wrapper function that is created by DILUCULUM_WRAP_FUNCTION() for a given function name.

Parameters:

FUNC

The function whose wrapper name is desired.

Definition at line 88 of file LuaWrappers.hpp.


Classes
class	Diluculum::Impl::ClassTableFiller
Namespaces
namespace	Diluculum
	Everything in Diluculum is declared in this namespace.
namespace	Diluculum::Impl
	Implementation details of Diluculum.
Defines
#define	DILUCULUM_WRAPPER_FUNCTION(FUNC) Diluculum__ ## FUNC ## __Wrapper_Function
#define	DILUCULUM_WRAP_FUNCTION(FUNC)
#define	DILUCULUM_CLASS_TABLE(CLASS) Diluculum__Class_Table__ ## CLASS
#define	DILUCULUM_BEGIN_CLASS(CLASS)
#define	DILUCULUM_METHOD_WRAPPER(CLASS, METHOD) Diluculum__ ## CLASS ## __ ## METHOD ## __Method_Wrapper_Function
#define	DILUCULUM_CLASS_METHOD(CLASS, METHOD)
#define	DILUCULUM_END_CLASS(CLASS)
#define	DILUCULUM_REGISTER_CLASS(LUA_VARIABLE, CLASS) Diluculum_Register_Class__ ## CLASS (LUA_VARIABLE);
#define	DILUCULUM_REGISTER_OBJECT(LUA_VARIABLE, CLASS, OBJECT)
#define	DILUCULUM_BEGIN_MODULE(MODNAME)
#define	DILUCULUM_MODULE_ADD_CLASS(CLASS, LUACLASS) DILUCULUM_REGISTER_CLASS(theModule[LUACLASS], CLASS);
#define	DILUCULUM_MODULE_ADD_FUNCTION(CFUNC, LUAFUNC) theModule[LUAFUNC] = CFUNC;
#define	DILUCULUM_END_MODULE()
Functions
void	Diluculum::Impl::ReportErrorFromCFunction (lua_State *ls, const ::std::string &what)