Nuria::LuaRuntime Class Reference

Runtime for the LUA scripting language. More...

#include <luaruntime.hpp>

Inheritance diagram for Nuria::LuaRuntime:

Public Types
enum	LuaLib {   Base = 0x01, Math = 0x02, String = 0x04, Table = 0x08,   InputOutput = 0x10, OperatinSystem = 0x20, Package = 0x40, Debug = 0x80,   Bit = 0x100, Jit = 0x200, Ffi = 0x400, AllLibraries }
typedef std::function< bool(Ownership, void *, MetaObject *) >	ObjectHandler
enum	Ownership { OwnedByLua = 0x1, OwnedByCpp = 0x2 }

Public Member Functions
	LuaRuntime (LuaLibs libraries, QObject *parent=0)
	~LuaRuntime () override
LuaValues	allResults () const
void	collectGarbage ()
bool	execute (const QByteArray &script)
bool	executeStream (QIODevice *device)
LuaValue	global (const QString &name)
bool	hasGlobal (const QString &name)
LuaValue	lastResult () const
void *	luaState ()
Ownership	objectOwnership (void *object)
void	registerMetaObject (MetaObject *metaObject, const QByteArray &prefix=QByteArray())
void	setGlobal (const QString &name, const QVariant &value)
void	setGlobal (const QString &name, const LuaValue &value)
void	setObjectHandler (ObjectHandler handler, OwnershipFlags flags=OwnershipFlags(OwnedByLua|OwnedByCpp))
void	setObjectOwnership (void *object, Ownership ownership)

Friends
class	Internal::Delegate
class	LuaBuiltinFunctions
class	LuaCallbackTrampoline
class	LuaMetaObject
class	LuaMetaObjectWrapper
class	LuaObject

Detailed Description

Runtime for the LUA scripting language.

This class is a C++/Qt wrapper for LuaJit, a JITing implementation of the LUA VM. You can use it if you need scripting support in your application easily.

Usage

It's really easy to get started! First, instantiate a LuaRuntime. You can then export specific C++ classes to LUA using registerMetaObject() or run scripts using execute() or executeStream().

Currently, the only exposed API to Lua provided by LuaRuntime is "Nuria.connect(object, slotName, function)", which works like QObject::connect().

Garbage collection and ownership

Garbage collection is taken care of by Lua itself. What's more important is ownership of instances of C++ classes and structures. Generally, a class instance is owned by the world it was created in (So C++ or LUA) and thus may or may not be subject to garbage collection. This means in plain words:

• A object created inside LUA belongs to LUA and is subject to the GC.
• A object created outside of LUA is not subject to the GC.

You can control this more fine-grained if you want to though. LuaObject::fromStructure has a ownership argument for this. To change ownership later, you can use setObjectOwnership() and objectOwnership() to set or get the current ownership respectively. You can also register a handler using setObjectHandler() to install a runtime-wide function which is called whenever LUA collected a C++ object.

Class interoperability

Using Nuria::MetaObject, it's possible to use C++ classes inside Lua. You can pass C++ objects (That is, a void pointer with a MetaObject) to Lua or expose MetaObjects directly to Lua, which enable Lua scripts to construct instances at will.

Member Typedef Documentation

typedef std::function< bool(Ownership, void *, MetaObject *) > Nuria::LuaRuntime::ObjectHandler

Handler method for to-be-collected objects. This method is called when LUA is about to collect an object. The prototype looks as follows:

bool (Ownership ownership, void *object, MetaObject *metaObject);

ownership indicates who owns the object, object is the affected object with its metaObject. If ownership is OwnedByLua, the object will be destroyed if the handler returns true. In any other case object is not touched.

Member Enumeration Documentation

enum Nuria::LuaRuntime::LuaLib

Built-in LUA libraries.

Enumerator
AllLibraries	All LUA libraries. This is the default.

enum Nuria::LuaRuntime::Ownership

Ownership of objects inside LUA.

Enumerator
OwnedByLua	The object is owned by LUA and thus is subject to its garbage collection.
OwnedByCpp	The object is owned by C++ and thus is not garbage collected by LUA, even if it's no longer used in the runtime anywhere.

Constructor & Destructor Documentation

Nuria::LuaRuntime::LuaRuntime ( LuaLibs  libraries, QObject *  parent = 0  )

explicit

Constructor. Loads all libraries into the environment (These are provided by the internal Lua implementation).

Nuria::LuaRuntime::~LuaRuntime ( )

override

Destructor.

Member Function Documentation

LuaValues Nuria::LuaRuntime::allResults

(

)

const

Like lastResult(), but instead returns all results of the last execute() call. If no results were returned from the LUA script, an empty list is returned.

void Nuria::LuaRuntime::collectGarbage

(

)

Instructs the LUA runtime to run the garbage collector, which will free memory no longer used. If you're doing this to not only destroy structures but also really free their memory now, you should call this method twice as the LUA garbage collector will only destroy instances at first.

bool Nuria::LuaRuntime::execute

(

const QByteArray &

script

)

Executes script in the runtime. Returns true on success. Returns false if an error occured, like a syntax error.

If the call failed, lastResult() will return a string containing a human-readable error message.

After script has returned, lastResult() will return the result of it. If there were multiple results, then lastResult() will return a QVariantList containing all results.

See also

lastResult

bool Nuria::LuaRuntime::executeStream

(

QIODevice *

device

)

Reads all available bytes from device and executes it as script. device must be open and readable. Result is the same as execute().

See also

lastResult execute

LuaValue Nuria::LuaRuntime::global

(

const QString &

name

)

Returns global variable name.

bool Nuria::LuaRuntime::hasGlobal

(

const QString &

name

)

Returns true if there's a global variable called name.

LuaValue Nuria::LuaRuntime::lastResult

(

)

const

Returns the result of the last call to execute(). If multiple results were returned only the first one is returend.

See also

allResults

void* Nuria::LuaRuntime::luaState

(

)

Returns the internal LUA runtime. The returned pointer is of type lua_State*. To make use of it, you'll need to #include "lua.hpp".

Warning

The Lua integration doesn't expect sudden changes to the environment. Be careful with this function.

Ownership Nuria::LuaRuntime::objectOwnership

(

void *

object

)

Returns the ownership of object. If object does not exist, OwnedByLua is returned.

void Nuria::LuaRuntime::registerMetaObject	(	MetaObject *	metaObject,
		const QByteArray &	prefix = QByteArray()
	)

Registers metaObject for usage in the runtime. After this, the class can be used in LUA. The type will be stored as userdata inside LUA. Its name will be what MetaObject::className() returns. Namespaces will be interpreted as tables, meaning that the class "Something::Foo::Bar" will end up as "Something.Foo.Bar". prefix is prepended to the class name verbatim. Thus, if you want to put the meta object inside another table, you prefix to end with "::".

Note

Calling this multiple times on the same metaObject is harmless.

void Nuria::LuaRuntime::setGlobal	(	const QString &	name,
		const QVariant &	value
	)

Sets a global variable called name to value.

void Nuria::LuaRuntime::setGlobal	(	const QString &	name,
		const LuaValue &	value
	)

overload

void Nuria::LuaRuntime::setObjectHandler	(	ObjectHandler	handler,
		OwnershipFlags	flags = OwnershipFlags(OwnedByLua|OwnedByCpp)
	)

Installs a object handler called whenever a object is about to be collected by Luas garbage collector. You can control when handler should be called using flags, e.g. to be only notified when an object owned by Lua is collected.

See also

ObjectHandler

void Nuria::LuaRuntime::setObjectOwnership	(	void *	object,
		Ownership	ownership
	)

Changes the ownership of object to ownership. If object is not known to LUA, this function has no effect.

---

The documentation for this class was generated from the following file:

• luaruntime.hpp