LuaCocoa Class Reference

LuaCocoa is the primary class you use to bridge your Lua code with Objective-C (and vice-versa). More...

#import <LuaCocoa.h>

List of all members.

Public Member Functions
(id)	- init
	Initializes a new LuaCocoa instance, complete with a new lua_State.
(id)	- initWithLuaState:assumeOwnership:
	Will initialize a new LuaCococa instance with the lua_State you provide.
(bool)	- loadFrameworkWithBaseName:hintPath:searchHintPathFirst:skipDLopen:
(bool)	- isFrameworkLoaded:
(void)	- collectExhaustivelyWaitUntilDone:
	Forces both the Lua and Objective-C garbage collectors to collect exhaustively.
(NSString *)	- pcallLuaFunction:withSignature:
	Convenience method to pcall functions in Lua.
(NSString *)	- pcallLuaFunction:errorFunction:withSignature:
	Convenience method to pcall functions in Lua and allows an error function to be specified.
Static Public Member Functions
(void)	+ collectExhaustivelyWaitUntilDone:
	Forces the Objective-C garbage collector to collect exhaustively.
Properties
struct lua_State *	luaState
	Returns the lua_State associated with the LuaCocoa instance.
bool	skipDLopen
bool	disableImportFromLua
Private Attributes
bool	ownsLuaState
NSMutableDictionary *	frameworksLoaded

---

Detailed Description

LuaCocoa is the primary class you use to bridge your Lua code with Objective-C (and vice-versa).

LuaCocoa associates a lua_State with Objective-C so you may easily cross between languages. Behind the scenes, LuaCocoa loads dependent frameworks and dylibs, parses XML, and uses the Obj-C runtime to provide core bridging functions.

Definition at line 114 of file LuaCocoa.h.

---

Member Function Documentation

- (void) collectExhaustivelyWaitUntilDone:

(bool)

should_wait_until_done

Forces both the Lua and Objective-C garbage collectors to collect exhaustively.

This will first force Lua to garbage collect exhaustively, and then subsequently force Objective-C's garbage collector to collectExhaustively. Under Objective-C garbage collection, it might be a good idea to call this before closing the lua_State because there is a potential race condition/out-of-order clean-up bug where LuaCocoaProxyObjects might still be pending to be cleaned up after the lua_State is closed. Since they are intimately connected to their lua_States, their access will result in an illegal access of freed memory. This function is safe to call under traditional Obj-C memory management. Lua will still be forced to garbage collect, but the Obj-C collector will be a no-op.

Parameters:

should_wait_until_done

Set to true if you want the function to block until garbage collection is complete.

+ (void) collectExhaustivelyWaitUntilDone:

(bool)

should_wait_until_done

Forces the Objective-C garbage collector to collect exhaustively.

This will tell Objective-C's garbage collector to collectExhaustively. This is a class version, so there is no Lua state to invoke garbage collection on. This function is safe to call under traditional Obj-C memory management.

Parameters:

should_wait_until_done

Set to true if you want the function to block until garbage collection is complete.

See also:

- collectExhaustivelyWaitUntilDone:

- (id) init

Initializes a new LuaCocoa instance, complete with a new lua_State.

When creating a new LuaCocoa instance with this initializer, a new lua_State will be created to go along with it. You should not try to replace the lua_State or directly close the lua_State behind the LuaCocoa object wrapper's back.

- (id) initWithLuaState:		(struct lua_State *)	lua_state
assumeOwnership:		(bool)	should_assume_ownership

Will initialize a new LuaCococa instance with the lua_State you provide.

Parameters:

lua_state	The lua_State you want to bind the LuaCocoa instance to.
should_assume_ownership	If true, LuaCocoa will manage cleanup of the lua_State. If set to false, you are responsible for cleaning up the lua_State. It must not be destroyed until after this instance is destroyed.

- (bool) isFrameworkLoaded:

(NSString *)

base_name

- (bool) loadFrameworkWithBaseName:		(NSString *)	base_name
hintPath:		(NSString *)	hint_path
searchHintPathFirst:		(bool)	search_hint_path_first
skipDLopen:		(bool)	skip_dl_open

- (NSString*) pcallLuaFunction:		(const char *)	lua_function_name
errorFunction:		(lua_CFunction)	error_function
withSignature:		(const char *)	parameter_signature
,			...

Convenience method to pcall functions in Lua and allows an error function to be specified.

This convenience method adopts the techniques described in Programming in Lua's call_va function to make calling arbitrary Lua functions a little easier.

Warning:

Parameter signatures are subject to change in future releases to be more consistent with Obj-C. Sorry. FIXME: Unify with Obj-C method signatures. Perhaps call actual LuaCocoa backend for parsing? Adapted from Programming in Lua call_va Example:

   [luaCocoa callFunction:@"OnMouseUp" withSignature:"@@idd>bids@@@@", 
       the_layer, layer_name, button_number, x_pos, y_pos,
       &bool_val, &int_val, &double_val, &str_val, &ns_str_val, &layer_val, &array_val, &dict_val];

In this case, we pass in two Obj-C objects followed by an int and two doubles. The > marker denotes the return types. In this case, we expect the Lua function to return a boolean, int, double, const char* and 4 Obj-C objects. The return objects go through the propertylist conversion, so in particular, Lua tables and arrays get passed back as NSDictionary and NSArray. Notes: Since I pop the stack at the end of the function (so you don't have to worry about balancing), I can't return a char* because it could get deallocated before I am done. So, the easiest answer seems to be to convert to an NSString. So 's' tokens on the return side get copied into NSString, so you must provide that type of variable. Also, passing nil to Lua functions and Lua functions returning nil are not supported well. (nil might work through the property list.) Bugs: error handling isn't quite right. luaL_error isn't right because we haven't pcall'ed yet or have returned from pcall. I don't think error: has all the correct information. I think I need to write a special error handler the case of being outside pcall. TODO: Figure out how to support optional return parameters.

Note:

In addition to Programming in Lua which uses 'b' (boolean) 'd' (double) 'i' (integer) 's' (string) '>' I also add '@' for id, '#' for Class, and 'v' for void*.

Parameters:

lua_function_name	The name of the Lua function to call.
error_function	The error function to handle any Lua errors.
parameter_signature	A format string describing the parameter types. (See above notes.)
...	The list of parameters to go with the format string.

Returns:

A NSString containing an error message if pcall failed, nil otherwise.

- (NSString*) pcallLuaFunction:		(const char *)	lua_function_name
withSignature:		(const char *)	parameter_signature
,			...

Convenience method to pcall functions in Lua.

This convenience method adopts the techniques described in Programming in Lua's call_va function to make calling arbitrary Lua functions a little easier.

Warning:

Parameter signatures are subject to change in future releases to be more consistent with Obj-C. Sorry. FIXME: Unify with Obj-C method signatures. Perhaps call actual LuaCocoa backend for parsing? Adapted from Programming in Lua call_va Example:

   [luaCocoa callFunction:@"OnMouseUp" withSignature:"@@idd>bids@@@@", 
        the_layer, layer_name, button_number, x_pos, y_pos,
        &bool_val, &int_val, &double_val, &str_val, &ns_str_val, &layer_val, &array_val, &dict_val];

In this case, we pass in two Obj-C objects followed by an int and two doubles. The > marker denotes the return types. In this case, we expect the Lua function to return a boolean, int, double, const char* and 4 Obj-C objects. The return objects go through the propertylist conversion, so in particular, Lua tables and arrays get passed back as NSDictionary and NSArray. Notes: Since I pop the stack at the end of the function (so you don't have to worry about balancing), I can't return a char* because it could get deallocated before I am done. So, the easiest answer seems to be to convert to an NSString. So 's' tokens on the return side get copied into NSString, so you must provide that type of variable. Also, passing nil to Lua functions and Lua functions returning nil are not supported well. (nil might work through the property list.) Bugs: error handling isn't quite right. luaL_error isn't right because we haven't pcall'ed yet or have returned from pcall. I don't think error: has all the correct information. I think I need to write a special error handler the case of being outside pcall. TODO: Figure out how to support optional return parameters.

Note:

In addition to Programming in Lua which uses 'b' (boolean) 'd' (double) 'i' (integer) 's' (string) '>' I also add '@' for id, '#' for Class, and 'v' for void*.

Parameters:

lua_function_name	The name of the Lua function to call.
parameter_signature	A format string describing the parameter types. (See above notes.)
...	The list of parameters to go with the format string.

Returns:

A NSString containing an error message if pcall failed, nil otherwise.

---

Member Data Documentation

- (NSMutableDictionary*) frameworksLoaded [private]

Definition at line 119 of file LuaCocoa.h.

- (bool) ownsLuaState [private]

Definition at line 118 of file LuaCocoa.h.

---

Property Documentation

- (bool) disableImportFromLua [read, write, assign]

Definition at line 121 of file LuaCocoa.h.

- (struct lua_State *) luaState

Returns the lua_State associated with the LuaCocoa instance.

Returns the lua_State associated with the LuaCocoa instance.

Returns:

The lua_State

Definition at line 117 of file LuaCocoa.h.

- (bool) skipDLopen [read, write, assign]

Definition at line 120 of file LuaCocoa.h.

---

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

• LuaCocoa.h