fawkes::LuaContext Class Reference

Lua C++ wrapper. More...

#include <lua/context.h>

Inheritance diagram for fawkes::LuaContext:


Public Member Functions
	LuaContext (bool watch_dirs=true, bool enable_tracebacks=true)
	Constructor.
	LuaContext (lua_State *L)
	Wrapper contstructor.
	~LuaContext ()
	Destructor.
void	set_start_script (const char *start_script)
	Set start script.
void	restart ()
	Restart Lua.
void	add_package_dir (const char *path)
	Add a Lua package directory.
void	add_cpackage_dir (const char *path)
	Add a Lua C package directory.
void	add_package (const char *package)
	Add a default package.
lua_State *	get_lua_state ()
	Get Lua state.
void	lock ()
	Lock Lua state.
bool	try_lock ()
	Try to lock the Lua state.
void	unlock ()
	Unlock Lua state.
void	do_file (const char *filename)
	Execute file.
void	do_string (const char *format,...)
	Execute string.
void	load_string (const char *s)
	Load Lua string.
void	pcall (int nargs=0, int nresults=0, int errfunc=0)
	Protected call.
void	set_usertype (const char name, void data, const char type_name, const char name_space=0)
	Assign usertype to global variable.
void	set_string (const char name, const char value)
	Assign string to global variable.
void	set_number (const char *name, lua_Number value)
	Assign number to global variable.
void	set_boolean (const char *name, bool value)
	Assign boolean to global variable.
void	set_integer (const char *name, lua_Integer value)
	Assign integer to global variable.
void	remove_global (const char *name)
	Remove global variable.
void	set_global (const char *name)
	Set a global value.
void	push_boolean (bool value)
	Push boolean on top of stack.
void	push_fstring (const char *format,...)
	Push formatted string on top of stack.
void	push_integer (lua_Integer value)
	Push integer on top of stack.
void	push_light_user_data (void *p)
	Push light user data on top of stack.
void	push_lstring (const char *s, size_t len)
	Push substring on top of stack.
void	push_nil ()
	Push nil on top of stack.
void	push_number (lua_Number value)
	Push number on top of stack.
void	push_string (const char *value)
	Push string on top of stack.
void	push_thread ()
	Push thread on top of stack.
void	push_value (int idx)
	Push a copy of the element at the given index on top of the stack.
void	push_vfstring (const char *format, va_list arg)
	Push formatted string on top of stack.
void	push_usertype (void data, const char type_name, const char *name_space=0)
	Push usertype on top of stack.
void	pop (int n)
	Pop value(s) from stack.
void	remove (int idx)
	Remove value from stack.
int	stack_size ()
	Get size of stack.
void	create_table (int narr=0, int nrec=0)
	Create a table on top of the stack.
void	set_table (int t_index=-3)
	Set value of a table.
void	set_field (const char *key, int t_index=-2)
	Set field of a table.
void	get_table (int idx)
	Get value from table.
void	get_field (int idx, const char *k)
	Get named value from table.
void	get_global (const char *name)
	Get global variable.
void	raw_set (int idx)
	Set value without invoking meta methods.
void	raw_seti (int idx, int n)
	Set indexed value without invoking meta methods.
void	raw_get (int idx)
	Get value without invoking meta methods.
void	raw_geti (int idx, int n)
	Get indexed value without invoking meta methods.
lua_Number	to_number (int idx)
	Retrieve stack value as number.
lua_Integer	to_integer (int idx)
	Retrieve stack value as integer.
bool	to_boolean (int idx)
	Retrieve stack value as boolean.
const char *	to_string (int idx)
	Retrieve stack value as string.
bool	is_boolean (int idx)
	Check if stack value is a boolean.
bool	is_cfunction (int idx)
	Check if stack value is a C function.
bool	is_function (int idx)
	Check if stack value is a function.
bool	is_light_user_data (int idx)
	Check if stack value is light user data.
bool	is_nil (int idx)
	Check if stack value is nil.
bool	is_number (int idx)
	Check if stack value is a number.
bool	is_string (int idx)
	Check if stack value is a string.
bool	is_table (int idx)
	Check if stack value is a table.
bool	is_thread (int idx)
	Check if stack value is a thread.
size_t	objlen (int idx)
	Get object length.
void	setfenv (int idx=-2)
	Set function environment.
void	add_watcher (LuaContextWatcher *watcher)
	Add a context watcher.
void	remove_watcher (LuaContextWatcher *watcher)
	Remove a context watcher.
virtual void	fam_event (const char *filename, unsigned int mask)
	Event has been raised.
void	process_fam_events ()
	Process FAM events.

Detailed Description

Lua C++ wrapper.

This thin wrapper allows for easy integration of Fawkes into other applications. It provides convenience methods to some Lua and tolua++ features like setting global variables or pushing/popping values.

It allows raw access to the Lua state since this class does not and should not provide all the features Lua provides. If you use this make sure that you lock the Lua context to avoid multi-threading problems (if that is a possible concern in your application).

LuaContext can use a FileAlterationMonitor on all added package and C package directories. If anything changes in these directories the Lua instance is then automatically restarted (closed, re-opened and re-initialized).

Author:: Tim Niemueller

Definition at line 45 of file context.h.

Constructor & Destructor Documentation

fawkes::LuaContext::LuaContext	(	bool	watch_dirs = `true`,
		bool	enable_tracebacks = `true`
	)

Constructor.

Parameters:

	watch_dirs	true to watch added package and C package dirs for changes
	enable_tracebacks	if true an error function is installed at the top of the stackand used for pcalls where errfunc is 0.

Definition at line 68 of file context.cpp.

References fawkes::FileAlterationMonitor::add_filter(), and fawkes::FileAlterationMonitor::add_listener().

fawkes::LuaContext::LuaContext ( lua_State * L )

Wrapper contstructor.

This wraps around an existing Lua state. It does not initialize the state in the sense that it would add variables etc. It only provides convenient access to the state methods via a C++ interface. It's mainly intended to be used to create a LuaContext to be passed to LuaContextWatcher::lua_restarted(). The state is not closed on destruction as is done when using the other ctor.

Parameters:

L

Lua state to wrap

Definition at line 95 of file context.cpp.

fawkes::LuaContext::~LuaContext ( )

Destructor.

Definition at line 105 of file context.cpp.

References fawkes::Mutex::lock().

Member Function Documentation

void fawkes::LuaContext::add_cpackage_dir ( const char * path )

Add a Lua C package directory.

The directory is added to the search path for lua C packages. Files with a .so suffix will be considered as Lua modules.

Parameters:

path

path to add

Definition at line 273 of file context.cpp.

References do_string(), lock(), and fawkes::FileAlterationMonitor::watch_dir().

Referenced by LuaAgentExecutionThread::init().

void fawkes::LuaContext::add_package ( const char * package )

Add a default package.

Packages that are added this way are automatically loaded now and on restart().

Parameters:

package

package to add

Definition at line 290 of file context.cpp.

References do_string(), and lock().

Referenced by LuaAgentExecutionThread::init().

void fawkes::LuaContext::add_package_dir ( const char * path )

Add a Lua package directory.

The directory is added to the search path for lua packages. Files with a .lua suffix will be considered as Lua modules.

Parameters:

path

path to add

Definition at line 256 of file context.cpp.

References do_string(), lock(), and fawkes::FileAlterationMonitor::watch_dir().

Referenced by LuaAgentExecutionThread::init().

void fawkes::LuaContext::add_watcher ( fawkes::LuaContextWatcher * watcher )

Add a context watcher.

Parameters:

watcher

watcher to add

Definition at line 1144 of file context.cpp.

References fawkes::LockList< Type >::push_back_locked().

Referenced by fawkes::LuaInterfaceImporter::LuaInterfaceImporter().

void fawkes::LuaContext::create_table	(	int	narr = `0`,
		int	nrec = `0`
	)

Create a table on top of the stack.

Parameters:

	narr	number of array elements
	nrec	number of non-array elements

Definition at line 823 of file context.cpp.

void fawkes::LuaContext::do_file ( const char * filename )

Execute file.

Parameters:

filename

filet to load and excute.

Definition at line 343 of file context.cpp.

References lock().

Referenced by set_start_script().

void fawkes::LuaContext::do_string	(	const char *	format,
			...
	)

Execute string.

Parameters:

format

format of string to execute, arguments can be the same as for vasprintf.

Definition at line 433 of file context.cpp.

References lock().

Referenced by add_cpackage_dir(), add_package(), add_package_dir(), SkillerExecutionThread::loop(), LuaAgentExecutionThread::loop(), set_start_script(), and fawkes::LuaTriggerManager::trigger().

void fawkes::LuaContext::fam_event	(	const char *	filename,
		unsigned int	mask
	)			`[virtual]`

Event has been raised.

Parameters:

	filename	name of the file that triggered the event
	mask	mask indicating the event. Currently inotify event flags are used, see inotify.h.

Implements fawkes::FamListener.

Definition at line 1170 of file context.cpp.

References restart().

void fawkes::LuaContext::get_field	(	int	idx,
		const char *	k
	)

Get named value from table.

Retrieves the t[k], where k is the given key and t is a table at the given index idx. The value is pushed onto the stack.

Parameters:

	idx	index of the table
	k	key of the table entry

Definition at line 890 of file context.cpp.

void fawkes::LuaContext::get_global ( const char * name )

Get global variable.

Parameters:

name

name of the global variable

Definition at line 947 of file context.cpp.

lua_State * fawkes::LuaContext::get_lua_state ( )

Get Lua state.

Allows for raw modification of the used Lua state. Remember proper locking!

Returns:: Currently used Lua state

Definition at line 307 of file context.cpp.

void fawkes::LuaContext::get_table ( int idx )

Get value from table.

Assumes that an index k is at the top of the stack. Then t[k] is retrieved, where t is a table at the given index idx. The resulting value is pushed onto the stack, while the key k is popped from the stack, thus the value replaces the key.

Parameters:

idx

index of the table on the stack

Definition at line 877 of file context.cpp.

bool fawkes::LuaContext::is_boolean ( int idx )

Check if stack value is a boolean.

Parameters:

idx

stack index of value

Returns:: true if value is a boolean, false otherwise

Definition at line 1023 of file context.cpp.

bool fawkes::LuaContext::is_cfunction ( int idx )

Check if stack value is a C function.

Parameters:

idx

stack index of value

Returns:: true if value is a C function, false otherwise

Definition at line 1034 of file context.cpp.

bool fawkes::LuaContext::is_function ( int idx )

Check if stack value is a function.

Parameters:

idx

stack index of value

Returns:: true if value is a function, false otherwise

Definition at line 1045 of file context.cpp.

bool fawkes::LuaContext::is_light_user_data ( int idx )

Check if stack value is light user data.

Parameters:

idx

stack index of value

Returns:: true if value is light user data , false otherwise

Definition at line 1056 of file context.cpp.

bool fawkes::LuaContext::is_nil ( int idx )

Check if stack value is nil.

Parameters:

idx

stack index of value

Returns:: true if value is nil, false otherwise

Definition at line 1067 of file context.cpp.

bool fawkes::LuaContext::is_number ( int idx )

Check if stack value is a number.

Parameters:

idx

stack index of value

Returns:: true if value is a number, false otherwise

Definition at line 1078 of file context.cpp.

bool fawkes::LuaContext::is_string ( int idx )

Check if stack value is a string.

Parameters:

idx

stack index of value

Returns:: true if value is a string, false otherwise

Definition at line 1089 of file context.cpp.

bool fawkes::LuaContext::is_table ( int idx )

Check if stack value is a table.

Parameters:

idx

stack index of value

Returns:: true if value is a table, false otherwise

Definition at line 1100 of file context.cpp.

bool fawkes::LuaContext::is_thread ( int idx )

Check if stack value is a thread.

Parameters:

idx

stack index of value

Returns:: true if value is a thread, false otherwise

Definition at line 1111 of file context.cpp.

void fawkes::LuaContext::load_string ( const char * s )

Load Lua string.

Loads the Lua string and places it as a function on top of the stack.

Parameters:

s

string to load

Definition at line 463 of file context.cpp.

Referenced by SkillerExecutionThread::loop().

void fawkes::LuaContext::lock ( )

Lock Lua state.

Definition at line 315 of file context.cpp.

References fawkes::Mutex::lock().

Referenced by add_cpackage_dir(), add_package(), add_package_dir(), do_file(), do_string(), pop(), push_boolean(), push_fstring(), push_integer(), push_light_user_data(), push_lstring(), push_nil(), push_number(), push_string(), push_thread(), push_usertype(), push_value(), push_vfstring(), remove(), remove_global(), restart(), set_boolean(), set_integer(), set_number(), set_string(), and set_usertype().

size_t fawkes::LuaContext::objlen ( int idx )

Get object length.

Parameters:

idx

stack index of value

Returns:: size of object

Definition at line 1122 of file context.cpp.

void fawkes::LuaContext::pcall	(	int	nargs = `0`,
		int	nresults = `0`,
		int	errfunc = `0`
	)

Protected call.

Calls the function on top of the stack. Errors are handled gracefully.

Parameters:

	nargs	number of arguments
	nresults	number of results
	errfunc	stack index of an error handling function

Exceptions:

	Exception	thrown for generic runtime error or if the error function could not be executed.
	OutOfMemoryException	thrown if not enough memory was available

Definition at line 491 of file context.cpp.

Referenced by SkillerExecutionThread::loop().

void fawkes::LuaContext::pop ( int n )

Pop value(s) from stack.

Parameters:

n

number of values to pop

Definition at line 785 of file context.cpp.

References lock(), and stack_size().

Referenced by SkillerExecutionThread::loop().

void fawkes::LuaContext::process_fam_events ( )

Process FAM events.

Definition at line 1163 of file context.cpp.

References fawkes::FileAlterationMonitor::process_events().

Referenced by SkillerExecutionThread::loop(), and LuaAgentExecutionThread::loop().

void fawkes::LuaContext::push_boolean ( bool value )

Push boolean on top of stack.

Parameters:

value

value to push

Definition at line 639 of file context.cpp.

References lock().

void fawkes::LuaContext::push_fstring	(	const char *	format,
			...
	)

Push formatted string on top of stack.

Parameters:

format

string format

See also:: man 3 sprintf

Definition at line 651 of file context.cpp.

References lock().

void fawkes::LuaContext::push_integer ( lua_Integer value )

Push integer on top of stack.

Parameters:

value

value to push

Definition at line 665 of file context.cpp.

References lock().

void fawkes::LuaContext::push_light_user_data ( void * p )

Push light user data on top of stack.

Parameters:

p

pointer to light user data to push

Definition at line 676 of file context.cpp.

References lock().

void fawkes::LuaContext::push_lstring	(	const char *	s,
		size_t	len
	)

Push substring on top of stack.

Parameters:

	s	string to push
	len	length of string to push

Definition at line 688 of file context.cpp.

References lock().

void fawkes::LuaContext::push_nil ( )

Push nil on top of stack.

Definition at line 698 of file context.cpp.

References lock().

void fawkes::LuaContext::push_number ( lua_Number value )

Push number on top of stack.

Parameters:

value

value to push

Definition at line 709 of file context.cpp.

References lock().

void fawkes::LuaContext::push_string ( const char * value )

Push string on top of stack.

Parameters:

value

value to push

Definition at line 720 of file context.cpp.

References lock().

void fawkes::LuaContext::push_thread ( )

Push thread on top of stack.

Definition at line 730 of file context.cpp.

References lock().

void fawkes::LuaContext::push_usertype	(	void *	data,
		const char *	type_name,
		const char *	name_space = `0`
	)

Push usertype on top of stack.

Parameters:

	data	usertype data
	type_name	type name of the data
	name_space	C++ namespace of type, prepended to type_name

Definition at line 767 of file context.cpp.

References lock().

void fawkes::LuaContext::push_value ( int idx )

Push a copy of the element at the given index on top of the stack.

Parameters:

idx

index of the value to copy

Definition at line 741 of file context.cpp.

References lock().

Referenced by SkillerExecutionThread::loop().

void fawkes::LuaContext::push_vfstring	(	const char *	format,
		va_list	arg
	)

Push formatted string on top of stack.

Parameters:

	format	string format
	arg	variadic argument list

See also:: man 3 sprintf

Definition at line 754 of file context.cpp.

References lock().

void fawkes::LuaContext::raw_get ( int idx )

Get value without invoking meta methods.

Similar to get_table(), but does raw access, i.e. without invoking meta-methods.

Parameters:

idx

index of the table

Definition at line 925 of file context.cpp.

void fawkes::LuaContext::raw_geti	(	int	idx,
		int	n
	)

Get indexed value without invoking meta methods.

Pushes t[n] onto the stack, where t is a table at index idx.

Parameters:

	idx	index of the table
	n	index in the table

Definition at line 937 of file context.cpp.

void fawkes::LuaContext::raw_set ( int idx )

Set value without invoking meta methods.

Similar to set_table(), but does raw access, i.e. without invoking meta-methods.

Parameters:

idx

index of the table

Definition at line 901 of file context.cpp.

void fawkes::LuaContext::raw_seti	(	int	idx,
		int	n
	)

Set indexed value without invoking meta methods.

Sets t[n]=v, where t is a table at index idx and v is the value at the top of the stack.

Parameters:

	idx	index of the table
	n	index in the table

Definition at line 914 of file context.cpp.

void fawkes::LuaContext::remove ( int idx )

Remove value from stack.

Parameters:

idx

index of element to remove

Definition at line 798 of file context.cpp.

References lock(), and stack_size().

void fawkes::LuaContext::remove_global ( const char * name )

Remove global variable.

Assigns nil to the given variable and removes it from internal assignment maps.

Parameters:

name

name of value to remove

Definition at line 959 of file context.cpp.

References lock().

void fawkes::LuaContext::remove_watcher ( fawkes::LuaContextWatcher * watcher )

Remove a context watcher.

Parameters:

watcher

watcher to remove

Definition at line 1154 of file context.cpp.

References fawkes::LockList< Type >::remove_locked().

Referenced by fawkes::LuaInterfaceImporter::~LuaInterfaceImporter().

void fawkes::LuaContext::restart ( )

Restart Lua.

Creates a new Lua state, initializes it, anf if this went well the current state is swapped with the new state.

Definition at line 233 of file context.cpp.

References lock(), and fawkes::LibLogger::log_error().

Referenced by fam_event().

void fawkes::LuaContext::set_boolean	(	const char *	name,
		bool	value
	)

Assign boolean to global variable.

Parameters:

	name	name of global variable to assign the value to
	value	value to assign

Definition at line 589 of file context.cpp.

References lock().

void fawkes::LuaContext::set_field	(	const char *	key,
		int	t_index = `-2`
	)

Set field of a table.

Does the equivalent to t[k] = v, where t is the value at the given valid index and v is the value at the top of the stack. This function pops the value from the stack. As in Lua, this function may trigger a metamethod for the "newindex" event.

Parameters:

	key	key of the field to set
	t_index	index of the table on the stack, defaults to the element just below the value to set (-2, second last element on the stack).

Definition at line 851 of file context.cpp.

void fawkes::LuaContext::set_global ( const char * name )

Set a global value.

Sets the global variable with the given name to the value currently on top of the stack. No check whatsoever regarding the name is done.

Parameters:

name

name of the variable to assign

Definition at line 863 of file context.cpp.

void fawkes::LuaContext::set_integer	(	const char *	name,
		lua_Integer	value
	)

Assign integer to global variable.

Parameters:

	name	name of global variable to assign the value to
	value	value to assign

Definition at line 623 of file context.cpp.

References lock().

void fawkes::LuaContext::set_number	(	const char *	name,
		lua_Number	value
	)

Assign number to global variable.

Parameters:

	name	name of global variable to assign the value to
	value	value to assign

Definition at line 606 of file context.cpp.

References lock().

void fawkes::LuaContext::set_start_script ( const char * start_script )

Set start script.

The script will be executed once immediately in this method, make sure you call this after all other init-relevant routines like add_* if you need to access these in the start script!

Parameters:

start_script

script to execute now and on restart(). If the string is the path and name of an accessible file it is loaded via do_file(), otherwise it is considered to be the name of a module and loaded via Lua's require(). Note however, that if you use a module, special care has to be taken to correctly modify the global environment!

Definition at line 211 of file context.cpp.

References do_file(), and do_string().

Referenced by LuaAgentExecutionThread::init().

void fawkes::LuaContext::set_string	(	const char *	name,
		const char *	value
	)

Assign string to global variable.

Parameters:

	name	name of global variable to assign the value to
	value	value to assign

Definition at line 572 of file context.cpp.

References lock().

Referenced by LuaAgentExecutionThread::init().

void fawkes::LuaContext::set_table ( int t_index = -3 )

Set value of a table.

Sets value t[k] = v. t is the table at the given index, by default it is the third-last entry (index is -3). v is the value at the top of the stack, k is the element just below the top.

Parameters:

t_index

index of the table on the stack

Definition at line 836 of file context.cpp.

void fawkes::LuaContext::set_usertype	(	const char *	name,
		void *	data,
		const char *	type_name,
		const char *	name_space = `0`
	)

Assign usertype to global variable.

Parameters:

	name	name of global variable to assign the value to
	data	usertype data
	type_name	type name of the data
	name_space	C++ namespace of type, prepended to type_name

Definition at line 548 of file context.cpp.

References lock().

Referenced by LuaAgentExecutionThread::init().

void fawkes::LuaContext::setfenv ( int idx = -2 )

Set function environment.

Sets the table on top of the stack as environment of the function at the given stack index.

Parameters:

idx

stack index of function

Definition at line 1134 of file context.cpp.

Referenced by SkillerExecutionThread::loop().

int fawkes::LuaContext::stack_size ( )

Get size of stack.

Returns:: number of elements on the stack

Definition at line 812 of file context.cpp.

Referenced by pop(), and remove().

bool fawkes::LuaContext::to_boolean ( int idx )

Retrieve stack value as boolean.

Parameters:

idx

stack index of value

Returns:: value as boolean

Definition at line 1001 of file context.cpp.

lua_Integer fawkes::LuaContext::to_integer ( int idx )

Retrieve stack value as integer.

Parameters:

idx

stack index of value

Returns:: value as integer

Definition at line 990 of file context.cpp.

lua_Number fawkes::LuaContext::to_number ( int idx )

Retrieve stack value as number.

Parameters:

idx

stack index of value

Returns:: value as number

Definition at line 979 of file context.cpp.

const char * fawkes::LuaContext::to_string ( int idx )

Retrieve stack value as string.

Parameters:

idx

stack index of value

Returns:: value as string

Definition at line 1012 of file context.cpp.

bool fawkes::LuaContext::try_lock ( )

Try to lock the Lua state.

Returns:: true if the state has been locked, false otherwise.

Definition at line 325 of file context.cpp.

References fawkes::Mutex::try_lock().

void fawkes::LuaContext::unlock ( )

Unlock Lua state.

Definition at line 333 of file context.cpp.

References fawkes::Mutex::unlock().

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

src/libs/lua/context.h
src/libs/lua/context.cpp

Context Navigation

fawkes::LuaContext Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation