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`.
12 KiB
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
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:
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
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.
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.
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
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.requireresolves throughpackage.loadedandpackage.preloadonly. 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.dumpraises an error.table:concat foreach foreachi getn insert maxn remove setn sort.math: all of Lua 5.1, plusmath.mod.bit:tobit tohex bnot band bor bxor lshift rshift arshift rol ror bswap.os:clock date difftime getenv time. Noexecute,exit,remove,renameortmpname.io:write,read(always nil),openandlines(read-only below the file root),type,stdout,stderr. Files supportread lines seek close.debug:traceback getinfo getlocal setlocal getupvalue setupvalue getmetatable setmetatable getregistry getfenv setfenv;sethookandgethookaccept calls but install nothing.