Files
lua/docs/API.md
T
waozi 8033702823 Borrow VM strings through std so wasm32 sees their length
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`.
2026-11-07 02:48:50 -03:00

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. 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.