Rework upvalues to use Upvalues(T) wrapper type

Replaces the previous closure API with a unified approach where
functions declare upvalues using the Upvalues(T) wrapper as the first parameter.

Signed-off-by: Maksym Pavlenko <pavlenko.maksym@gmail.com>

Author: mxpv

CHANGELOG.md

@@ -12,7 +12,7 @@ All notable changes to this project will be documented in this file.
   - Handles both stack buffer (small strings) and dynamic allocation (large strings)
 - Variadic arguments support with `Varargs` iterator for functions accepting variable number of arguments
   - `Varargs.raiseError()` method for throwing descriptive type validation errors
-- Closure support with `Table.setClosure()` for Lua-style upvalues
+- **BREAKING**: `setClosure` Lua closures must use `Upvalues(T)` as first parameter
 - Canonical Zig iterator pattern for table iteration with `Table.iterator()`
 - Metatable management APIs:
   - `Lua.createMetaTable()` for flexible metatable creation without global registration

CLAUDE.md

@@ -101,22 +101,29 @@ The library supports custom memory allocators through `Lua.init()`:
 - All Lua memory operations (allocation, reallocation, freeing) go through the custom allocator
 
 ### Closure Upvalues (`setClosure`)
-The `setClosure` method accepts upvalues that can be either a single value or a tuple:
-- **Single value**: Pass directly without wrapping: `setClosure("func", value, fn)`
-- **Multiple values**: Pass as tuple: `setClosure("func", .{val1, val2}, fn)`
-- **No upvalues**: Pass empty tuple: `setClosure("func", .{}, fn)`
+The `setClosure` method creates Lua C closures using the `Upvalues(T)` wrapper type:
+- Functions must use `Upvalues(T)` as their first parameter
+- **Single upvalue**: `setClosure("func", value, fn)` where fn takes `Upvalues(T)`
+- **Multiple upvalues**: Use tuple `setClosure("func", .{val1, val2}, fn)` where fn takes `Upvalues(struct{T1, T2})`
 
 Examples:
 ```zig
-// Single upvalue - pass directly
-try table.setClosure("getValue", &state, getValueFn);
-try table.setClosure("addFive", 5, addFn);
+// Single upvalue
+fn getValue(upv: Upvalues(*State), key: []const u8) i32 {
+    return upv.value.getGlobal(key);
+}
+try table.setClosure("getValue", &state, getValue);
 
-// Multiple upvalues - use tuple
-try table.setClosure("transform", .{ 2.0, 10.0 }, transformFn);
+fn addFive(upv: Upvalues(i32), x: i32) i32 {
+    return x + upv.value;
+}
+try table.setClosure("addFive", 5, addFive);
 
-// No upvalues
-try table.setClosure("helper", .{}, helperFn);
+// Multiple upvalues - use tuple
+fn transform(upv: Upvalues(struct { f32, f32 }), x: f32) f32 {
+    return x * upv.value[0] + upv.value[1];
+}
+try table.setClosure("transform", .{ 2.0, 10.0 }, transform);
 ```
 
 ## Development Patterns

README.md

@@ -146,11 +146,11 @@ pub fn main() !void {
     const table = lua.createTable(.{});
     defer table.deinit();
     
-    fn getGlobal(lua_ptr: *Lua, key: []const u8) !i32 {
-        return try lua_ptr.globals().get(key, i32) orelse 0;
+    fn getGlobal(upv: Lua.Upvalues(*Lua), key: []const u8) !i32 {
+        return try upv.value.globals().get(key, i32) orelse 0;
     }
     const lua_ptr = @constCast(&lua);
-    try table.setClosure("getGlobal", .lua_ptr, getGlobal);
+    try table.setClosure("getGlobal", lua_ptr, getGlobal);
     try lua.globals().set("funcs", table);
     try lua.globals().set("myValue", @as(i32, 123));
     
@@ -236,9 +236,9 @@ pub fn main() !void {
 Efficient string building using Luau's StrBuf API with automatic memory management.
 
 ```zig
-fn buildGreeting(lua: *Lua, name: []const u8, age: i32) !Lua.StrBuf {
+fn buildGreeting(upv: Lua.Upvalues(*Lua), name: []const u8, age: i32) !Lua.StrBuf {
     var buf: Lua.StrBuf = undefined;
-    buf.init(lua);
+    buf.init(upv.value);
     buf.addString("Hello, ");
     buf.addLString(name);
     buf.addString("! You are ");

examples/guided_tour.zig

@@ -632,9 +632,9 @@ pub fn main() !void {
 
         // Return StrBuf from Zig functions
         const formatMessage = struct {
-            fn call(l: *luaz.Lua, name: []const u8, age: i32) !luaz.Lua.StrBuf {
+            fn call(upv: luaz.Lua.Upvalues(*luaz.Lua), name: []const u8, age: i32) !luaz.Lua.StrBuf {
                 var b: luaz.Lua.StrBuf = undefined;
-                b.init(l);
+                b.init(upv.value);
                 b.addLString(name);
                 b.addString(" is ");
                 try b.add(age);

src/lua.zig

@@ -393,35 +393,59 @@ pub const Lua = struct {
             self.state().pop(1); // Pop table
         }
 
-        /// Sets a function in the table as a closure with upvalues.
+        /// Sets a function with upvalues in the table as a Lua C closure.
         ///
-        /// Similar to `set(key, func)` but allows creating Lua closures with captured values.
+        /// Similar to `set(key, func)` but allows creating closures with captured values.
         /// Upvalues are values that are captured and accessible to the function.
-        /// The function must accept the upvalues as its first parameter.
+        /// The function must accept upvalues as its first parameter using the `Upvalues(T)` wrapper type.
         ///
         /// WARNING: When using light user data pointers as upvalues, the user is responsible
         /// for ensuring the pointer remains valid for the lifetime of the closure.
         ///
         /// Parameters:
         /// - `key`: The table key where the closure will be stored
         /// - `upvalues`: Values to be captured as upvalues (single value or tuple)
-        /// - `func`: A Zig function that accepts upvalues as its first parameter
+        /// - `func`: A Zig function with `Upvalues(T)` as its first parameter
         ///
         /// Examples:
         /// ```zig
-        /// // Single upvalue
-        /// fn add(increment: i32, x: i32) i32 { return x + increment; }
-        /// try table.setClosure("add5", .{5}, add);
+        /// fn add(upv: Upvalues(i32), x: i32) i32 {
+        ///     return upv.value + x;
+        /// }
+        /// try table.setClosure("add5", 5, add);
         ///
-        /// // Multiple upvalues (tuple)
-        /// fn scaledAdd(upvals: struct { f32, f32 }, x: f32) f32 {
-        ///     return x * upvals[0] + upvals[1];
+        /// fn transform(upv: Upvalues(struct { scale: f32, offset: f32 }), x: f32) f32 {
+        ///     return x * upv.value.scale + upv.value.offset;
         /// }
-        /// try table.setClosure("transform", .{ 2.0, 10.0 }, scaledAdd);
+        /// try table.setClosure("scale2add10", .{ .scale = 2.0, .offset = 10.0 }, transform);
         /// ```
         ///
         /// Errors: `Error.OutOfMemory` if stack allocation fails
         pub fn setClosure(self: Table, key: anytype, upvalues: anytype, func: anytype) !void {
+            const FuncType = @TypeOf(func);
+            const func_info = @typeInfo(FuncType);
+
+            if (func_info != .@"fn") {
+                @compileError("Third parameter must be a function");
+            }
+
+            const arg_tuple = std.meta.ArgsTuple(FuncType);
+            const arg_fields = std.meta.fields(arg_tuple);
+
+            if (arg_fields.len == 0) {
+                @compileError("Function must have at least one parameter (Upvalues)");
+            }
+
+            const FirstParamType = arg_fields[0].type;
+            const first_param_info = @typeInfo(FirstParamType);
+
+            if (first_param_info != .@"struct" or
+                !@hasDecl(FirstParamType, "is_upvalues") or
+                !FirstParamType.is_upvalues)
+            {
+                @compileError("First parameter of the function must be an Upvalues type");
+            }
+
             const upvalues_info = @typeInfo(@TypeOf(upvalues));
             const upvalue_count = if (upvalues_info == .@"struct" and upvalues_info.@"struct".is_tuple)
                 upvalues_info.@"struct".fields.len
@@ -443,12 +467,7 @@ pub const Lua = struct {
             }
 
             // Create the closure with upvalues
-            const FuncType = @TypeOf(func);
-            const arg_fields = std.meta.fields(std.meta.ArgsTuple(FuncType));
-            if (arg_fields.len == 0) {
-                @compileError("Closure function must have at least one parameter for upvalues");
-            }
-            const trampoline: State.CFunction = stack.createFunc(self.ref.lua, func, arg_fields[0].type);
+            const trampoline: State.CFunction = stack.createFunc(self.ref.lua, func);
             self.state().pushCClosureK(trampoline, @typeName(@TypeOf(func)), @intCast(upvalue_count), null);
 
             self.state().setTable(-3); // Set table[key] = closure and pop key and value
@@ -1071,6 +1090,25 @@ pub const Lua = struct {
         }
     };
 
+    /// Generic wrapper for upvalues passed to Lua C closure functions.
+    ///
+    /// This type enables functions to receive upvalues in a type-safe manner when registered
+    /// as Lua C closures with `table.setClosure()`. The upvalues are automatically injected
+    /// when the function is called from Lua.
+    ///
+    /// `Upvalues(T)` must be used as the first parameter of the function.
+    ///
+    /// See `Table.setClosure()` documentation for usage examples.
+    pub fn Upvalues(comptime T: type) type {
+        return struct {
+            value: T,
+
+            /// Marker field to distinguish from regular types
+            pub const is_upvalues = true;
+            pub const UpvalueType = T;
+        };
+    }
+
     /// Variadic arguments iterator for functions accepting variable number of arguments from Lua.
     ///
     /// This type enables Zig functions to accept any number of arguments from Lua

src/stack.zig

@@ -285,7 +285,7 @@ pub fn push(lua: Lua, value: anytype) void {
                 return;
             }
 
-            const trampoline = createFunc(lua, value, null);
+            const trampoline = createFunc(lua, value);
             lua.state.pushCFunction(trampoline, @typeName(T));
         },
         else => {
@@ -327,25 +327,21 @@ pub fn pushResult(lua: Lua, result: anytype) c_int {
 }
 
 /// Creates a Lua C function from a Zig function.
-/// If ClosureType is provided, creates a closure requiring `pushCClosure`.
-pub fn createFunc(_: Lua, value: anytype, comptime ClosureType: ?type) State.CFunction {
+/// Automatically detects Upvalues type in first parameter for closure functions.
+pub fn createFunc(_: Lua, value: anytype) State.CFunction {
     const T = @TypeOf(value);
     const arg_tuple = std.meta.ArgsTuple(T);
     const arg_fields = std.meta.fields(arg_tuple);
 
-    // Detect if first parameter should be treated as upvalues
-    const has_upvalues = ClosureType != null;
-
-    // Compile-time validation for closures
-    if (has_upvalues) {
-        if (arg_fields.len == 0) {
-            @compileError("Closure function must have at least one parameter for upvalues");
-        }
-        if (arg_fields[0].type != ClosureType.?) {
-            @compileError("First parameter type (" ++ @typeName(arg_fields[0].type) ++
-                ") must match ClosureType (" ++ @typeName(ClosureType.?) ++ ")");
+    // Detect if first parameter is an Upvalues type
+    const first_param_is_upvalues = if (arg_fields.len > 0) blk: {
+        const FirstParamType = arg_fields[0].type;
+        const type_info = @typeInfo(FirstParamType);
+        if (type_info == .@"struct" and @hasDecl(FirstParamType, "is_upvalues")) {
+            break :blk FirstParamType.is_upvalues;
         }
-    }
+        break :blk false;
+    } else false;
 
     // Validate Varargs is only used as the last parameter
     inline for (arg_fields, 0..) |field, i| {
@@ -365,24 +361,28 @@ pub fn createFunc(_: Lua, value: anytype, comptime ClosureType: ?type) State.CFu
             var args: arg_tuple = undefined;
 
             // Handle first parameter - upvalues or regular argument
-            const arg_start_idx = if (has_upvalues) blk: {
-                // First parameter is upvalues - populate from upvalue indices
-                const CT = ClosureType.?;
-                const ct_info = @typeInfo(CT);
+            const arg_start_idx = if (first_param_is_upvalues) blk: {
+                // First parameter is Upvalues type - populate from upvalue indices
+                const FirstParamType = arg_fields[0].type;
+                const UpvalueType = FirstParamType.UpvalueType;
+                const upvalue_info = @typeInfo(UpvalueType);
 
-                if (ct_info == .@"struct" and ct_info.@"struct".is_tuple) {
+                if (upvalue_info == .@"struct" and upvalue_info.@"struct".is_tuple) {
                     // Multiple upvalues as tuple
-                    const upvalues_fields = std.meta.fields(CT);
-                    inline for (upvalues_fields, 0..) |field, i| {
+                    var upvalue_tuple: UpvalueType = undefined;
+                    const upvalue_fields = std.meta.fields(UpvalueType);
+                    inline for (upvalue_fields, 0..) |field, i| {
                         const idx = State.upvalueIndex(@intCast(i + 1));
-                        args[0][i] = toValue(l, field.type, idx) orelse
+                        upvalue_tuple[i] = toValue(l, field.type, idx) orelse
                             l.state.typeError(idx, @typeName(field.type));
                     }
+                    args[0] = FirstParamType{ .value = upvalue_tuple };
                 } else {
                     // Single upvalue
                     const idx = State.upvalueIndex(1);
-                    args[0] = toValue(l, CT, idx) orelse
-                        l.state.typeError(idx, @typeName(CT));
+                    const upvalue = toValue(l, UpvalueType, idx) orelse
+                        l.state.typeError(idx, @typeName(UpvalueType));
+                    args[0] = FirstParamType{ .value = upvalue };
                 }
                 break :blk 1; // Start stack args from index 1, skip upvalue parameter
             } else blk: {
@@ -984,7 +984,8 @@ test "StrBuf pointer fixup on value copy" {
     // need to be fixed to point to the new buffer location.
 
     const TestFunction = struct {
-        fn buildMessage(l: *Lua, name: []const u8, age: i32) !Lua.StrBuf {
+        fn buildMessage(upv: Lua.Upvalues(*Lua), name: []const u8, age: i32) !Lua.StrBuf {
+            const l = upv.value;
             var buf: Lua.StrBuf = undefined;
             buf.init(l);
             buf.addLString(name);

src/tests.zig

@@ -1415,45 +1415,47 @@ test "function clone" {
     try expect(result2 == 30);
 }
 
-fn closureAdd5(n: i32, x: i32) i32 {
-    return x + n;
+fn closureAdd5(upv: Lua.Upvalues(i32), x: i32) i32 {
+    return x + upv.value;
 }
 
-fn closureTransform(upv: struct { f32, f32 }, x: f32) f32 {
-    return x * upv[0] + upv[1];
+fn closureTransform(upv: Lua.Upvalues(struct { f32, f32 }), x: f32) f32 {
+    return x * upv.value[0] + upv.value[1];
 }
 
-fn closureOptAdd(thresh: i32, x: i32, y: ?i32) i32 {
+fn closureOptAdd(upv: Lua.Upvalues(i32), x: i32, y: ?i32) i32 {
+    const thresh = upv.value;
     return if (x > thresh) x + (y orelse 0) else x;
 }
 
-fn closureMultiply(cfg: Lua.Table, x: i32) !i32 {
+fn closureMultiply(upv: Lua.Upvalues(Lua.Table), x: i32) !i32 {
+    const cfg = upv.value;
     const m = try cfg.get("mult", i32) orelse 1;
     return x * m;
 }
 
-fn closureConstant(val: i32) i32 {
-    return val;
+fn closureConstant(upv: Lua.Upvalues(i32)) i32 {
+    return upv.value;
 }
 
-fn closureSumAll(base: i32, a: ?i32, b: ?i32) i32 {
-    return base + (a orelse 0) + (b orelse 0);
+fn closureSumAll(upv: Lua.Upvalues(i32), a: ?i32, b: ?i32) i32 {
+    return upv.value + (a orelse 0) + (b orelse 0);
 }
 
-fn closureSingle(increment: i32, x: i32) i32 {
-    return x + increment;
+fn closureSingle(upv: Lua.Upvalues(i32), x: i32) i32 {
+    return x + upv.value;
 }
 
 const ClosureCounter = struct {
     count: i32,
 
-    fn increment(self: *@This(), amount: i32) i32 {
-        self.count += amount;
-        return self.count;
+    fn increment(upv: Lua.Upvalues(*ClosureCounter), amount: i32) i32 {
+        upv.value.count += amount;
+        return upv.value.count;
     }
 
-    fn getValue(self: *const @This()) i32 {
-        return self.count;
+    fn getValue(upv: Lua.Upvalues(*ClosureCounter)) i32 {
+        return upv.value.count;
     }
 };
 
@@ -1551,8 +1553,8 @@ test "metatable with closure function and table attachment" {
     // Step 2: Set function with upvalue (i32 = 4) and one parameter
     // The function returns sum of upvalue + passed parameter
     const AddFunc = struct {
-        fn add(upvalue: i32, param: i32) i32 {
-            return upvalue + param;
+        fn add(upv: Lua.Upvalues(i32), param: i32) i32 {
+            return upv.value + param;
         }
     };
 
@@ -1826,7 +1828,8 @@ test "StrBuf integration with Table operations" {
 }
 
 // Define a Zig function that builds and returns StrBuf by pointer
-fn makeMsg(l: *Lua, name: []const u8, value: i32) !Lua.StrBuf {
+fn makeMsg(upv: Lua.Upvalues(*Lua), name: []const u8, value: i32) !Lua.StrBuf {
+    const l = upv.value;
     var buf: Lua.StrBuf = undefined;
     buf.init(l);
     buf.addString("Hello ");
@@ -1855,7 +1858,8 @@ test "StrBuf returned from Zig functions" {
 }
 
 // Test function that returns StrBuf as part of a tuple
-fn makeMsgTuple(l: *Lua, name: []const u8, value: i32) !struct { Lua.StrBuf, i32 } {
+fn makeMsgTuple(upv: Lua.Upvalues(*Lua), name: []const u8, value: i32) !struct { Lua.StrBuf, i32 } {
+    const l = upv.value;
     var buf: Lua.StrBuf = undefined;
     buf.init(l);
     buf.addString("Tuple: ");
@@ -1886,7 +1890,8 @@ test "StrBuf returned in tuple from Zig functions" {
 }
 
 // Test function that builds a large StrBuf to force dynamic allocation
-fn makeLargeMsg(l: *Lua, count: i32) !Lua.StrBuf {
+fn makeLargeMsg(upv: Lua.Upvalues(*Lua), count: i32) !Lua.StrBuf {
+    const l = upv.value;
     var buf: Lua.StrBuf = undefined;
     buf.init(l);