fawkes::LuaContext Class Reference

Lua C++ wrapper. More...

#include <lua/context.h>

Inheritance diagram for fawkes::LuaContext:
Inheritance graph
[legend]

List of all members.

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 (  ) 
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:

Generated on 1 Mar 2011 for Fawkes API by  doxygen 1.6.1