CoronaLua.h

GetCoronaThread()

lua_State* CoronaLuaGetCoronaThread( lua_State *coroutine )

Gives you the main Lua state used by Corona given the Lua state corresponding to a coroutine. Returns NULL if the coroutine is not a coroutine that belongs to Corona's main Lua state. If coroutine happens to be Corona's main Lua state, then it returns coroutine.

NOTE: Lua uses the word 'thread' to mean coroutine, e.g. a cooperative (not pre-emptive) thread.

New()

lua_State* CoronaLuaNew()

Creates a new lua_State context. Typically, you just use the lua_State from CoronaRuntime.

Delete()

void CoronaLuaDelete( lua_State *L )

Deletes a lua_State created by Corona::Lua::New()

Normalize()

int CoronaLuaNormalize( lua_State *L, int index )

Returns an absolute index location on the Lua stack for the passed index. This is useful if you have negative stack indices, as these are relative to the top of the stack.

GetContext()

void *CoronaLuaGetContext( lua_State *L )

Returns a platform-specific pointer.

InitializeContext()

void CoronaLuaInitializeContext( lua_State *L, void *context, const char *metatableName )

Initializes a platform-specific pointer. The metatableName argument may be NULL. However, if you want the pointer to be freed, you must specify a valid metatable contain a __gc method which gives you a way to finalize the pointer.

NewRef()

CoronaLuaRef CoronaLuaNewRef( lua_State *L, int index )

Returns a new CoronaLuaRef object which holds a reference to the Lua object on the Lua stack at index. You can use this to store and access Lua objects from native code.

DeleteRef()

void CoronaLuaDeleteRef( lua_State *L, CoronaLuaRef ref )

Deletes a CoronaLuaRef reference, and frees the referene to the underlying Lua object.

EqualRef()

int CoronaLuaEqualRef( lua_State *L, CoronaLuaRef ref, int index )

Returns 1 if the Lua value represented by ref is equal to the value at index following the semantices of the Lua == operator (that is, may call metamethods). Otherwise returns 0. Also returns 0 if index is non valid.

NewEvent()

void CoronaLuaNewEvent( lua_State *L, const char *eventName )

Creates a Lua table with the name property set to eventName and pushes it to the top of the Lua stack.

DispatchEvent()

void CoronaLuaDispatchEvent( lua_State *L, CoronaLuaRef listenerRef, int nresults )

Invokes the listener corresponding to listenerRef passing the value at the top of the stack as the Corona event table. You should use CoronaLuaNewEvent() to create this event. This function pops the value from the top of the stack.

IsListener()

bool CoronaLuaIsListener( lua_State *L, int index, const char *eventName )

Returns whether the function at index is a Corona listener.

PushRuntime()

void CoronaLuaPushRuntime( lua_State *L )

Pushes the global Runtime object on the stack.

RuntimeDispatchEvent()

void CoronaLuaRuntimeDispatchEvent( lua_State *L, int index )

Invokes the equivalent of Runtime:dispatchEvent( event ) with the event object at index. The object at index must be a Lua table with the name property set to the event type.

Gotcha: The event object at index is left on the stack.

NOTE: This is available starting in build 843

NewGCMetatable()

void CoronaLuaNewGCMetatable( lua_State* L, const char name[], lua_CFunction __gc1 )

Creates a metatable called name with a finalizer function __gc1

NewMetatable()

void CoronaLuaNewMetatable( lua_State* L, const char name[], const luaL_Reg vtable[] )

Creates a metatable called name with the functions in vtable

InitializeGCMetatable()

void CoronaLuaInitializeGCMetatable( lua_State* L, const char name[], lua_CFunction __gc1 )

Same as CoronaLuaNewGCMetatable(), but doesn't leave anything on stack.

InitializeMetatable()

void CoronaLuaInitializeMetatable( lua_State* L, const char name[], const luaL_Reg vtable[] )

Same as CoronaLuaNewMetatable(), but doesn't leave anything on stack.

PushUserdata()

void CoronaLuaPushUserdata( lua_State* L, void* ud, const char metatableName[] )

Wraps the pointer ud in a Lua userdata object and sets the userdata's metatable to metatableName.

NOTE: Assumes there will be only one Lua instance of the userdata. In other words, when the GC collects the ud, ud will get deleted!

ToUserdata()

void* CoronaLuaToUserdata( lua_State* L, int index )

Returns the pointer wrapped by the Lua userdata at index

CheckUserdata()

void* CoronaLuaCheckUserdata( lua_State* L, int index, const char metatableName[] )

Same as CoronaLuaToUserdata() except it returns NULL if the userdata at index doesn't have a metatable that matches metatableName.

RegisterModuleLoader()

void CoronaLuaRegisterModuleLoader( lua_State *L, const char *name, lua_CFunction loader, int nupvalues = 0 )

Registers loader corresponding to module name. You can pass state variables to the loader by pushing those values on to the Lua stack and specifying the number of values via nupvalues.

Similar to lua_pushcclosure(), this function will pop nupvalues from the stack. Note: Prior to build 869, these values were not popped.

RegisterModuleLoaders()

void CoronaLuaRegisterModuleLoaders( lua_State *L, const luaL_Reg moduleLoaders[], int nupvalues = 0 )

Same as CoronaLuaRegisterModuleLoader() but you register multiple name/loader pairs.

CoronaLuaInsertPackageLoader()

void CoronaLuaInsertPackageLoader( lua_State *L, lua_CFunction loader, int index )

Performs the equivalent of the following Lua code:

table.insert( package.loaders, index, loader )

GetErrorHandler()

lua_CFunction CoronaLuaGetErrorHandler()

Returns the error handler invoked on a Lua exception. By default, this is NULL, which means an internal Corona handler is called.

SetErrorHandler()

void CoronaLuaSetErrorHandler( lua_CFunction newValue )

Sets the error handler invoked on a Lua exception. By default, an internal Corona handler is called.

DoCall()

int CoronaLuaDoCall( lua_State* L, int narg, int nresults )

Does a protected call (see lua_pcall) on a function that's on the stack. narg includes the total function and the number of arguments passed to it.

DoBuffer()

int CoronaLuaDoBuffer( lua_State *L, lua_CFunction loader, lua_CFunction pushargs )

DoFile()

int CoronaLuaDoFile( lua_State *L, const char* file, int narg, bool clear )

Same as DoCall() except the function is the chunk contained in file.