Add support for lua.getLocal() and lua.setLocal() (#11)

Author: thsackos

README.md

@@ -87,7 +87,7 @@ you.
 |-----------------------------|---------------------------------------|
 | Lua C API (`lua_*`)         | 🎉 100% coverage<sup>†</sup> (92/92)  |
 | Auxilary Library (`luaL_*`) | 🤩 100% coverage (48/48)              |
-| Debug API (`lua_Debug`)     | 56% coverage (7/12)                   |
+| Debug API (`lua_Debug`)     | 72% coverage (9/12)                   |
 | LuaJIT Extensions           | *No plans to implement.*              |
 
 *†: Coroutine yield/resume is not yet part of the public `zig-luajit` Zig API, see [#6][ISSUE-6].*
@@ -279,14 +279,14 @@ This section describes the current status of Zig language bindings ("the Zig API
 | C API Symbol               | Available in `zig-luajit`           |
 |----------------------------|-------------------------------------|
 | `lua_getinfo`              | ☑️ `lua.getInfo()`                   |
+| `lua_getstack`             | ☑️ `lua.getStack()`                  |
 | `lua_gethookcount`         | ☑️ `lua.getHookCount()`              |
 | `lua_gethookmask`          | ☑️ `lua.getHookMask()`               |
 | `lua_gethook`              | ☑️ `lua.getHook()`                   |
-| `lua_getlocal`             ||
-| `lua_getstack`             | ☑️ `lua.getStack()`                  |
-| `lua_getupvalue`           ||
 | `lua_sethook`              | ☑️ `lua.setHook()`                   |
-| `lua_setlocal`             ||
+| `lua_getlocal`             | ☑️ `lua.getLocal()`                  |
+| `lua_setlocal`             | ☑️ `lua.setLocal()`                  |
+| `lua_getupvalue`           ||
 | `lua_setupvalue`           ||
 
 

src/root.zig

@@ -61,6 +61,14 @@ pub const Lua = opaque {
         return @ptrCast(str.ptr);
     }
 
+    fn asSlice(str: ?[*:0]const u8) ?[:0]const u8 {
+        if (str) |s| {
+            return std.mem.sliceTo(s, 0);
+        } else {
+            return null;
+        }
+    }
+
     fn asCFn(f: CFunction) ?*const fn (?*c.lua_State) callconv(.c) c_int {
         return @ptrCast(f);
     }
@@ -926,11 +934,8 @@ pub const Lua = opaque {
     /// Stack Behavior: `[-0, +1, m]`
     pub fn pushFString(lua: *Lua, comptime format: [:0]const u8, args: anytype) [:0]const u8 {
         const string: ?[*:0]const u8 = @call(.auto, c.lua_pushfstring, .{ asState(lua), format.ptr } ++ args);
-        if (string) |s| {
-            // NOTE: This seems dangerous. I don't really like this solution, but it doesn't look like there is any other option.
-            // We are making a strong assumption that Lua returns a well-behaved zero-terminated string.
-            const len = std.mem.indexOfSentinel(u8, 0, s);
-            return s[0..len :0];
+        if (asSlice(string)) |str| {
+            return str;
         } else {
             std.debug.panic("Received unexpected NULL response from lua.pushFString(\"{s}, ...\")", .{format});
         }
@@ -2463,9 +2468,8 @@ pub const Lua = opaque {
         assert(pattern.len > 0); // gsub(string, "", replacement) causes an infinite loop -- avoid using the empty string as a pattern.
 
         const str: ?[*:0]const u8 = c.luaL_gsub(asState(lua), @ptrCast(string.ptr), @ptrCast(pattern.ptr), @ptrCast(replacement.ptr));
-        if (str) |s| {
-            const len = std.mem.indexOfSentinel(u8, 0, s);
-            return s[0..len :0];
+        if (asSlice(str)) |s| {
+            return s;
         } else {
             lua.raiseErrorFormat(
                 "gsub('%s', '%s', '%s') returned null instead of the replaced string.",
@@ -3017,6 +3021,52 @@ pub const Lua = opaque {
     pub fn getHookMask(lua: *Lua) HookMask {
         return @bitCast(c.lua_gethookmask(asState(lua)));
     }
+
+    /// Gets information about a local variable of a given activation record. The parameter `info` must have been
+    /// filled by a previous call to `getStack()` or given as an argument to a hook.
+    ///
+    /// The `index` selects which local variable to inspect (1 is the first parameter or active local variable,
+    /// and so on, until the last active local variable).
+    ///
+    /// When the `index` is valid, pushes the variable's value onto the stack and returns its name. Variable names
+    /// starting with '(' (such as the name `(*temporary)`) represent internal variables (loop control variables,
+    /// temporaries, and C function locals).
+    ///
+    /// When the `index` is negative or greater than the number of active local variables, this function returns
+    /// `null` and nothing is pushed onto the stack.
+    ///
+    /// From: `const char *lua_getlocal(lua_State *L, lua_Debug *ar, int n);`
+    /// Refer to: https://www.lua.org/manual/5.1/manual.html#lua_getlocal
+    /// Stack Behavior: `[-0, +(0|1), -]`
+    pub fn getLocal(lua: *Lua, info: *Lua.DebugInfo, index: i32) ?[:0]const u8 {
+        lua.skipIndexValidation(
+            index,
+            "getLocal() is well-behaved and defined to return null when the index is not valid.",
+        );
+
+        const str: ?[*:0]const u8 = @ptrCast(c.lua_getlocal(asState(lua), @ptrCast(info), index));
+        return asSlice(str);
+    }
+
+    /// Sets the value of a local variable during hook execution. The parameter `info` must have been filled by a
+    /// previous call to `getStack()` or given as an argument to a hook.
+    ///
+    /// Always pops the value at the top of the stack.
+    /// * When the `index` is valid, assigns the value at the top of the stack to the variable at the given index
+    /// * When the `index` is negative or greater than the number of local variables, this function returns `null`.
+    ///
+    /// From: `const char *lua_setlocal(lua_State *L, lua_Debug *ar, int n);`
+    /// Refer to: https://www.lua.org/manual/5.1/manual.html#lua_setlocal
+    /// Stack Behavior: `[-1, +0, -]`
+    pub fn setLocal(lua: *Lua, info: *Lua.DebugInfo, index: i32) ?[:0]const u8 {
+        lua.skipIndexValidation(
+            index,
+            "setLocal() is well-behaved and defined to return null when the index is not valid.",
+        );
+
+        const str: ?[*:0]const u8 = @ptrCast(c.lua_setlocal(asState(lua), @ptrCast(info), index));
+        return asSlice(str);
+    }
 };
 
 test "Lua can be initialized with an allocator" {
@@ -5755,3 +5805,136 @@ test "getHookCount() can be used check the current hook function count" {
     lua.setHook(T.hook, Lua.HookMask.call_and_return, 42);
     try std.testing.expectEqual(e2, lua.getHookCount());
 }
+
+test "getLocal and setLocal can inspect and modify local variables" {
+    const lua = try Lua.init(std.testing.allocator);
+    defer lua.deinit();
+
+    const T = struct {
+        var locals_data = std.ArrayList(struct {
+            name: []const u8,
+            value: i32,
+        }).init(std.testing.allocator);
+
+        fn hookLocalVars(l: *Lua, info: *Lua.DebugInfo) callconv(.c) void {
+            if (info.event != Lua.HookEventKind.line or info.currentline != 4) {
+                // Restrict the hook to only execute on line 3 where we can modify `y`
+                return;
+            }
+
+            if (!l.getInfo("l", info)) {
+                return l.raiseErrorFormat("Could not get debug info.", .{});
+            }
+
+            var i: i32 = 1;
+            while (true) {
+                const name = l.getLocal(info, i);
+                if (name == null) {
+                    break;
+                }
+
+                const value = l.toIntegerStrict(-1) catch -1;
+                locals_data.append(.{
+                    .name = std.mem.sliceTo(name.?, 0),
+                    .value = @intCast(value),
+                }) catch unreachable;
+
+                l.pop(1);
+                i += 1;
+            }
+
+            if (l.getLocal(info, 2)) |name| {
+                l.pop(1);
+                l.pushInteger(42);
+                const before = l.getTop();
+                const modified_name = l.setLocal(info, 2);
+                std.testing.expectEqual(before - 1, l.getTop()) catch unreachable;
+                std.testing.expectEqualStrings(name, modified_name.?) catch unreachable;
+            }
+        }
+
+        fn cleanup() void {
+            locals_data.deinit();
+        }
+    };
+    defer T.cleanup();
+
+    const test_code =
+        \\function test_locals()
+        \\  local x = 10
+        \\  local y = 20
+        \\  return x + y  -- Should return 10 + 42 = 52 after our hook runs
+        \\end
+    ;
+    try lua.doString(test_code);
+
+    lua.setHook(T.hookLocalVars, .{ .on_line = true }, 0);
+    try std.testing.expectEqual(Lua.Type.function, lua.getGlobal("test_locals"));
+    try lua.callProtected(0, 1, 0);
+
+    try std.testing.expect(lua.isInteger(-1));
+    try std.testing.expectEqual(52, try lua.toIntegerStrict(-1)); // Should be 52 because we modified `y` from 20 to 42
+
+    try std.testing.expect(T.locals_data.items.len >= 2); // The variables x and y must be found, there may be other temporary variables as well
+    try std.testing.expectEqualStrings("x", T.locals_data.items[0].name);
+    try std.testing.expectEqual(10, T.locals_data.items[0].value);
+    try std.testing.expectEqualStrings("y", T.locals_data.items[1].name);
+    try std.testing.expectEqual(20, T.locals_data.items[1].value);
+}
+
+test "getLocal() and setLocal() should return null for invalid indices" {
+    const lua = try Lua.init(std.testing.allocator);
+    defer lua.deinit();
+
+    const T = struct {
+        var hook_executed = false;
+
+        fn edgeCaseHook(l: *Lua, info: *Lua.DebugInfo) callconv(.c) void {
+            if (info.event != Lua.HookEventKind.line or info.currentline != 3) {
+                return;
+            }
+
+            hook_executed = true;
+
+            if (!l.getInfo("l", info)) {
+                return l.raiseErrorFormat("Could not get debug info.", .{});
+            }
+
+            var before = l.getTop();
+            const out_of_bounds = l.getLocal(info, 9999);
+            std.testing.expect(out_of_bounds == null) catch unreachable;
+            std.testing.expectEqual(before, l.getTop()) catch unreachable; // Stack should not change when index is invalid.
+
+            before = l.getTop();
+            const negative_index = l.getLocal(info, -10);
+            std.testing.expect(negative_index == null) catch unreachable;
+            std.testing.expectEqual(before, l.getTop()) catch unreachable; // Stack should not change when index is invalid.
+
+            l.pushInteger(100);
+            before = l.getTop();
+            const out_of_bounds_set_result = l.setLocal(info, 9999);
+            std.testing.expect(out_of_bounds_set_result == null) catch unreachable;
+            std.testing.expectEqual(before - 1, l.getTop()) catch unreachable; // Stack should always be popped even if index is invalid
+
+            l.pushInteger(100);
+            before = l.getTop();
+            const negative_set_result = l.setLocal(info, -10);
+            std.testing.expect(negative_set_result == null) catch unreachable;
+            std.testing.expectEqual(before - 1, l.getTop()) catch unreachable; // Stack should always be popped even if index is invalid
+        }
+    };
+
+    const test_code =
+        \\function test_edge_cases()
+        \\  local x = 10
+        \\  return x
+        \\end
+    ;
+    try lua.doString(test_code);
+
+    lua.setHook(T.edgeCaseHook, .{ .on_line = true }, 0);
+    try std.testing.expectEqual(Lua.Type.function, lua.getGlobal("test_edge_cases"));
+    try lua.callProtected(0, 1, 0);
+
+    try std.testing.expect(T.hook_executed);
+}