Fengari Documentation

Because Lua strings are 8-bit clean and can contain null bytes (\0), Fengari implements them using Uint8Array objects to preserve raw bytes.

When interacting between JS and Lua:

• Pushing JS strings to Lua: Use lua_pushliteral(L, string) to convert a JS string into a byte array before pushing it to the stack.
• Getting Lua strings as JS strings: Use lua_tojsstring(L, idx) to attempt conversion to a UTF-16 JS string. Note that this may not yield expected results if the Lua string contains invalid UTF-16 sequences.
• Other conversion utilities: You can also use luastring_of, to_luastring, to_jsstring, and to_uristring for string manipulations.

Fengari provides a JavaScript API that is a direct port of the Lua C API. The fengari object exposes modules that correspond to standard Lua C headers:

• fengari.lua: Equivalent to lua.h (constants and core functions).
• fengari.lauxlib: Equivalent to lauxlib.h (auxiliary library).
• fengari.lualib: Equivalent to lualib.h (standard Lua libraries).
• fengari.luaconf: Configuration constants.

To use it, initialize a new Lua state using lauxlib.luaL_newstate() and open the standard libraries with lualib.luaL_openlibs(L).

const luaconf  = fengari.luaconf;
const lua      = fengari.lua;
const lauxlib  = fengari.lauxlib;
const lualib   = fengari.lualib;

const L = lauxlib.luaL_newstate();

lualib.luaL_openlibs(L);

lua.lua_pushliteral(L, "hello world!");

When lualib.luaL_openlibs(L) is called, a global Lua table named fengari is automatically loaded. This table contains metadata about the current release:

• fengari.VERSION (and VERSION_MAJOR, VERSION_MINOR, VERSION_NUM, VERSION_RELEASE)
• fengari.AUTHORS
• fengari.COPYRIGHT
• fengari.RELEASE

Fengari provides proxy mechanisms to hold references to Lua values in JavaScript.

• lua_toproxy(L, idx): Returns a JavaScript object p that holds a reference to the Lua value at stack index idx. This object can be called with a lua_State to push that value onto the state's stack.
• lua_isproxy(p, L): Returns true if the object p is a proxy. If L is provided, it also verifies that p belongs to the same global state.

To expose JavaScript functions to the Lua environment, use the following aliases:

• lua_pushjsfunction(L, func): An alias for lua_pushcfunction.
• lua_pushjsclosure(L, func, n): An alias for lua_pushcclosure.

The main entrypoint exports the primary Lua engine components. To use Fengari, you typically interact with these four modules:

• luaconf: Configuration constants and settings.
• lua: The core Lua state and stack manipulation functions.
• lauxlib: Lua auxiliary library functions (e.g., for loading modules or handling errors).
• lualib: The standard Lua libraries (e.g., table, string, math).