diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 41 |
1 files changed, 37 insertions, 4 deletions
@@ -22,7 +22,8 @@ However it is rare to use this repository directly. Once you've loaded fengari, you can use the JS API: -```javascript +```js +const luaconf = fengari.luaconf; const lua = fengari.lua; const lauxlib = fengari.lauxlib; const lualib = fengari.lualib; @@ -45,16 +46,21 @@ Fengari implements Lua 5.3 semantics and will hopefully follow future Lua releas 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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 `lua.to_luastring`, `lua.to_jsstring` and `lua.to_uristring`. +To address that issue, Fengari uses [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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 - `lua_gc`/`collectgarbage`: Fengari relies on the JS garbage collector and does not implement its own. @@ -66,11 +72,21 @@ In the browser `require` and `package.loadlib` try to find a file by making sync - `os.execute` - `debug.debug()` doesn't work from web workers due to lack of a method to get synchronous user input - [Weak tables](http://www.lua.org/manual/5.3/manual.html#2.5.2) +- `__gc` metamethods -### _Differences_ from C API +### _Differences_ +- `package.jspath` instead of `package.cpath` +- `LUA_JSPATH_DEFAULT` instead of `LUA_CPATH_DEFAULT` (and contains .js extensions rather than .so or .dll extensions) - `lua_tointegerx` and `lua_tonumberx` do not have out-parameters indicating conversion success. Instead, ``false`` is returned when conversion fails. +- `luaL_execresult` takes an extra argument: an error object. The error object should have a fields `status`, `signal` and `errno`. +- `luaL_fileresult` takes an extra argument: an error object. The error object should have a field `errno`. + + +### 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 @@ -115,9 +131,25 @@ var p = lua_toproxy(L, 1); p(L); ```` + +### `fengari` library + +A library containing metadata about the fengari release. + + - `AUTHORS` + - `COPYRIGHT` + - `RELEASE` + - `VERSION` + - `VERSION_MAJOR` + - `VERSION_MINOR` + - `VERSION_NUM` + - `VERSION_RELEASE` + +This library is automatically loaded by `luaL_openlibs` into the global `"fengari"`. + + ## NYI -- `math.randomseed()` - `io.input()`: partially implemented - `io.lines()` - `io.open()` @@ -130,6 +162,7 @@ p(L); - `file:setvbuf()` - `file:__gc()` + ## References - [Source code for Lua 5.3](lua.org/source/5.3/) |