ezEngine  Milestone 7
ezLuaWrapper Class Reference

#include <LuaWrapper.h>

Classes

struct  ezScriptStates
 

Public Member Functions

Setting up the Script
 ezLuaWrapper ()
 Generates a NEW Lua-Script, which is empty.
 
 ezLuaWrapper (lua_State *s)
 Takes an EXISTING Lua-Script and allows to get easier access to it.
 
 ~ezLuaWrapper ()
 Destroys the Lua-Script, if it was created, but leaves it intact, if this instance did not generate the Lua-Script.
 
void Clear ()
 Clears the script to be empty.
 
lua_State * GetLuaState ()
 
ezResult ExecuteString (const char *szString, const char *szDebugChunkName="chunk", ezLogInterface *pLogInterface=nullptr) const
 
Managing Tables
ezResult OpenTable (const char *szTable)
 
ezResult OpenTableFromParameter (ezUInt32 iFunctionParameter)
 Opens the Table n, that was passed to a C-Function on its Parameter-Stack.
 
void CloseTable ()
 Closes the table that was opened last.
 
void CloseAllTables ()
 Closes all open Tables.
 
void PushTable (const char *szTableName, bool bGlobalTable)
 Pushes an existing table onto Lua's stack. Either one that is in local scope, or a global table.
 
Variable and Function Checks
bool IsVariableAvailable (const char *szVariable) const
 Checks, whether the Variable with the given Name exists.
 
bool IsFunctionAvailable (const char *szFunction) const
 Checks, whether the Function with the given Name exists.
 
Reading Variables
int GetIntVariable (const char *szName, ezInt32 iDefault=0) const
 Returns the Value of the Variable with the given name, or the default-value, if it does not exist.
 
bool GetBoolVariable (const char *szName, bool bDefault=false) const
 Returns the Value of the Variable with the given name, or the default-value, if it does not exist.
 
float GetFloatVariable (const char *szName, float fDefault=0.0f) const
 Returns the Value of the Variable with the given name, or the default-value, if it does not exist.
 
const char * GetStringVariable (const char *szName, const char *szDefault="") const
 Returns the Value of the Variable with the given name, or the default-value, if it does not exist.
 
Modifying Variables
void SetVariableNil (const char *szName) const
 Sets the Variable with the given name (in scope) to nil.
 
void SetVariable (const char *szName, ezInt32 iValue) const
 Sets the Variable with the given name (in scope) with the given value.
 
void SetVariable (const char *szName, bool bValue) const
 Sets the Variable with the given name (in scope) with the given value.
 
void SetVariable (const char *szName, float fValue) const
 Sets the Variable with the given name (in scope) with the given value.
 
void SetVariable (const char *szName, const char *szValue) const
 Sets the Variable with the given name (in scope) with the given value.
 
void SetVariable (const char *szName, const char *szValue, ezUInt32 len) const
 Sets the Variable with the given name (in scope) with the given value.
 
Calling Functions
void RegisterCFunction (const char *szFunctionName, lua_CFunction pFunction, void *pLightUserData=nullptr) const
 Registers a C-Function to the Script under a certain Name.
 
bool PrepareFunctionCall (const char *szFunctionName)
 Prepares a function to be called. After that the parameters can be pushed. Returns false if no function with the given name exists in the scope.
 
ezResult CallPreparedFunction (ezUInt32 iExpectedReturnValues=0, ezLogInterface *pLogInterface=nullptr)
 
void DiscardReturnValues ()
 Call this after you called a prepared Lua-function, that returned some values. If zero values were returned, this function is optional.
 
ezInt32 ReturnToScript () const
 
Calling Function with Parameters
void PushParameter (ezInt32 iParam)
 
void PushParameter (bool bParam)
 
void PushParameter (float fParam)
 
void PushParameter (const char *szParam)
 
void PushParameter (const char *szParam, ezUInt32 length)
 
void PushParameterNil ()
 
Inspecting Function Parameters
void * GetFunctionLightUserData () const
 Returns the currently executed function light user data that was passed to RegisterCFunction.
 
ezUInt32 GetNumberOfFunctionParameters () const
 Returns how many Parameters were passed to the called C-Function.
 
bool IsParameterInt (ezUInt32 iParameter) const
 Checks the nth Parameter passed to a C-Function for its type.
 
bool IsParameterBool (ezUInt32 iParameter) const
 Checks the nth Parameter passed to a C-Function for its type.
 
bool IsParameterFloat (ezUInt32 iParameter) const
 Checks the nth Parameter passed to a C-Function for its type.
 
bool IsParameterTable (ezUInt32 iParameter) const
 Checks the nth Parameter passed to a C-Function for its type.
 
bool IsParameterString (ezUInt32 iParameter) const
 Checks the nth Parameter passed to a C-Function for its type.
 
bool IsParameterNil (ezUInt32 iParameter) const
 Checks the nth Parameter passed to a C-Function for its type.
 
int GetIntParameter (ezUInt32 iParameter) const
 Returns the Value of the nth Parameter.
 
bool GetBoolParameter (ezUInt32 iParameter) const
 Returns the Value of the nth Parameter.
 
float GetFloatParameter (ezUInt32 iParameter) const
 Returns the Value of the nth Parameter.
 
const char * GetStringParameter (ezUInt32 iParameter) const
 Returns the Value of the nth Parameter.
 
Function Return Values
void PushReturnValue (ezInt32 iParam)
 Pushes a value as a return value for a called C-Function.
 
void PushReturnValue (bool bParam)
 Pushes a value as a return value for a called C-Function.
 
void PushReturnValue (float fParam)
 Pushes a value as a return value for a called C-Function.
 
void PushReturnValue (const char *szParam)
 Pushes a value as a return value for a called C-Function.
 
void PushReturnValue (const char *szParam, ezUInt32 length)
 Pushes a value as a return value for a called C-Function.
 
void PushReturnValueNil ()
 Pushes a value as a return value for a called C-Function.
 
bool IsReturnValueInt (ezUInt32 iReturnValue) const
 Checks the nth return-value passed to a C-Function for its type.
 
bool IsReturnValueBool (ezUInt32 iReturnValue) const
 Checks the nth return-value passed to a C-Function for its type.
 
bool IsReturnValueFloat (ezUInt32 iReturnValue) const
 Checks the nth return-value passed to a C-Function for its type.
 
bool IsReturnValueString (ezUInt32 iReturnValue) const
 Checks the nth return-value passed to a C-Function for its type.
 
bool IsReturnValueNil (ezUInt32 iReturnValue) const
 Checks the nth return-value passed to a C-Function for its type.
 
int GetIntReturnValue (ezUInt32 iReturnValue) const
 Returns the value of the nth return-value.
 
bool GetBoolReturnValue (ezUInt32 iReturnValue) const
 Returns the value of the nth return-value.
 
float GetFloatReturnValue (ezUInt32 iReturnValue) const
 Returns the value of the nth return-value.
 
const char * GetStringReturnValue (ezUInt32 iReturnValue) const
 Returns the value of the nth return-value.
 

Static Private Member Functions

static void * lua_allocator (void *ud, void *ptr, size_t osize, size_t nsize)
 An Allocator for Lua. Optimizes (in theory) the allocations. More...
 

Private Attributes

lua_State * m_pState
 The Lua-State for the Script.
 
bool m_bReleaseOnExit
 If this script created the Lua-State, it also releases it on exit.
 
ezScriptStates m_States
 

Static Private Attributes

static const ezInt32 s_ParamOffset = 1
 

Detailed Description

This class encapsulates ONE Lua-Script.

It makes it easier to interact with the script, to get data out of it (e.g. for configuration files), to register C-functions to it and to call script-functions. It is possible to load more than one Lua-File into one Lua-Script, one can dynamically generate code and pass it as a string to the script. It ALSO allows to construct the ezLuaWrapper with a working lua_State-Pointer and thus only simplify interaction with an already existing script (for example, when a C-Function is called in a Script, it passes its lua_State to that Function).

Note
Lua starts counting at 1, not at 0. However ezLuaWrapper does NOT do this, but uses the C++ convention instead! That means, when you query the first parameter or return-value passed to your function, you need to query for value 0, not for value 1.

Member Function Documentation

ezResult ezLuaWrapper::CallPreparedFunction ( ezUInt32  iExpectedReturnValues = 0,
ezLogInterface pLogInterface = nullptr 
)

Calls the prepared Function with the previously pushed Parameters.

You must pass in how many return values you expect from this function and the function must stick to that, otherwise an assert will trigger. After you are finished inspecting the return values, you need to call DiscardReturnValues() to clean them up.

Returns EZ_FAILURE if anything went wrong during function execution. Reports errors via pLogInterface.

ezResult ezLuaWrapper::ExecuteString ( const char *  szString,
const char *  szDebugChunkName = "chunk",
ezLogInterface pLogInterface = nullptr 
) const

Executes a string containing Lua-Code.

Parameters
szStringThe lua code to execute.
szDebugChunkNameAn optional name for the lua code, to ease debugging when errors occur.
pLogInterfaceAn optional log interface where error messages are written to. If nullptr is passed in, error messages are written to the global log.
lua_State * ezLuaWrapper::GetLuaState ( )
inline

Returns the lua state for custom access.

It is not recommended to modify the lua state directly, however for certain functionality that the wrapper does not implement this might be necessary. Make sure to either do all modifications at the start, before using the LuaWrapper on it (as it has some internal state), or to only do actions that will end up in the same stack state as before.

void * ezLuaWrapper::lua_allocator ( void *  ud,
void *  ptr,
size_t  osize,
size_t  nsize 
)
staticprivate

An Allocator for Lua. Optimizes (in theory) the allocations.

Todo:
Create optimized allocator.
ezResult ezLuaWrapper::OpenTable ( const char *  szTable)

Opens the Lua-Table with the given name for reading and writing.

All following calls to functions that read/write variables are working in the scope of the last opened table. The table to open needs to be in scope itself. Returns EZ_FAILURE, if it's not possible (the table does not exist in this scope).

void ezLuaWrapper::PushParameter ( ezInt32  iParam)
inline

Pushes a parameter on the stack to be passed to the next function called. Do this after PrepareFunctionCall() and before CallPreparedFunction().

void ezLuaWrapper::PushParameter ( bool  bParam)
inline

Pushes a parameter on the stack to be passed to the next function called. Do this after PrepareFunctionCall() and before CallPreparedFunction().

void ezLuaWrapper::PushParameter ( float  fParam)
inline

Pushes a parameter on the stack to be passed to the next function called. Do this after PrepareFunctionCall() and before CallPreparedFunction().

void ezLuaWrapper::PushParameter ( const char *  szParam)
inline

Pushes a parameter on the stack to be passed to the next function called. Do this after PrepareFunctionCall() and before CallPreparedFunction().

void ezLuaWrapper::PushParameter ( const char *  szParam,
ezUInt32  length 
)
inline

Pushes a parameter on the stack to be passed to the next function called. Do this after PrepareFunctionCall() and before CallPreparedFunction().

void ezLuaWrapper::PushParameterNil ( )
inline

Pushes a nil parameter on the stack to be passed to the next function called. Do this after PrepareFunctionCall() and before CallPreparedFunction().

ezInt32 ezLuaWrapper::ReturnToScript ( ) const
inline

Return the value of this function in a called C-Function.

A typical C function should look like this:

int CFunction(lua_State* state)
{
ezLuaWrapper s(state);
.. do something ..
return s.ReturnToScript();
}

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