From b669db4a1dfe18350655000fea041cb443374070 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Sat, 30 May 2026 20:40:08 -0400 Subject: [PATCH 1/2] feat(debug): track upvalue names; implement getupvalue/setupvalue Name each upvalue on the prototype and implement debug.getupvalue/ setupvalue against the runtime upvalue cells. The chunk-level `_ENV` is a register-0 local with no upvalue descriptor, so a loaded chunk had no upvalue to introspect and `load` ignored its 4th `env` argument. Model a loaded chunk's `_ENV` as upvalue slot 0: `load` now backs it with a real cell (honoring the optional `env` arg, defaulting to `_G`), and `load_env` sources that cell in both the interpreter and the bytecode dispatcher (falling back to `_G`). - Prototype: add `upvalue_names`; populate from descriptors for nested functions and as `["_ENV"]` for the chunk. - debug.getupvalue/setupvalue: name + read/write upvalue cells, bounds-checked. - Display: surface upvalue names in the closure inspect output. - Suite runner: the stopgap `load` helper now attaches the `_ENV` cell too. locals.lua is no longer fully skipped: debug.getupvalue/setupvalue, custom-env load, and nested-closure `_ENV` introspection all pass. The remaining nested `local _ENV` redirection failure (lines 148-154) is an unrelated scope leak, deferred via a partial skip (#284). Closes #256 --- lib/lua/compiler/codegen.ex | 8 +++++ lib/lua/compiler/prototype.ex | 2 ++ lib/lua/vm/dispatcher.ex | 9 ++++- lib/lua/vm/display.ex | 1 + lib/lua/vm/display/closure.ex | 12 ++++++- lib/lua/vm/executor.ex | 17 +++++++-- lib/lua/vm/stdlib.ex | 43 +++++++++++++++------- lib/lua/vm/stdlib/debug.ex | 48 ++++++++++++++++++++++--- tasks/suite_runner.ex | 21 ++++++++--- test/language/stdlib/debug_test.exs | 56 +++++++++++++++++++++++++++++ test/lua/vm/display_test.exs | 3 +- test/lua53_skips.exs | 9 ++--- 12 files changed, 198 insertions(+), 31 deletions(-) diff --git a/lib/lua/compiler/codegen.ex b/lib/lua/compiler/codegen.ex index 9bcb511f..76a86e09 100644 --- a/lib/lua/compiler/codegen.ex +++ b/lib/lua/compiler/codegen.ex @@ -43,6 +43,10 @@ defmodule Lua.Compiler.Codegen do # Reverse to maintain order prototypes: Enum.reverse(ctx.prototypes), upvalue_descriptors: [], + # The chunk's implicit `_ENV` is its sole upvalue (Lua 5.3 §3.3.1). It has + # no descriptor (it is bound as register 0, not captured from a parent), + # so name it explicitly here for `debug.getupvalue`/`setupvalue`. + upvalue_names: ["_ENV"], param_count: 0, is_vararg: func_scope.is_vararg, max_registers: Enum.max([func_scope.max_register, ctx.next_reg, Map.get(ctx, :peak_reg, 0)]), @@ -1524,6 +1528,10 @@ defmodule Lua.Compiler.Codegen do instructions: body_instructions, prototypes: Enum.reverse(body_ctx.prototypes), upvalue_descriptors: func_scope.upvalue_descriptors, + # Each descriptor carries its source name as the third element + # ({:parent_local, reg, name} | {:parent_upvalue, idx, name}); surface + # them in declaration order for the debug library. + upvalue_names: Enum.map(func_scope.upvalue_descriptors, &elem(&1, 2)), param_count: func_scope.param_count, is_vararg: func_scope.is_vararg, max_registers: Enum.max([func_scope.max_register, body_ctx.next_reg, Map.get(body_ctx, :peak_reg, 0)]), diff --git a/lib/lua/compiler/prototype.ex b/lib/lua/compiler/prototype.ex index 4756238b..7204a53f 100644 --- a/lib/lua/compiler/prototype.ex +++ b/lib/lua/compiler/prototype.ex @@ -16,6 +16,7 @@ defmodule Lua.Compiler.Prototype do instructions: [instruction()], prototypes: [t()], upvalue_descriptors: [upvalue_descriptor()], + upvalue_names: [String.t()], param_count: non_neg_integer(), is_vararg: boolean(), max_registers: non_neg_integer(), @@ -33,6 +34,7 @@ defmodule Lua.Compiler.Prototype do defstruct instructions: [], prototypes: [], upvalue_descriptors: [], + upvalue_names: [], param_count: 0, is_vararg: false, max_registers: 0, diff --git a/lib/lua/vm/dispatcher.ex b/lib/lua/vm/dispatcher.ex index 66eaee1b..f51d0bf5 100644 --- a/lib/lua/vm/dispatcher.ex +++ b/lib/lua/vm/dispatcher.ex @@ -200,7 +200,14 @@ defmodule Lua.VM.Dispatcher do dispatch(code, pc + 1, regs, upvalues, proto, state, cont, frames) {@op_load_env, dest} -> - regs = :erlang.setelement(dest + 1, regs, State.g_ref(state)) + env = + if tuple_size(upvalues) > 0 do + Map.get(state.upvalue_cells, :erlang.element(1, upvalues)) + else + State.g_ref(state) + end + + regs = :erlang.setelement(dest + 1, regs, env) dispatch(code, pc + 1, regs, upvalues, proto, state, cont, frames) {@op_get_upvalue, dest, index} -> diff --git a/lib/lua/vm/display.ex b/lib/lua/vm/display.ex index 09b1a643..f93c7335 100644 --- a/lib/lua/vm/display.ex +++ b/lib/lua/vm/display.ex @@ -129,6 +129,7 @@ defmodule Lua.VM.Display do line: first_line, arity: proto.param_count, vararg?: proto.is_vararg, + upvalue_names: proto.upvalue_names, ref: ref } end diff --git a/lib/lua/vm/display/closure.ex b/lib/lua/vm/display/closure.ex index 03a5c0da..9d828ea8 100644 --- a/lib/lua/vm/display/closure.ex +++ b/lib/lua/vm/display/closure.ex @@ -17,6 +17,8 @@ defmodule Lua.VM.Display.Closure do have `:arity` equal to the fixed-parameter count; the variadic flag is reflected by appending `+...` in the inspect output. - `:vararg?` — true when the closure accepts varargs (`...`). + - `:upvalue_names` — the closure's upvalue names in declaration order + (for example `["_ENV"]` for a loaded chunk). - `:ref` — the original `{:lua_closure, proto, upvalues}` tuple so callers can still reach the live closure (for example via `Lua.call_function/3`). @@ -31,10 +33,11 @@ defmodule Lua.VM.Display.Closure do line: non_neg_integer(), arity: non_neg_integer(), vararg?: boolean(), + upvalue_names: [String.t()], ref: tuple() } - defstruct [:source, :line, :arity, :vararg?, :ref] + defstruct [:source, :line, :arity, :vararg?, :ref, upvalue_names: []] defimpl Inspect do import Inspect.Algebra @@ -43,6 +46,12 @@ defmodule Lua.VM.Display.Closure do arity = Integer.to_string(c.arity || 0) arity = if c.vararg?, do: arity <> "+...", else: arity + upvalues = + case c.upvalue_names || [] do + [] -> empty() + names -> concat([", upvalues: [", Enum.join(names, ", "), "]"]) + end + concat([ "#Lua.Closure" ]) end diff --git a/lib/lua/vm/executor.ex b/lib/lua/vm/executor.ex index 6d070674..5362d804 100644 --- a/lib/lua/vm/executor.ex +++ b/lib/lua/vm/executor.ex @@ -650,12 +650,14 @@ defmodule Lua.VM.Executor do end # ── load_env ─────────────────────────────────────────────────────────────── - # Loads the runtime `_G` table reference into `dest`. Plan A16 emits this + # Loads the chunk's `_ENV` table reference into `dest`. Plan A16 emits this # at the start of every chunk so `_ENV` (a chunk-level local at register 0) - # is initialised before user code runs. + # is initialised before user code runs. A chunk loaded with a custom + # environment carries it in upvalue slot 0 (see `Stdlib.compile_loaded_chunk`); + # otherwise `_ENV` defaults to the global table `_G`. defp do_execute([{:load_env, dest} | rest], regs, upvalues, proto, state, cont, frames, line) do - regs = put_elem(regs, dest, State.g_ref(state)) + regs = put_elem(regs, dest, load_env_value(upvalues, state)) do_execute(rest, regs, upvalues, proto, state, cont, frames, line) end @@ -2838,6 +2840,15 @@ defmodule Lua.VM.Executor do %{state | open_upvalues: Map.reject(ou, fn {reg, _} -> reg >= threshold end)} end + # Resolve the `_ENV` value for a chunk's `load_env` instruction: a custom + # environment lives in upvalue slot 0 when present (a chunk loaded via + # `load(..., env)`), otherwise default to the global table `_G`. + defp load_env_value(upvalues, state) when tuple_size(upvalues) > 0 do + Map.get(state.upvalue_cells, elem(upvalues, 0)) + end + + defp load_env_value(_upvalues, state), do: State.g_ref(state) + # ── Call helpers: copy args without allocating an intermediate list ──────── # # `copy_args_to_regs` moves `count` values from `src_regs[src_off..]` into diff --git a/lib/lua/vm/stdlib.ex b/lib/lua/vm/stdlib.ex index c2b054a3..2b022827 100644 --- a/lib/lua/vm/stdlib.ex +++ b/lib/lua/vm/stdlib.ex @@ -414,20 +414,20 @@ defmodule Lua.VM.Stdlib do # is called repeatedly; each call must return a string piece, and the # chunk ends when it returns nil, an empty string, or no value. # Returns the compiled function, or (nil, error message) on failure. - defp lua_load([chunk | _rest], state) when is_binary(chunk) do - compile_loaded_chunk(chunk, state) + defp lua_load([chunk | rest], state) when is_binary(chunk) do + compile_loaded_chunk(chunk, load_env_arg(rest, state), state) end - defp lua_load([{:lua_closure, _, _} = reader | _rest], state) do - load_from_reader(reader, state) + defp lua_load([{:lua_closure, _, _} = reader | rest], state) do + load_from_reader(reader, load_env_arg(rest, state), state) end - defp lua_load([{:compiled_closure, _, _} = reader | _rest], state) do - load_from_reader(reader, state) + defp lua_load([{:compiled_closure, _, _} = reader | rest], state) do + load_from_reader(reader, load_env_arg(rest, state), state) end - defp lua_load([{:native_func, _} = reader | _rest], state) do - load_from_reader(reader, state) + defp lua_load([{:native_func, _} = reader | rest], state) do + load_from_reader(reader, load_env_arg(rest, state), state) end defp lua_load([_other | _], state) do @@ -444,16 +444,26 @@ defmodule Lua.VM.Stdlib do # it signals end-of-chunk (nil or ""). Bails out with `(nil, error_msg)` # if the reader ever returns a non-string non-nil value, mirroring the # behavior of Lua 5.3's reference implementation. - defp load_from_reader(reader, state) do + defp load_from_reader(reader, env, state) do case collect_reader_chunks(reader, state, []) do {:ok, source, state} -> - compile_loaded_chunk(source, state) + compile_loaded_chunk(source, env, state) {:error, msg, state} -> {[nil, msg], state} end end + # The optional 4th argument to `load(chunk, chunkname, mode, env)` is the + # environment the loaded chunk sees as `_ENV`. When absent or nil it defaults + # to the current global table `_G` (Lua 5.3 §6.1). + defp load_env_arg(rest, state) do + case Enum.at(rest, 2) do + nil -> State.g_ref(state) + env -> env + end + end + defp collect_reader_chunks(reader, state, acc) do {results, state} = Executor.call_function(reader, [], state) @@ -475,20 +485,27 @@ defmodule Lua.VM.Stdlib do end end - defp compile_loaded_chunk(source, state) do + defp compile_loaded_chunk(source, env, state) do case Lua.Parser.parse(source) do {:ok, ast} -> # Compiler currently never returns errors, always succeeds — see # `Lua.Compiler.compile!/2` for the matching note. {:ok, prototype} = Lua.Compiler.compile(ast) + # A loaded chunk's sole upvalue is `_ENV`. Back it with a real cell + # holding `env` so `load_env` sources it (instead of `_G`), the chunk's + # global writes route through `env`, and `debug.getupvalue`/`setupvalue` + # can read and mutate it. + env_cell = make_ref() + state = %{state | upvalue_cells: Map.put(state.upvalue_cells, env_cell, env)} + # When the bytecode compiler accepts the loaded chunk, surface # it as a `:compiled_closure` so the dispatcher takes over. # Otherwise fall back to the standard interpreted closure. closure = case prototype.bytecode do - nil -> {:lua_closure, prototype, {}} - _ -> {:compiled_closure, prototype, {}} + nil -> {:lua_closure, prototype, {env_cell}} + _ -> {:compiled_closure, prototype, {env_cell}} end {[closure], state} diff --git a/lib/lua/vm/stdlib/debug.ex b/lib/lua/vm/stdlib/debug.ex index ad6404a4..2d7c54eb 100644 --- a/lib/lua/vm/stdlib/debug.ex +++ b/lib/lua/vm/stdlib/debug.ex @@ -16,8 +16,8 @@ defmodule Lua.VM.Stdlib.Debug do - `debug.setlocal(level, local, value)` - Stub returning nil - `debug.sethook([hook, mask [, count]])` - Stub no-op - `debug.gethook([thread])` - Stub returning nil - - `debug.getupvalue(f, up)` - Stub returning nil - - `debug.setupvalue(f, up, value)` - Stub returning nil + - `debug.getupvalue(f, up)` - Returns the name and value of an upvalue + - `debug.setupvalue(f, up, value)` - Sets an upvalue, returning its name - `debug.upvalueid(f, n)` - Stub returning nil """ @@ -211,12 +211,52 @@ defmodule Lua.VM.Stdlib.Debug do defp debug_setmetatable([obj | _], state), do: {[obj], state} defp debug_setmetatable([], state), do: {[nil], state} + # debug.getupvalue(f, up) — returns the name and value of the up-th upvalue of + # function `f`, or nil when `up` is out of range or `f` is not a Lua closure. + defp debug_getupvalue([closure, n | _], state) when is_number(n) do + case upvalue_slot(closure, n) do + {:ok, name, cell} -> {[name, Map.get(state.upvalue_cells, cell)], state} + :error -> {[nil], state} + end + end + + defp debug_getupvalue(_args, state), do: {[nil], state} + + # debug.setupvalue(f, up, value) — assigns `value` to the up-th upvalue of + # function `f`, returning its name (or nil when out of range / not a closure). + defp debug_setupvalue([closure, n | rest], state) when is_number(n) do + value = List.first(rest) + + case upvalue_slot(closure, n) do + {:ok, name, cell} -> + {[name], %{state | upvalue_cells: Map.put(state.upvalue_cells, cell, value)}} + + :error -> + {[nil], state} + end + end + + defp debug_setupvalue(_args, state), do: {[nil], state} + + # Resolve the up-th (1-based) upvalue of a closure to {name, cell_ref}. Every + # element of a closure's upvalue tuple is a cell ref keyed in + # `state.upvalue_cells`; the name comes from the prototype's `upvalue_names`. + defp upvalue_slot({tag, proto, upvalues}, n) when tag in [:lua_closure, :compiled_closure] do + index = trunc(n) - 1 + + if index >= 0 and index < tuple_size(upvalues) and index < length(proto.upvalue_names) do + {:ok, Enum.at(proto.upvalue_names, index), elem(upvalues, index)} + else + :error + end + end + + defp upvalue_slot(_closure, _n), do: :error + # Stubs defp debug_getlocal(_args, state), do: {[nil], state} defp debug_setlocal(_args, state), do: {[nil], state} defp debug_sethook(_args, state), do: {[], state} defp debug_gethook(_args, state), do: {[nil, "", 0], state} - defp debug_getupvalue(_args, state), do: {[nil], state} - defp debug_setupvalue(_args, state), do: {[nil], state} defp debug_upvalueid(_args, state), do: {[nil], state} end diff --git a/tasks/suite_runner.ex b/tasks/suite_runner.ex index 46ee17e0..ad89ea73 100644 --- a/tasks/suite_runner.ex +++ b/tasks/suite_runner.ex @@ -139,18 +139,31 @@ defmodule Lua.SuiteRunner do end defp install_load(lua) do - Lua.set!(lua, ["load"], fn args, state -> + Lua.set!(lua, ["load"], fn args, lua -> code = List.first(args) chunk_name = Enum.at(args, 1, "") + vm = lua.state + + # A loaded chunk's sole upvalue is `_ENV`. Back it with a real cell + # holding the requested environment (the optional 4th arg, defaulting to + # `_G`) so `debug.getupvalue`/`setupvalue` and custom-env writes work — + # mirroring `Lua.VM.Stdlib.compile_loaded_chunk/3`. + env = + case Enum.at(args, 3) do + nil -> Lua.VM.State.g_ref(vm) + env -> env + end case Lua.Parser.parse(code) do {:ok, ast} -> proto = Lua.Compiler.compile!(ast, source: chunk_name) - closure = {:lua_closure, proto, {}} - {[closure], state} + env_cell = make_ref() + vm = %{vm | upvalue_cells: Map.put(vm.upvalue_cells, env_cell, env)} + closure = {:lua_closure, proto, {env_cell}} + {[closure], %{lua | state: vm}} {:error, error} -> - {[nil, "parse error: #{inspect(error)}"], state} + {[nil, "parse error: #{inspect(error)}"], lua} end end) end diff --git a/test/language/stdlib/debug_test.exs b/test/language/stdlib/debug_test.exs index 056d8d35..2114556f 100644 --- a/test/language/stdlib/debug_test.exs +++ b/test/language/stdlib/debug_test.exs @@ -65,4 +65,60 @@ defmodule Lua.Language.Stdlib.DebugTest do assert {[nil, nil], _} = Lua.eval!(lua, code) end + + test "debug.getupvalue reads the _ENV upvalue of a loaded chunk", %{lua: lua} do + code = """ + local name, val = debug.getupvalue(load"a=3", 1) + return name, val == _G + """ + + assert {["_ENV", true], _} = Lua.eval!(lua, code) + end + + test "load honors a custom environment, exposed as _ENV", %{lua: lua} do + code = """ + local c = {} + local f = load("a = 3", nil, nil, c) + local name, val = debug.getupvalue(f, 1) + local before = c.a + f() + return name, val == c, before, c.a + """ + + assert {["_ENV", true, nil, 3], _} = Lua.eval!(lua, code) + end + + test "debug.getupvalue names captured upvalues and bounds-checks", %{lua: lua} do + # Every nested function captures `_ENV` as upvalue 1; explicit captures + # follow in declaration order. `debug.getupvalue(_, 3)` is out of range. + code = """ + local x = 10 + local function outer() return function() return x end end + local inner = outer() + local env_name = debug.getupvalue(inner, 1) + local name, val = debug.getupvalue(inner, 2) + return env_name, name, val, debug.getupvalue(inner, 3) + """ + + assert {["_ENV", "x", 10, nil], _} = Lua.eval!(lua, code) + end + + test "debug.setupvalue mutates an upvalue and returns its name", %{lua: lua} do + code = """ + local x = 1 + local function getx() return x end + local name = debug.setupvalue(getx, 2, 99) + return name, getx() + """ + + assert {["x", 99], _} = Lua.eval!(lua, code) + end + + test "debug.getupvalue returns nil for non-closures", %{lua: lua} do + code = """ + return debug.getupvalue(print, 1), debug.getupvalue(42, 1) + """ + + assert {[nil, nil], _} = Lua.eval!(lua, code) + end end diff --git a/test/lua/vm/display_test.exs b/test/lua/vm/display_test.exs index c3a855f1..0dc822bf 100644 --- a/test/lua/vm/display_test.exs +++ b/test/lua/vm/display_test.exs @@ -71,7 +71,8 @@ defmodule Lua.VM.DisplayTest do assert %Closure{source: "", line: 1, arity: 2, vararg?: false, ref: ref} = c assert match?({:lua_closure, _, _}, ref) or match?({:compiled_closure, _, _}, ref) - assert inspect(c) == "#Lua.Closure\", line: 1, arity: 2>" + # The closure captures `_ENV` as an upvalue, surfaced in the inspect output. + assert inspect(c) == "#Lua.Closure\", line: 1, arity: 2, upvalues: [_ENV]>" end test "wraps Lua closures returned in decode: false mode" do diff --git a/test/lua53_skips.exs b/test/lua53_skips.exs index 63e078ae..d1e481be 100644 --- a/test/lua53_skips.exs +++ b/test/lua53_skips.exs @@ -166,10 +166,11 @@ ], "locals.lua" => [ %{ - lines: :all, - category: :unimplemented, - reason: "debug.getupvalue not implemented; _ENV introspection via debug library missing", - issue: nil + lines: 148..154, + category: :semantic, + reason: + "nested `local _ENV = {assert=assert, ...}` redirection leaks scope: free-name `assert` resolves to nil at line 150 (debug.getupvalue/setupvalue and _ENV introspection now pass)", + issue: 284 } ], "math.lua" => [ From 9df1c62668880977dfdb564318608a73a8073f37 Mon Sep 17 00:00:00 2001 From: Dave Lucia Date: Sat, 30 May 2026 20:57:12 -0400 Subject: [PATCH 2/2] refactor(stdlib): tighten upvalue_slot bounds and load_env_arg shape MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address self-review on #285: drop the redundant `length/1` check in `upvalue_slot/2` (the two collection sizes are equal by construction — keep the O(1) `tuple_size/1` check) and replace the positional `Enum.at(rest, 2)` lookup in `load_env_arg/2` with a head pattern match. --- lib/lua/vm/stdlib.ex | 8 ++------ lib/lua/vm/stdlib/debug.ex | 6 ++++-- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/lib/lua/vm/stdlib.ex b/lib/lua/vm/stdlib.ex index 2b022827..ee6dcc33 100644 --- a/lib/lua/vm/stdlib.ex +++ b/lib/lua/vm/stdlib.ex @@ -457,12 +457,8 @@ defmodule Lua.VM.Stdlib do # The optional 4th argument to `load(chunk, chunkname, mode, env)` is the # environment the loaded chunk sees as `_ENV`. When absent or nil it defaults # to the current global table `_G` (Lua 5.3 §6.1). - defp load_env_arg(rest, state) do - case Enum.at(rest, 2) do - nil -> State.g_ref(state) - env -> env - end - end + defp load_env_arg([_chunkname, _mode, env | _], _state) when env != nil, do: env + defp load_env_arg(_rest, state), do: State.g_ref(state) defp collect_reader_chunks(reader, state, acc) do {results, state} = Executor.call_function(reader, [], state) diff --git a/lib/lua/vm/stdlib/debug.ex b/lib/lua/vm/stdlib/debug.ex index 2d7c54eb..01a4006a 100644 --- a/lib/lua/vm/stdlib/debug.ex +++ b/lib/lua/vm/stdlib/debug.ex @@ -240,11 +240,13 @@ defmodule Lua.VM.Stdlib.Debug do # Resolve the up-th (1-based) upvalue of a closure to {name, cell_ref}. Every # element of a closure's upvalue tuple is a cell ref keyed in - # `state.upvalue_cells`; the name comes from the prototype's `upvalue_names`. + # `state.upvalue_cells`; the name comes from the prototype's `upvalue_names`, + # which is built alongside the upvalue tuple and is the same length by + # construction. defp upvalue_slot({tag, proto, upvalues}, n) when tag in [:lua_closure, :compiled_closure] do index = trunc(n) - 1 - if index >= 0 and index < tuple_size(upvalues) and index < length(proto.upvalue_names) do + if index >= 0 and index < tuple_size(upvalues) do {:ok, Enum.at(proto.upvalue_names, index), elem(upvalues, index)} else :error