Access point to Lua context. More...

Classes
class	Registry
	Type of registry accessor. More...

Public Types
enum	InitializeExplicitly
	Static constant to signal explicit context construction.

Public Member Functions
Life cycle
	Context (lua_State *s, const InitializeExplicitly &) noexcept
	Explicit construction. More...

	Context (const Context &)=delete
	Copying is prohibited.

Context &	operator= (const Context &)=delete
	Assignment to Context is prohibited.

Returning values
template<typename... ValueTypes>
Retval	ret (ValueTypes &&...values)
	Return arbitrary number of values. More...

Retval	ret (const Valset &vs) noexcept
	Return a single value set. More...

Error handling
Temporary	where ()
	Create a value that describes current call context.

Retval	error (Valobj msg)
	Report an error to Lua. This function never returns. More...

Retval	error ()
	Report error to Lua. This function never returns. More...

Memory control
void	gcCollect () noexcept
	Perform full garbage collection cycle.

void	gcStop () noexcept
	Stop automatic garbage collection.

void	gcResume () noexcept
	Resume automatic garbage collection.

bool	gcIsRunning () const noexcept
	Check if automatic garbaghe collection is running [Lua 5.2+ only].

size_t	queryMemoryTotal () const noexcept
	Query allocated memory amount. More...

Function handling
template<typename... UpvalueTypes>
Temporary	closure (CFunction fn, UpvalueTypes &&...upvalues_) noexcept
	Create a closure from C function.

template<typename... UpvalueTypes>
Temporary	closure (CFunction fn, UpvalueTypes &&...upvalues_) noexcept
	Create a closure from LFunction. More...

template<typename ReturnValueType , typename... ArgTypes>
Temporary	wrap (ReturnValueType(*fn)(ArgTypes...)) noexcept
	Create a wrapped Lua-compatible function from generic C/C++ function. More...

template<typename Host , typename ReturnValueType , typename... ArgTypes>
Temporary	wrap (ReturnValueType(Host::*fn)(ArgTypes...)) noexcept
	Create a wrapped Lua-compatible function from member function. More...

template<typename ReturnValueType , typename... ArgTypes>
Temporary	vwrap (ReturnValueType(*fn)(ArgTypes...)) noexcept
	Create a wrapped Lua-compatible function from generic C++ function discarding the call result. More...

template<typename Host , typename ReturnValueType , typename... ArgTypes>
Temporary	vwrap (ReturnValueType(Host::*fn)(ArgTypes...)) noexcept
	Create a wrapped Lua-compatible function from member function discarding the call result. More...

Temporary	chunk (const char *chunkText) noexcept
	Compile a string into a chunk. More...

Temporary	chunk (const std::string &chunkText) noexcept
	Compile a string into a chunk. More...

Temporary	load (const char *fileName) noexcept
	Load a file as chunk. More...

Temporary	load (const std::string &fileName) noexcept
	Load a file as chunk. More...

void	runString (const char *command)
	Run a command string. More...

void	runString (const std::string &command)
	Run a command string. More...

void	runFile (const char *fileName)
	Execute file. More...

void	runFile (const std::string &fileName)
	Execute file. More...

Metatables
template<typename UD >
Temporary	mt () noexcept
	Metatable accessor for user data type. More...

General information
int	getVersion () const noexcept
	Version number (major * 100 + minor) [Lua 5.2+ only].

Direct Lua API interaction
	operator::lua_State * () const noexcept
	Access to raw state pointer via implicit conversion.

size_t	getTop () const noexcept
	Current stack size.

Accessor objects and accompanying functions
GlobalIndexer	global
	Global variable accessor. More...

UpvalueIndexer	upvalues
	Upvalue accessor. More...

const Valset	args
	Function arguments. More...

Registry	registry
	Registry accessor. More...

template<typename... ArgTypes>
bool	checkArgs (size_t amount=0) noexcept
	Check for function arguments and count. More...

template<typename... ArgTypes>
void	requireArgs (size_t amount=0)
	Check for function arguments and count and report an error in case of failure. More...

Detailed Description

Access point to Lua context.

This object is passed to compatible functions. It gives access to function's arguments, global variables and so on. Context is used to access general Lua functions such as garbage collector or memory monitoring, and to return values or report errors.

Constructor & Destructor Documentation

Context	(	lua_State *	s,
		const InitializeExplicitly &
	)

noexcept

Explicit construction.

Sometimes it is necessary to use Lua API++ features outside of compatible function. You may construct a Context object explicitly using this constructor as follows:

Context c(luaStatePtr, Context::initializeExplicitly);

Warning: This operation is considered unsafe. Be careful with stack manipulations and do not create duplicates of Context object.

Member Function Documentation

Retval ret ( ValueTypes &&... values )

inline

Return arbitrary number of values.

Pass values to be returned from the function to this function in return operator.

Note: After calling this function, automatic stack management stops functioning in order to preserve return values.

Warning: Use this function only in return operator!

Retval ret ( const Valset & vs )

inlinenoexcept

Return a single value set.

Special case: all values that reside on stack after the set are dropped, and the values belonging to the set are used directly as multiple return values, without copying.

Note: After calling this function, automatic stack management stops functioning in order to preserve return values.

Warning: Use this function only in return operator!

Retval error ( Valobj msg )

Report an error to Lua. This function never returns.

Recommended use:

return context.error(msg);

Retval error ( )

Report error to Lua. This function never returns.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Recommended use:

return context.error();

Default message will be the result of where function.

size_t queryMemoryTotal ( ) const

noexcept

Query allocated memory amount.

Returns: Number of bytes allocated by Lua.

Temporary closure	(	CFunction	fn,
		UpvalueTypes &&...	upvalues_
	)

noexcept

Create a closure from LFunction.

All closures created by this function share common wrapper.

Warning: The wrapper is using first upvalue (index 1) internally. Provided upvalues (if any) start at index 2. This holds true for automatically promoted LFunctions too.

Temporary wrap ( ReturnValueType(*)(ArgTypes...) fn )

noexcept

Create a wrapped Lua-compatible function from generic C/C++ function.

This function will create a Lua function wrapper that converts Lua arguments into native values, calls the C function with those arguments and converts the return value back into Lua value.

See also: LUAPP_ARG_CONVERT; LUAPP_RV_CONVERT

Temporary wrap ( ReturnValueType(Host::*)(ArgTypes...) fn )

noexcept

Create a wrapped Lua-compatible function from member function.

This function will create a Lua function wrapper that converts Lua arguments into native values, calls the C function with those arguments and converts the return value back into Lua value. First argument is expected to be convertible to Host.

See also: LUAPP_ARG_CONVERT; LUAPP_RV_CONVERT

Temporary vwrap ( ReturnValueType(*)(ArgTypes...) fn )

noexcept

Create a wrapped Lua-compatible function from generic C++ function discarding the call result.

This function will create a Lua function wrapper that converts Lua arguments into native values, calls the C function with those arguments, discards call result and returns nothing.

See also: LUAPP_ARG_CONVERT

Temporary vwrap ( ReturnValueType(Host::*)(ArgTypes...) fn )

noexcept

Create a wrapped Lua-compatible function from member function discarding the call result.

This function will create a Lua function wrapper that converts Lua arguments into native values, calls the C function with those arguments and converts the return value back into Lua value. First argument is expected to be convertible to Host.

See also: LUAPP_ARG_CONVERT

Temporary chunk ( const char * chunkText )

noexcept

Compile a string into a chunk.

Precondition: chunkText != nullptr

Exceptions

std::runtime_error on compilation failure (syntax errors). Exception object will contain error description.

Temporary chunk ( const std::string & chunkText )

noexcept

Compile a string into a chunk.

Exceptions

std::runtime_error on compilation failure (syntax errors). Exception object will contain error description. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Temporary load ( const char * fileName )

noexcept

Load a file as chunk.

Precondition: fileName != nullptr

Exceptions

std::runtime_error on compilation failure (file missing or syntax errors). Exception object will contain error description.

Temporary load ( const std::string & fileName )

noexcept

Load a file as chunk.

Exceptions

std::runtime_error on compilation failure (file missing or syntax errors). Exception object will contain error description. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void runString ( const char * command )

inline

Run a command string.

Precondition: command != nullptr

Exceptions

std::runtime_error on compilation or execution failure. Exception object will contain error description.

void runString ( const std::string & command )

inline

Run a command string.

Exceptions

std::runtime_error on compilation or execution failure. Exception object will contain error description. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void runFile ( const char * fileName )

inline

Execute file.

Precondition: fileName != nullptr

Exceptions

std::runtime_error on compilation or execution failure. Exception object will contain error description.

void runFile ( const std::string & fileName )

inline

Execute file.

Exceptions

std::runtime_error on compilation or execution failure. Exception object will contain error description. This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Temporary mt ( )

noexcept

Metatable accessor for user data type.

Use this function to retrieve or set metatable for registered userdata. The userdata type is specified explicitly with this function.

Note: This is a better alternative to using registry with type description strings.

See also: LUAPP_USERDATA

bool checkArgs ( size_t amount = 0 )

inlinenoexcept

Check for function arguments and count.

Checks args for existence of arguments of specified types. The function checks for presence of arguments convertible to types specified in template parameters. If "amount" is bigger than the number of template parameters, the function also checks that args.size() >= amount. Example: c.checkArgs<double, string>(4); checks that 4 arguments were passed to the function, first of which is a number and the second is a string.

Note: void is acceptable in template parameter list as a "placeholder" type, matching any type of value.

Parameters

amount Minimum amount of arguments that must be present on the stack.

Returns: true if required amount of arguments of required types is present, false otherwise.

See also: requireArgs

void requireArgs ( size_t amount = 0 )

Check for function arguments and count and report an error in case of failure.

Checks args for existence of arguments of specified types. The function checks for presence of arguments convertible to types specified in template parameters. If "amount" is bigger than the number of template parameters, the function also checks that args.size() >= amount. If the specification is not met, Lua error with diagnostic message is raised.

Note: void is acceptable in template parameter list as a "placeholder" type, matching any type of value.

Parameters

amount Minimum amount of arguments that must be present on the stack.

See also: checkArgs

Member Data Documentation

GlobalIndexer global

Global variable accessor.

Indexed with strings (const char* and std::string).

UpvalueIndexer upvalues

Upvalue accessor.

Indexed with 1-based integer indices.

const Valset args

Function arguments.

See also: lua::Valset

Registry registry

Registry accessor.

use int key = registry.store(any_value); to get integer key for stored value;
index registry with integer keys to access stored values;
index registry with type-associated strings to access userdata metatables (or better use mt function instead).

Classes

Public Types

Public Member Functions

Accessor objects and accompanying functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation