Lutok: lutok::state Class Reference

Lutok 0.4

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Files Functions Variables Macros
Classes | Public Member Functions | Private Member Functions | Private Attributes | Friends
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