Introduce the require dsl. For when you need the assertion to pass before continuing (#1103)

* Introduce the require-dsl. expect, but it returns the result of the expression

As implied, this is basically a copy-paste of the functionality of expect. It's not complete, and it's not well-tested. But it gets the idea across.
Future work is cleaning this up, backfilling tests for features (such as the unwrap function), and adding support for polling requirements (i.e. toEventually).

Other than functionality, require also files the errorThrown issue type with XCTest, whereas expect files the assertionFailed issue type. This has minor differences that are mostly semantics.

Also, in addition to the require dsl, this also adds unwrap, which is a shorthand for `require(...).toNot(beNil())`.

* Backfill some tests for requirement

Support async, but not yet polling.

* CustomNSError is only defined in Foundation

* Support polling using require

Oh, gosh. This is terrible. I think a cleaner way to do this would be to change MatcherResult to also store the most recent value.
But that would be a breaking change, and might require updating existing matchers, so... no.

* require should allow you to discard the result

Rename requireAsync to requirea - matching the example set forth by expecta.
Adds requires, which is requirea, but for specifying SyncRequirement.

* Document require in the README

Update the table of contents with doctoc.

* Remove AssertionHandler.require., require matcher failures will be recorded as test assertion failures, which is what they are anyway.

* backfill tests for pollUnwrap

Also actually mark the non-polling require dsl as discardableResult

* Mark Expectation.onFailure as deprecated in favor of the require dsl

* Rename RequirementError to RequireError

Fixed test failure on linux

* Allow passing a custom error to be thrown by require

* Update readme TOC

Author: younata

Nimble.xcodeproj/project.pbxproj

@@ -125,7 +125,12 @@
 		857D1849253610A900D8693A /* BeWithin.swift in Sources */ = {isa = PBXBuildFile; fileRef = 857D1848253610A900D8693A /* BeWithin.swift */; };
 		857D184F2536124400D8693A /* BeWithinTest.swift in Sources */ = {isa = PBXBuildFile; fileRef = 857D184D2536123F00D8693A /* BeWithinTest.swift */; };
 		8913649429E6925F00AD535E /* utils.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1F14FB63194180C5009F2A08 /* utils.swift */; };
+		891729D52B1842D6005CC866 /* DSL+Require.swift in Sources */ = {isa = PBXBuildFile; fileRef = 891729D42B1842D6005CC866 /* DSL+Require.swift */; };
+		891729D72B18431D005CC866 /* Requirement.swift in Sources */ = {isa = PBXBuildFile; fileRef = 891729D62B18431D005CC866 /* Requirement.swift */; };
 		891A04712AB0164500B46613 /* AsyncTimerSequence.swift in Sources */ = {isa = PBXBuildFile; fileRef = 891A04702AB0164500B46613 /* AsyncTimerSequence.swift */; };
+		8922828A2B2833B7002DA355 /* PollingTest+Require.swift in Sources */ = {isa = PBXBuildFile; fileRef = 892282892B2833B7002DA355 /* PollingTest+Require.swift */; };
+		8922828D2B283818002DA355 /* Polling+Require.swift in Sources */ = {isa = PBXBuildFile; fileRef = 8922828B2B2837E1002DA355 /* Polling+Require.swift */; };
+		8922828F2B283956002DA355 /* AsyncAwaitTest+Require.swift in Sources */ = {isa = PBXBuildFile; fileRef = 8922828E2B283956002DA355 /* AsyncAwaitTest+Require.swift */; };
 		892FDF1329D3EA7700523A80 /* AsyncExpression.swift in Sources */ = {isa = PBXBuildFile; fileRef = 892FDF1229D3EA7700523A80 /* AsyncExpression.swift */; };
 		896962412A5FABD000A7929D /* AsyncAllPass.swift in Sources */ = {isa = PBXBuildFile; fileRef = 896962402A5FABD000A7929D /* AsyncAllPass.swift */; };
 		8969624A2A5FAD5F00A7929D /* AsyncAllPassTest.swift in Sources */ = {isa = PBXBuildFile; fileRef = 896962452A5FAD4500A7929D /* AsyncAllPassTest.swift */; };
@@ -310,7 +315,12 @@
 		7B5358C11C39155600A23FAA /* ObjCSatisfyAnyOfTest.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = ObjCSatisfyAnyOfTest.m; sourceTree = "<group>"; };
 		857D1848253610A900D8693A /* BeWithin.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BeWithin.swift; sourceTree = "<group>"; };
 		857D184D2536123F00D8693A /* BeWithinTest.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BeWithinTest.swift; sourceTree = "<group>"; };
+		891729D42B1842D6005CC866 /* DSL+Require.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "DSL+Require.swift"; sourceTree = "<group>"; };
+		891729D62B18431D005CC866 /* Requirement.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Requirement.swift; sourceTree = "<group>"; };
 		891A04702AB0164500B46613 /* AsyncTimerSequence.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AsyncTimerSequence.swift; sourceTree = "<group>"; };
+		892282892B2833B7002DA355 /* PollingTest+Require.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "PollingTest+Require.swift"; sourceTree = "<group>"; };
+		8922828B2B2837E1002DA355 /* Polling+Require.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "Polling+Require.swift"; sourceTree = "<group>"; };
+		8922828E2B283956002DA355 /* AsyncAwaitTest+Require.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "AsyncAwaitTest+Require.swift"; sourceTree = "<group>"; };
 		892FDF1229D3EA7700523A80 /* AsyncExpression.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = AsyncExpression.swift; sourceTree = "<group>"; };
 		896962402A5FABD000A7929D /* AsyncAllPass.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AsyncAllPass.swift; sourceTree = "<group>"; };
 		896962452A5FAD4500A7929D /* AsyncAllPassTest.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AsyncAllPassTest.swift; sourceTree = "<group>"; };
@@ -448,13 +458,16 @@
 				892FDF1229D3EA7700523A80 /* AsyncExpression.swift */,
 				1FD8CD081968AB07008ED995 /* DSL.swift */,
 				899441F32902EF0900C1FAF9 /* DSL+AsyncAwait.swift */,
+				891729D42B1842D6005CC866 /* DSL+Require.swift */,
 				DA9E8C811A414BB9002633C2 /* DSL+Wait.swift */,
 				1FD8CD091968AB07008ED995 /* Expectation.swift */,
 				1FD8CD0A1968AB07008ED995 /* Expression.swift */,
 				1FE661561E6574E20035F243 /* ExpectationMessage.swift */,
 				1FD8CD0B1968AB07008ED995 /* FailureMessage.swift */,
 				1F1871E31CA89FB600A34BF2 /* Polling.swift */,
 				89F5E0852908E655001F9377 /* Polling+AsyncAwait.swift */,
+				8922828B2B2837E1002DA355 /* Polling+Require.swift */,
+				891729D62B18431D005CC866 /* Requirement.swift */,
 				1F1A742D1940169200FFFC47 /* Info.plist */,
 				1FD8CD0C1968AB07008ED995 /* Matchers */,
 				1F1A742E1940169200FFFC47 /* Nimble.h */,
@@ -470,10 +483,12 @@
 				CDC157902511957100EAA480 /* DSLTest.swift */,
 				89F5E096290C37B8001F9377 /* OnFailureThrowsTest.swift */,
 				89F5E06C290765BB001F9377 /* PollingTest.swift */,
+				892282892B2833B7002DA355 /* PollingTest+Require.swift */,
 				CDBC39B82462EA7D00069677 /* PredicateTest.swift */,
 				89F5E095290C37B8001F9377 /* StatusTest.swift */,
 				1F0648D31963AAB2001F9C46 /* SynchronousTest.swift */,
 				899441EE2902EE4B00C1FAF9 /* AsyncAwaitTest.swift */,
+				8922828E2B283956002DA355 /* AsyncAwaitTest+Require.swift */,
 				89C297CB2A911CDA002A143F /* AsyncTimerSequenceTest.swift */,
 				89C297CD2A92AB34002A143F /* AsyncPromiseTest.swift */,
 				965B0D0B1B62C06D0005AE66 /* UserDescriptionTest.swift */,
@@ -959,6 +974,7 @@
 				1FD8CD451968AB07008ED995 /* BeginWith.swift in Sources */,
 				1FD8CD4B1968AB07008ED995 /* BeIdenticalTo.swift in Sources */,
 				1FD8CD431968AB07008ED995 /* BeEmpty.swift in Sources */,
+				891729D52B1842D6005CC866 /* DSL+Require.swift in Sources */,
 				1F1871D41CA89EEE00A34BF2 /* NMBStringify.m in Sources */,
 				A8F6B5BD2070186D00FCB5ED /* SatisfyAllOf.swift in Sources */,
 				1FD8CD531968AB07008ED995 /* BeNil.swift in Sources */,
@@ -968,8 +984,10 @@
 				1FD8CD351968AB07008ED995 /* DSL.swift in Sources */,
 				7B5358BF1C38479700A23FAA /* SatisfyAnyOf.swift in Sources */,
 				896962412A5FABD000A7929D /* AsyncAllPass.swift in Sources */,
+				891729D72B18431D005CC866 /* Requirement.swift in Sources */,
 				1FD8CD391968AB07008ED995 /* Expression.swift in Sources */,
 				891A04712AB0164500B46613 /* AsyncTimerSequence.swift in Sources */,
+				8922828D2B283818002DA355 /* Polling+Require.swift in Sources */,
 				89EEF5A52A03293100988224 /* AsyncMatcher.swift in Sources */,
 				1FD8CD3B1968AB07008ED995 /* FailureMessage.swift in Sources */,
 				1FA0C3FF1E30B14500623165 /* Matcher.swift in Sources */,
@@ -1038,6 +1056,7 @@
 				DDEFAEB51A93CBE6005CA37A /* ObjCAllPassTest.m in Sources */,
 				1F4A56801A3B333F009E1637 /* ObjCBeLessThanTest.m in Sources */,
 				857D184F2536124400D8693A /* BeWithinTest.swift in Sources */,
+				8922828F2B283956002DA355 /* AsyncAwaitTest+Require.swift in Sources */,
 				1F0648CD19639F5A001F9C46 /* ObjectWithLazyProperty.swift in Sources */,
 				89F5E0A4290C3803001F9377 /* ObjCContainTest.m in Sources */,
 				106112C52251E13B000A5848 /* BeResultTest.swift in Sources */,
@@ -1046,6 +1065,7 @@
 				89C297CC2A911CDA002A143F /* AsyncTimerSequenceTest.swift in Sources */,
 				DD9A9A9019CF43AD00706F49 /* BeIdenticalToObjectTest.swift in Sources */,
 				1F4BB8B61DACA0E30048464B /* ThrowAssertionTest.swift in Sources */,
+				8922828A2B2833B7002DA355 /* PollingTest+Require.swift in Sources */,
 				8913649429E6925F00AD535E /* utils.swift in Sources */,
 				89F5E0A2290C37FB001F9377 /* ObjCBeNilTest.m in Sources */,
 				1F0648D51963AAB2001F9C46 /* SynchronousTest.swift in Sources */,

README.md

@@ -32,10 +32,23 @@ expect(ocean.isClean).toEventually(beTruthy())
   - [Operator Overloads](#operator-overloads)
   - [Lazily Computed Values](#lazily-computed-values)
   - [C Primitives](#c-primitives)
-  - [Async/Await in Expectations](#asyncawait-support)
+  - [Async/Await Support](#asyncawait-support)
+    - [Async Matchers](#async-matchers)
   - [Polling Expectations](#polling-expectations)
+    - [Using Polling Expectations in Async Tests](#using-polling-expectations-in-async-tests)
+    - [Verifying a Matcher will Never or Always Match](#verifying-a-matcher-will-never-or-always-match)
+    - [Waiting for a Callback to be Called](#waiting-for-a-callback-to-be-called)
+    - [Changing the Timeout and Polling Intervals](#changing-the-timeout-and-polling-intervals)
+    - [Changing default Timeout and Poll Intervals](#changing-default-timeout-and-poll-intervals)
+      - [Quick](#quick)
+      - [XCTest](#xctest)
   - [Objective-C Support](#objective-c-support)
   - [Disabling Objective-C Shorthand](#disabling-objective-c-shorthand)
+- [Using `require` to demand that a matcher pass before continuing](#using-require-to-demand-that-a-matcher-pass-before-continuing)
+  - [Polling with `require`.](#polling-with-require)
+  - [Using `require` with Async expressions and Async matchers](#using-require-with-async-expressions-and-async-matchers)
+  - [Using `unwrap` to replace `require(...).toNot(beNil())`](#using-unwrap-to-replace-requiretonotbenil)
+  - [Throwing a Custom Error from Require](#throwing-a-custom-error-from-require)
 - [Built-in Matcher Functions](#built-in-matcher-functions)
   - [Type Checking](#type-checking)
   - [Equivalence](#equivalence)
@@ -49,6 +62,8 @@ expect(ocean.isClean).toEventually(beTruthy())
   - [Collection Membership](#collection-membership)
   - [Strings](#strings)
   - [Collection Elements](#collection-elements)
+    - [Swift](#swift)
+    - [Objective-C](#objective-c)
   - [Collection Count](#collection-count)
   - [Notifications](#notifications)
   - [Result](#result)
@@ -61,12 +76,15 @@ expect(ocean.isClean).toEventually(beTruthy())
   - [Customizing Failure Messages](#customizing-failure-messages)
     - [Basic Customization](#basic-customization)
     - [Full Customization](#full-customization)
+  - [Asynchronous Matchers](#asynchronous-matchers)
   - [Supporting Objective-C](#supporting-objective-c)
     - [Properly Handling `nil` in Objective-C Matchers](#properly-handling-nil-in-objective-c-matchers)
-  - [Migrating from the Old Matcher API](#migrating-from-the-old-matcher-api)
 - [Installing Nimble](#installing-nimble)
   - [Installing Nimble as a Submodule](#installing-nimble-as-a-submodule)
   - [Installing Nimble via CocoaPods](#installing-nimble-via-cocoapods)
+  - [Installing Nimble via Swift Package Manager](#installing-nimble-via-swift-package-manager)
+    - [Xcode](#xcode)
+    - [Package.Swift](#packageswift)
   - [Using Nimble without XCTest](#using-nimble-without-xctest)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -677,6 +695,89 @@ NMB_expect(^{ return seagull.squawk; }, __FILE__, __LINE__).to(NMB_equal(@"Squee
   names that conflict with Nimble functions, such as `expect` or
   `equal`. If that's not the case, there's no point in disabling the
   shorthand.
+  
+# Using `require` to demand that a matcher pass before continuing
+
+Nimble 13.1 added the `require` dsl to complement `expect`. `require`
+looks similar to `expect` and works with matchers just like `expect` does. The
+difference is that `require` requires that the matcher passes - if the matcher
+doesn't pass, then `require` will throw an error. Additionally, if `require`
+does pass, then it'll return the result of running the expression.
+
+For example, in testing a function that returns an array, you might need to
+first guarantee that there are exactly 3 items in the array before continuing
+to assert on it. Instead of writing code that needlessly duplicates an assertion
+and a conditional like so:
+
+```swift
+let collection = myFunction()
+expect(collection).to(haveCount(3))
+guard collection.count == 3 else { return }
+// ...
+```
+
+You can replace that with:
+
+```swift
+let collection = try require(myFunction()).to(haveCount(3))
+// ...
+```
+
+## Polling with `require`.
+
+Because `require` does everything you can do with `expect`, you can also use
+`require` to [poll matchers](#polling-expectations) using `toEventually`,
+`eventuallyTo`, `toEventuallyNot`, `toNotEventually`, `toNever`, `neverTo`,
+`toAlways`, and `alwaysTo`. These work exactly the same as they do when using
+`expect`, except that they throw if they fail, and they return the value of the
+expression when they pass.
+
+## Using `require` with Async expressions and Async matchers
+
+`require` also works with both async expressions
+(`require { await someExpression() }.to(...)`), and async matchers
+(`require().to(someAsyncMatcher())`).
+
+Note that to prevent compiler confusion,
+you cannot use `require` with async autoclosures. That is,
+`require(await someExpression())` will not compile. You can instead either
+make the closure explicit (`require { await someExpression() }`), or use the
+`requirea` function, which does accept autoclosures.
+Similarly, if you ever wish to use the sync version of `require` when the
+compiler is trying to force you to use the async version, you can use the
+`requires` function, which only allows synchronous expressions.
+
+## Using `unwrap` to replace `require(...).toNot(beNil())`
+
+It's very common to require that a value not be nil. Instead of writing
+`try require(...).toNot(beNil())`, Nimble provides the `unwrap` function. This
+expression throws an error if the expression evaluates to nil, or returns the
+non-nil result when it passes. For example:
+
+```swift
+let value = try unwrap(nil as Int?) // throws
+let value = try unwrap(1 as Int?) // returns 1
+```
+
+Additionally, there is also the `pollUnwrap` function, which aliases to
+`require(...).toEventuallyNot(beNil())`. This is extremely useful for verifying
+that a value that is updated on a background thread was eventually set to a
+non-nil value.
+
+Note: As with `require`, there are `unwraps`, `unwrapa`, `pollUnwraps`, and
+`pollUnwrapa` variants for allowing you to use autoclosures specifically with
+synchronous or asynchronous code.
+
+## Throwing a Custom Error from Require
+
+By default, if the matcher fails in a `require`, then a `RequireError` will be
+thrown. You can override this behavior and throw a custom error by passing a
+non-nil `Error` value to the `customError` parameter:
+
+```swift
+try require(1).to(equal(2)) // throws a `RequireError`
+try require(customError: MyCustomError(), 1).to(equal(2)) // throws a `MyCustomError`
+```
 
 # Built-in Matcher Functions