Fawkes API  Fawkes Development Version
fawkes::LuaContext Class Reference

Lua C++ wrapper. More...

#include <>>

Inheritance diagram for fawkes::LuaContext:

List of all members.

Public Member Functions

 LuaContext (bool enable_tracebacks=true)
 Constructor.
 LuaContext (lua_State *L)
 Wrapper contstructor.
 ~LuaContext ()
 Destructor.
void setup_fam (bool auto_restart, bool conc_thread)
 Setup file alteration monitor.
RefPtr< FileAlterationMonitorget_fam () const
 Get file alteration monitor.
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 set_cfunction (const char *name, lua_CFunction f)
 Assign cfunction 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 push_cfunction (lua_CFunction f)
 Push C function 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

Constructor & Destructor Documentation

fawkes::LuaContext::LuaContext ( bool  enable_tracebacks = true)

Constructor.

Parameters:
enable_tracebacksif true an error function is installed at the top of the stackand used for pcalls where errfunc is 0.

Definition at line 66 of file context.cpp.

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:
LLua state to wrap

Definition at line 87 of file context.cpp.

fawkes::LuaContext::~LuaContext ( )

Destructor.

Definition at line 98 of file context.cpp.


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:
pathpath to add

Definition at line 311 of file context.cpp.

Referenced by LuaAgentContinuousExecutionThread::init(), and LuaAgentPeriodicExecutionThread::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:
packagepackage to add

Definition at line 328 of file context.cpp.

Referenced by LuaAgentContinuousExecutionThread::init(), and LuaAgentPeriodicExecutionThread::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:
pathpath to add

Definition at line 294 of file context.cpp.

Referenced by LuaAgentContinuousExecutionThread::init(), and LuaAgentPeriodicExecutionThread::init().

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

Add a context watcher.

Parameters:
watcherwatcher to add

Definition at line 1214 of file context.cpp.

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

Create a table on top of the stack.

Parameters:
narrnumber of array elements
nrecnumber of non-array elements

Definition at line 892 of file context.cpp.

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

Execute file.

Parameters:
filenamefilet to load and excute.

Definition at line 381 of file context.cpp.

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

Execute string.

Parameters:
formatformat of string to execute, arguments can be the same as for vasprintf.

Definition at line 471 of file context.cpp.

Referenced by fawkes::LuaTriggerManager::trigger(), LuaAgentContinuousExecutionThread::LuaThread::loop(), LuaAgentPeriodicExecutionThread::loop(), and SkillerExecutionThread::loop().

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

Event has been raised.

Parameters:
filenamename of the file that triggered the event
maskmask indicating the event. Currently inotify event flags are used, see inotify.h.

Implements fawkes::FamListener.

Definition at line 1240 of file context.cpp.

RefPtr< FileAlterationMonitor > fawkes::LuaContext::get_fam ( ) const

Get file alteration monitor.

Returns:
reference counted pointer to file alteration monitor. Note that the pointer might be invalid if setup_fam() has not been called.

Definition at line 143 of file context.cpp.

Referenced by LuaAgentContinuousExecutionThread::init().

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:
idxindex of the table
kkey of the table entry

Definition at line 959 of file context.cpp.

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

Get global variable.

Parameters:
namename of the global variable

Definition at line 1016 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 345 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:
idxindex of the table on the stack

Definition at line 946 of file context.cpp.

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

Check if stack value is a boolean.

Parameters:
idxstack index of value
Returns:
true if value is a boolean, false otherwise

Definition at line 1093 of file context.cpp.

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

Check if stack value is a C function.

Parameters:
idxstack index of value
Returns:
true if value is a C function, false otherwise

Definition at line 1104 of file context.cpp.

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

Check if stack value is a function.

Parameters:
idxstack index of value
Returns:
true if value is a function, false otherwise

Definition at line 1115 of file context.cpp.

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

Check if stack value is light user data.

Parameters:
idxstack index of value
Returns:
true if value is light user data , false otherwise

Definition at line 1126 of file context.cpp.

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

Check if stack value is nil.

Parameters:
idxstack index of value
Returns:
true if value is nil, false otherwise

Definition at line 1137 of file context.cpp.

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

Check if stack value is a number.

Parameters:
idxstack index of value
Returns:
true if value is a number, false otherwise

Definition at line 1148 of file context.cpp.

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

Check if stack value is a string.

Parameters:
idxstack index of value
Returns:
true if value is a string, false otherwise

Definition at line 1159 of file context.cpp.

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

Check if stack value is a table.

Parameters:
idxstack index of value
Returns:
true if value is a table, false otherwise

Definition at line 1170 of file context.cpp.

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

Check if stack value is a thread.

Parameters:
idxstack index of value
Returns:
true if value is a thread, false otherwise

Definition at line 1181 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:
sstring to load

Definition at line 501 of file context.cpp.

Referenced by SkillerExecutionThread::loop().

void fawkes::LuaContext::lock ( )

Lock Lua state.

Definition at line 353 of file context.cpp.

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

Get object length.

Parameters:
idxstack index of value
Returns:
size of object

Definition at line 1192 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:
nargsnumber of arguments
nresultsnumber of results
errfuncstack index of an error handling function
Exceptions:
Exceptionthrown for generic runtime error or if the error function could not be executed.
OutOfMemoryExceptionthrown if not enough memory was available

Definition at line 529 of file context.cpp.

Referenced by SkillerExecutionThread::loop().

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

Pop value(s) from stack.

Parameters:
nnumber of values to pop

Definition at line 854 of file context.cpp.

Referenced by SkillerExecutionThread::loop().

void fawkes::LuaContext::process_fam_events ( )

Process FAM events.

Definition at line 1233 of file context.cpp.

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

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

Push boolean on top of stack.

Parameters:
valuevalue to push

Definition at line 697 of file context.cpp.

void fawkes::LuaContext::push_cfunction ( lua_CFunction  f)

Push C function on top of stack.

Parameters:
fC Function to push

Definition at line 843 of file context.cpp.

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

Push formatted string on top of stack.

Parameters:
formatstring format
See also:
man 3 sprintf

Definition at line 709 of file context.cpp.

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

Push integer on top of stack.

Parameters:
valuevalue to push

Definition at line 723 of file context.cpp.

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

Push light user data on top of stack.

Parameters:
ppointer to light user data to push

Definition at line 734 of file context.cpp.

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

Push substring on top of stack.

Parameters:
sstring to push
lenlength of string to push

Definition at line 746 of file context.cpp.

void fawkes::LuaContext::push_nil ( )

Push nil on top of stack.

Definition at line 756 of file context.cpp.

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

Push number on top of stack.

Parameters:
valuevalue to push

Definition at line 767 of file context.cpp.

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

Push string on top of stack.

Parameters:
valuevalue to push

Definition at line 778 of file context.cpp.

void fawkes::LuaContext::push_thread ( )

Push thread on top of stack.

Definition at line 788 of file context.cpp.

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

Push usertype on top of stack.

Parameters:
datausertype data
type_nametype name of the data
name_spaceC++ namespace of type, prepended to type_name

Definition at line 825 of file context.cpp.

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

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

Parameters:
idxindex of the value to copy

Definition at line 799 of file context.cpp.

Referenced by SkillerExecutionThread::loop().

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

Push formatted string on top of stack.

Parameters:
formatstring format
argvariadic argument list
See also:
man 3 sprintf

Definition at line 812 of file context.cpp.

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:
idxindex of the table

Definition at line 994 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:
idxindex of the table
nindex in the table

Definition at line 1006 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:
idxindex of the table

Definition at line 970 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:
idxindex of the table
nindex in the table

Definition at line 983 of file context.cpp.

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

Remove value from stack.

Parameters:
idxindex of element to remove

Definition at line 867 of file context.cpp.

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:
namename of value to remove

Definition at line 1028 of file context.cpp.

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

Remove a context watcher.

Parameters:
watcherwatcher to remove

Definition at line 1224 of file context.cpp.

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 271 of file context.cpp.

Referenced by LuaAgentContinuousExecutionThread::fam_event().

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

Assign boolean to global variable.

Parameters:
namename of global variable to assign the value to
valuevalue to assign

Definition at line 630 of file context.cpp.

void fawkes::LuaContext::set_cfunction ( const char *  name,
lua_CFunction  f 
)

Assign cfunction to global variable.

Parameters:
namename of global variable to assign the value to
ffunction

Definition at line 681 of file context.cpp.

Referenced by LuaAgentContinuousExecutionThread::init().

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:
keykey of the field to set
t_indexindex 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 920 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:
namename of the variable to assign

Definition at line 932 of file context.cpp.

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

Assign integer to global variable.

Parameters:
namename of global variable to assign the value to
valuevalue to assign

Definition at line 664 of file context.cpp.

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

Assign number to global variable.

Parameters:
namename of global variable to assign the value to
valuevalue to assign

Definition at line 647 of file context.cpp.

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_scriptscript 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 249 of file context.cpp.

Referenced by LuaAgentContinuousExecutionThread::init(), and LuaAgentPeriodicExecutionThread::init().

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

Assign string to global variable.

Parameters:
namename of global variable to assign the value to
valuevalue to assign

Definition at line 613 of file context.cpp.

Referenced by LuaAgentContinuousExecutionThread::init(), and LuaAgentPeriodicExecutionThread::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_indexindex of the table on the stack

Definition at line 905 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:
namename of global variable to assign the value to
datausertype data
type_nametype name of the data
name_spaceC++ namespace of type, prepended to type_name

Definition at line 589 of file context.cpp.

Referenced by LuaAgentContinuousExecutionThread::init(), and LuaAgentPeriodicExecutionThread::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:
idxstack index of function

Definition at line 1204 of file context.cpp.

Referenced by SkillerExecutionThread::loop().

void fawkes::LuaContext::setup_fam ( bool  auto_restart,
bool  conc_thread 
)

Setup file alteration monitor.

Setup an internal file alteration monitor that can react to changes on Lua files and packages.

Parameters:
auto_restartautomatically restart the Lua context in case of an event
conc_threadtrue to run a concurrent thread for event processing. If and only if you set this to false, ensure that process_fam_events() periodically.

Definition at line 124 of file context.cpp.

Referenced by LuaAgentContinuousExecutionThread::init(), and LuaAgentPeriodicExecutionThread::init().

int fawkes::LuaContext::stack_size ( )

Get size of stack.

Returns:
number of elements on the stack

Definition at line 881 of file context.cpp.

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

Retrieve stack value as boolean.

Parameters:
idxstack index of value
Returns:
value as boolean

Definition at line 1071 of file context.cpp.

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

Retrieve stack value as integer.

Parameters:
idxstack index of value
Returns:
value as integer

Definition at line 1060 of file context.cpp.

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

Retrieve stack value as number.

Parameters:
idxstack index of value
Returns:
value as number

Definition at line 1049 of file context.cpp.

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

Retrieve stack value as string.

Parameters:
idxstack index of value
Returns:
value as string

Definition at line 1082 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 363 of file context.cpp.

void fawkes::LuaContext::unlock ( )

Unlock Lua state.

Definition at line 371 of file context.cpp.


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