Lutok  0.5
Classes | Public Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
lutok::state Class Reference

A RAII model for the Lua state. More...

#include <state.hpp>

Classes

struct  impl
 Internal implementation for lutok::state. More...
 

Public Member Functions

 state (void)
 Initializes the Lua state. More...
 
 ~state (void)
 Destructor for the Lua state. More...
 
void close (void)
 Terminates this Lua session. More...
 
void get_global (const std::string &)
 Wrapper around lua_getglobal. More...
 
void get_global_table (void)
 Pushes a reference to the global table onto the stack. More...
 
bool get_metafield (const int, const std::string &)
 Wrapper around luaL_getmetafield. More...
 
bool get_metatable (const int)
 Wrapper around lua_getmetatable. More...
 
void get_table (const int)
 Wrapper around lua_gettable. More...
 
int get_top (void)
 Wrapper around lua_gettop. More...
 
void insert (const int)
 Wrapper around lua_insert. More...
 
bool is_boolean (const int)
 Wrapper around lua_isboolean. More...
 
bool is_function (const int)
 Wrapper around lua_isfunction. More...
 
bool is_nil (const int)
 Wrapper around lua_isnil. More...
 
bool is_number (const int)
 Wrapper around lua_isnumber. More...
 
bool is_string (const int)
 Wrapper around lua_isstring. More...
 
bool is_table (const int)
 Wrapper around lua_istable. More...
 
bool is_userdata (const int)
 Wrapper around lua_isuserdata. More...
 
void load_file (const std::string &)
 Wrapper around luaL_loadfile. More...
 
void load_string (const std::string &)
 Wrapper around luaL_loadstring. More...
 
void new_table (void)
 Wrapper around lua_newtable. More...
 
template<typename Type >
Type * new_userdata (void)
 Wrapper around lua_newuserdata. More...
 
bool next (const int)
 Wrapper around lua_next. More...
 
void open_all (void)
 Wrapper around luaL_openlibs. More...
 
void open_base (void)
 Wrapper around luaopen_base. More...
 
void open_string (void)
 Wrapper around luaopen_string. More...
 
void open_table (void)
 Wrapper around luaopen_table. More...
 
void pcall (const int, const int, const int)
 Wrapper around lua_pcall. More...
 
void pop (const int)
 Wrapper around lua_pop. More...
 
void push_boolean (const bool)
 Wrapper around lua_pushboolean. More...
 
void push_cxx_closure (cxx_function, const int)
 Wrapper around lua_pushcclosure. More...
 
void push_cxx_function (cxx_function)
 Wrapper around lua_pushcfunction. More...
 
void push_integer (const int)
 Wrapper around lua_pushinteger. More...
 
void push_nil (void)
 Wrapper around lua_pushnil.
 
void push_string (const std::string &)
 Wrapper around lua_pushstring. More...
 
void push_value (const int)
 Wrapper around lua_pushvalue. More...
 
void raw_get (const int)
 Wrapper around lua_rawget. More...
 
void raw_set (const int)
 Wrapper around lua_rawset. More...
 
void set_global (const std::string &)
 Wrapper around lua_setglobal. More...
 
void set_metatable (const int)
 Wrapper around lua_setmetatable. More...
 
void set_table (const int)
 Wrapper around lua_settable. More...
 
bool to_boolean (const int)
 Wrapper around lua_toboolean. More...
 
long to_integer (const int)
 Wrapper around lua_tointeger. More...
 
template<typename Type >
Type * to_userdata (const int)
 Wrapper around lua_touserdata. More...
 
std::string to_string (const int)
 Wrapper around lua_tostring. More...
 
int upvalue_index (const int)
 Wrapper around lua_upvalueindex. More...
 

Private Member Functions

void * new_userdata_voidp (const size_t)
 Wrapper around lua_newuserdata. More...
 
void * to_userdata_voidp (const int)
 Wrapper around lua_touserdata. More...
 
 state (void *)
 Initializes the Lua state from an existing raw state. More...
 
void * raw_state (void)
 Gets the internal lua_State object. More...
 

Private Attributes

std::tr1::shared_ptr< impl_pimpl
 Pointer to the shared internal implementation.
 

Friends

class state_c_gate
 

Detailed Description

A RAII model for the Lua state.

This class holds the state of the Lua interpreter during its existence and provides wrappers around several Lua library functions that operate on such state.

These wrapper functions differ from the C versions in that they use the implicit state hold by the class, they use C++ types where appropriate and they use exceptions to report errors.

The wrappers intend to be as lightweight as possible but, in some situations, they are pretty complex because they need to do extra work to capture the errors reported by the Lua C API. We prefer having fine-grained error control rather than efficiency, so this is OK.

Constructor & Destructor Documentation

lutok::state::state ( void *  raw_state_)
explicitprivate

Initializes the Lua state from an existing raw state.

Instances constructed using this method do NOT own the raw state. This means that, on exit, the state will not be destroyed.

Parameters
raw_state_The raw Lua state to wrap.
lutok::state::state ( void  )

Initializes the Lua state.

You must share the same state object alongside the lifetime of your Lua session. As soon as the object is destroyed, the session is terminated.

lutok::state::~state ( void  )

Destructor for the Lua state.

Closes the session unless it has already been closed by calling the close() method. It is recommended to explicitly close the session in the code.

Member Function Documentation

void lutok::state::close ( void  )

Terminates this Lua session.

It is recommended to call this instead of relying on the destructor to do the cleanup, but it is not a requirement to use close().

Precondition
close() has not yet been called.
The Lua stack is empty. This is not truly necessary but ensures that our code is consistent and clears the stack explicitly.
void lutok::state::get_global ( const std::string &  name)

Wrapper around lua_getglobal.

Parameters
nameThe second parameter to lua_getglobal.
Exceptions
api_errorIf lua_getglobal fails.
Warning
Terminates execution if there is not enough memory to manipulate the Lua stack.
void lutok::state::get_global_table ( void  )

Pushes a reference to the global table onto the stack.

This is a wrapper around the incompatible differences between Lua 5.1 and 5.2 to access to the globals table.

Postcondition
state(-1) Contains the reference to the globals table.
bool lutok::state::get_metafield ( const int  index,
const std::string &  name 
)

Wrapper around luaL_getmetafield.

Parameters
indexThe second parameter to luaL_getmetafield.
nameThe third parameter to luaL_getmetafield.
Returns
The return value of luaL_getmetafield.
Warning
Terminates execution if there is not enough memory to manipulate the Lua stack.
bool lutok::state::get_metatable ( const int  index)

Wrapper around lua_getmetatable.

Parameters
indexThe second parameter to lua_getmetatable.
Returns
The return value of lua_getmetatable.
void lutok::state::get_table ( const int  index)

Wrapper around lua_gettable.

Parameters
indexThe second parameter to lua_gettable.
Exceptions
api_errorIf lua_gettable fails.
Warning
Terminates execution if there is not enough memory to manipulate the Lua stack.
int lutok::state::get_top ( void  )

Wrapper around lua_gettop.

Returns
The return value of lua_gettop.
void lutok::state::insert ( const int  index)

Wrapper around lua_insert.

Parameters
indexThe second parameter to lua_insert.
bool lutok::state::is_boolean ( const int  index)

Wrapper around lua_isboolean.

Parameters
indexThe second parameter to lua_isboolean.
Returns
The return value of lua_isboolean.
bool lutok::state::is_function ( const int  index)

Wrapper around lua_isfunction.

Parameters
indexThe second parameter to lua_isfunction.
Returns
The return value of lua_isfunction.
bool lutok::state::is_nil ( const int  index)

Wrapper around lua_isnil.

Parameters
indexThe second parameter to lua_isnil.
Returns
The return value of lua_isnil.
bool lutok::state::is_number ( const int  index)

Wrapper around lua_isnumber.

Parameters
indexThe second parameter to lua_isnumber.
Returns
The return value of lua_isnumber.
bool lutok::state::is_string ( const int  index)

Wrapper around lua_isstring.

Parameters
indexThe second parameter to lua_isstring.
Returns
The return value of lua_isstring.
bool lutok::state::is_table ( const int  index)

Wrapper around lua_istable.

Parameters
indexThe second parameter to lua_istable.
Returns
The return value of lua_istable.
bool lutok::state::is_userdata ( const int  index)

Wrapper around lua_isuserdata.

Parameters
indexThe second parameter to lua_isuserdata.
Returns
The return value of lua_isuserdata.
void lutok::state::load_file ( const std::string &  file)

Wrapper around luaL_loadfile.

Parameters
fileThe second parameter to luaL_loadfile.
Exceptions
api_errorIf luaL_loadfile returns an error.
file_not_found_errorIf the file cannot be accessed.
Warning
Terminates execution if there is not enough memory.
void lutok::state::load_string ( const std::string &  str)

Wrapper around luaL_loadstring.

Parameters
strThe second parameter to luaL_loadstring.
Exceptions
api_errorIf luaL_loadstring returns an error.
Warning
Terminates execution if there is not enough memory.
void lutok::state::new_table ( void  )

Wrapper around lua_newtable.

Warning
Terminates execution if there is not enough memory.
template<typename Type >
Type * lutok::state::new_userdata ( void  )

Wrapper around lua_newuserdata.

This allocates an object as big as the size of the provided Type.

Returns
The pointer to the allocated userdata object.
Warning
Terminates execution if there is not enough memory.
void * lutok::state::new_userdata_voidp ( const size_t  size)
private

Wrapper around lua_newuserdata.

This is internal. The public type-safe interface of this method should be used instead.

Parameters
sizeThe second parameter to lua_newuserdata.
Returns
The return value of lua_newuserdata.
Warning
Terminates execution if there is not enough memory.
bool lutok::state::next ( const int  index)

Wrapper around lua_next.

Parameters
indexThe second parameter to lua_next.
Returns
True if there are more elements to process; false otherwise.
Warning
Terminates execution if there is not enough memory.
void lutok::state::open_all ( void  )

Wrapper around luaL_openlibs.

Exceptions
api_errorIf luaL_openlibs fails.
Warning
Terminates execution if there is not enough memory.
void lutok::state::open_base ( void  )

Wrapper around luaopen_base.

Exceptions
api_errorIf luaopen_base fails.
Warning
Terminates execution if there is not enough memory.
void lutok::state::open_string ( void  )

Wrapper around luaopen_string.

Exceptions
api_errorIf luaopen_string fails.
Warning
Terminates execution if there is not enough memory.
void lutok::state::open_table ( void  )

Wrapper around luaopen_table.

Exceptions
api_errorIf luaopen_table fails.
Warning
Terminates execution if there is not enough memory.
void lutok::state::pcall ( const int  nargs,
const int  nresults,
const int  errfunc 
)

Wrapper around lua_pcall.

Parameters
nargsThe second parameter to lua_pcall.
nresultsThe third parameter to lua_pcall.
errfuncThe fourth parameter to lua_pcall.
Exceptions
api_errorIf lua_pcall returns an error.
void lutok::state::pop ( const int  count)

Wrapper around lua_pop.

Parameters
countThe second parameter to lua_pop.
void lutok::state::push_boolean ( const bool  value)

Wrapper around lua_pushboolean.

Parameters
valueThe second parameter to lua_pushboolean.
void lutok::state::push_cxx_closure ( cxx_function  function,
const int  nvalues 
)

Wrapper around lua_pushcclosure.

This is not a pure wrapper around lua_pushcclosure because this has to do extra magic to allow passing C++ functions instead of plain C functions.

Parameters
functionThe C++ function to be pushed as a closure.
nvaluesThe number of upvalues that the function receives.
void lutok::state::push_cxx_function ( cxx_function  function)

Wrapper around lua_pushcfunction.

This is not a pure wrapper around lua_pushcfunction because this has to do extra magic to allow passing C++ functions instead of plain C functions.

Parameters
functionThe C++ function to be pushed.
void lutok::state::push_integer ( const int  value)

Wrapper around lua_pushinteger.

Parameters
valueThe second parameter to lua_pushinteger.
void lutok::state::push_string ( const std::string &  str)

Wrapper around lua_pushstring.

Parameters
strThe second parameter to lua_pushstring.
Warning
Terminates execution if there is not enough memory.
void lutok::state::push_value ( const int  index)

Wrapper around lua_pushvalue.

Parameters
indexThe second parameter to lua_pushvalue.
void lutok::state::raw_get ( const int  index)

Wrapper around lua_rawget.

Parameters
indexThe second parameter to lua_rawget.
void lutok::state::raw_set ( const int  index)

Wrapper around lua_rawset.

Parameters
indexThe second parameter to lua_rawset.
Warning
Terminates execution if there is not enough memory to manipulate the Lua stack.
void * lutok::state::raw_state ( void  )
private

Gets the internal lua_State object.

Returns
The raw Lua state. This is returned as a void pointer to prevent including the lua.hpp header file from our public interface. The only way to call this method is by using the c_gate module, and c_gate takes care of casting this object to the appropriate type.
void lutok::state::set_global ( const std::string &  name)

Wrapper around lua_setglobal.

Parameters
nameThe second parameter to lua_setglobal.
Exceptions
api_errorIf lua_setglobal fails.
Warning
Terminates execution if there is not enough memory to manipulate the Lua stack.
void lutok::state::set_metatable ( const int  index)

Wrapper around lua_setmetatable.

Parameters
indexThe second parameter to lua_setmetatable.
void lutok::state::set_table ( const int  index)

Wrapper around lua_settable.

Parameters
indexThe second parameter to lua_settable.
Exceptions
api_errorIf lua_settable fails.
Warning
Terminates execution if there is not enough memory to manipulate the Lua stack.
bool lutok::state::to_boolean ( const int  index)

Wrapper around lua_toboolean.

Parameters
indexThe second parameter to lua_toboolean.
Returns
The return value of lua_toboolean.
long lutok::state::to_integer ( const int  index)

Wrapper around lua_tointeger.

Parameters
indexThe second parameter to lua_tointeger.
Returns
The return value of lua_tointeger.
std::string lutok::state::to_string ( const int  index)

Wrapper around lua_tostring.

Parameters
indexThe second parameter to lua_tostring.
Returns
The return value of lua_tostring.
Warning
Terminates execution if there is not enough memory.
template<typename Type >
Type * lutok::state::to_userdata ( const int  index)

Wrapper around lua_touserdata.

Parameters
indexThe second parameter to lua_touserdata.
Returns
The return value of lua_touserdata.
void * lutok::state::to_userdata_voidp ( const int  index)
private

Wrapper around lua_touserdata.

This is internal. The public type-safe interface of this method should be used instead.

Parameters
indexThe second parameter to lua_touserdata.
Returns
The return value of lua_touserdata.
Warning
Terminates execution if there is not enough memory.
int lutok::state::upvalue_index ( const int  index)

Wrapper around lua_upvalueindex.

Parameters
indexThe first parameter to lua_upvalueindex.
Returns
The return value of lua_upvalueindex.

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