diff --git a/docs/API.md b/docs/API.md index c9fcd8a6..b703d204 100644 --- a/docs/API.md +++ b/docs/API.md @@ -678,6 +678,7 @@ build instructions. - [`difftime(time2 [, time1])`](#difftimetime2--time1) - [`xpcall(f, msgh [, arg1, ...])`](#xpcallf-msgh--arg1-) - [`GetCallstackHeight()` / `GetErrorCallstackHeight()` / `SetErrorCallstackHeight([height])`](#getcallstackheight--geterrorcallstackheight--seterrorcallstackheightheight) + - [`debuglocals([level [, skipFunctionsAndUserdata]])`](#debuglocalslevel--skipfunctionsanduserdata) - [`collectgarbage(opt [, arg])`](#collectgarbageopt--arg) - [`table.wipe(t)` / `wipe(t)`](#tablewipet--wipet) - [`table.count(tbl)`](#tablecounttbl) @@ -16136,6 +16137,32 @@ end Works in the world and on the login screen. +### `debuglocals([level [, skipFunctionsAndUserdata]])` + +Returns the local variables and the upvalues of a call level as one string. +An error handler uses it to show the values in the code that caused the +error. `level` counts the same as in `debugstack`, and is 1 by default. + +Each variable is one `name=value` line. A string value is in quotes. A +table shows the name of its frame, or ``, then its fields one space in, +then `}`. Fields of tables inside a table do not show. A function shows the +file and line where it is defined. + +If `skipFunctionsAndUserdata` is `true`, function and userdata values do not +show. The text stops at 4095 bytes. + +`debuglocals` works only while an error handler runs. At other times it +returns nothing. + +```lua +seterrorhandler(function(message) + local level = GetCallstackHeight() - GetErrorCallstackHeight() + 1 + print(debuglocals(level, true)) +end) +``` + +The error window shows these values under **Locals**. + ### `collectgarbage(opt [, arg])` Accepts Lua 5.1's string options. The stock 5.0 collector takes only an diff --git a/docs/LuaCAPI.md b/docs/LuaCAPI.md index 7c7bbf00..db550928 100644 --- a/docs/LuaCAPI.md +++ b/docs/LuaCAPI.md @@ -178,9 +178,9 @@ behaviour the comment describes (`push 0; mov edx, 1; mov ecx, L`) is | `0x006F4450` | `lua_next` | fastcall | calls `luaH_next` at `0x006FA2A0` | ★ | | `0x006F44E0` | `lua_concat` | fastcall | calls `luaV_concat` at `0x006F84D0` | ★ | | `0x006F4560` | `lua_newuserdata` | fastcall | tag 7; calls `luaS_newudata` at `0x006F9E30` | ★ | -| `0x006F45B0` | `lua_getupvalue` | fastcall | reads upvalue from C closure | ◦ | -| `0x006F4660` | `lua_setupvalue` | fastcall | | ◦ | -| `0x006F46E0` | *internal upvalue helper*| | shared by get/set above | ◦ | +| `0x006F45B0` | `lua_pushupvalues` | fastcall | pushes the running C closure's upvalues, returns how many | ★ | +| `0x006F4660` | `lua_getupvalue` | fastcall | `(L, funcindex, n)`: pushes upvalue n, returns its name or null | ★ | +| `0x006F46E0` | `aux_upvalue` | | finds upvalue n of a function, returns its name | ★ | ## Auxiliary library (`luaL_*`) diff --git a/src/Offsets.h b/src/Offsets.h index 1e6052b4..706e39f1 100644 --- a/src/Offsets.h +++ b/src/Offsets.h @@ -8795,8 +8795,20 @@ enum Offsets { LUA_GET_STACK = 0x006FBAA0, LUA_GET_INFO = 0x006FBC70, SIZEOF_LUA_DEBUG = 0x60, + OFF_LUA_DEBUG_NAME = 0x04, OFF_LUA_DEBUG_SOURCE = 0x10, OFF_LUA_DEBUG_CURRENTLINE = 0x14, + OFF_LUA_DEBUG_LINEDEFINED = 0x1C, + // `lua_getlocal(L, ar, n)` — `const char *__fastcall` (n on the stack): + // pushes local n of the call level ar names (ar+0x5C, i_ci) and returns + // its name, or returns null and pushes nothing (no such local, or a C + // level). No engine callers. + LUA_GET_LOCAL = 0x006FBB20, + // `lua_getupvalue(L, funcindex, n)` — `const char *__fastcall` (n on the + // stack): pushes upvalue n of the function at funcindex and returns its + // name ("" for a C closure), or null for no such upvalue or a value that + // is not a function. (0x006F45B0 is lua_pushupvalues.) + LUA_GET_UPVALUE = 0x006F4660, // `luaO_chunkid(out, source, bufflen)` — `void __fastcall(char *out /*ecx*/, // const char *source /*edx*/, int bufflen /*stack*/)`, RET 4: the name a // chunk has in error messages. `=name` is copied as is, `@file` is the diff --git a/src/baselib/DebugLocals.cpp b/src/baselib/DebugLocals.cpp new file mode 100644 index 00000000..f11594b5 --- /dev/null +++ b/src/baselib/DebugLocals.cpp @@ -0,0 +1,221 @@ +// This file is part of ClassicAPI. +// +// ClassicAPI is free software: you can redistribute it and/or modify it under the terms +// of the GNU General Public License as published by the Free Software Foundation, either +// version 3 of the License, or (at your option) any later version. +// +// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY +// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE. See the GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License along with +// ClassicAPI. If not, see . + +// `debuglocals([level [, skipFunctionsAndUserdata]])` — the locals and then +// the upvalues of a call level as text, one `name=value` line each, for an +// error report. 4.3.4's Script_debuglocals and the FrameScript_PackVariable +// it formats with, in retail's spacing (probed: `n=7`, `s="hi"`, +// `t=
{`, ` k=1`, `}`; 4.3.4 writes `n = 7` and `t =
{`): +// - Only while an error handler runs; otherwise it returns nothing. 4.3.4 +// tests a flag its error function sets around the handler call. 1.12's +// error function sets none, but while a handler runs that function's +// level is on the stack (ErrorCallstack::ErrorFunctionLevel). +// - `level` counts as lua_getstack and debugstack do: 1 is the caller. +// Less than 1 is 1. +// - A table prints as `name=
{`, or with the frame's name for a +// frame (t[0], as FrameScript_GetObject reads it), then its fields one +// space in at the top level only, then `}`. A function prints where it +// is defined. The text stops at 4095 bytes, each line at 1023. +// Retail's second argument, which its Blizzard_ScriptErrors passes as true, +// leaves out the function and userdata values, at the top level and in +// tables. +// +// A number key in int range prints truncated with %d, as 4.3.4's +// IsIntegerNumber tests only the range: 2.5 prints as 2. Two departures from +// 4.3.4, both where it would fail inside the handler: a number key outside +// that range is formatted from a copy, not converted in place (that breaks +// lua_next), and a key that is not a number or string prints as its type in +// angle brackets (4.3.4 formats a null string). +// +// Retail also lists `(*temporary)` lines: 5.1's lua_getlocal names each stack +// slot past a level's locals so, a C level's arguments included (an +// `error("x")` report shows `(*temporary)="x"`). 1.12's lua_getlocal +// (0x6FBB20) is 5.0's, which names declared locals only. Those slots are +// the compiler's registers, which 5.0 and 5.1 allocate differently, so they +// are left out rather than imitated. +// +// Registered on both Lua states, like the base-library helpers. + +#include "Game.h" +#include "Offsets.h" +#include "baselib/ErrorCallstack.h" + +#include +#include +#include +#include +#include +#include + +namespace BaseLib::DebugLocals { + +namespace { + +namespace Lua = Game::Lua; + +using lua_getlocal_t = const char *(__fastcall *)(void *L, const void *ar, int n); +using lua_getupvalue_t = const char *(__fastcall *)(void *L, int funcindex, int n); + +const auto GetLocal = reinterpret_cast(Offsets::LUA_GET_LOCAL); +const auto GetUpvalue = reinterpret_cast(Offsets::LUA_GET_UPVALUE); + +constexpr size_t kTextMax = 4095; // 4.3.4's 4096-byte buffer, less its NUL +constexpr size_t kLineSize = 1024; + +struct Packer { + void *L; + bool skipFunctionsAndUserdata; + std::string text; + + void Line(const char *fmt, const char *indent, const char *name, const char *value = "", + int number = 0) { + char line[kLineSize]; + std::snprintf(line, sizeof line, fmt, indent, name, value, number); + const size_t room = kTextMax - text.size(); + text.append(line, std::min(room, std::strlen(line))); + } + + // The value on the stack top, as 4.3.4's FrameScript_PackVariable. + void Pack(const char *name, int depth) { + const char *indent = depth > 0 ? " " : ""; + switch (Lua::Type(L, -1)) { + case Lua::TYPE_NIL: + Line("%s%s=nil\n", indent, name); + break; + case Lua::TYPE_BOOLEAN: + Line("%s%s=%s\n", indent, name, Lua::ToBoolean(L, -1) ? "true" : "false"); + break; + case Lua::TYPE_LIGHTUSERDATA: + case Lua::TYPE_USERDATA: + if (!skipFunctionsAndUserdata) + Line("%s%s=\n", indent, name); + break; + case Lua::TYPE_NUMBER: + Line("%s%s=%s\n", indent, name, Lua::ToString(L, -1)); // a copy: safe to convert + break; + case Lua::TYPE_STRING: + Line("%s%s=\"%s\"\n", indent, name, Lua::ToString(L, -1)); + break; + case Lua::TYPE_TABLE: + PackTable(name, depth, indent); + break; + case Lua::TYPE_FUNCTION: + if (!skipFunctionsAndUserdata) + PackFunction(name, indent); + break; + default: + Line("%s%s=<%s>\n", indent, name, Lua::TypeName(L, Lua::Type(L, -1))); + break; + } + } + + void PackTable(const char *name, int depth, const char *indent) { + void *object = Lua::ResolveObject(L, -1); + Line("%s%s=%s{\n", indent, name, object ? Lua::ObjectDisplayName(object) : "
"); + if (depth == 0) { + Lua::PushNil(L); + while (Lua::Next(L, -2) != 0) { + char key[32]; + const char *keyName = key; + const int keyType = Lua::Type(L, -2); + const double number = keyType == Lua::TYPE_NUMBER ? Lua::ToNumber(L, -2) : 0; + if (keyType == Lua::TYPE_NUMBER && std::isfinite(number) && number >= -2147483648.0 && + number <= 2147483647.0) { + std::snprintf(key, sizeof key, "%d", static_cast(number)); + } else if (keyType == Lua::TYPE_STRING) { + keyName = Lua::ToString(L, -2); + } else if (keyType == Lua::TYPE_NUMBER) { + Lua::PushValue(L, -2); + std::snprintf(key, sizeof key, "%s", Lua::ToString(L, -1)); + Lua::SetTop(L, -2); + } else { + std::snprintf(key, sizeof key, "<%s>", Lua::TypeName(L, keyType)); + } + Pack(keyName, 1); + Lua::SetTop(L, -2); // the value; the key stays for lua_next + } + } + Line("%s}\n", indent, ""); + } + + void PackFunction(const char *name, const char *indent) { + alignas(4) uint8_t ar[Offsets::SIZEOF_LUA_DEBUG]; + Lua::PushValue(L, -1); + Lua::GetInfo(L, ">nS", ar); // pops the copy + const auto field = [&ar](uintptr_t offset) { return Game::Read(ar, offset); }; + const char *source = field(Offsets::OFF_LUA_DEBUG_SOURCE); + const int line = Game::Read(ar, Offsets::OFF_LUA_DEBUG_LINEDEFINED); + if (const char *fn = field(Offsets::OFF_LUA_DEBUG_NAME)) { + char named[kLineSize]; + std::snprintf(named, sizeof named, "%s() defined %s", fn, source ? source : "?"); + Line("%s%s=%s:%d\n", indent, name, named, line); + } else { + Line("%s%s= defined %s:%d\n", indent, name, source ? source : "?", line); + } + } +}; + +int __fastcall Script_debuglocals(void *L) { + if (ErrorCallstack::ErrorFunctionLevel(L) == 0) + return 0; + int level = static_cast(Lua::ToNumber(L, 1)); + if (level <= 0) + level = 1; + Packer packer{L, Lua::ToBoolean(L, 2) != 0, {}}; + + alignas(4) uint8_t ar[Offsets::SIZEOF_LUA_DEBUG]; + if (Lua::GetStack(L, level, ar)) { + const char *name; + for (int i = 1; (name = GetLocal(L, ar, i)) != nullptr; i++) { + packer.Pack(name, 0); + Lua::SetTop(L, -2); + } + Lua::GetInfo(L, "f", ar); // the level's function + for (int i = 1; (name = GetUpvalue(L, -1, i)) != nullptr; i++) { + packer.Pack(name, 0); + Lua::SetTop(L, -2); + } + Lua::SetTop(L, -2); + } + Lua::PushLString(L, packer.text.data(), static_cast(packer.text.size())); + return 1; +} + +const Game::Doc::Field kDebuglocalsArgs[] = { + Game::Doc::Opt("level", "number", "1", "The call level, as debugstack counts it."), + Game::Doc::Opt("skipFunctionsAndUserdata", "boolean", "false", + "Leaves out function and userdata values."), +}; +const Game::Doc::Field kDebuglocalsRets[] = { + Game::Doc::Opt("locals", "string", nullptr, + "One `name=value` line for each local and upvalue. Nothing outside an " + "error handler."), +}; +const Game::Doc::Function kDebuglocals{ + "The local variables and upvalues of a call level as text, for an error report.", + kDebuglocalsArgs, kDebuglocalsRets, "LuaGlobals"}; + +void RegisterInGame() { + Game::Lua::RegisterGlobalFunction("debuglocals", &Script_debuglocals, &kDebuglocals); +} + +void RegisterGlue() { + Game::Lua::RegisterGlueFunction("debuglocals", &Script_debuglocals, &kDebuglocals); +} + +const Game::ModuleAutoRegister _autoreg{&RegisterInGame}; +const Game::GlueModuleAutoRegister _autoregGlue{&RegisterGlue}; + +} // namespace + +} // namespace BaseLib::DebugLocals diff --git a/src/baselib/ErrorCallstack.cpp b/src/baselib/ErrorCallstack.cpp index b0678e61..9d7713e2 100644 --- a/src/baselib/ErrorCallstack.cpp +++ b/src/baselib/ErrorCallstack.cpp @@ -40,12 +40,26 @@ #include "Game.h" #include "Offsets.h" +#include "baselib/ErrorCallstack.h" #include #include namespace BaseLib::ErrorCallstack { +int ErrorFunctionLevel(void *L) { + const auto errorFunction = reinterpret_cast(Offsets::FUN_FRAMESCRIPT_CALL_ERROR_HANDLER); + alignas(4) uint8_t ar[Offsets::SIZEOF_LUA_DEBUG]; + for (int level = 1; Game::Lua::GetStack(L, level, ar); ++level) { + Game::Lua::GetInfo(L, "f", ar); // the level's function; nil for a lost tail call + const bool found = Game::Lua::ToCFunction(L, -1) == errorFunction; + Game::Lua::SetTop(L, -2); + if (found) + return level; + } + return 0; +} + namespace { std::optional g_setHeight; @@ -59,21 +73,6 @@ int Height(void *L) { return height; } -// The innermost level whose function is the engine's error function, or 0 -// when no error is being reported. -int ErrorFunctionLevel(void *L) { - const auto errorFunction = reinterpret_cast(Offsets::FUN_FRAMESCRIPT_CALL_ERROR_HANDLER); - alignas(4) uint8_t ar[Offsets::SIZEOF_LUA_DEBUG]; - for (int level = 1; Game::Lua::GetStack(L, level, ar); ++level) { - Game::Lua::GetInfo(L, "f", ar); // the level's function; nil for a lost tail call - const bool found = Game::Lua::ToCFunction(L, -1) == errorFunction; - Game::Lua::SetTop(L, -2); - if (found) - return level; - } - return 0; -} - int __fastcall Script_GetCallstackHeight(void *L) { Game::Lua::PushNumber(L, Height(L)); return 1; diff --git a/src/baselib/ErrorCallstack.h b/src/baselib/ErrorCallstack.h new file mode 100644 index 00000000..e86ffddb --- /dev/null +++ b/src/baselib/ErrorCallstack.h @@ -0,0 +1,23 @@ +// This file is part of ClassicAPI. +// +// ClassicAPI is free software: you can redistribute it and/or modify it under the terms +// of the GNU General Public License as published by the Free Software Foundation, either +// version 3 of the License, or (at your option) any later version. +// +// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY +// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +// PURPOSE. See the GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License along with +// ClassicAPI. If not, see . + +#pragma once + +namespace BaseLib::ErrorCallstack { + +// The innermost call level whose function is the engine's error function +// (FUN_FRAMESCRIPT_CALL_ERROR_HANDLER), or 0 when no error is being +// reported. Nonzero exactly while an error handler runs. +int ErrorFunctionLevel(void *L); + +} // namespace BaseLib::ErrorCallstack diff --git a/src/embed/AddOns/!!!ClassicAPI/FrameXML/ScriptErrorsFrame.lua b/src/embed/AddOns/!!!ClassicAPI/FrameXML/ScriptErrorsFrame.lua index c60d745f..3b81efd5 100644 --- a/src/embed/AddOns/!!!ClassicAPI/FrameXML/ScriptErrorsFrame.lua +++ b/src/embed/AddOns/!!!ClassicAPI/FrameXML/ScriptErrorsFrame.lua @@ -23,15 +23,15 @@ -- - The text is a ScrollingEditBoxTemplate with a MinimalScrollBar, the -- ScrollBox pair retail uses for scrolling edit boxes, not retail's -- ScrollFrameTemplate, which ClassicAPI does not port. --- - The stack is retail's GetErrorData without the locals, taken in the --- SetText slot: GetErrorCallstackHeight finds the code that failed --- however many handlers sit between it and the slot. 1.12 has no --- debuglocals. +-- - The stack and locals are retail's GetErrorData, taken in the SetText +-- slot: GetErrorCallstackHeight finds the code that failed however many +-- handlers sit between it and the slot. No |K strings to remove, and no +-- C_StringUtil.EscapeDecimalNonPrintables. -- - No scriptErrors cvar (1.12 always shows errors), no LUA_WARNING, no -- gamepad legend. -- - Lua 5.0: no `...` expression, no # operator. -local function GetErrorStack() +local function GetErrorData() -- Example of how debug stack level is calculated -- Current stack: [1, 2, 3, 4, 5] (current function is at 1, total current height is 5) -- Stack at time of error: [1, 2] (these are currently now index 4 and 5, but at the time of error the stack height is 2) @@ -40,13 +40,20 @@ local function GetErrorStack() local errorCallStackHeight = GetErrorCallstackHeight(); local errorStackOffset = errorCallStackHeight and (errorCallStackHeight - 1); local debugStackLevel = currentStackHeight - (errorStackOffset or 0); - return debugstack(debugStackLevel); + local skipFunctionsAndUserdata = true; + + local stack = debugstack(debugStackLevel); + local locals = debuglocals(debugStackLevel, skipFunctionsAndUserdata); + + return stack, locals; end local ERROR_FORMAT = "|cffffd200Message:|r|cffffffff %s|r\n" .. "|cffffd200Time:|r|cffffffff %s|r\n" .. "|cffffd200Count:|r|cffffffff %s|r\n" .. "|cffffd200Stack:|r\n" + .. "|cffffffff%s|r\n" + .. "|cffffd200Locals:|r\n" .. "|cffffffff%s|r"; local INDEX_ORDER_FORMAT = "%d / %d"; @@ -68,15 +75,16 @@ function ScriptErrorsFrame_OnLoad(self) ScrollUtil.RegisterScrollBoxWithScrollBar(scrollBox, self.ScrollBar); ScriptErrors_Message.SetText = function(_, message) - ScriptErrorsFrame_OnError(message, GetErrorStack()); + ScriptErrorsFrame_OnError(message, GetErrorData()); end ScriptErrors.Show = function() end end -function ScriptErrorsFrame_OnError(message, stack) +function ScriptErrorsFrame_OnError(message, stack, locals) local self = ScriptErrorsFrame; message = tostring(message); stack = stack or ""; + locals = locals or ""; local messageKey = message .. "\n" .. stack; local index = self.seen[messageKey]; @@ -84,7 +92,7 @@ function ScriptErrorsFrame_OnError(message, stack) local errorData = self.errorData[index]; errorData.count = errorData.count + 1; else - table.insert(self.errorData, { count = 1, message = message, time = date(), stack = stack }); + table.insert(self.errorData, { count = 1, message = message, time = date(), stack = stack, locals = locals }); index = table.getn(self.errorData); self.seen[messageKey] = index; end @@ -106,7 +114,7 @@ function ScriptErrorsFrame_Update() -- SetText puts the cursor and the scroll back at the top. local errorData = self.errorData[self.index]; if ( errorData ) then - self.ScrollingEditBox:SetText(string.format(ERROR_FORMAT, errorData.message, errorData.time, errorData.count, errorData.stack)); + self.ScrollingEditBox:SetText(string.format(ERROR_FORMAT, errorData.message, errorData.time, errorData.count, errorData.stack, errorData.locals)); self.ScrollingEditBox:GetEditBox():HighlightText(0); else self.ScrollingEditBox:ClearText();