# Lua 5.5 Language Feature Spec Status legend: βœ… implemented Β· 🟑 partial Β· ❌ missing Β· 🚫 out of scope Reference: `lua-5.5.0/doc/manual.html` Β§3 ("The Language"). Section numbers below mirror the manual so it's easy to cross-check. --- ## 3.1 Lexical conventions ### Identifiers | Item | Status | Notes | |---|---|---| | `[A-Za-z_][A-Za-z0-9_]*`, case-sensitive | βœ… | | | Reserved word list (22 keywords) | βœ… | `and break do else elseif end false for function goto if in local nil not or repeat return then true until while` | ### Comments | Item | Status | Notes | |---|---|---| | Line comment `-- …` | βœ… | | | Long comment `--[[ … ]]` (level 0) | βœ… | | | Long comment `--[=[ … ]=]`, `--[==[ … ]==]` (level N) | βœ… | any level N; `try_open_long_bracket` counts `=`s generically | ### Numeric literals | Form | Status | Notes | |---|---|---| | Decimal int `123` | βœ… | | | Decimal float `3.14` | βœ… | | | Exponent `1e10`, `2.5E-3` | βœ… | | | Hex int `0xFF`, `0Xff` | βœ… | wraps mod 2^64 (long literals denote low 64 bits) | | Hex float `0x1.8p3`, `0x1p-4` | βœ… | parsed via C99 `strtod`; presence of `.` or `p` forces float | | Numeric underscores (not Lua std) | 🚫 | not in Lua 5.5 | ### String literals | Form | Status | Notes | |---|---|---| | Short `"…"` and `'…'` | βœ… | | | Escapes `\n \t \\ \" \' \0 \a \b \f \r \v` | βœ… | | | `\xHH` (2 hex digits) | βœ… | | | `\u{H…}` (UTF-8, up to 6-byte form ≀ 0x7FFFFFFF) | βœ… | matches reference Lua's accepted range | | `\ddd` (1–3 decimal digits) | βœ… | value must fit in a byte (0–255) | | `\z` (skip following whitespace, incl. newlines) | βœ… | | | `\` β†’ literal `\n` | βœ… | CR/LF/CRLF/LFCR all collapse to one `\n` | | Long bracket `[[ … ]]`, leading newline stripped | βœ… | | | Long bracket level N `[=[ … ]=]`, `[==[ … ]==]` | βœ… | any level N | --- ## 3.2 Values and types | Type | Status | Representation | |---|---|---| | `nil` | βœ… | host `null` (anyref null) | | `boolean` | βœ… | `i31ref` tag | | `number` integer (64-bit) | βœ… | `i31ref` if in 31-bit range, else boxed `$LuaInt` | | `number` float (IEEE-754 double) | βœ… | boxed `$LuaFloat` | | `string` | βœ… | `$LuaString` wrapping `(array i8)` | | `function` | βœ… | `$LuaClosure` = (funcref `$LuaFn`, upvalue array) | | `table` | βœ… | `$LuaTable` = (keys, vals, n, cap, meta) | | `thread` (coroutines) | ❌ | blocked on WASM stack-switching | | `userdata` (light & full) | 🚫 | no embedding API by design | Type checks (`type(x)`): βœ… returns canonical names. `math.type(x)` for `integer`/`float` distinction: βœ… returns `"integer"` / `"float"` / `nil` (fail for non-number). --- ## 3.3 Statements ### 3.3.1 Blocks / chunks | Item | Status | Notes | |---|---|---| | Chunk = block; implicit varargs at top level | βœ… | top-level `...` works | | `do … end` bare block | βœ… | | | `;` empty statement | βœ… | | ### 3.3.2 Local declarations | Item | Status | Notes | |---|---|---| | `local x` | βœ… | initialized to `nil` | | `local x, y, z = e1, e2, e3` | βœ… | multi-assign with adjustment | | `local x = f()` (multret adjusted to 1) | βœ… | | | `local x, y = f()` (multret expanded) | βœ… | | | Attribute `local x = …` | βœ… | compile-time rejection of reassignment; prefix form `local a, b` also works | | Attribute `local x = …` | 🟑 | `__close(value, nil)` called in reverse order at natural block exit; nil/false skipped; early exits (`return`/`break`/`goto`/error) do not yet trigger close | | Lexical block scoping, shadowing | βœ… | | ### 3.3.3 Assignment | Item | Status | Notes | |---|---|---| | `lhs = expr` simple | βœ… | | | `a, b, c = e1, e2, e3` multi | βœ… | | | `a, b = b, a` swap semantics (RHS evaluated first) | βœ… | | | LHS: `name`, `t.k`, `t[k]` | βœ… | | | Implicit global assignment | βœ… | `x = 1` at top level creates a global | | Explicit `global x` declaration | βœ… | non-standard; project convention | ### 3.3.4 Control structures | Item | Status | |---|---| | `if e then … elseif e then … else … end` | βœ… | | `while e do … end` | βœ… | | `repeat … until e` (cond sees locals from body) | βœ… | | `break` | βœ… | | `return e1, …` (must be last in block) | βœ… | | `goto label` / `::label::` | βœ… | forward and backward jumps; lowered to WASM `br` on labelled blocks; Lua scoping rule enforced (cannot jump into scope of a local) | ### 3.3.5 For statements | Item | Status | Notes | |---|---|---| | Numeric `for i = a, b do … end` | βœ… | step = 1 | | Numeric `for i = a, b, c do … end` | βœ… | signed step; int vs float typing per spec | | Generic `for k in iter do … end` | βœ… | | | Generic `for k, v[, …] in iter[, state[, init[, closing]]] do … end` | βœ… | closing-value (4th expr) not honoured | ### 3.3.6 Function definitions | Form | Status | |---|---| | `function f() … end` (global, dotted, method) | βœ… | | `local function f() … end` | βœ… | | Anonymous `function() … end` expression | βœ… | | Method definition `function T:m(self_args) … end` | βœ… | | Method call sugar `obj:m(args)` | βœ… | | Multiple return values | βœ… | | Varargs `function(…)` and `function(a, …)` | βœ… | | `...` spliced into call args / returns / table ctor / multi-assign | βœ… | | Proper tail calls (`return f(...)`) | βœ… | lowered to `return_call_ref` | --- ## 3.4 Expressions ### 3.4.1 Arithmetic operators | Op | Status | Notes | |---|---|---| | `+` `-` `*` | βœ… | intΓ—int β†’ int, else float | | `/` (float division, always float) | βœ… | | | `//` (floor division) | βœ… | int and float forms | | `%` (modulo) | βœ… | int and float floor-mod; `a - floor(a/b)*b` | | `^` (exponent, always float) | βœ… | | | Unary `-` | βœ… | | | `__add` / `__sub` / `__mul` / `__div` / `__mod` / `__pow` / `__unm` / `__idiv` metamethods | βœ… | all eight; consulted when operand is non-numeric | ### 3.4.2 Bitwise operators | Op | Status | Notes | |---|---|---| | `&` `\|` `~` (xor) `<<` `>>` (binary) | βœ… | 64-bit integer semantics; negative shift counts swap direction; `\|count\| >= 64` yields 0 | | Unary `~` (bnot) | βœ… | | | `__band/__bor/__bxor/__bnot/__shl/__shr` metamethods | βœ… | fired when operand is not integer-convertible | Float operands with no fractional part in signed i64 range are accepted (Lua's "convertible to integer" rule). ### 3.4.3 Coercions and conversions | Item | Status | Notes | |---|---|---| | Int↔float promotion in arithmetic | βœ… | | | Stringβ†’number coercion in arithmetic (e.g. `"3" + 1`) | βœ… | via `$coerce_num`; leading/trailing whitespace stripped; `"3e0" + 0` β†’ float | | Numberβ†’string coercion in `..` | βœ… | | | Integer-valued float comparison rules | βœ… | | ### 3.4.4 Relational operators | Op | Status | Notes | |---|---|---| | `==` `~=` | βœ… | structural for strings; reference equality for tables/functions | | `<` `<=` `>` `>=` | βœ… | numbers and strings | | `__eq` metamethod | βœ… | | | `__lt` / `__le` metamethods | βœ… | | ### 3.4.5 Logical operators | Op | Status | |---|---| | `and` (short-circuit) | βœ… | | `or` (short-circuit) | βœ… | | `not` | βœ… | ### 3.4.6 String concatenation | Item | Status | Notes | |---|---|---| | `..` (right-associative) | βœ… | | | Numberβ†’string coercion via `..` | βœ… | | | `__concat` metamethod | βœ… | fired when either operand is non-string non-number; left operand's handler wins | ### 3.4.7 Length operator | Item | Status | Notes | |---|---|---| | `#s` for strings (byte length) | βœ… | | | `#t` for tables (border) | βœ… | | | `__len` metamethod | βœ… | overrides border rule on tables; also fires on other non-string values | ### 3.4.8 Precedence Matches Lua 5.5 precedence table fully: `or` < `and` < comparisons < `|` < `~` (bxor) < `&` < `<< >>` < `..` < `+ -` < `* / // %` < unary < `^`. ### 3.4.9 Table constructors | Form | Status | |---|---| | `{}` empty | βœ… | | `{e1, e2, e3}` positional | βœ… | | `{k1 = v1, k2 = v2}` named | βœ… | | `{[expr] = v}` computed key | βœ… | | Mixed | βœ… | | Last expression spread (`{f()}`, `{...}`) | βœ… | | Trailing `,` or `;` separator | βœ… | ### 3.4.10 Function calls | Form | Status | Notes | |---|---|---| | `f(args)` | βœ… | | | `f"string"` (paren-less single string arg) | βœ… | | | `f{table}` (paren-less single table arg) | βœ… | | | `obj:method(args)` | βœ… | | | `__call` metamethod | βœ… | `$lua_call_any` walks the `__call` chain; cycle limit enforced | ### 3.4.11 Function definitions (as expressions) See Β§3.3.6. All forms supported. --- ## 3.5 Visibility rules Lexical scoping + upvalue capture by reference (shared boxes). Transitive capture across nested closures: βœ…. --- ## 3.6 Error handling | Item | Status | Notes | |---|---|---| | `error(v)` raise | βœ… | | | `error(v, level)` | βœ… | level 0 disables prefix; level N walks the call-frame stack | | `pcall(f, …)` β†’ `(ok, …)` | βœ… | | | `xpcall(f, msgh, …)` | βœ… | msgh called on error; its return value is the second result | | `assert(v[, msg])` | βœ… | | | Stack tracebacks | 🟑 | `debug.traceback` walks the `$call_lines` frame stack; limited to source positions (no function names, no `debug.getinfo`) | | Underlying mechanism | β€” | WASM `throw $LuaError` + `try_table` | --- ## 3.7 Metatables and metamethods | Metamethod | Status | Notes | |---|---|---| | `__index` (table) | βœ… | | | `__index` (function) | βœ… | | | `__newindex` (table or function) | βœ… | fires only for absent keys; `rawset` bypasses | | `__call` | βœ… | walks chain; callee prepended to args | | `__add` | βœ… | | | `__sub` `__mul` `__div` `__mod` `__pow` `__unm` `__idiv` | βœ… | | | `__band` `__bor` `__bxor` `__bnot` `__shl` `__shr` | βœ… | fired when operand is not integer-convertible | | `__concat` | βœ… | | | `__len` | βœ… | | | `__eq` | βœ… | | | `__lt` `__le` | βœ… | | | `__tostring` | βœ… | `tostring`, `print`, and `string.format %s` all honour it | | `__metatable` (protect metatable) | βœ… | `getmetatable` returns the value; `setmetatable` raises | | `__pairs` | ❌ | | | `__gc` | 🚫 | no finalizers on host GC | | `__close` | 🟑 | natural block exit only; early exits (`return`/`break`/`goto`/error) not yet wired β€” see Β§3.3.2 | | `__name` | βœ… | renames the type in `tostring` output and type-aware error messages | | `__mode` (weak tables) | 🚫 | no weak refs in WasmGC today | --- ## 3.8 Garbage collection Delegated to host GC. `collectgarbage(…)` is not implemented; reference behaviour (incremental/generational, parameters, finalizers) is intentionally out of scope β€” the host owns lifetime. --- ## 3.9 Coroutines ❌ Entire feature. Blocked on the WASM stack-switching proposal shipping in browsers. --- ## Remaining gaps β€” concrete implementation list Ordered by estimated effort (smallest first): 1. **`__pairs`** β€” the `pairs` builtin currently uses the raw next-based iteration; a `__pairs` lookup before falling through would be a small addition. 2. **`` on early exits** β€” `__close` fires at natural block exit but not on `return`, `break`, `goto`, or error unwinds through an active close scope. Completing it needs an active-close-scope stack in codegen plus per-scope `try_table` unwinding β€” a milestone, not a small fix. 3. **`__gc`** β€” 🚫 not applicable; no finalizers in WasmGC. 4. **`__mode` (weak tables)** β€” 🚫 not applicable; no weak refs in WasmGC. 5. **Full `debug.*` library** β€” `debug.traceback` walks the frame stack (source positions only; no function names). `debug.getinfo` is unimplemented β€” its `nparams`/`nups`/`isvararg`/`linedefined` fields need per-function metadata that an AOT compiler without debug info doesn't retain. 6. **`load` / `loadfile`** β€” AOT-only; would need the compiler shipped at runtime. `require` works via `-m FILE` static modules. 7. **Coroutines** β€” blocked on the WASM stack-switching proposal shipping in browsers.