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