Home

Awesome

Build Status npm License: MIT #fengari on libera.chat Code Quality: Javascript Total Alerts

<p align="center"> <img src="https://github.com/fengari-lua/fengari/raw/master/logo.png" alt="Fengari" width="304" height="304"> </p>

Fengari

🌙 φεγγάρι - The Lua VM written in JS ES6 for Node and the browser

This repository contains the core fengari code (which is a port of the Lua C library) which includes parser, virtual machine and base libraries. However it is rare to use this repository directly.

The JS API

Once you've loaded fengari, you can use the JS API:

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!");

The JS API is exactly the same as the C API so fengari.lua exposes the same constants and functions as lua.h, fengari.lauxlib the same as lauxlib.h and fengari.lualib the same as lualib.h. If you're unfamiliar with the C API, you can take a look at the manual.

Semantics

Fengari implements Lua 5.3 semantics and will hopefully follow future Lua releases. If you find any noticeable difference between Fengari and Lua's behaviours, please report it.

Strings

Lua strings are 8-bits clean and can embed \0. Which means that invalid UTF-8/16 strings are valid Lua strings. Lua functions like string.dump even use strings as a way of storing binary data.

To address that issue, Fengari uses Uint8Array objects containing the raw bytes to implement lua strings. To push a JS string on the stack you can use lua_pushliteral which will convert it to an array of bytes before pushing it. To get a Lua string on the stack as a JS string you can use lua_tojsstring which will attempt to convert it to a UTF-16 JS string. The latter won't give you what you expect if the Lua string is not a valid UTF-16 sequence. You can also convert strings with luastring_of, to_luastring, to_jsstring and to_uristring.

Integers

The JS number type is always a double, and hence cannot accurately represent integers with more than 53 bits. As such, we've taken the route of a rarely used define (LUA_INT_TYPE=LUA_INT_LONG) in the PUC-Rio sources, where floats are doubles, but integers are 32 bits.

require and package.loadlib

In the browser require and package.loadlib try to find a file by making synchronous XHR requests.

require has been extended to allow searchers to yield.

Missing features

Differences

Configuring

Some luaconf options can be chosen at library load time. Fengari looks for process.env.FENGARICONF and if it exists, parses it as a JSON string.

Extensions

dv = lua_todataview(L, idx)

Equivalent to lua_tolstring but returns a DataView instead of a string.

lua_pushjsfunction(L, func)

Alias for lua_pushcfunction.

lua_pushjsclosure(L, func, n)

Alias for lua_pushcclosure.

lua_atnativeerror(L, func)

Sets a function to be called if a native JavaScript error is thrown across a lua pcall. The function will be run as if it were a message handler (see https://www.lua.org/manual/5.3/manual.html#2.3). The current message handler will be run after the native error handler returns.

b = lua_isproxy(p, L)

Returns a boolean b indicating whether p is a proxy (See lua_toproxy). If L is non-null, only returns true if p belongs to the same global state.

p = lua_toproxy(L, idx)

Returns a JavaScript object p that holds a reference to the lua value at the stack index idx. This object can be called with a lua_State to push the value onto that state's stack.

This example would be an inefficient way to write lua_pushvalue(L, 1):

var p = lua_toproxy(L, 1);
p(L);

fengari library

A library containing metadata about the fengari release.

This library is automatically loaded by luaL_openlibs into the global "fengari".

NYI

References