Improved API of hook method on NSObject

lukaskubanek · lukaskubanek · commit d1948cdc0c03 · 2025-03-23T13:08:31.000+01:00
diff --git a/Sources/InterposeKit/InterposeKit.swift b/Sources/InterposeKit/InterposeKit.swift
@@ -1,31 +1,5 @@
 import Foundation
 
-extension NSObject {
-    /// Hook an `@objc dynamic` instance method via selector  on the current object or class..
-    @discardableResult public func hook<MethodSignature, HookSignature> (
-        _ selector: Selector,
-        methodSignature: MethodSignature.Type = MethodSignature.self,
-        hookSignature: HookSignature.Type = HookSignature.self,
-        _ implementation: (TypedHook<MethodSignature, HookSignature>) -> HookSignature?) throws -> AnyHook {
-
-        if let klass = self as? AnyClass {
-            return try Interpose.ClassHook(class: klass, selector: selector, implementation: implementation).apply()
-        } else {
-            return try Interpose.ObjectHook(object: self, selector: selector, implementation: implementation).apply()
-        }
-    }
-
-    /// Hook an `@objc dynamic` instance method via selector  on the current object or class..
-    @discardableResult public class func hook<MethodSignature, HookSignature> (
-        _ selector: Selector,
-        methodSignature: MethodSignature.Type = MethodSignature.self,
-        hookSignature: HookSignature.Type = HookSignature.self,
-        _ implementation: (TypedHook<MethodSignature, HookSignature>) -> HookSignature?) throws -> AnyHook {
-        return try Interpose.ClassHook(class: self as AnyClass,
-                                       selector: selector, implementation: implementation).apply()
-    }
-}
-
 /// Interpose is a modern library to swizzle elegantly in Swift.
 ///
 /// Methods are hooked via replacing the implementation, instead of the usual exchange.
diff --git a/Sources/InterposeKit/NSObject+InterposeKit.swift b/Sources/InterposeKit/NSObject+InterposeKit.swift
@@ -0,0 +1,100 @@
+import ObjectiveC
+
+extension NSObject {
+    
+    /// Installs a hook for the specified Objective-C selector on this object instance.
+    ///
+    /// This method replaces the implementation of an Objective-C instance method with
+    /// a block-based implementation, while optionally allowing access to the original
+    /// implementation.
+    ///
+    /// To be hookable, the method must be exposed to the Objective-C runtime. When written
+    /// in Swift, it must be marked `@objc dynamic`.
+    ///
+    /// - Parameters:
+    ///   - selector: The selector of the instance method to hook.
+    ///   - methodSignature: The expected C function type of the original method implementation.
+    ///   - hookSignature: The type of the replacement block.
+    ///   - implementation: A closure that receives a `TypedHook` and returns the replacement
+    ///     implementation block.
+    ///
+    /// - Returns: An `AnyHook` representing the installed hook, allowing to remove the hook later
+    ///   by calling `hook.revert()`.
+    ///
+    /// - Throws: An error if the hook could not be applied, such as if the method does not exist
+    ///   or is not implemented in Objective-C.
+    ///
+    /// ### Example
+    ///
+    /// ```swift
+    /// let hook = try object.addHook(
+    ///     for: #selector(MyClass.someMethod),
+    ///     methodSignature: (@convention(c) (NSObject, Selector, Int) -> Void).self,
+    ///     hookSignature: (@convention(block) (NSObject, Int) -> Void).self
+    /// ) { hook in
+    ///     return { `self`, parameter in
+    ///         hook.original(self, hook.selector, parameter)
+    ///     }
+    /// }
+    ///
+    /// hook.revert()
+    /// ```
+    @discardableResult
+    public func addHook<MethodSignature, HookSignature>(
+        for selector: Selector,
+        methodSignature: MethodSignature.Type,
+        hookSignature: HookSignature.Type,
+        implementation: (TypedHook<MethodSignature, HookSignature>) -> HookSignature?
+    ) throws -> AnyHook {
+        try Interpose.ObjectHook(
+            object: self,
+            selector: selector,
+            implementation: implementation
+        ).apply()
+    }
+    
+}
+
+extension NSObject {
+    
+    @available(*, deprecated, renamed: "addHook(for:methodSignature:hookSignature:using:)")
+    @discardableResult
+    public func hook<MethodSignature, HookSignature> (
+        _ selector: Selector,
+        methodSignature: MethodSignature.Type = MethodSignature.self,
+        hookSignature: HookSignature.Type = HookSignature.self,
+        _ implementation: (TypedHook<MethodSignature, HookSignature>) -> HookSignature?
+    ) throws -> AnyHook {
+        precondition(
+            !(self is AnyClass),
+            "There should not be a way to cast an NSObject to AnyClass."
+        )
+        
+        return try self.addHook(
+            for: selector,
+            methodSignature: methodSignature,
+            hookSignature: hookSignature,
+            implementation: implementation
+        )
+    }
+    
+    @available(*, deprecated, message: """
+    Deprecated to avoid confusion: this hooks instance methods on classes, but can be mistaken \
+    for hooking class methods, which is not supported. Use `Interpose(Class.self)` with \
+    `prepareHook(…)` to make the intent explicit.
+    """)
+    @discardableResult
+    public class func hook<MethodSignature, HookSignature> (
+        _ selector: Selector,
+        methodSignature: MethodSignature.Type = MethodSignature.self,
+        hookSignature: HookSignature.Type = HookSignature.self,
+        _ implementation: (TypedHook<MethodSignature, HookSignature>) -> HookSignature?
+    ) throws -> AnyHook {
+        return try Interpose.ClassHook(
+            class: self as AnyClass,
+            selector: selector,
+            implementation: implementation
+        ).apply()
+    }
+    
+}
diff --git a/Tests/InterposeKitTests/MultipleInterposing.swift b/Tests/InterposeKitTests/MultipleInterposing.swift
@@ -25,12 +25,14 @@ final class MultipleInterposingTests: InterposeKitTestCase {
         XCTAssertEqual(testObj.sayHi(), testClassHi + testString)
         XCTAssertEqual(testObj2.sayHi(), testClassHi)
 
-        try testObj.hook(
-            #selector(TestClass.sayHi),
+        try testObj.addHook(
+            for: #selector(TestClass.sayHi),
             methodSignature: (@convention(c) (AnyObject, Selector) -> String).self,
-            hookSignature: (@convention(block) (AnyObject) -> String).self) { store in { bSelf in
-                return store.original(bSelf, store.selector) + testString2
-                }
+            hookSignature: (@convention(block) (AnyObject) -> String).self
+        ) { hook in
+            return { `self` in
+                return hook.original(self, hook.selector) + testString2
+            }
         }
 
         XCTAssertEqual(testObj.sayHi(), testClassHi + testString + testString2)
diff --git a/Tests/InterposeKitTests/ObjectInterposeTests.swift b/Tests/InterposeKitTests/ObjectInterposeTests.swift
@@ -11,15 +11,17 @@ final class ObjectInterposeTests: InterposeKitTestCase {
         XCTAssertEqual(testObj.sayHi(), testClassHi)
         XCTAssertEqual(testObj2.sayHi(), testClassHi)
 
-        let hook = try testObj.hook(
-            #selector(TestClass.sayHi),
+        let hook = try testObj.addHook(
+            for: #selector(TestClass.sayHi),
             methodSignature: (@convention(c) (AnyObject, Selector) -> String).self,
-            hookSignature: (@convention(block) (AnyObject) -> String).self) { store in { bSelf in
-                print("Before Interposing \(bSelf)")
-                let string = store.original(bSelf, store.selector)
-                print("After Interposing \(bSelf)")
+            hookSignature: (@convention(block) (AnyObject) -> String).self
+        ) { hook in
+            return { `self` in
+                print("Before Interposing \(self)")
+                let string = hook.original(self, hook.selector)
+                print("After Interposing \(self)")
                 return string + testString
-                }
+            }
         }
 
         XCTAssertEqual(testObj.sayHi(), testClassHi + testString)
@@ -38,11 +40,14 @@ final class ObjectInterposeTests: InterposeKitTestCase {
         let returnIntOverrideOffset = 2
         XCTAssertEqual(testObj.returnInt(), returnIntDefault)
 
-        let hook = try testObj.hook(#selector(TestClass.returnInt)) { (store: TypedHook
-            <@convention(c) (AnyObject, Selector) -> Int,
-                @convention(block) (AnyObject) -> Int>) in {
-                    let int = store.original($0, store.selector)
-                    return int + returnIntOverrideOffset
+        let hook = try testObj.addHook(
+            for: #selector(TestClass.returnInt),
+            methodSignature: (@convention(c) (AnyObject, Selector) -> Int).self,
+            hookSignature: (@convention(block) (AnyObject) -> Int).self
+        ) { hook in
+            return { `self` in
+                let int = hook.original(self, hook.selector)
+                return int + returnIntOverrideOffset
             }
         }
 
@@ -66,11 +71,14 @@ final class ObjectInterposeTests: InterposeKitTestCase {
         XCTAssertEqual(testObj.returnInt(), returnIntDefault)
 
         // Functions need to be `@objc dynamic` to be hookable.
-        let hook = try testObj.hook(#selector(TestClass.returnInt)) { (store: TypedHook
-            <@convention(c) (AnyObject, Selector) -> Int,
-            @convention(block) (AnyObject) -> Int>) in {
+        let hook = try testObj.addHook(
+            for: #selector(TestClass.returnInt),
+            methodSignature: (@convention(c) (AnyObject, Selector) -> Int).self,
+            hookSignature: (@convention(block) (AnyObject) -> Int).self
+        ) { hook in
+            return { `self` in
                 // You're free to skip calling the original implementation.
-                store.original($0, store.selector) + returnIntOverrideOffset
+                hook.original(self, hook.selector) + returnIntOverrideOffset
             }
         }
         XCTAssertEqual(testObj.returnInt(), returnIntDefault + returnIntOverrideOffset)
@@ -102,11 +110,13 @@ final class ObjectInterposeTests: InterposeKitTestCase {
         XCTAssertEqual(testObj.calculate(var1: 1, var2: 2, var3: 3), 1 + 2 + 3)
 
         // Functions need to be `@objc dynamic` to be hookable.
-        let hook = try testObj.hook(#selector(TestClass.calculate)) { (store: TypedHook
-            <@convention(c) (AnyObject, Selector, Int, Int, Int) -> Int,
-            @convention(block) (AnyObject, Int, Int, Int) -> Int>) in {
-                // You're free to skip calling the original implementation.
-                let orig = store.original($0, store.selector, $1, $2, $3)
+        let hook = try testObj.addHook(
+            for: #selector(TestClass.calculate),
+            methodSignature: (@convention(c) (AnyObject, Selector, Int, Int, Int) -> Int).self,
+            hookSignature: (@convention(block) (AnyObject, Int, Int, Int) -> Int).self
+        ) { hook in
+            return {
+                let orig = hook.original($0, hook.selector, $1, $2, $3)
                 return orig + 1
             }
         }
@@ -121,11 +131,14 @@ final class ObjectInterposeTests: InterposeKitTestCase {
                                           var4: 4, var5: 5, var6: 6), 1 + 2 + 3 + 4 + 5 + 6)
 
         // Functions need to be `@objc dynamic` to be hookable.
-        let hook = try testObj.hook(#selector(TestClass.calculate2)) { (store: TypedHook
-            <@convention(c) (AnyObject, Selector, Int, Int, Int, Int, Int, Int) -> Int,
-            @convention(block) (AnyObject, Int, Int, Int, Int, Int, Int) -> Int>) in {
+        let hook = try testObj.addHook(
+            for: #selector(TestClass.calculate2),
+            methodSignature: (@convention(c) (AnyObject, Selector, Int, Int, Int, Int, Int, Int) -> Int).self,
+            hookSignature: (@convention(block) (AnyObject, Int, Int, Int, Int, Int, Int) -> Int).self
+        ) { hook in
+            return {
                 // You're free to skip calling the original implementation.
-                let orig = store.original($0, store.selector, $1, $2, $3, $4, $5, $6)
+                let orig = hook.original($0, hook.selector, $1, $2, $3, $4, $5, $6)
                 return orig + 1
             }
         }
@@ -140,10 +153,13 @@ final class ObjectInterposeTests: InterposeKitTestCase {
         XCTAssertEqual(testObj.doubleString(string: str), str + str)
 
         // Functions need to be `@objc dynamic` to be hookable.
-        let hook = try testObj.hook(#selector(TestClass.doubleString)) { (store: TypedHook
-            <@convention(c) (AnyObject, Selector, String) -> String,
-            @convention(block) (AnyObject, String) -> String>) in {
-                store.original($0, store.selector, $1) + str
+        let hook = try testObj.addHook(
+            for: #selector(TestClass.doubleString),
+            methodSignature: (@convention(c) (AnyObject, Selector, String) -> String).self,
+            hookSignature: (@convention(block) (AnyObject, String) -> String).self
+        ) { hook in
+            return { `self`, parameter in
+                hook.original(self, hook.selector, parameter) + str
             }
         }
         XCTAssertEqual(testObj.doubleString(string: str), str + str + str)
@@ -155,8 +171,8 @@ final class ObjectInterposeTests: InterposeKitTestCase {
         let object = TestClass()
         XCTAssertEqual(object.getPoint(), CGPoint(x: -1, y: 1))
         
-        let hook = try object.hook(
-            #selector(TestClass.getPoint),
+        let hook = try object.addHook(
+            for: #selector(TestClass.getPoint),
             methodSignature: (@convention(c) (NSObject, Selector) -> CGPoint).self,
             hookSignature: (@convention(block) (NSObject) -> CGPoint).self
         ) { hook in
@@ -182,8 +198,8 @@ final class ObjectInterposeTests: InterposeKitTestCase {
             CGPoint(x: 1, y: 1)
         )
         
-        let hook = try object.hook(
-            #selector(TestClass.passthroughPoint(_:)),
+        let hook = try object.addHook(
+            for: #selector(TestClass.passthroughPoint(_:)),
             methodSignature: (@convention(c) (NSObject, Selector, CGPoint) -> CGPoint).self,
             hookSignature: (@convention(block) (NSObject, CGPoint) -> CGPoint).self
         ) { hook in
