lua::state Class Reference

#include <luaxx/luaxx.hpp>

List of all members.

---

Detailed Description

This is the Luaxx equivalent of lua_State.

The functions provided by this class, closely resemble those of the Lua C API.

Definition at line 156 of file luaxx.hpp.

Public Member Functions
template<>
std::string	as (std::string default_value, int index)
	Get the value at index as a string.
template<>
bool	as (bool default_value, int index)
	Get the value at index as a bool.
template<typename T>
T	as (int index=-1)
	Get the value at index as the given type.
template<typename T>
T	as (T default_value, int index=-1)
	Get the value at index as the given type.
state &	call (int nargs=0, int nresults=0)
	Call a lua function in unprotected mode.
state &	check (number &n, int narg)
	Check an argument of the current function.
state &	check (std::string &s, int narg)
	Check an argument of the current function.
state &	check (integer &i, int narg)
	Check an argument of the current function.
state &	check (int narg)
	Check an argument of the current function.
state &	checkstack (int size)
	Ensure the stack is at least the given size.
bool	empty ()
	Check if the stack is empty.
template<typename msg_t>
void	error (msg_t message)
	Generate a Lua error.
state &	getfield (const std::string &k, int index=-1)
	Get a value from a table on the stack.
state &	getglobal (const std::string &name)
	Load a global symbol onto the stack.
bool	getmetatable (int index)
	Get the metatable of the value at the given index.
state &	getmetatable (const std::string &tname)
	Get the metatable associated with the given registry entry.
state &	gettable (int index=-2)
	Get a value from a table on the stack.
int	gettop ()
	Get the number of elements in the stack.
state &	insert (int index)
	Move the top element to the given index.
template<typename T>
bool	is (int index=-1)
	Check if the given index is of the given type (defaults to using lua_isnumber()).
template<typename iterator_t>
state &	load (iterator_t begin, iterator_t end)
	Load a sequence of data as a Lua chunk.
state &	loadfile (const std::string &filename)
	Load a file as a Lua chunk.
state &	loadstring (const std::string &s)
	Load a string as a Lua chunk.
bool	newmetatable (const std::string &tname)
	Create a new metatable and add it to the registry.
state &	newtable ()
	Create a new table on the stack.
void *	newuserdata (size_t nbytes)
	Create a new userdatum on the stack.
template<typename userdata_t>
userdata_t *	newuserdata ()
	Create a new userdatum on the stack.
bool	next (int index=-2)
	Get the next key value pair from a table on the stack.
size_t	objlen (int index=-1)
	Get the length of a value on the stack.
	operator lua_State * ()
	Convert a lua::state to a lua_State*.
state &	pcall (int nargs=0, int nresults=0, int on_error=0)
	Call a lua function.
state &	pop (int elements=1)
	Remove the given number of elemens from the stack.
state &	push (void *p)
	Push a light userdatum on to the stack.
state &	push (table)
	Create a new table on to the stack.
state &	push (cfunction f)
	Push an C function onto the stack.
state &	push (const std::string &s)
	Push an std::string onto the stack.
state &	push (const char *s)
	Push a C-style string onto the stack.
state &	push (const char *s, size_t length)
	Push a C-style string onto the stack.
template<typename T>
state &	push (T number)
	Push a number onto the stack.
state &	push (bool boolean)
	Push a boolean onto the stack.
state &	push (nil)
	Push a nil onto the stack.
state &	push ()
	Push a nil onto the stack.
template<typename T>
state &	pushlightuserdata (T p)
	Push a light userdatum on to the stack.
state &	pushvalue (int index)
	Push a copy of the element at the given index to the top of the stack.
state &	remove (int index)
	Remove the given index from the stack.
state &	replace (int index)
	Replace the given index with the top element.
state &	setfield (const std::string &k, int index=-2)
	Set a field in a table.
state &	setglobal (const std::string &name)
	Set a global symbol.
state &	settable (int index=-3)
	Set a value in a table.
state &	settop (int index)
	Set a new index as the top of the stack.
int	size ()
	Get the number of elements in the stack.
	state (lua_State *L)
	Construct our lua environment from an existing lua_State.
	state ()
	Construct our lua environment.
template<>
state &	to (std::string &string, int index)
	Get the value at index as a string.
template<>
state &	to (bool &boolean, int index)
	Get the value at index as a bool.
template<typename T>
state &	to (T &number, int index=-1)
	Get the value at index as the given numeric type.
template<typename T>
state &	touserdata (T &p, int index=-1)
	Get the value at index as (light) userdata.
	~state ()
	Destroy our lua environment.

---

Constructor & Destructor Documentation

lua::state::state

(

lua_State *

L

)

Construct our lua environment from an existing lua_State.

Parameters:

L

the existing state to use.

This function differs from the normal constructor as it sets a flag that prevents lua_close() from being called when this class is destroyed.

Definition at line 46 of file luaxx.cc.

---

Member Function Documentation

std::string lua::state::as	(	std::string	default_value,
		int	index
	)			[inline]

Get the value at index as a string.

Parameters:

	default_value	this value is returned if the conversion fails
	index	the index to get

Note:

This function does not pop the value from the stack.

lua::state::as(std::string()) will convert the value at the indicated index to a string on the stack. This can confuse lua::state::next();

Returns:

the indicated value from the stack or the default value if the conversion fails

Definition at line 150 of file luaxx.cc.

bool lua::state::as	(	bool	default_value,
		int	index
	)			[inline]

Get the value at index as a bool.

Parameters:

	default_value	this value is returned if the conversion fails
	index	the index to get

Note:

This function does not pop the value from the stack.

Returns:

the indicated value from the stack or the default value if the conversion fails

Definition at line 667 of file luaxx.cc.

std::string lua::state::as

(

int

index = -1

)

[inline]

Get the value at index as the given type.

[specialization] Get the value at index as a string (T = std::string).

[specialization] Get the value at index as a bool (T = bool).

Template Parameters:

T

the expected type of the value

Parameters:

index

the index to get

Note:

This function does not pop the value from the stack.

The default version of this function uses lua_tonumber() but specializations may cause different behavior.

Todo:

Instead of throwing an exception here, we may just return an error code.

Exceptions:

lua::bad_conversion

if the value on the stack could not be converted to the indicated type

This function will return the value on the stack as the given type. If the value is not of the given type no conversion will be performed and lua::bad_conversion will be thrown. There are some exceptions to this rule, for example, numbers will be converted to strings and vice-versa (conversion is only performed if the matching lua_is*() function returns true). The state::to() function should be used to perform automatic conversion.

Returns:

the indicated value as the given type if possible

Note:

lua::state::as(std::string()) will convert the value at the indicated index to a string on the stack. This can confuse lua::state::next();

Definition at line 378 of file luaxx.hpp.

template<typename T>

T lua::state::as	(	T	default_value,
		int	index = -1
	)			[inline]

Get the value at index as the given type.

Template Parameters:

T

the type to retrieve the value on the stack as (the default template function uses lua_tonumber(), specializations may cause different behavior)

Parameters:

	default_value	this value is returned if the conversion fails
	index	the index to get

Note:

This function does not pop the value from the stack.

Returns:

the indicated value from the stack or the default value if the conversion fails

Definition at line 346 of file luaxx.hpp.

state & lua::state::call	(	int	nargs = 0,
		int	nresults = 0
	)

Call a lua function in unprotected mode.

Parameters:

	nargs	the number of args to pass to the function
	nresults	the number of values to return from the function stored.

Note:

If there is an error in the call the program will terminate.

Returns:

a reference to this lua::state

Definition at line 297 of file luaxx.cc.

state & lua::state::check	(	number &	n,
		int	narg
	)

Check an argument of the current function.

Parameters:

	n	the lua::number (lua_Number) to hold the returned value
	narg	the argument number to check

This function checks if the given argument number is a lua::number (lua_Number, a double by default).

Note:

This function is meant to be called from with in a lua::cfunction. The error throw is internal to the lua interpreter. When compiled as C++, a C++ exception is thrown, so the stack is properly unwound. This exception is not meant to be caught.

Definition at line 261 of file luaxx.cc.

state & lua::state::check	(	std::string &	s,
		int	narg
	)

Check an argument of the current function.

Parameters:

	s	the string to hold the returned value
	narg	the argument number to check

This function checks if the given argument number is a string.

Note:

This function is meant to be called from with in a lua::cfunction. The error throw is internal to the lua intrepeter. When compiled as C++, a C++ exception is thrown, so the stack is properly unwound. This exception is not meant to be caught.

Definition at line 239 of file luaxx.cc.

state & lua::state::check	(	integer &	i,
		int	narg
	)

Check an argument of the current function.

Parameters:

	i	the lua::integer (lua_Integer) to hold the returned value
	narg	the argument number to check

This function checks if the given argument number is an integer.

Note:

This is different from lua::check(int(), ...). It returns a lua::integer (lua_Integer), which may not be an int.

This function is meant to be called from with in a lua::cfunction. The error throw is internal to the lua intrepeter. When compiled as C++, a C++ exception is thrown, so the stack is properly unwound. This exception is not meant to be caught.

Definition at line 205 of file luaxx.cc.

state & lua::state::check

(

int

narg

)

Check an argument of the current function.

Parameters:

narg

the argument number to check

This function will throw a lua error if there is no argument at the given position.

Note:

This function is meant to be called from with in a lua::cfunction. The error throw is internal to the lua interpreter. When compiled as C++, a C++ exception is thrown, so the stack is properly unwound. This exception is not meant to be caught.

Definition at line 168 of file luaxx.cc.

state & lua::state::checkstack

(

int

size

)

Ensure the stack is at least the given size.

Parameters:

size

the size to use

If the stack is smaller than the given size, it will grow to the specified size.

Exceptions:

lua::exception

Thrown if the operation fails.

Returns:

a reference to this lua::state

Definition at line 311 of file luaxx.cc.

bool lua::state::empty

(

)

Check if the stack is empty.

Returns:

true if the stack is empty, false otherwise

Definition at line 348 of file luaxx.cc.

template<typename msg_t>

void lua::state::error

(

msg_t

message

)

[inline]

Generate a Lua error.

Template Parameters:

msg_t

the type of error message data (should be automatically determined)

Parameters:

message

the error message/value

Note:

This function is used to raise errors from lua::cfunctions.

This function never returns, instead it throws an exception caught by the intepreter.

Definition at line 406 of file luaxx.hpp.

References push().

state & lua::state::getfield	(	const std::string &	k,
		int	index = -1
	)

Get a value from a table on the stack.

Parameters:

	k	the key
	index	the index the table is stored at

This function gets a value from the table at the given index and pushes it onto the stack.

Returns:

a reference to this lua::state

Definition at line 459 of file luaxx.cc.

state & lua::state::getglobal

(

const std::string &

name

)

Load a global symbol onto the stack.

Parameters:

name

the name of the global to load

This function loads a global symbol onto the stack from the lua state.

Returns:

a reference to this lua::state

Definition at line 567 of file luaxx.cc.

bool lua::state::getmetatable

(

int

index

)

Get the metatable of the value at the given index.

Parameters:

index

the index the value is stored at

This function pushes on to the stack the metatabe of the value at the given index.

Note:

This function uses lua_getmetatable() internally.

Returns:

false if the value at the given index does not have a metatable or if the index is not valid

Definition at line 520 of file luaxx.cc.

state & lua::state::getmetatable

(

const std::string &

tname

)

Get the metatable associated with the given registry entry.

Parameters:

tname

the name in the registry

This function gets the metatable associated with the given key in the registry. The resulting metatable is pushed onto the stack.

Note:

This function uses luaL_getmetatable() internally.

Returns:

a reference to this lua::state

Definition at line 504 of file luaxx.cc.

state & lua::state::gettable

(

int

index = -2

)

Get a value from a table on the stack.

Parameters:

index

the index the table is stored at

This function gets a value from the table at the given index and pushes it onto the stack.

Note:

You should have already pushed the key used to reference this value onto the stack before calling this function.

Returns:

a reference to this lua::state

Definition at line 445 of file luaxx.cc.

int lua::state::gettop

(

)

Get the number of elements in the stack.

Note:

This value is also the index of the top element.

Returns:

the number of elements in the stack

Definition at line 333 of file luaxx.cc.

state & lua::state::insert

(

int

index

)

Move the top element to the given index.

Parameters:

index

the index to insert at

Note:

All elements on top of the given index are shifted up to open space for this element.

Returns:

a reference to this lua::state

Definition at line 358 of file luaxx.cc.

bool lua::state::is< lightuserdata >

(

int

index = -1

)

[inline]

Check if the given index is of the given type (defaults to using lua_isnumber()).

[specialization] Check if the given index is light userdata (T = lua::lightuserdata).

[specialization] Check if the given index is userdata (T = lua::userdata).

[specialization] Check if the given index is a function (T = lua::function).

[specialization] Check if the given index is a C function (T = lua::cfunction).

[specialization] Check if the given index is a table (T = lua::table).

[specialization] Check if the given index is a string (T = std::string).

[specialization] Check if the given index is a boolean (T = bool).

[specialization] Check if the given index is a nil (T = lua::nil).

Template Parameters:

T

the type to check for (the default, if no specializations match, does lua_isnumber())

Parameters:

index

the index to check

Note:

the default version (used if no specialization is matched) will check if the given value is a number

Returns:

whether the value at the given index is a nil

Definition at line 287 of file luaxx.hpp.

template<typename iterator_t>

state & lua::state::load	(	iterator_t	begin,
		iterator_t	end
	)			[inline]

Load a sequence of data as a Lua chunk.

Template Parameters:

iterator_t

the type of iterator to use (should be automatically determined)

Parameters:

	begin	an iterator to the start of the sequence
	end	an iterator to the end of the sequence (one past the end)

This function takes a sequence of data and attempts to convert it into a Lua chunk. The type of data passed must be able to be converted into an 8-bit char.

Note:

This function should automatically detect if the data is text or binary.

Returns:

a reference to this lua::state

Definition at line 428 of file luaxx.hpp.

state & lua::state::loadfile

(

const std::string &

filename

)

Load a file as a Lua chunk.

Parameters:

filename

the name of the file to load

Returns:

a reference to this lua::state

Definition at line 592 of file luaxx.cc.

state & lua::state::loadstring

(

const std::string &

s

)

Load a string as a Lua chunk.

Parameters:

s

the string to load

Returns:

a reference to this lua::state

Definition at line 601 of file luaxx.cc.

bool lua::state::newmetatable

(

const std::string &

tname

)

Create a new metatable and add it to the registry.

Parameters:

tname

the name to use for the new metatable in the registry

This function creates a new metatable and adds it to the registry with the given key. This function also pushes the new metatable onto the stack.

Note:

Regardless of the return value, the new metatable is always pushed on to the stack.

Returns:

true if a new metatable was created, false if the registry alread has a key with the given name.

Definition at line 422 of file luaxx.cc.

state & lua::state::newtable

(

)

Create a new table on the stack.

Returns:

a reference to this lua::state

Definition at line 404 of file luaxx.cc.

void * lua::state::newuserdata

(

size_t

nbytes

)

Create a new userdatum on the stack.

Parameters:

nbytes

the size of the new userdatum

Returns:

a pointer to the new userdatum

Definition at line 430 of file luaxx.cc.

template<typename userdata_t>

userdata_t * lua::state::newuserdata

(

)

[inline]

Create a new userdatum on the stack.

Template Parameters:

userdata_t

the type of the userdata (will be passed to sizeof())

This function creates a new userdatum on the stack the size of userdata_t and return a pointer to it.

Returns:

a pointer to the new userdatum

Definition at line 393 of file luaxx.hpp.

bool lua::state::next

(

int

index = -2

)

Get the next key value pair from a table on the stack.

Parameters:

index

the stack index the table is at

This function pops a key from the stack and pushes the next key value pair to the stack. The key will be stored at index -2 and the value will be at index -1. The key is expected to be on the top of the stack.

Note:

While traversing a table, do not call lua::state::to(std::string()) directly on a key, unless you know that the key is actually a string. lua::state::to(std::string()) changes the value at the given index; this confuses the next call to lua::state::next().

While Loop Example:

 while(L.next() != 0) {
    // do stuff
    L.pop();
 }

For Loop Example:

 for(L.push(lua::nil()); L.next(); L.pop()) {
    // do stuff
 }

Returns:

true as long as there are remaining items in the table

Definition at line 555 of file luaxx.cc.

size_t lua::state::objlen

(

int

index = -1

)

Get the length of a value on the stack.

Parameters:

index

the index the value is stored at

Returns:

the length of the indicated value

Definition at line 610 of file luaxx.cc.

lua::state::operator lua_State *

(

)

[inline]

Convert a lua::state to a lua_State*.

This operator allows lua::state to behave like a lua_State pointer.

Note:

This should be used as a last result to interoperate with C code. This may be removed in future versions of Luaxx.

Definition at line 467 of file luaxx.hpp.

state & lua::state::pcall	(	int	nargs = 0,
		int	nresults = 0,
		int	on_error = 0
	)

Call a lua function.

Parameters:

	nargs	the number of args to pass to the function
	nresults	the number of values to return from the function
	on_error	A stack index where the error handling function is stored.

Note:

The error handling function must be pushed in the stack before the function to be called and its arguments.

Returns:

a reference to this lua::state

Definition at line 285 of file luaxx.cc.

state & lua::state::pop

(

int

elements = 1

)

Remove the given number of elemens from the stack.

Parameters:

elements

the number of elements to remove

Returns:

a reference to this lua::state

Definition at line 386 of file luaxx.cc.

state & lua::state::push

(

void *

p

)

Push a light userdatum on to the stack.

Parameters:

p

the pointer to push

Returns:

a reference to this lua::state

Definition at line 132 of file luaxx.cc.

state & lua::state::push

(

table

)

Create a new table on to the stack.

See also:

state::newtable()

Returns:

a reference to this lua::state

Definition at line 123 of file luaxx.cc.

state & lua::state::push

(

cfunction

f

)

Push an C function onto the stack.

Parameters:

f

the function to push

Returns:

a reference to this lua::state

Definition at line 114 of file luaxx.cc.

state & lua::state::push

(

const std::string &

s

)

Push an std::string onto the stack.

Parameters:

s

the string to push

Returns:

a reference to this lua::state

Definition at line 105 of file luaxx.cc.

state & lua::state::push

(

const char *

s

)

Push a C-style string onto the stack.

Parameters:

s

the string to push

Note:

This must be a '0' terminated string.

Returns:

a reference to this lua::state

Definition at line 96 of file luaxx.cc.

state & lua::state::push	(	const char *	s,
		size_t	length
	)

Push a C-style string onto the stack.

Parameters:

	s	the string to push
	length	the length of the string

Returns:

a reference to this lua::state

Definition at line 86 of file luaxx.cc.

template<typename T>

state & lua::state::push

(

T

number

)

[inline]

Push a number onto the stack.

Template Parameters:

T

the numeric type to push (should be automatically determined, if there is no specialization for the desired type, lua_pushnumber() will be used, and may fail)

Parameters:

number

the number to push

Returns:

a reference to this lua::state

Definition at line 261 of file luaxx.hpp.

state & lua::state::push

(

bool

boolean

)

Push a boolean onto the stack.

Parameters:

boolean

the value to push

Returns:

a reference to this lua::state

Definition at line 76 of file luaxx.cc.

state & lua::state::push

(

nil

)

Push a nil onto the stack.

Returns:

a reference to this lua::state

Definition at line 67 of file luaxx.cc.

state & lua::state::push

(

)

Push a nil onto the stack.

Returns:

a reference to this lua::state

Definition at line 59 of file luaxx.cc.

Referenced by error().

template<typename T>

state & lua::state::pushlightuserdata

(

T

p

)

[inline]

Push a light userdatum on to the stack.

Template Parameters:

T

the type of data to push (should be automatically determined)

Parameters:

p

the pointer to push

Returns:

a reference to this lua::state

Definition at line 272 of file luaxx.hpp.

state & lua::state::pushvalue

(

int

index

)

Push a copy of the element at the given index to the top of the stack.

Parameters:

index

the index of the element to copy

Returns:

a reference to this lua::state

Definition at line 396 of file luaxx.cc.

state & lua::state::remove

(

int

index

)

Remove the given index from the stack.

Parameters:

index

the index to remove

Note:

Elements are shifted down to fill in the empty spot.

Returns:

a reference to this lua::state

Definition at line 377 of file luaxx.cc.

state & lua::state::replace

(

int

index

)

Replace the given index with the top element.

Parameters:

index

the index to replae

Returns:

a reference to this lua::state

Definition at line 367 of file luaxx.cc.

Referenced by to().

state & lua::state::setfield	(	const std::string &	k,
		int	index = -2
	)

Set a field in a table.

Parameters:

	k	the key
	index	the index the table is stored at

This function sets a value in a table stored at the given index.

Note:

The value to be used should be on the top of the stack.

Returns:

a reference to this lua::state

Definition at line 489 of file luaxx.cc.

state & lua::state::setglobal

(

const std::string &

name

)

Set a global symbol.

Parameters:

name

the name of the global to set

This function sets/creates a global symbol from the value above it on the stack.

Note:

You should have pushed the value of the symbol onto the stack before calling this function.

Returns:

a reference to this lua::state

Definition at line 583 of file luaxx.cc.

state & lua::state::settable

(

int

index = -3

)

Set a value in a table.

Parameters:

index

the index the table is stored at

This function sets a value in a table stored at the given index.

Note:

The key and value to be used should have already been pushed on the stack in that order.

Returns:

a reference to this lua::state

Definition at line 474 of file luaxx.cc.

state & lua::state::settop

(

int

index

)

Set a new index as the top of the stack.

Parameters:

index

the index to use as the new top

Note:

If the previous top was higher than the new one, top values are discarded. Otherwise this function pushs nils on to the stack to get the proper size.

Returns:

a reference to this lua::state

Definition at line 324 of file luaxx.cc.

int lua::state::size

(

)

Get the number of elements in the stack.

Note:

This value is also the index of the top element.

Returns:

the number of elements in the stack

Definition at line 341 of file luaxx.cc.

state & lua::state::to	(	std::string &	string,
		int	index
	)			[inline]

Get the value at index as a string.

Parameters:

	string	where to store the value
	index	the index to get

Note:

This function does not pop the value from the stack.

Todo:

Instead of throwing an exception here, we may just return an error code.

Note:

lua::state::to(std::string()) will convert the value at the indicated index to a string on the stack. This can confuse lua::state::next();

Exceptions:

lua::bad_conversion

if the value on the stack could not be converted to the indicated type

Returns:

a reference to this lua::state

Definition at line 650 of file luaxx.cc.

References replace().

state & lua::state::to	(	bool &	boolean,
		int	index
	)			[inline]

Get the value at index as a bool.

Parameters:

	boolean	where to store the value
	index	the index to get

Note:

This function does not pop the value from the stack.

Todo:

Instead of throwing an exception here, we may just return an error code.

Exceptions:

lua::bad_conversion

if the value on the stack could not be converted to the indicated type

Returns:

a reference to this lua::state

Definition at line 625 of file luaxx.cc.

template<typename T>

state & lua::state::to	(	T &	number,
		int	index = -1
	)			[inline]

Get the value at index as the given numeric type.

Template Parameters:

T

they numeric type to static_cast<T>() the numeric value on the stack to

Parameters:

	number	where to store the value
	index	the index to get

Note:

This function does not pop the value from the stack.

Todo:

Instead of throwing an exception here, we may just return an error code.

Exceptions:

lua::bad_conversion

if the value on the stack could not be converted to the indicated type

Returns:

a reference to this lua::state

Definition at line 304 of file luaxx.hpp.

template<typename T>

state & lua::state::touserdata	(	T &	p,
		int	index = -1
	)			[inline]

Get the value at index as (light)