lua_run.h

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 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.

LUAR_LOAD_FLAG( n)

Convert a library index into a bit mask. 

1
(((uint16_t)1) << (n))
LUAR_LOAD_BASE

Load the base globals (_G) 

1
LUAR_LOAD_FLAG(LUAR_LOAD_O_BASE)
LUAR_LOAD_PACKAGE

Load ´package´ 

1
LUAR_LOAD_FLAG(LUAR_LOAD_O_PACKAGE)
LUAR_LOAD_CORO

Load ´coroutine´ 

1
LUAR_LOAD_FLAG(LUAR_LOAD_O_CORO)
LUAR_LOAD_TABLE

Load ´table´ 

1
LUAR_LOAD_FLAG(LUAR_LOAD_O_TABLE)
LUAR_LOAD_IO

Load ´io´ 

1
LUAR_LOAD_FLAG(LUAR_LOAD_O_IO)
LUAR_LOAD_OS

Load ´os´ 

1
LUAR_LOAD_FLAG(LUAR_LOAD_O_OS)
LUAR_LOAD_STRING

Load ´string´ 

1
LUAR_LOAD_FLAG(LUAR_LOAD_O_STRING)
LUAR_LOAD_MATH

Load ´math´ 

1
LUAR_LOAD_FLAG(LUAR_LOAD_O_MATH)
LUAR_LOAD_UTF8

Load ´utf8´ 

1
LUAR_LOAD_FLAG(LUAR_LOAD_O_UTF8)
LUAR_LOAD_DEBUG

Load ´debug´ 

1
LUAR_LOAD_FLAG(LUAR_LOAD_O_DEBUG)
LUAR_LOAD_ALL
1
(0xFFFF)               /** Load all standard modules */
LUAR_LOAD_NONE
1
(0x0000)               /** Do not load any modules */
lua_riot_close

Terminate the lua state. 

1
lua_close

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

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
enum LUAR_ERRORS
LUAR_EXIT
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.

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.

Parameters

errn:Error number as returned by lua_run.h::lua_riot_do_buffer() or lua_run.h::lua_riot_do_buffer()

Return values

  • A string describing the error, or “Unknown error”.
LUALIB_API lua_State * lua_riot_newstate(void * memory, msp430_types.h::size_t mem_size, lua_CFunction panicf)

Initialize a lua state and set the panic handler.

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.

Return values

  • the new state, or NULL if there is a memory allocation error.
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 debuging 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.

Return values

  • The index of the library that failed to load, or LUAR_LOAD_O_ALL if all libraries were loaded.
LUALIB_API int lua_riot_do_module(const char * modname, void * memory, msp430_types.h::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_run.h::lua_riot_newstate()

Parameters

mem_size:

See also

lua_run.h::lua_riot_newstate()

Parameters

modmask:

See also

lua_run.h::lua_riot_newstate()

Parameters

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.

See also

lua_run.h::LUAR_ERRORS). LUAR_EXIT indicates no error.

Return values

  • An error code (
LUALIB_API int lua_riot_do_buffer(const uint8_t * buf, msp430_types.h::size_t buflen, void * memory, msp430_types.h::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_run.h::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_run.h::lua_riot_newstate()

Parameters

mem_size:

See also

lua_run.h::lua_riot_newstate()

Parameters

modmask:

See also

lua_run.h::lua_riot_newstate()

Parameters

retval:

See also

lua_run.h::lua_riot_do_module()

See also

lua_run.h::lua_riot_do_module().

Return values