Improve Table API ergonomics by removing optional unwrapping

Replace optional return types with error handling for Table.get() and Table.getRaw().
This eliminates the need for repetitive optional unwrapping while maintaining type safety.

- Table.get() now returns T instead of ?T, throws Error.KeyNotFound when key missing
- Table.getRaw() now returns T instead of ?T, throws Error.KeyNotFound when index missing
- Remove getRequired() method as get() now provides the same behavior
- Add Error.KeyNotFound for missing keys or conversion failures
- Update all tests and documentation examples to use simplified API
- Update Debug.zig tests to work with new non-optional Function references

Author: mxpv

src/Debug.zig

@@ -765,8 +765,8 @@ test "debugTrace shows function names in call stack" {
 
     // Get the innerFunc and set a breakpoint
     const func = try lua.globals().get("innerFunc", Lua.Function);
-    defer func.?.deinit();
-    _ = try func.?.setBreakpoint(2, true); // Line 2: return 42
+    defer func.deinit();
+    _ = try func.setBreakpoint(2, true); // Line 2: return 42
 
     // Call the nested functions - this should hit the breakpoint
     const result = try lua.eval("return outerFunc()", .{}, i32);
@@ -819,16 +819,15 @@ test "breakpoint and single step debugging with callbacks" {
 
     // Get function reference
     const func = try lua.globals().get("test_func", Lua.Function);
-    try expect(func != null);
-    defer func.?.deinit();
+    defer func.deinit();
 
-    const breakpoint_line = try func.?.setBreakpoint(4, true);
+    const breakpoint_line = try func.setBreakpoint(4, true);
     try expectEqual(breakpoint_line, 5);
 
     lua.debug().setSingleStep(true);
     lua.setCallbacks(&callbacks);
 
-    const result = try func.?.call(.{}, i32);
+    const result = try func.call(.{}, i32);
 
     try expectEqual(result.ok, 60);
     try expectEqual(callbacks.break_hits, 1);
@@ -864,17 +863,17 @@ test "coroutine debug break" {
     , .{}, void);
 
     const func = try thread.globals().get("test_func", Lua.Function);
-    defer func.?.deinit();
+    defer func.deinit();
 
-    _ = try func.?.setBreakpoint(2, true);
+    _ = try func.setBreakpoint(2, true);
 
-    const first_result = try func.?.call(.{}, i32);
+    const first_result = try func.call(.{}, i32);
     try expectEqual(first_result, .debugBreak);
 
     try expectEqual(thread.status(), .normal);
 
     // Call function again - should complete and return result
-    const second_result = try func.?.call(.{}, i32);
+    const second_result = try func.call(.{}, i32);
     try expectEqual(second_result.ok, 42);
 
     // Assert debugbreak callback was called exactly twice
@@ -929,11 +928,11 @@ test "getInfo and stackDepth in debug breakpoint" {
 
     // Get the function and set a breakpoint
     const func = try lua.globals().get("testFunction", Lua.Function);
-    defer func.?.deinit();
-    _ = try func.?.setBreakpoint(3, true); // Line 3: return x * 2
+    defer func.deinit();
+    _ = try func.setBreakpoint(3, true); // Line 3: return x * 2
 
     // Call the function - this should hit the breakpoint
-    const result = try func.?.call(.{ 5, 10 }, i32);
+    const result = try func.call(.{ 5, 10 }, i32);
     try expectEqual(result.ok.?, 30);
 
     // Verify breakpoint was hit
@@ -955,7 +954,7 @@ test "getInfo outside of hook" {
     _ = try lua.eval(code, .{}, void);
 
     // Get the function and execute it
-    const func = (try lua.globals().get("testFunction", Lua.Function)).?;
+    const func = try lua.globals().get("testFunction", Lua.Function);
     defer func.deinit();
 
     const result = try func.call(.{ 5, 10 }, i32);
@@ -1036,11 +1035,11 @@ test "getArg in debug breakpoint" {
 
     // Get the function and set a breakpoint
     const func = try lua.globals().get("testArguments", Lua.Function);
-    defer func.?.deinit();
-    _ = try func.?.setBreakpoint(3, true); // Line 3: return sum
+    defer func.deinit();
+    _ = try func.setBreakpoint(3, true); // Line 3: return sum
 
     // Call the function with known arguments - this should hit the breakpoint
-    const result = try func.?.call(.{ 100, 200 }, i32);
+    const result = try func.call(.{ 100, 200 }, i32);
     try expectEqual(result.ok.?, 300);
 
     // Verify breakpoint was hit and arguments were tested
@@ -1132,10 +1131,10 @@ test "getLocal and setLocal in debug breakpoint" {
     }
 
     const func = try lua.globals().get("testLocals", Lua.Function);
-    defer func.?.deinit();
-    _ = try func.?.setBreakpoint(5, true); // Line 5: return sum
+    defer func.deinit();
+    _ = try func.setBreakpoint(5, true); // Line 5: return sum
 
-    const call_result = try func.?.call(.{ 100, 200 }, i32);
+    const call_result = try func.call(.{ 100, 200 }, i32);
     try expectEqual(call_result.ok.?, 400);
 
     try expect(LocalVariableTester.breakpoint_hit);
@@ -1227,13 +1226,13 @@ test "getUpvalue and setUpvalue in debug breakpoint" {
     }
 
     const func = try lua.globals().get("innerFunction", Lua.Function);
-    defer func.?.deinit();
+    defer func.deinit();
 
     // Try line 3 (function start is line 2, line 3 is return)
-    const actual_line = try func.?.setBreakpoint(3, true);
+    const actual_line = try func.setBreakpoint(3, true);
     try expectEqual(actual_line, 3);
 
-    const call_result = try func.?.call(.{}, i32);
+    const call_result = try func.call(.{}, i32);
     try expectEqual(call_result.ok.?, 1998); // 999 * 2 (modified upvalue)
 
     try expect(UpvalueTester.breakpoint_hit);
@@ -1270,35 +1269,35 @@ test "high-level getUpvalue and setUpvalue API" {
     }
 
     const func = try lua.globals().get("closure", Lua.Function);
-    defer func.?.deinit();
+    defer func.deinit();
 
     const debug = lua.debug();
 
     // Test getting upvalue using high-level API
-    const upval1 = debug.getUpvalue(func.?, 1, i32);
+    const upval1 = debug.getUpvalue(func, 1, i32);
     try expect(upval1 != null);
     try expectEqual(upval1.?.value, 42);
     try expect(std.mem.eql(u8, upval1.?.name, "shared_value"));
 
     // Test setting upvalue using high-level API
-    const set_name = debug.setUpvalue(func.?, 1, i32, 100);
+    const set_name = debug.setUpvalue(func, 1, i32, 100);
     try expect(set_name != null);
     try expect(std.mem.eql(u8, set_name.?, "shared_value"));
 
     // Verify the upvalue was changed
-    const upval2 = debug.getUpvalue(func.?, 1, i32);
+    const upval2 = debug.getUpvalue(func, 1, i32);
     try expect(upval2 != null);
     try expectEqual(upval2.?.value, 100);
 
     // Test the function returns the modified upvalue
-    const call_result = try func.?.call(.{}, i32);
+    const call_result = try func.call(.{}, i32);
     try expectEqual(call_result.ok.?, 100);
 
     // Test getting non-existent upvalue
-    const upval_invalid = debug.getUpvalue(func.?, 10, i32);
+    const upval_invalid = debug.getUpvalue(func, 10, i32);
     try expect(upval_invalid == null);
 
     // Test setting non-existent upvalue
-    const set_invalid = debug.setUpvalue(func.?, 10, i32, 42);
+    const set_invalid = debug.setUpvalue(func, 10, i32, 42);
     try expect(set_invalid == null);
 }

src/Lua.zig

@@ -60,6 +60,8 @@ pub const Error = error{
     Runtime,
     /// Breakpoint could not be set at the specified line.
     InvalidBreakpoint,
+    /// Key not found in table or value could not be converted to requested type.
+    KeyNotFound,
 };
 
 /// Assert handler function type for Luau VM assertions.
@@ -582,26 +584,25 @@ pub const Table = struct {
     /// Directly retrieves `table[index]` without invoking metamethods.
     /// This is faster than `get()` but doesn't respect custom table behavior.
     ///
-    /// Returns `null` if the index doesn't exist or the value cannot be converted to type `T`.
-    ///
     /// Examples:
     /// ```zig
     /// const value = try table.getRaw(1, i32);     // Get table[1] as i32
     /// const text = try table.getRaw(5, []u8);     // Get table[5] as string
     /// const flag = try table.getRaw(-1, bool);    // Get table[-1] as bool
     /// ```
     ///
-    /// Returns: `?T` - The converted value, or `null` if not found or conversion failed
-    /// Errors: `Error.OutOfMemory` if stack allocation fails
-    pub fn getRaw(self: Table, index: i32, comptime T: type) !?T {
+    /// Returns: `T` - The converted value
+    /// Errors: `Error.OutOfMemory` if stack allocation fails, `Error.KeyNotFound` if index doesn't exist or conversion failed
+    pub fn getRaw(self: Table, index: i32, comptime T: type) !T {
         try self.ref.lua.checkStack(2);
 
         stack.push(self.state(), self.ref); // Push table ref
         _ = self.state().rawGetI(-1, index); // Push value of t[i] onto stack.
 
         defer self.state().pop(1); // Pop table
 
-        return stack.pop(self.ref.lua, T);
+        const value = stack.pop(self.ref.lua, T);
+        return value orelse error.KeyNotFound;
     }
 
     /// Sets a table element by key with full Lua semantics (invokes __newindex metamethod).
@@ -747,8 +748,6 @@ pub const Table = struct {
     /// - Lua nil → Optional types (`?T`) as `null`
     /// - Any valid value → Optional types (`?T`) as wrapped value
     ///
-    /// Returns `null` if the key doesn't exist or the value cannot be converted to type `T`.
-    ///
     /// Note: String conversion is not supported via `get` due to Lua's garbage collection.
     /// For safe string handling, use Lua code with `eval()` or the low-level State API.
     ///
@@ -761,7 +760,7 @@ pub const Table = struct {
     /// const pos = try table.get("pos", @Vector(3, f32)); // Get vector value
     ///
     /// // Optional types (handle missing values gracefully)
-    /// const maybe_value = try table.get("missing", ?i32);  // null if missing
+    /// const maybe_value = table.get("missing", ?i32) catch null;  // null if missing
     /// const nullable = try table.get("nil_field", ?i32);   // null if nil
     ///
     /// // Different key types
@@ -775,9 +774,9 @@ pub const Table = struct {
     /// // The tuple becomes a nested table accessible by index
     /// ```
     ///
-    /// Returns: `?T` - The converted value, or `null` if not found or conversion failed
-    /// Errors: `Error.OutOfMemory` if stack allocation fails
-    pub fn get(self: Table, key: anytype, comptime T: type) !?T {
+    /// Returns: `T` - The converted value
+    /// Errors: `Error.OutOfMemory` if stack allocation fails, `Error.KeyNotFound` if key doesn't exist or conversion failed
+    pub fn get(self: Table, key: anytype, comptime T: type) !T {
         try self.ref.lua.checkStack(2);
 
         stack.push(self.state(), self.ref); // Push table ref
@@ -786,7 +785,8 @@ pub const Table = struct {
         _ = self.state().getTable(-2); // Pop key and push "table[key]" onto stack
         defer self.state().pop(1); // Pop table
 
-        return stack.pop(self.ref.lua, T);
+        const value = stack.pop(self.ref.lua, T);
+        return value orelse error.KeyNotFound;
     }
 
     /// Calls a function stored in the table.
@@ -1624,7 +1624,7 @@ pub const Function = struct {
     ///
     /// // Coroutine example - function can yield
     /// const thread = lua.createThread();
-    /// const func = try thread.globals().get("coroutine_func", Function).?;
+    /// const func = try thread.globals().get("coroutine_func", Function);
     /// defer func.deinit();
     ///
     /// const result1 = try func.call(.{}, i32);     // Start coroutine, may yield
@@ -1665,13 +1665,13 @@ pub const Function = struct {
     ///     _ = try lua.eval("function fibonacci(n) return n < 2 and n or fibonacci(n-1) + fibonacci(n-2) end", .{}, void);
     ///     const globals = lua.globals();
     ///     const fib = try globals.get("fibonacci", Lua.Function);
-    ///     defer fib.?.deinit();
+    ///     defer fib.deinit();
     ///
     ///     // Compile for better performance
-    ///     fib.?.compile();
+    ///     fib.compile();
     ///
     ///     // Function calls now use compiled native code
-    ///     const result = try fib.?.call(.{10}, i32);
+    ///     const result = try fib.call(.{10}, i32);
     /// }
     /// ```
     pub fn compile(self: @This()) void {
@@ -1690,9 +1690,9 @@ pub const Function = struct {
     /// Example:
     /// ```zig
     /// const func = try lua.globals().get("myFunc", Lua.Function);
-    /// defer func.?.deinit();
+    /// defer func.deinit();
     ///
-    /// const cloned = try func.?.clone();
+    /// const cloned = try func.clone();
     /// defer cloned.deinit();
     /// ```
     ///
@@ -2521,8 +2521,8 @@ test "table ops" {
     try expectEq(try table.get("flag", bool), false);
 
     // Test non-existent keys
-    try expectEq(try table.getRaw(999, i32), null);
-    try expectEq(try table.get("missing", i32), null);
+    try expectError(Error.KeyNotFound, table.getRaw(999, i32));
+    try expectError(Error.KeyNotFound, table.get("missing", i32));
 
     // Test pushing table to stack
     try table.set("test", 42);