lua_run.h File Reference

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

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
bufText data (lua source code).
buflenSize 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
modnamename 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]retvalValue 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
memoryPointer 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_sizeSize of the memory region that will be used as heap. Currently this functionality is not supported and this must be set to 0.
panicfFunction 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
LLua state
modmaskBinary 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
errnError number as returned by lua_riot_do_buffer() or lua_riot_do_buffer()
Returns
A string describing the error, or "Unknown error".