Convenience functions for running Lua code. More...
Detailed Description
Convenience functions for running Lua code.
This functions make it easy to create and use new Lua context: It provides:
- Easy to use routines for executing modules as scripts.
- 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. | |
| 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. More... | |
| 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. | |
| LUALIB_API const char * | lua_riot_strerror (int errn) |
| Return a string describing an error from LUAR_ERRORS. | |
| 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. | |
| LUALIB_API int | lua_riot_openlibs (lua_State *L, uint16_t modmask) |
| Open builtin libraries. | |
| 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. | |
| 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. | |
Macro Definition Documentation
◆ lua_riot_close
| #define lua_riot_close lua_close |
◆ LUAR_LOAD_ALL
| #define LUAR_LOAD_ALL (0xFFFF) /** Load all standard modules */ |
◆ LUAR_LOAD_BASE
| #define LUAR_LOAD_BASE LUAR_LOAD_FLAG(LUAR_LOAD_O_BASE) |
◆ LUAR_LOAD_CORO
| #define LUAR_LOAD_CORO LUAR_LOAD_FLAG(LUAR_LOAD_O_CORO) |
◆ LUAR_LOAD_DEBUG
| #define LUAR_LOAD_DEBUG LUAR_LOAD_FLAG(LUAR_LOAD_O_DEBUG) |
◆ LUAR_LOAD_FLAG
| #define LUAR_LOAD_FLAG | ( | n | ) | (((uint16_t)1) << (n)) |
◆ LUAR_LOAD_IO
| #define LUAR_LOAD_IO LUAR_LOAD_FLAG(LUAR_LOAD_O_IO) |
◆ LUAR_LOAD_MATH
| #define LUAR_LOAD_MATH LUAR_LOAD_FLAG(LUAR_LOAD_O_MATH) |
◆ LUAR_LOAD_NONE
| #define LUAR_LOAD_NONE (0x0000) /** Do not load any modules */ |
◆ LUAR_LOAD_OS
| #define LUAR_LOAD_OS LUAR_LOAD_FLAG(LUAR_LOAD_O_OS) |
◆ LUAR_LOAD_PACKAGE
| #define LUAR_LOAD_PACKAGE LUAR_LOAD_FLAG(LUAR_LOAD_O_PACKAGE) |
◆ LUAR_LOAD_STRING
| #define LUAR_LOAD_STRING LUAR_LOAD_FLAG(LUAR_LOAD_O_STRING) |
◆ LUAR_LOAD_TABLE
| #define LUAR_LOAD_TABLE LUAR_LOAD_FLAG(LUAR_LOAD_O_TABLE) |
◆ LUAR_LOAD_UTF8
| #define LUAR_LOAD_UTF8 LUAR_LOAD_FLAG(LUAR_LOAD_O_UTF8) |
Enumeration Type Documentation
◆ LUAR_ERRORS
| enum LUAR_ERRORS |
Errors that can be raised when running lua code.
◆ LUAR_LOAD_ORDER
| enum LUAR_LOAD_ORDER |
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()
| LUALIB_API const 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".
