Convenience functions for running Lua code. More...

Detailed Description

Convenience functions for running Lua code.

Author: Juan Carrano j.car.nosp@m.rano.nosp@m.@fu-b.nosp@m.erli.nosp@m.n.de

This functions make it easy to create and use new Lua context: It provides:

Easy to use routines for executing modules as scrips.
Control over which modules get loaded.
Support for using a local heap allocator.
Out of memory handling via setjmp/longjmp.

This library is not strictly required, as all of the functionality could be implemented in terms of the public lua api, but it covers most of the use cases, and thus avoids code repetition in applications.

Definition in file lua_run.h.

#include <stdint.h>
#include "lua.h"

Include dependency graph for lua_run.h:

Go to the source code of this file.

#define	LUAR_LOAD_FLAG(n) (((uint16_t)1) << (n))
	Convert a library index into a bit mask.

#define	LUAR_LOAD_BASE LUAR_LOAD_FLAG(LUAR_LOAD_O_BASE)
	Load the base globals (_G)

#define	LUAR_LOAD_PACKAGE LUAR_LOAD_FLAG(LUAR_LOAD_O_PACKAGE)
	Load ´package´

#define	LUAR_LOAD_CORO LUAR_LOAD_FLAG(LUAR_LOAD_O_CORO)
	Load ´coroutine´

#define	LUAR_LOAD_TABLE LUAR_LOAD_FLAG(LUAR_LOAD_O_TABLE)
	Load ´table´

#define	LUAR_LOAD_IO LUAR_LOAD_FLAG(LUAR_LOAD_O_IO)
	Load ´io´

#define	LUAR_LOAD_OS LUAR_LOAD_FLAG(LUAR_LOAD_O_OS)
	Load ´os´

#define	LUAR_LOAD_STRING LUAR_LOAD_FLAG(LUAR_LOAD_O_STRING)
	Load ´string´

#define	LUAR_LOAD_MATH LUAR_LOAD_FLAG(LUAR_LOAD_O_MATH)
	Load ´math´

#define	LUAR_LOAD_UTF8 LUAR_LOAD_FLAG(LUAR_LOAD_O_UTF8)
	Load ´utf8´

#define	LUAR_LOAD_DEBUG LUAR_LOAD_FLAG(LUAR_LOAD_O_DEBUG)
	Load ´debug´

#define	LUAR_LOAD_ALL (0xFFFF) /** Load all standard modules */

#define	LUAR_LOAD_NONE (0x0000) /** Do not load any modules */

#define	lua_riot_close lua_close
	Terminate the lua state. More...

enum	LUAR_LOAD_ORDER { LUAR_LOAD_O_BASE, LUAR_LOAD_O_PACKAGE, LUAR_LOAD_O_CORO, LUAR_LOAD_O_TABLE, LUAR_LOAD_O_IO, LUAR_LOAD_O_OS, LUAR_LOAD_O_STRING, LUAR_LOAD_O_MATH, LUAR_LOAD_O_UTF8, LUAR_LOAD_O_DEBUG, LUAR_LOAD_O_ALL }
	Order in which the builtin libraries are loaded.

enum	LUAR_ERRORS { LUAR_EXIT, LUAR_STARTUP_ERR, LUAR_LOAD_ERR, LUAR_NOMODULE, LUAR_COMPILE_ERR, LUAR_RUNTIME_ERR, LUAR_MEMORY_ERR, LUAR_INTERNAL_ERR }
	Errors that can be raised when running lua code. More...

const char *	lua_riot_str_errors []
	Human-readable description of the errors.

const LUALIB_API char *	lua_riot_strerror (int errn)
	Return a string describing an error from LUAR_ERRORS. More...

LUALIB_API lua_State *	lua_riot_newstate (void *memory, size_t mem_size, lua_CFunction panicf)
	Initialize a lua state and set the panic handler. More...

LUALIB_API int	lua_riot_openlibs (lua_State *L, uint16_t modmask)
	Open builtin libraries. More...

LUALIB_API int	lua_riot_do_module (const char modname, void memory, size_t mem_size, uint16_t modmask, int *retval)
	Initialize the interpreter and run a built-in module in protected mode. More...

LUALIB_API int	lua_riot_do_buffer (const uint8_t buf, size_t buflen, void memory, size_t mem_size, uint16_t modmask, int *retval)
	Initialize the interpreter and run a user supplied buffer in protected mode. More...

Macro Definition Documentation

◆ lua_riot_close

#define lua_riot_close lua_close

Terminate the lua state.

You must call this function if you want the finalizers (the __gc metamethods) to be called.

Definition at line 147 of file lua_run.h.

Enumeration Type Documentation

◆ LUAR_ERRORS

enum LUAR_ERRORS

Errors that can be raised when running lua code.

Enumerator
LUAR_STARTUP_ERR	The program exited without error.
LUAR_LOAD_ERR	Error setting up the interpreter.
LUAR_NOMODULE	Error while loading libraries.
LUAR_COMPILE_ERR	The specified module could not be found.
LUAR_RUNTIME_ERR	The Lua code failed to compile.
LUAR_MEMORY_ERR	Error in code execution.
LUAR_INTERNAL_ERR	Lua could not allocate enough memory. Error inside the Lua VM. Right now, if this happens, you may leak memory from the heap. If your program is the only one using the dynamic allocation, just clean the heap.

Definition at line 91 of file lua_run.h.

Function Documentation

◆ lua_riot_do_buffer()

LUALIB_API int lua_riot_do_buffer	(	const uint8_t *	buf,
		size_t	buflen,
		void *	memory,
		size_t	mem_size,
		uint16_t	modmask,
		int *	retval
	)

Initialize the interpreter and run a user supplied buffer in protected mode.

Only text data (i.e. lua source code) can be loaded by this function. The lua interpreter is not robust against corrupt binary code.

See also: lua_riot_do_module() for more information on internal errors.

Parameters

buf	Text data (lua source code).
buflen	Size of the text data in bytes. If buf is a zero-terminated string, the zero must not be counted.
memory

See also: lua_riot_newstate()

Parameters

mem_size

See also: lua_riot_newstate()

Parameters

modmask

See also: lua_riot_newstate()

Parameters

[out] retval

See also: lua_riot_do_module()

Returns

See also: lua_riot_do_module().

◆ lua_riot_do_module()

LUALIB_API int lua_riot_do_module	(	const char *	modname,
		void *	memory,
		size_t	mem_size,
		uint16_t	modmask,
		int *	retval
	)

Initialize the interpreter and run a built-in module in protected mode.

In addition to running code in protected mode, this also sets a panic function that long-jumps back to this function, in case there is an internal interpreter error (LUAR_INTERNAL_ERR). Right now the only things that the application can are either to abort(), or to manually reset the heap (only if there's no other thread using it).

Parameters

modname	name of the module.
memory

See also: lua_riot_newstate()

Parameters

mem_size

See also: lua_riot_newstate()

Parameters

modmask

See also: lua_riot_newstate()

Parameters

[out] retval Value returned by the lua code, if it is a number, or zero if no value is returned or the value is not a number. If retval is null, the value is not stored.

Returns: An error code (

See also: LUAR_ERRORS). LUAR_EXIT indicates no error.

◆ lua_riot_newstate()

LUALIB_API lua_State* lua_riot_newstate	(	void *	memory,
		size_t	mem_size,
		lua_CFunction	panicf
	)

Initialize a lua state and set the panic handler.

Todo:: Use a per-state allocator

Parameters

memory	Pointer to memory region that will be used as heap for the allocator. Currently this functionality is not supported and this must be set to NULL.
mem_size	Size of the memory region that will be used as heap. Currently this functionality is not supported and this must be set to 0.
panicf	Function to be passed to lua_atpanic. If set to NULL, a generic function that does nothing will be used.

Returns: the new state, or NULL if there is a memory allocation error.

◆ lua_riot_openlibs()

LUALIB_API int lua_riot_openlibs	(	lua_State *	L,
		uint16_t	modmask
	)

Open builtin libraries.

This is like luaL_openlibs but it allows selecting which libraries will be loaded.

Libraries are loaded in the order specified by the LUAR_LOAD_ORDER enum. If there is an error the load sequence is aborted and the index of the library that failed is reported.

If debugging is enabled (compile with the LUA_DEBUG macro), then the test library will be unconditionally loaded.

Parameters

L	Lua state
modmask	Binary mask that indicates which modules should be loaded. The mask is made from a combination of the LUAR_LOAD_* macros.

Returns: The index of the library that failed to load, or LUAR_LOAD_O_ALL if all libraries were loaded.

◆ lua_riot_strerror()

const LUALIB_API char* lua_riot_strerror ( int errn )

Return a string describing an error from LUAR_ERRORS.

Parameters

errn	Error number as returned by lua_riot_do_buffer() or lua_riot_do_buffer()

Returns: A string describing the error, or "Unknown error".