Lutok: lutok::state Class Reference

Lutok 0.6.1 |

Loading...
Searching...
No Matches
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.
| ~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::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

## ◆ state() [1/2]

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.

## ◆ state() [2/2]

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.

## ◆ ~state()

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

## ◆ close()

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.

## ◆ get_global()

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.

## ◆ get_global_table()

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.

## ◆ get_metafield()

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.

## ◆ get_metatable()

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.

## ◆ get_table()

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.

## ◆ get_top()

int lutok::state::get_top | ( | void |  | ) |

Wrapper around lua_gettop.

Returns
  The return value of lua_gettop.

## ◆ insert()

void lutok::state::insert | ( | const int | index | ) |

Wrapper around lua_insert.

Parameters

  index | The second parameter to lua_insert.

## ◆ is_boolean()

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.

## ◆ is_function()

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.

## ◆ is_nil()

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.

## ◆ is_number()

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.

## ◆ is_string()

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.

## ◆ is_table()

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.

## ◆ is_userdata()

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.

## ◆ load_file()

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.

## ◆ load_string()

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.

## ◆ new_table()

void lutok::state::new_table | ( | void |  | ) |

Wrapper around lua_newtable.

Warning
  Terminates execution if there is not enough memory.

## ◆ new_userdata()

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.

## ◆ new_userdata_voidp()

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.

## ◆ next()

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.

## ◆ open_all()

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.

## ◆ open_base()

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.

## ◆ open_string()

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.

## ◆ open_table()

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.

## ◆ pcall()

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.

## ◆ pop()

void lutok::state::pop | ( | const int | count | ) |

Wrapper around lua_pop.

Parameters

  count | The second parameter to lua_pop.

## ◆ push_boolean()

void lutok::state::push_boolean | ( | const bool | value | ) |

Wrapper around lua_pushboolean.

Parameters

  value | The second parameter to lua_pushboolean.

## ◆ push_cxx_closure()

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.

## ◆ push_cxx_function()

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.

## ◆ push_integer()

void lutok::state::push_integer | ( | const int | value | ) |

Wrapper around lua_pushinteger.

Parameters

  value | The second parameter to lua_pushinteger.

## ◆ push_string()

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.

## ◆ push_value()

void lutok::state::push_value | ( | const int | index | ) |

Wrapper around lua_pushvalue.

Parameters

  index | The second parameter to lua_pushvalue.

## ◆ raw_get()

void lutok::state::raw_get | ( | const int | index | ) |

Wrapper around lua_rawget.

Parameters

  index | The second parameter to lua_rawget.

## ◆ raw_set()

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.

## ◆ raw_state()

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.

## ◆ set_global()

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.

## ◆ set_metatable()

void lutok::state::set_metatable | ( | const int | index | ) |

Wrapper around lua_setmetatable.

Parameters

  index | The second parameter to lua_setmetatable.

## ◆ set_table()

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.

## ◆ to_boolean()

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.

## ◆ to_integer()

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.

## ◆ to_string()

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.

## ◆ to_userdata()

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.

## ◆ to_userdata_voidp()

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.

## ◆ upvalue_index()

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