Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 89 additions & 0 deletions .agents/plans/A44-debug-getinfo-name.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
---
id: A44
title: "debug.getinfo(level, 'n') populates name/namewhat from the caller's call site"
issue: 279
pr: 290
branch: feat/debug-getinfo-name
base: main
status: review
direction: A
unlocks:
- constructs.lua
---

## Goal

Make `debug.getinfo(level, "n")` return a non-nil `name` (and a matching
`namewhat`) for the common call forms, so the issue repro passes:

```lua
function F(a) return a end
F(1)
assert(debug.getinfo(1, "n").name == 'F')
```

## Out of scope

- The full PUC-Lua `getfuncname` caller-instruction walk for every form.
We reuse the compile-time name hint already threaded onto `:call`/`:self`
instructions (the same hint that powers "attempt to call a nil value
(global 'foo')" errors). That hint covers global, local, upvalue, field,
and method call sites.
- Naming of functions reached through forms that carry no hint at the call
site (e.g. a call through a temporary, `(t[expr])()`, immediately-invoked
anonymous closures). Those keep `name == nil` / `namewhat == ""`, matching
the PUC-Lua "unknown" fallback closely enough for the suite.
- `name`/`namewhat` for the entry chunk and for native (C) functions inspected
by value (`debug.getinfo(somefunc, "n")`): still nil. PUC-Lua also leaves
the value-based query without a name unless it can find a global binding.

## Success criteria

- `debug.getinfo(1, "n").name == "F"` for `function F() ... end; F()`.
- `namewhat` is `"global"` / `"local"` / `"upvalue"` / `"field"` / `"method"`
matching the call site, and `""` when no name is known.
- A regression unit test pins the issue repro.
- `constructs.lua` skip range narrows past line 226.
- `mix test` and the lua53 suite stay green.

## Implementation notes

The name is recovered from the *caller's* call instruction, PUC-Lua style,
but resolved at compile time: every `:call`/`:self` instruction already
carries a `name_hint` tagged tuple (`{:global, "F"}`, `{:local, "x"}`, ...),
and the executor already records `name: hint_name(name_hint)` on each
`call_stack` frame.

Two small changes:

1. Executor: also stash the hint *tag* on the frame as `:namewhat`
(`"global"`, `"local"`, `"upvalue"`, `"field"`, `"method"`), alongside the
existing `:name`. Done at both call-frame construction sites
(`do_execute` `:call` handler and `dispatcher_call_info/3`).
2. `debug.getinfo`: for an integer `level`, read the callee frame for that
level (`call_stack` is headed by the running function when a native
callback is executing) and surface its `name`/`namewhat`.

No prototype/codegen change is needed: the hint already lives on the
instruction stream, which is the more faithful PUC-Lua model than capturing
the declared name on the prototype.

## Verification

- `mix format`
- `mix compile --warnings-as-errors`
- `mix test`
- `mix test test/lua53_suite_test.exs --only lua53`
- New regression test under `test/lua/vm/stdlib/`.

## Risks

- Level-to-frame mapping: a native callback does not push its own frame, so
the running Lua function's frame is the head of `call_stack`. Verified
empirically before relying on it.
- Frame shape is read by the error formatter via `Map.get/2`; adding a
`:namewhat` key is additive and cannot break existing readers.

## Discoveries

(none yet)
19 changes: 17 additions & 2 deletions lib/lua/vm/executor.ex
Original file line number Diff line number Diff line change
Expand Up @@ -484,7 +484,7 @@ defmodule Lua.VM.Executor do
@doc false
@spec dispatcher_call_info(term(), term(), non_neg_integer()) :: map()
def dispatcher_call_info(proto, name_hint, line) do
%{source: proto.source, line: line, name: hint_name(name_hint)}
%{source: proto.source, line: line, name: hint_name(name_hint), namewhat: hint_namewhat(name_hint)}
end

# ── Break ──────────────────────────────────────────────────────────────────
Expand Down Expand Up @@ -965,7 +965,11 @@ defmodule Lua.VM.Executor do
# `:call_one` clause handles dispatcher → dispatcher chains
# without going through this branch.
args = collect_args(regs, base + 1, total_args)
call_info = %{source: proto.source, line: line, name: hint_name(name_hint), namewhat: hint_namewhat(name_hint)}
State.check_call_depth!(state)
state = %{state | call_stack: [call_info | state.call_stack], call_depth: state.call_depth + 1}
{results, state} = Dispatcher.execute(callee_proto, args, callee_upvalues, state)
state = %{state | call_stack: tl(state.call_stack), call_depth: state.call_depth - 1}
continue_after_call(results, regs, rest, upvalues, proto, state, cont, frames, line, base, result_count)

{:lua_closure, callee_proto, callee_upvalues} ->
Expand Down Expand Up @@ -998,7 +1002,7 @@ defmodule Lua.VM.Executor do
open_upvalues: state.open_upvalues
}

call_info = %{source: proto.source, line: line, name: hint_name(name_hint)}
call_info = %{source: proto.source, line: line, name: hint_name(name_hint), namewhat: hint_namewhat(name_hint)}

State.check_call_depth!(state)

Expand Down Expand Up @@ -2234,6 +2238,17 @@ defmodule Lua.VM.Executor do
defp hint_name(nil), do: nil
defp hint_name(hint) when is_tuple(hint), do: elem(hint, 1)

# Maps a call-site `name_hint` tag to the Lua 5.3 `namewhat` string reported
# by `debug.getinfo(level, "n")`. The hint is recovered at compile time from
# the caller's instruction, mirroring PUC-Lua's `getfuncname` classification.
defp hint_namewhat(nil), do: ""
defp hint_namewhat({:global, _}), do: "global"
defp hint_namewhat({:local, _}), do: "local"
defp hint_namewhat({:upvalue, _}), do: "upvalue"
defp hint_namewhat({:field, _, _}), do: "field"
defp hint_namewhat({:method, _, _}), do: "method"
defp hint_namewhat(_), do: ""

@doc """
Reads `t[key]` honoring the `__index` metamethod chain.

Expand Down
23 changes: 21 additions & 2 deletions lib/lua/vm/stdlib/debug.ex
Original file line number Diff line number Diff line change
Expand Up @@ -109,25 +109,44 @@ defmodule Lua.VM.Stdlib.Debug do
# currently-running Lua chunk from the native callback's perspective).
# Higher levels walk the saved call frames.
defp stack_info_for_level(level, state) do
{name, namewhat} = name_info_for_level(level, state)

case stack_position_for_level(level, state) do
{line, source} ->
%{
"source" => source || "=?",
"currentline" => line || -1,
"what" => "Lua",
"name" => nil
"name" => name,
"namewhat" => namewhat
}

nil ->
%{
"source" => "=?",
"currentline" => -1,
"what" => "main",
"name" => nil
"name" => name,
"namewhat" => namewhat
}
end
end

# The `"n"` fields describe how the function at `level` was reached, recovered
# from the caller's call instruction (Lua 5.3 §6.10, PUC-Lua `getfuncname`).
# When a native callback is executing, the running Lua function's own frame is
# the head of `call_stack`, so level `L` maps to `call_stack[L - 1]`. A frame
# without a recovered name (e.g. a call through a temporary, or a function
# reached by a tail call) reports `name == nil` / `namewhat == ""`.
defp name_info_for_level(level, state) when level >= 1 do
case Enum.at(state.call_stack, level - 1) do
nil -> {nil, ""}
frame -> {Map.get(frame, :name), Map.get(frame, :namewhat, "")}
end
end

defp name_info_for_level(_level, _state), do: {nil, ""}

defp stack_position_for_level(1, _state) do
case Executor.current_position() do
{nil, nil} -> nil
Expand Down
55 changes: 55 additions & 0 deletions test/language/stdlib/debug_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,61 @@ defmodule Lua.Language.Stdlib.DebugTest do
assert {["Lua"], _} = Lua.eval!(lua, code)
end

test "debug.getinfo(1, 'n') matches the issue repro", %{lua: lua} do
code = """
function F(a)
assert(debug.getinfo(1, "n").name == 'F')
return a
end
return F(1)
"""

assert {[1], _} = Lua.eval!(lua, code)
end

test "debug.getinfo(1, 'n') classifies namewhat by call form", %{lua: lua} do
code = """
local results = {}

function GlobalFn() return debug.getinfo(1, "n") end
local g = GlobalFn()
results[1] = g.name
results[2] = g.namewhat

local function LocalFn() return debug.getinfo(1, "n") end
local l = LocalFn()
results[3] = l.name
results[4] = l.namewhat

local t = {}
function t.field() return debug.getinfo(1, "n") end
local f = t.field()
results[5] = f.name
results[6] = f.namewhat

function t:method() return debug.getinfo(1, "n") end
local m = t:method()
results[7] = m.name
results[8] = m.namewhat

return results[1], results[2], results[3], results[4],
results[5], results[6], results[7], results[8]
"""

assert {["GlobalFn", "global", "LocalFn", "local", "field", "field", "method", "method"], _} =
Lua.eval!(lua, code)
end

test "debug.getinfo(1, 'n') leaves name nil when the call carries no hint", %{lua: lua} do
code = """
local fns = { function() return debug.getinfo(1, "n") end }
local info = fns[1]()
return info.name, info.namewhat
"""

assert {[nil, ""], _} = Lua.eval!(lua, code)
end

test "debug.traceback returns a string", %{lua: lua} do
code = """
local tb = debug.traceback("error here")
Expand Down
6 changes: 3 additions & 3 deletions test/lua53_skips.exs
Original file line number Diff line number Diff line change
Expand Up @@ -85,11 +85,11 @@
],
"constructs.lua" => [
%{
lines: 225..313,
lines: 232..313,
category: :unimplemented,
reason:
"two upstream blockers gate this block: debug.getinfo(1,\"n\").name returns nil (call-stack name introspection unimplemented) at line 226, and os.time is nil at line 237 (feeds _ENV.GLOB1, used by line 248 and the short-circuit harness leaf). The short-circuit harness itself (287-298) is verified green up to level 4 by test/lua/vm/short_circuit_test.exs",
issue: 281
"os.time is nil at line 237 (feeds _ENV.GLOB1, used by line 248 and the short-circuit harness leaf), so this block stays skipped until the os stdlib lands. The debug.getinfo(1,\"n\").name block above (line 226) now passes. The short-circuit harness itself (287-298) is verified green up to level 4 by test/lua/vm/short_circuit_test.exs",
issue: 280
}
],
"coroutine.lua" => [
Expand Down
Loading