The VM built string views from a hand-written { *u8, u64 } descriptor,
which on wasm32 (size_t lengths) read every string as empty. Views now go
through std's BytesFromPointer, which uses the target's slice layout.
The object records and LuaSyntaxNode are private again, now that the
toolchain (locked to 88b505bf) handles Vecs of module-private records.
`make wasm` builds the VM for the web platform with Emscripten and runs
it in a private headless Chromium as part of `make test`.
270 lines
12 KiB
Markdown
270 lines
12 KiB
Markdown
# Lua VM embedding API
|
|
|
|
`#import "lua/vm"` gives a Lua 5.1 virtual machine (LuaJIT dialect) written
|
|
in Ziran. The API follows the shape of the Lua C API: a host owns a
|
|
`LuaState` record, values move through a stack, and natives are plain Ziran
|
|
procedures. Names below are stable. Use `LuaState` only through them: its
|
|
fields are internal, and the object records they hold are private to the
|
|
package.
|
|
|
|
## State
|
|
|
|
```zi
|
|
state: LuaState
|
|
L := *state
|
|
LuaOpen(L) // false when the record was already open
|
|
status := LuaDoString(L, "print('hi')", "=demo")
|
|
if status != LUA_OK { message, ok := LuaToString(L, -1) }
|
|
LuaClose(L) // runs pending __gc and host finalizers, frees all
|
|
```
|
|
|
|
`LuaState` is large; keep it in a global or on the heap. One state is one
|
|
Lua universe and is not thread-safe. `LuaOpen` loads every standard library
|
|
(base, coroutine, string, table, math, os, io, bit, debug).
|
|
|
|
| Procedure | Meaning |
|
|
| --- | --- |
|
|
| `LuaSetHost(L, host: *void)`, `LuaHost(L) -> *void` | A host pointer for natives and hooks. |
|
|
| `LuaSetPrintSink(L, sink: LuaPrintSink, context: *void)` | `print`, `io.write` and `io.stdout:write` go to `sink(context, text)` instead of standard output. |
|
|
| `LuaSetFileRoot(L, path)` | Lets `dofile`, `loadfile`, `io.open` and `io.lines` read files below `path`. Empty (the default) disables Lua-side file access. |
|
|
| `LuaAllowEnvironment(L, prefix)` | Lets `os.getenv` read variables whose names start with `prefix`; repeatable. Otherwise `os.getenv` returns nil. |
|
|
| `LuaCollectGarbage(L)` | A full collection, from the host or a native (skipped inside a hook). |
|
|
| `LuaMemoryUsed(L) -> s64` | Estimated live heap bytes. |
|
|
|
|
## Status codes and constants
|
|
|
|
`LUA_OK`, `LUA_YIELD`, `LUA_ERRRUN`, `LUA_ERRSYNTAX`, `LUA_ERRMEM`,
|
|
`LUA_ERRERR`, `LUA_ERRFILE`. `LUA_MULTRET` (-1) asks for all results.
|
|
|
|
Pseudo-indices: `LUA_REGISTRYINDEX`, `LUA_GLOBALSINDEX` (the running
|
|
thread's globals), `LUA_ENVIRONINDEX` (the running native's environment) and
|
|
`LuaUpvalueIndex(i)` for native closure upvalues.
|
|
|
|
Type codes from `LuaType`: `LUA_TYPE_NONE` (-1, invalid index), `LUA_TYPE_NIL`,
|
|
`LUA_TYPE_BOOLEAN`, `LUA_TYPE_LIGHTUSERDATA`, `LUA_TYPE_NUMBER`,
|
|
`LUA_TYPE_STRING`, `LUA_TYPE_TABLE`, `LUA_TYPE_FUNCTION`, `LUA_TYPE_USERDATA`,
|
|
`LUA_TYPE_THREAD`. `LuaTypeName(L, type)` gives the Lua name.
|
|
|
|
## The stack
|
|
|
|
Index 1 is the first argument of the running native (or the first value the
|
|
host pushed), -1 the top. Reading an index past the top gives nil.
|
|
|
|
| Procedure | Meaning |
|
|
| --- | --- |
|
|
| `LuaGetTop(L) -> s32` | Number of values. |
|
|
| `LuaSetTop(L, index)` | Grow with nils or drop values; `LuaSetTop(L, 0)` clears. |
|
|
| `LuaPop(L, n)` | Drop `n` values. |
|
|
| `LuaPushValue(L, index)` | Push a copy. |
|
|
| `LuaInsert(L, index)` | Move the top value into `index`, shifting up. |
|
|
| `LuaRemove(L, index)` | Remove, shifting down. |
|
|
| `LuaReplace(L, index)` | Pop the top value into `index`; works with upvalue and global pseudo-indices. |
|
|
| `LuaAbsIndex(L, index) -> s32` | A positive index for a relative one. |
|
|
| `LuaCheckStack(L, extra) -> bool` | Ensure room for `extra` more values. |
|
|
|
|
## Values
|
|
|
|
Push: `LuaPushNil`, `LuaPushBoolean(L, bool)`, `LuaPushNumber(L, float64)`,
|
|
`LuaPushInteger(L, s64)`, `LuaPushString(L, string)` (copied and interned),
|
|
`LuaPushLightUserdata(L, *void)`, `LuaPushNative(L, fn, name)`,
|
|
`LuaPushNativeClosure(L, fn, count, name)`, `LuaPushThreadValue(L) -> bool`
|
|
(true on the main thread).
|
|
|
|
Read: `LuaToNumber -> float64` (0 when not convertible),
|
|
`LuaToNumberChecked -> (value, ok)`, `LuaToInteger -> s64` (truncated,
|
|
saturated), `LuaToBoolean`, `LuaToString -> (text, ok)`, `LuaToUserdata ->
|
|
*void`, `LuaUserdataTag -> s64`, `LuaObjLen -> s64` (raw table
|
|
length, string length, the length of a number as text, else 0).
|
|
|
|
`LuaToString` converts a number in place to a string, as `lua_tolstring`
|
|
does. The returned text views interned VM memory: copy it before the value
|
|
can be collected (after it leaves the stack and Lua code runs).
|
|
|
|
Tests: `LuaIsNone`, `LuaIsNil`, `LuaIsNoneOrNil`, `LuaIsBoolean`,
|
|
`LuaIsNumber` (numbers and numeric strings), `LuaIsString` (strings and
|
|
numbers), `LuaIsTable`, `LuaIsFunction`, `LuaIsNative`, `LuaIsUserdata`
|
|
(full or light). Comparison: `LuaRawEqual(L, a, b) -> bool`,
|
|
`LuaEqual(L, a, b) -> (equal, ok)` and `LuaLessThan(L, a, b) -> (less, ok)`
|
|
run metamethods.
|
|
|
|
## Tables
|
|
|
|
| Procedure | Meaning |
|
|
| --- | --- |
|
|
| `LuaNewTable(L)`, `LuaCreateTable(L, narr, nrec)` | Push a new table, optionally presized. |
|
|
| `LuaGetField(L, index, name) -> bool` | Push `t[name]` (metamethods). |
|
|
| `LuaSetField(L, index, name) -> bool` | `t[name] = pop()` (metamethods). |
|
|
| `LuaGetTable(L, index) -> bool` | Pop a key, push `t[key]`. |
|
|
| `LuaSetTable(L, index) -> bool` | Pop value and key, `t[key] = value`. |
|
|
| `LuaGetGlobal(L, name)`, `LuaSetGlobal(L, name)` | The same on the globals. |
|
|
| `LuaRawGet(L, index)`, `LuaRawSet(L, index) -> bool` | Without metamethods; `LuaRawSet` is false for a nil or NaN key. |
|
|
| `LuaRawGetI(L, index, n)`, `LuaRawSetI(L, index, n)` | Integer keys, raw. |
|
|
| `LuaNext(L, index) -> s32` | Pop a key, push the next key and value: 1, or 0 at the end, or -1 for an invalid key. |
|
|
|
|
Iterate like the C API:
|
|
|
|
```zi
|
|
LuaPushNil(L)
|
|
while LuaNext(L, table) == 1 {
|
|
// key at -2, value at -1
|
|
LuaPop(L, 1)
|
|
}
|
|
```
|
|
|
|
The bool results are false when a metamethod raised an error. Inside a
|
|
native, return `LUA_NATIVE_ERROR` then; from the host, wrap the work in a
|
|
native and call it with `LuaPCall` when metamethods can fail.
|
|
|
|
## Metatables, userdata and environments
|
|
|
|
| Procedure | Meaning |
|
|
| --- | --- |
|
|
| `LuaGetMetatable(L, index) -> bool` | Push the metatable; false (nothing pushed) without one. |
|
|
| `LuaSetMetatable(L, index) -> bool` | Pop a table or nil into the value's metatable (tables, userdata, or the shared one of a basic type). |
|
|
| `LuaNewMetatable(L, name) -> bool` | Push `registry[name]`, creating it; false when it existed. |
|
|
| `LuaGetRegistryMetatable(L, name)` | Push `registry[name]`. |
|
|
| `LuaNewUserdata(L, data: *void, tag: s64)` | Push a full userdata wrapping host data; `tag` names the host type. |
|
|
| `LuaNewUserdataFinalized(L, data, tag, finalizer: LuaFinalizer)` | The same; `finalizer(L, data, tag)` runs when it is collected or the state closes, after any `__gc`. |
|
|
| `LuaTestUserdata(L, index, name) -> *void` | The data of a userdata whose metatable is `registry[name]`, else null. |
|
|
| `LuaGetFenv(L, index)`, `LuaSetFenv(L, index) -> bool` | A function's, userdata's or thread's environment table. |
|
|
|
|
The VM never owns host data: a userdata holds the pointer, and the host
|
|
frees it in the finalizer.
|
|
|
|
## Natives
|
|
|
|
```zi
|
|
LuaNative :: #type (L: *LuaState) -> s32;
|
|
```
|
|
|
|
A native reads its arguments at 1..`LuaGetTop(L)`, pushes results and
|
|
returns how many (the top values are taken). It returns `LUA_NATIVE_ERROR`
|
|
to raise the pending error, or `LuaYield(L, n)` to yield.
|
|
|
|
```zi
|
|
Add :: (L: *LuaState) -> s32 {
|
|
a, ok1 := LuaCheckNumber(L, 1)
|
|
if !ok1 { return LUA_NATIVE_ERROR }
|
|
b, ok2 := LuaCheckNumber(L, 2)
|
|
if !ok2 { return LUA_NATIVE_ERROR }
|
|
LuaPushNumber(L, a + b)
|
|
return 1
|
|
}
|
|
|
|
LuaRegister(L, "add", Add) // globals.add
|
|
LuaNewTable(L)
|
|
LuaSetNative(L, -1, "add", Add) // t.add
|
|
LuaSetGlobal(L, "host")
|
|
```
|
|
|
|
Argument checks set the standard error and return `ok = false`:
|
|
`LuaCheckNumber`, `LuaCheckInteger`, `LuaCheckString` (numbers convert),
|
|
`LuaCheckTable -> bool`, `LuaCheckAny -> bool`, and `LuaOptNumber`,
|
|
`LuaOptInteger`, `LuaOptString` with a fallback for nil or missing.
|
|
|
|
Raising errors (each returns `LUA_NATIVE_ERROR`):
|
|
|
|
- `LuaErrorText(L, message)`: "chunk:line: message" at the Lua caller.
|
|
- `LuaArgError(L, n, message)`: "bad argument #n to 'name' (message)".
|
|
- `LuaTypeError(L, n, expected)`: "... (expected expected, got type)".
|
|
- `LuaRaiseError(L)`: raise the value on top of the stack as is.
|
|
|
|
`LuaPushNativeClosure(L, fn, count, name)` takes the top `count` values as
|
|
upvalues; read them with `LuaPushValue(L, LuaUpvalueIndex(i))` and write them
|
|
with `LuaReplace(L, LuaUpvalueIndex(i))`.
|
|
|
|
## Loading and calling
|
|
|
|
| Procedure | Meaning |
|
|
| --- | --- |
|
|
| `LuaLoadBuffer(L, text, chunkname) -> s32` | Compile and push a function, or push the message (`LUA_ERRSYNTAX`). |
|
|
| `LuaLoadString(L, text) -> s32` | `LuaLoadBuffer` with the text as its name. |
|
|
| `LuaLoadFile(L, path) -> s32` | Load a host file (not limited by the file root); `LUA_ERRFILE` when unreadable. |
|
|
| `LuaDoString(L, text, chunkname) -> s32` | Load and run with a traceback handler; results stay on the stack. |
|
|
| `LuaDoFile(L, path) -> s32` | The same for a host file. |
|
|
| `LuaCall(L, nargs, want) -> bool` | Unprotected call of the function below `nargs` arguments. Inside a native, return `LUA_NATIVE_ERROR` when false. |
|
|
| `LuaPCall(L, nargs, want, handler) -> s32` | Protected call; `handler` is a stack index of a message handler or 0. On error the message replaces the function and arguments. |
|
|
| `LuaTraceback(L, message, level)` | Push "message\nstack traceback:\n...". |
|
|
|
|
Chunk names follow Lua: "@file.lua" prints as `file.lua:3:`, "=name" as
|
|
`name:3:`, anything else as `[string "..."]:3:`. Lua errors carry a
|
|
position; `error(value)` with a non-string keeps the value as is.
|
|
|
|
Call `LuaPCall` or `LuaDoString` from the host. A host call outside any
|
|
protected call leaves its error pending with no handler to receive it.
|
|
|
|
## Registry references
|
|
|
|
`LuaRef(L) -> s32` pops a value into the registry and returns a handle
|
|
(`LUA_REFNIL` for nil); `LuaPushRef(L, ref)` pushes it back; `LuaUnref(L,
|
|
ref)` releases it. A referenced value stays alive.
|
|
|
|
## Coroutines
|
|
|
|
`LuaNewThread(L)` pops a function and pushes a coroutine running it.
|
|
`LuaResume(L, index, nargs) -> (status, count)` resumes the coroutine at
|
|
`index` with the top `nargs` values; its yielded or returned values (or the
|
|
error message) replace them. The status is `LUA_YIELD`, `LUA_OK` (finished)
|
|
or an error.
|
|
|
|
A native yields with `return LuaYield(L, n)`, yielding its top `n` values;
|
|
the values passed to the next resume become that native call's results.
|
|
|
|
```zi
|
|
Wait :: (L: *LuaState) -> s32 { return LuaYield(L, LuaGetTop(L)) }
|
|
```
|
|
|
|
As in Lua 5.1, yielding across a `pcall`, a metamethod or a native that
|
|
called back into Lua raises "attempt to yield across metamethod/C-call
|
|
boundary".
|
|
|
|
## Limits and hooks
|
|
|
|
```zi
|
|
LuaLimits :: struct {
|
|
max_memory: s64 // estimated live bytes; 0 = unlimited
|
|
max_native_depth: s32 // nested native re-entry (default 190)
|
|
max_frames: s32 // Lua call frames per thread (default 200000)
|
|
}
|
|
limits := LuaGetLimits(L)
|
|
limits.max_memory = 64 * 1048576
|
|
LuaSetLimits(L, limits)
|
|
```
|
|
|
|
Going over `max_memory` raises "not enough memory" in the running Lua code
|
|
after a collection fails to free enough. Deep recursion raises "stack
|
|
overflow".
|
|
|
|
`LuaSetHook(L, hook: LuaHook, count)` calls `hook(L) -> bool` every `count`
|
|
checkpoints (Lua calls and loop back-edges). Returning false raises an error
|
|
in the running Lua code: "instruction limit exceeded", or the message set
|
|
with `LuaSetHookMessage(L, message)` inside the hook. `LuaClearHook(L)`
|
|
removes it. Use it to stop runaway mod code.
|
|
|
|
## Supported Lua
|
|
|
|
Lua 5.1 semantics with LuaJIT's extensions: `goto` and labels, `\x`, `\z`
|
|
and `\u{...}` escapes, `bit`, `math.log(x, base)`, `string.format("%a")`, `load` with a
|
|
reader function, `newproxy`.
|
|
|
|
- Base: `assert collectgarbage dofile error gcinfo getfenv getmetatable ipairs
|
|
load loadfile loadstring newproxy next pairs pcall print rawequal rawget
|
|
rawset require select setfenv setmetatable tonumber tostring type unpack
|
|
xpcall _G _VERSION`. `require` resolves through `package.loaded` and
|
|
`package.preload` only.
|
|
- `coroutine`: `create resume yield status running wrap`.
|
|
- `string`: `byte char dump find format gfind gmatch gsub len lower match rep
|
|
reverse sub upper`, with Lua patterns, and strings indexable as
|
|
`("x"):upper()`. `string.dump` raises an error.
|
|
- `table`: `concat foreach foreachi getn insert maxn remove setn sort`.
|
|
- `math`: all of Lua 5.1, plus `math.mod`.
|
|
- `bit`: `tobit tohex bnot band bor bxor lshift rshift arshift rol ror bswap`.
|
|
- `os`: `clock date difftime getenv time`. No `execute`, `exit`, `remove`,
|
|
`rename` or `tmpname`.
|
|
- `io`: `write`, `read` (always nil), `open` and `lines` (read-only below the
|
|
file root), `type`, `stdout`, `stderr`. Files support `read lines seek
|
|
close`.
|
|
- `debug`: `traceback getinfo getlocal setlocal getupvalue setupvalue
|
|
getmetatable setmetatable getregistry getfenv setfenv`; `sethook` and
|
|
`gethook` accept calls but install nothing.
|