Add push(enum:) API

Author: tomsci

Sources/Lua/Documentation.docc/Articles/BridgingSwiftToLua.md

@@ -10,7 +10,7 @@ Basic Swift types are pushed by value -- that is to say they are copied and conv
 
 Bridged values on the other hand are represented in Lua using the `userdata` Lua type, which from the Swift side behave as if there was an assignment like `var userdataVar: T? = myval` (where `T` is the type used in the `Metatable`, described below). So for classes, the `userdata` holds an additional reference to the object, and for structs the `userdata` holds a value copy of it. A `__gc` metamethod is automatically generated, which means that when the `userdata` is garbage collected by Lua, the equivalent of `userdataVar = nil` is performed.
 
-> Note: While defining metatables for `struct` types is supported, all userdata in Lua are copy-by-reference, so the object will behave more like a class from the Lua side. Overall, `class` types can be a better fit for how the bridging logic behaves.
+> Note: While defining metatables for `struct` (and `enum`) types is supported, all userdata in Lua are copy-by-reference, so the object will behave more like a class from the Lua side. Overall, `class` types can be a better fit for how the bridging logic behaves.
 
 As described so far, the `userdata` plays nicely with Lua and Swift object lifetimes and memory management, but does not allow you to do anything useful with it from Lua other than controlling when it goes out of scope. This is where defining a metatable comes in.
 
@@ -73,9 +73,11 @@ L.register(Metatable<Foo>(fields: [
 
 Any arguments to the closure are type-checked using using `L.checkArgument<ArgumentType>()`. Anything which exceeds the type inference abilities of `memberfn` can always be written explicitly using `closure`. The full list of helpers that can be used to define fields is defined in ``Metatable/FieldType``. Note there are multiple overloads of `memberfn` to accommodate different numbers of arguments.
 
+> Note: The above description skipped some of the nuances that, for example, avoid copying the value when using `.closure` with a struct type, which would entail using `checkUserdata(1)` rather than `checkArgument(1)`. Use `.memberfn` where possible which hides that complexity.
+
 ## Pushing values into Lua
 
-Having defined a metatable for our type, we can use [`push(userdata:)`](doc:Lua/Swift/UnsafeMutablePointer/push(userdata:toindex:)) or [`push(any:)`](doc:Lua/Swift/UnsafeMutablePointer/push(any:toindex:)) to push instances of it on to the Lua stack, at which point we can assign it to a variable just like any other Lua value. Using the example `Foo` class described above, and assuming our Lua code expects a single global value called `foo` to be defined, we could use ``Lua/Swift/UnsafeMutablePointer/setglobal(name:)``:
+Having defined a metatable for our type by calling `register()`, we can use [`push(userdata:)`](doc:Lua/Swift/UnsafeMutablePointer/push(userdata:toindex:)) or [`push(any:)`](doc:Lua/Swift/UnsafeMutablePointer/push(any:toindex:)) to push instances of it on to the Lua stack, at which point we can assign it to a variable just like any other Lua value. Using the example `Foo` class described above, and assuming our Lua code expects a single global value called `foo` to be defined, we could use ``Lua/Swift/UnsafeMutablePointer/setglobal(name:)``:
 
 ```swift
 let foo = Foo()
@@ -155,7 +157,7 @@ To customize the bridging above and beyond adding fields to the userdata, we can
 ```swift
 L.register(Metatable<Foo>(
     call: .memberfn { obj in
-        print("I have no idea what this should do")
+        print("object was called")
     },
     close: .memberfn { obj in
         // Do whatever is appropriate to obj here,

Sources/Lua/Documentation.docc/Articles/LuaState.md

@@ -288,6 +288,7 @@ Some Lua C APIs do not make sense to be called from Swift; usually this is becau
 - ``Lua/Swift/UnsafeMutablePointer/push(tuple:)``
 - ``Lua/Swift/UnsafeMutablePointer/pushthread()``
 - ``Lua/Swift/UnsafeMutablePointer/pushglobals(toindex:)-3ot28``
+- ``Lua/Swift/UnsafeMutablePointer/push(enum:toindex:)``
 
 ### Iterators
 

Sources/Lua/LuaState.swift

@@ -2855,6 +2855,43 @@ extension UnsafeMutablePointer where Pointee == lua_State {
         }
     }
 
+    /// Pushes a table of all the cases of an enum on to the stack.
+    ///
+    /// Push all the cases of an enum on to the stack, as a table mapping case names to values. This is useful to make
+    /// an enum available for use by Lua code. The enum must be `CaseIterable` and ``Pushable`` -- this is most easily
+    /// done by also inheriting ``RawPushable``.
+    ///
+    /// For example:
+    /// ```swift
+    /// enum MyEnum: Int, CaseIterable, RawPushable {
+    ///     case foo = 1
+    ///     case bar = 2
+    /// }
+    ///
+    /// L.push(enum: MyEnum.self)
+    /// L.setglobal(name: "MyEnum")
+    /// try L.dostring("print(MyEnum.bar)") // prints "2"
+    /// ```
+    ///
+    /// The above `push` and `setglobal` calls could also be combined by using the [`.enum`](doc:Pushable/enum(_:))
+    /// `Pushable` helper.
+    ///
+    /// > Note: This function is for exposing the entire declaration of an enum to Lua. To push a particular enum value,
+    ///   treat it like any other pushable value and call [`push(value)`](doc:push(_:toindex:)-59fx9).
+    ///
+    /// - Parameter enumType: The enum to push on to the Lua stack, which must inherit `CaseIterable` and `Pushable`.
+    /// - Parameter toindex: See <doc:LuaState#Push-functions-toindex-parameter>.
+    public func push<T>(enum enumType: T.Type, toindex: CInt = -1) where T: CaseIterable & Pushable {
+        let cases = enumType.allCases
+        newtable(nrec: CInt(exactly: cases.count) ?? 0)
+        for c in cases {
+            rawset(-1, utf8Key: "\(c)", value: c)
+        }
+        if toindex != -1 {
+            insert(toindex)
+        }
+    }
+
     // MARK: - Calling into Lua
 
     /// Make a protected call to a Lua function, optionally including a stack trace in any errors.

Sources/Lua/Pushable.swift

@@ -148,6 +148,15 @@ public struct LuaUserdataWrapper: Pushable {
     }
 }
 
+/// A `Pushable` wrapper that pushes an enum.
+///
+/// See ``Pushable/enum(_:)``.
+public struct LuaEnumWrapper<T>: Pushable where T: CaseIterable & Pushable {
+    public func push(onto L: LuaState) {
+        L.push(enum: T.self)
+    }
+}
+
 public struct _NonPushableTypesHelper: Pushable {
     private init() {}
     public func push(onto L: LuaState) {
@@ -227,4 +236,45 @@ extension Pushable where Self == _NonPushableTypesHelper {
     public static func userdata(_ val: Any) -> LuaUserdataWrapper {
         return LuaUserdataWrapper(value: val)
     }
+
+    /// Returns a Pushable which pushes its value using `push(enum:)`.
+    ///
+    /// This permits the use of `.enum(enumType)` anywhere a Pushable can be specified. For example to define a global
+    /// value that exposes all the values of an enum `Foo`:
+    ///
+    /// ```swift
+    /// enum Foo: String, CaseIterable {
+    ///     case someThing
+    ///     case otherThing
+    /// }
+    ///
+    /// L.setglobal(name: "Foo", value: .enum(Foo.self))
+    /// // You can now do `Foo.someThing` etc from Lua.
+    /// ```
+    public static func `enum`<T>(_ e: T.Type) -> LuaEnumWrapper<T> where T: CaseIterable & Pushable {
+        return LuaEnumWrapper<T>()
+    }
+}
+
+/// Protocol for making a `RawRepresentable` type be `Pushable` using its `rawValue`.
+///
+/// By declaring that a type conforms to this protocol, the type becomes `Pushable` using its `rawValue`. For example,
+/// you can use this to make an enum `Pushable`:
+///
+/// ```swift
+/// enum E: String, RawPushable {
+///     case one
+///     case two
+/// }
+///
+/// L.push(E.one) // pushes the string "one" onto the stack
+/// ```
+///
+/// You do not need to supply an implementation of `Pushable.push(onto:)` -- one is created automatically.
+public protocol RawPushable: Pushable, RawRepresentable {}
+
+public extension RawPushable {
+    func push(onto state: LuaState) {
+        state.push(any: self.rawValue)
+    }
 }

Tests/lua-test/LuaTests.swift

@@ -1528,7 +1528,7 @@ final class LuaTests: XCTestCase {
                 "foo": .memberfn { $0.foo() }
             ])}
         }
-        L.register(DefaultMetatable()) // Make sure pushMetatable doesn't create a metatable for it
+        L.register(DefaultMetatable()) // This would prevent pushMetatable from creating an empty metatable for it
         XCTAssertFalse(L.isMetatableRegistered(for: Foo.self))
         L.pushMetatable(for: Foo.self)
         XCTAssertTrue(L.isMetatableRegistered(for: Foo.self)) // Won't return true if the default ended up being used
@@ -4251,6 +4251,122 @@ final class LuaTests: XCTestCase {
         XCTAssertTrue(name.hasPrefix("ItsFoo: "), "Wrong name \(name)")
     }
 
+    func test_push_enum() throws {
+        enum EStr: String, CaseIterable, RawPushable {
+            case one
+            case two
+            case three
+        }
+        L.push(enum: EStr.self)
+        L.setglobal(name: "EStr")
+        let estrdict: [String: String]? = L.globals["EStr"].tovalue()
+        XCTAssertEqual(estrdict, ["one": "one", "two": "two", "three": "three"])
+
+        enum EInt: Int, CaseIterable, RawPushable {
+            case one = 1
+            case two = 22
+            case three = 333
+        }
+        L.setglobal(name: "EInt", value: .enum(EInt.self))
+        let eintdict: [String: Int]? = L.globals["EInt"].tovalue()
+        XCTAssertEqual(eintdict, ["one": 1, "two": 22, "three": 333])
+
+
+        enum ERawPushable: String, CaseIterable, Pushable {
+            case one
+            case two
+            case three
+
+            func push(onto state: LuaState) {
+                state.push(userdata: self)
+            }
+        }
+
+        L.push(enum: ERawPushable.self)
+        L.setglobal(name: "ERawPushable")
+        // We're only checking the above compiles, so no need to do anything with it.
+    }
+
+    func test_RawPushable_enum() throws {
+        enum E: String, RawPushable {
+            case one
+            case two
+        }
 
+        L.push(E.one)
+        XCTAssertEqual(L.tovalue(1), "one")
+    }
+
+    func test_associated_value_enum() throws {
+        enum PushableEnum: Equatable, PushableWithMetatable {
+            case foo
+            case bar(Int)
+            case baz(Int, String)
+
+            static var metatable: Metatable<PushableEnum> {
+                return Metatable<PushableEnum>(fields: [
+                    "type": .property {
+                        switch $0 {
+                        case .foo: return "foo"
+                        case .bar(_): return "bar"
+                        case .baz(_, _): return "baz"
+                        }
+                    },
+                    "barval": .property(get: { val -> Int? in
+                        if case .bar(let barval) = val {
+                            return barval
+                        } else {
+                            return nil
+                        }
+                    }),
+                    "bazint": .property {
+                        let ret: Int?
+                        if case .baz(let bazint, _) = $0 {
+                            ret = bazint
+                        } else {
+                            ret = nil
+                        }
+                        return ret
+                    },
+                    "bazstr": .property {
+                        let ret: String?
+                        if case .baz(_, let bazstr) = $0 {
+                            ret = bazstr
+                        } else {
+                            ret = nil
+                        }
+                        return ret
+                    }
+                ],
+                eq: .synthesize)
+            }
+        }
+
+        L.push(PushableEnum.foo)
+        L.push(PushableEnum.bar(42))
+        L.push(PushableEnum.baz(43, "hello"))
+        L.push(PushableEnum.baz(43, "hello"))
+        L.push(PushableEnum.baz(43, "nope"))
+        XCTAssertTrue(try L.equal(1, 1)) // Will be true regardless of eq because they are the same object
+        XCTAssertFalse(try L.equal(1, 2))
+        XCTAssertTrue(try L.equal(3, 4)) // Requires the eq metamethod
+        XCTAssertFalse(try L.equal(3, 5))
+
+        XCTAssertEqual(L.tovalue(1), PushableEnum.foo)
+        XCTAssertEqual(L.tovalue(2), PushableEnum.bar(42))
+        XCTAssertEqual(L.tovalue(3), PushableEnum.baz(43, "hello"))
+
+        L.pop(2) // baz2 and baz3
+        L.setglobal(name: "baz")
+        L.setglobal(name: "bar")
+        L.setglobal(name: "foo")
+
+        try L.dostring("assert(foo.type == 'foo')")
+        try L.dostring("assert(bar.type == 'bar')")
+        try L.dostring("assert(baz.type == 'baz')")
+
+        XCTAssertNil(L.globals["foo"]["barval"].toint())
+        XCTAssertEqual(L.globals["bar"]["barval"].toint(), 42)
+    }
 }