Document require in the README

Update the table of contents with doctoc.

README.md

@@ -32,10 +32,22 @@ 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)
 - [Built-in Matcher Functions](#built-in-matcher-functions)
   - [Type Checking](#type-checking)
   - [Equivalence](#equivalence)
@@ -49,6 +61,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 +75,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 +694,78 @@ 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.
 
 # Built-in Matcher Functions