lutok::state Class Reference

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

#include <state.hpp>

List of all members.

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

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

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

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:

name	The second parameter to lua_getglobal.

Exceptions:

api_error

If 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:

index	The second parameter to luaL_getmetafield.
name	The 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:

index

The 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:

index

The second parameter to lua_gettable.

Exceptions:

api_error

If 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:

index

The second parameter to lua_insert.

bool lutok::state::is_boolean

(

const int

index

)

Wrapper around lua_isboolean.

Parameters:

index

The 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:

index

The 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:

index

The 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:

index

The 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:

index

The 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:

index

The 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:

index

The 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:

file	The second parameter to luaL_loadfile.

Exceptions:

api_error	If luaL_loadfile returns an error.
file_not_found_error	If 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:

str	The second parameter to luaL_loadstring.

Exceptions:

api_error

If 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:

size	The 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:

index

The 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_error

If luaL_openlibs fails.

Warning:

Terminates execution if there is not enough memory.

void lutok::state::open_base

(

void

)

Wrapper around luaopen_base.

Exceptions:

api_error

If luaopen_base fails.

Warning:

Terminates execution if there is not enough memory.

void lutok::state::open_string

(

void

)

Wrapper around luaopen_string.

Exceptions:

api_error

If luaopen_string fails.

Warning:

Terminates execution if there is not enough memory.

void lutok::state::open_table

(

void

)

Wrapper around luaopen_table.

Exceptions:

api_error

If 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:

nargs	The second parameter to lua_pcall.
nresults	The third parameter to lua_pcall.
errfunc	The fourth parameter to lua_pcall.

Exceptions:

api_error

If lua_pcall returns an error.

void lutok::state::pop

(

const int

count

)

Wrapper around lua_pop.

Parameters:

count

The second parameter to lua_pop.

void lutok::state::push_boolean

(

const bool

value

)

Wrapper around lua_pushboolean.

Parameters:

value

The 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:

function	The C++ function to be pushed as a closure.
nvalues	The 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:

function

The C++ function to be pushed.

void lutok::state::push_integer

(

const int

value

)

Wrapper around lua_pushinteger.

Parameters:

value

The second parameter to lua_pushinteger.

void lutok::state::push_string

(

const std::string &

str

)

Wrapper around lua_pushstring.

Parameters:

str	The 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:

index

The second parameter to lua_pushvalue.

void lutok::state::raw_get

(

const int

index

)

Wrapper around lua_rawget.

Parameters:

index

The second parameter to lua_rawget.

void lutok::state::raw_set

(

const int

index

)

Wrapper around lua_rawset.

Parameters:

index

The 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:

name	The second parameter to lua_setglobal.

Exceptions:

api_error

If 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:

index

The second parameter to lua_setmetatable.

void lutok::state::set_table

(

const int

index

)

Wrapper around lua_settable.

Parameters:

index

The second parameter to lua_settable.

Exceptions:

api_error

If 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:

index

The 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:

index

The 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:

index

The 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:

index

The 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:

index

The 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:

index

The first parameter to lua_upvalueindex.

Returns:

The return value of lua_upvalueindex.

---

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

• state.hpp
• state.cpp
• state.ipp