Deprecate Matcher-to-Predicate migration-path features as planned in the Deprecation Roadmap

Sources/Nimble/Adapters/NMBExpectation.swift

@@ -11,24 +11,27 @@ private func from(objcPredicate: NMBPredicate) -> Predicate<NSObject> {
     }
 }
 
-internal struct ObjCMatcherWrapper: Matcher {
-    let matcher: NMBMatcher
-
-    func matches(_ actualExpression: Expression<NSObject>, failureMessage: FailureMessage) -> Bool {
-        return matcher.matches(
-            // swiftlint:disable:next force_try
-            ({ try! actualExpression.evaluate() }),
-            failureMessage: failureMessage,
-            location: actualExpression.location)
-    }
-
-    func doesNotMatch(_ actualExpression: Expression<NSObject>, failureMessage: FailureMessage) -> Bool {
-        return matcher.doesNotMatch(
-            // swiftlint:disable:next force_try
-            ({ try! actualExpression.evaluate() }),
-            failureMessage: failureMessage,
-            location: actualExpression.location)
+private func from(matcher: NMBMatcher, style: ExpectationStyle) -> Predicate<NSObject> {
+    // Almost same as `Matcher.toClosure`
+    let closure: (Expression<NSObject>, FailureMessage) throws -> Bool = { expr, msg in
+        switch style {
+        case .toMatch:
+            return matcher.matches(
+                // swiftlint:disable:next force_try
+                ({ try! expr.evaluate() }),
+                failureMessage: msg,
+                location: expr.location
+            )
+        case .toNotMatch:
+            return !matcher.doesNotMatch(
+                // swiftlint:disable:next force_try
+                ({ try! expr.evaluate() }),
+                failureMessage: msg,
+                location: expr.location
+            )
+        }
     }
+    return Predicate._fromDeprecatedClosure(closure)
 }
 
 // Equivalent to Expectation, but for Nimble's Objective-C interface
@@ -65,7 +68,7 @@ public class NMBExpectation: NSObject {
             if let pred = matcher as? NMBPredicate {
                 self.expectValue.to(from(objcPredicate: pred))
             } else {
-                self.expectValue.to(ObjCMatcherWrapper(matcher: matcher))
+                self.expectValue.to(from(matcher: matcher, style: .toMatch))
             }
             return self
         }
@@ -76,7 +79,7 @@ public class NMBExpectation: NSObject {
             if let pred = matcher as? NMBPredicate {
                 self.expectValue.to(from(objcPredicate: pred), description: description)
             } else {
-                self.expectValue.to(ObjCMatcherWrapper(matcher: matcher), description: description)
+                self.expectValue.to(from(matcher: matcher, style: .toMatch), description: description)
             }
             return self
         }
@@ -87,7 +90,7 @@ public class NMBExpectation: NSObject {
             if let pred = matcher as? NMBPredicate {
                 self.expectValue.toNot(from(objcPredicate: pred))
             } else {
-                self.expectValue.toNot(ObjCMatcherWrapper(matcher: matcher))
+                self.expectValue.toNot(from(matcher: matcher, style: .toNotMatch))
             }
             return self
         }
@@ -98,7 +101,7 @@ public class NMBExpectation: NSObject {
             if let pred = matcher as? NMBPredicate {
                 self.expectValue.toNot(from(objcPredicate: pred), description: description)
             } else {
-                self.expectValue.toNot(ObjCMatcherWrapper(matcher: matcher), description: description)
+                self.expectValue.toNot(from(matcher: matcher, style: .toNotMatch), description: description)
             }
             return self
         }
@@ -118,7 +121,7 @@ public class NMBExpectation: NSObject {
                 )
             } else {
                 self.expectValue.toEventually(
-                    ObjCMatcherWrapper(matcher: matcher),
+                    from(matcher: matcher, style: .toMatch),
                     timeout: self._timeout,
                     description: nil
                 )
@@ -136,7 +139,7 @@ public class NMBExpectation: NSObject {
                 )
             } else {
                 self.expectValue.toEventually(
-                    ObjCMatcherWrapper(matcher: matcher),
+                    from(matcher: matcher, style: .toMatch),
                     timeout: self._timeout,
                     description: description
                 )
@@ -154,7 +157,7 @@ public class NMBExpectation: NSObject {
                 )
             } else {
                 self.expectValue.toEventuallyNot(
-                    ObjCMatcherWrapper(matcher: matcher),
+                    from(matcher: matcher, style: .toNotMatch),
                     timeout: self._timeout,
                     description: nil
                 )
@@ -172,7 +175,7 @@ public class NMBExpectation: NSObject {
                 )
             } else {
                 self.expectValue.toEventuallyNot(
-                    ObjCMatcherWrapper(matcher: matcher),
+                    from(matcher: matcher, style: .toNotMatch),
                     timeout: self._timeout,
                     description: description
                 )

Sources/Nimble/Expectation.swift

@@ -1,6 +1,6 @@
 import Foundation
 
-// Deprecated
+@available(*, deprecated)
 internal func expressionDoesNotMatch<T, U>(_ expression: Expression<T>, matcher: U, toNot: String, description: String?) -> (Bool, FailureMessage)
     where U: Matcher, U.ValueType == T {
     let msg = FailureMessage()
@@ -69,7 +69,9 @@ public struct Expectation<T> {
     ////////////////// OLD API /////////////////////
 
     /// DEPRECATED: Tests the actual value using a matcher to match.
-    public func to<U>(_ matcher: U, description: String? = nil)
+    @available(*, deprecated, message: "Use Predicate instead")
+    @discardableResult
+    public func to<U>(_ matcher: U, description: String? = nil) -> Self
         where U: Matcher, U.ValueType == T {
             let (pass, msg) = execute(
                 expression,
@@ -80,22 +82,28 @@ public struct Expectation<T> {
                 captureExceptions: false
             )
             verify(pass, msg)
+            return self
     }
 
     /// DEPRECATED: Tests the actual value using a matcher to not match.
-    public func toNot<U>(_ matcher: U, description: String? = nil)
+    @available(*, deprecated, message: "Use Predicate instead")
+    @discardableResult
+    public func toNot<U>(_ matcher: U, description: String? = nil) -> Self
         where U: Matcher, U.ValueType == T {
         // swiftlint:disable:next line_length
         let (pass, msg) = expressionDoesNotMatch(expression, matcher: matcher, toNot: "to not", description: description)
         verify(pass, msg)
+        return self
     }
 
     /// DEPRECATED: Tests the actual value using a matcher to not match.
     ///
     /// Alias to toNot().
-    public func notTo<U>(_ matcher: U, description: String? = nil)
+    @available(*, deprecated, message: "Use Predicate instead")
+    @discardableResult
+    public func notTo<U>(_ matcher: U, description: String? = nil) -> Self
         where U: Matcher, U.ValueType == T {
-        toNot(matcher, description: description)
+        return toNot(matcher, description: description)
     }
 
     ////////////////// NEW API /////////////////////

Sources/Nimble/Matchers/AllPass.swift

@@ -18,6 +18,7 @@ public func allPass<T, U>
         return createPredicate(matcher)
 }
 
+@available(*, deprecated, message: "Use Predicate instead")
 public func allPass<S, M>(_ elementMatcher: M) -> Predicate<S>
     where S: Sequence, M: Matcher, S.Iterator.Element == M.ValueType {
         return createPredicate(elementMatcher.predicate)

Sources/Nimble/Matchers/Async.swift

@@ -116,7 +116,7 @@ extension Expectation {
     }
 }
 
-// Deprecated
+@available(*, deprecated, message: "Use Predicate instead")
 extension Expectation {
     /// Tests the actual value using a matcher to match by checking continuously
     /// at each pollInterval until the timeout is reached.

Sources/Nimble/Matchers/MatcherFunc.swift

@@ -9,7 +9,7 @@
 /// Use the Matcher protocol instead of this type to accept custom matchers as
 /// input parameters.
 /// @see allPass for an example that uses accepts other matchers as input.
-@available(*, deprecated, message: "Use to Predicate instead")
+@available(*, deprecated, message: "Use Predicate instead")
 public struct MatcherFunc<T>: Matcher {
     public let matcher: (Expression<T>, FailureMessage) throws -> Bool
 
@@ -28,6 +28,7 @@ public struct MatcherFunc<T>: Matcher {
     /// Compatibility layer to new Matcher API. Converts an old-style matcher to a new one.
     /// Note: You should definitely spend the time to convert to the new api as soon as possible
     /// since this struct type is deprecated.
+    @available(*, deprecated, message: "Use Predicate directly instead")
     public var predicate: Predicate<T> {
         return Predicate.fromDeprecatedMatcher(self)
     }
@@ -44,7 +45,7 @@ public struct MatcherFunc<T>: Matcher {
 /// Use the Matcher protocol instead of this type to accept custom matchers as
 /// input parameters.
 /// @see allPass for an example that uses accepts other matchers as input.
-@available(*, deprecated, message: "Use to Predicate instead")
+@available(*, deprecated, message: "Use Predicate instead")
 public struct NonNilMatcherFunc<T>: Matcher {
     public let matcher: (Expression<T>, FailureMessage) throws -> Bool
 
@@ -79,6 +80,7 @@ public struct NonNilMatcherFunc<T>: Matcher {
     /// Compatibility layer to new Matcher API. Converts an old-style matcher to a new one.
     /// Note: You should definitely spend the time to convert to the new api as soon as possible
     /// since this struct type is deprecated.
+    @available(*, deprecated, message: "Use Predicate directly instead")
     public var predicate: Predicate<T> {
         return Predicate.fromDeprecatedMatcher(self)
     }

Sources/Nimble/Matchers/MatcherProtocols.swift

@@ -12,6 +12,7 @@ public protocol Matcher {
     func doesNotMatch(_ actualExpression: Expression<ValueType>, failureMessage: FailureMessage) throws -> Bool
 }
 
+@available(*, deprecated)
 extension Matcher {
     var predicate: Predicate<ValueType> {
         return Predicate.fromDeprecatedMatcher(self)

Sources/Nimble/Matchers/PostNotification.swift

@@ -66,6 +66,7 @@ public func postNotifications(
     }
 }
 
+@available(*, deprecated, message: "Use Predicate instead")
 public func postNotifications<T>(
     _ notificationsMatcher: T,
     fromNotificationCenter center: NotificationCenter = .default)

Sources/Nimble/Matchers/Predicate.swift

@@ -166,32 +166,41 @@ public enum PredicateStatus {
     }
 }
 
-// Backwards compatibility until Old Matcher API removal
-extension Predicate: Matcher {
-    /// Compatibility layer for old Matcher API, deprecated
-    public static func fromDeprecatedFullClosure(_ matcher: @escaping (Expression<T>, FailureMessage, Bool) throws -> Bool) -> Predicate {
+extension Predicate {
+    /// Compatibility layer for old Matcher API, deprecated.
+    /// Emulates the MatcherFunc API
+    internal static func _fromDeprecatedClosure(_ matcher: @escaping (Expression<T>, FailureMessage) throws -> Bool) -> Predicate {
+        // swiftlint:disable:previous identifier_name
         return Predicate { actual in
             let failureMessage = FailureMessage()
-            let result = try matcher(actual, failureMessage, true)
+            let result = try matcher(actual, failureMessage)
             return PredicateResult(
                 status: PredicateStatus(bool: result),
                 message: failureMessage.toExpectationMessage()
             )
         }
     }
+}
 
-    /// Compatibility layer for old Matcher API, deprecated.
-    /// Emulates the MatcherFunc API
-    public static func fromDeprecatedClosure(_ matcher: @escaping (Expression<T>, FailureMessage) throws -> Bool) -> Predicate {
+// Backwards compatibility until Old Matcher API removal
+@available(*, deprecated, message: "Use Predicate directly instead")
+extension Predicate: Matcher {
+    /// Compatibility layer for old Matcher API, deprecated
+    public static func fromDeprecatedFullClosure(_ matcher: @escaping (Expression<T>, FailureMessage, Bool) throws -> Bool) -> Predicate {
         return Predicate { actual in
             let failureMessage = FailureMessage()
-            let result = try matcher(actual, failureMessage)
+            let result = try matcher(actual, failureMessage, true)
             return PredicateResult(
                 status: PredicateStatus(bool: result),
                 message: failureMessage.toExpectationMessage()
             )
         }
+    }
 
+    /// Compatibility layer for old Matcher API, deprecated.
+    /// Emulates the MatcherFunc API
+    public static func fromDeprecatedClosure(_ matcher: @escaping (Expression<T>, FailureMessage) throws -> Bool) -> Predicate {
+        return _fromDeprecatedClosure(matcher)
     }
 
     /// Compatibility layer for old Matcher API, deprecated.

Sources/Nimble/Matchers/SatisfyAllOf.swift

@@ -8,6 +8,7 @@ public func satisfyAllOf<T>(_ predicates: Predicate<T>...) -> Predicate<T> {
 
 /// A Nimble matcher that succeeds when the actual value matches with all of the matchers
 /// provided in the variable list of matchers.
+@available(*, deprecated, message: "Use Predicate instead")
 public func satisfyAllOf<T, U>(_ matchers: U...) -> Predicate<T>
     where U: Matcher, U.ValueType == T {
         return satisfyAllOf(matchers.map { $0.predicate })

Sources/Nimble/Matchers/SatisfyAnyOf.swift

@@ -8,6 +8,7 @@ public func satisfyAnyOf<T>(_ predicates: Predicate<T>...) -> Predicate<T> {
 
 /// A Nimble matcher that succeeds when the actual value matches with any of the matchers
 /// provided in the variable list of matchers. 
+@available(*, deprecated, message: "Use Predicate instead")
 public func satisfyAnyOf<T, U>(_ matchers: U...) -> Predicate<T>
     where U: Matcher, U.ValueType == T {
         return satisfyAnyOf(matchers.map { $0.predicate })
@@ -45,10 +46,12 @@ public func || <T>(left: Predicate<T>, right: Predicate<T>) -> Predicate<T> {
         return satisfyAnyOf(left, right)
 }
 
+@available(*, deprecated, message: "Use Predicate instead")
 public func || <T>(left: NonNilMatcherFunc<T>, right: NonNilMatcherFunc<T>) -> Predicate<T> {
     return satisfyAnyOf(left, right)
 }
 
+@available(*, deprecated, message: "Use Predicate instead")
 public func || <T>(left: MatcherFunc<T>, right: MatcherFunc<T>) -> Predicate<T> {
     return satisfyAnyOf(left, right)
 }