Merge pull request #384 from ReactiveCocoa/readme-split

Break README into multiple documents.

Author: mdiep

.jazzy.yaml

@@ -1,10 +1,14 @@
 custom_categories:
   - name: Getting Started 
     children:
+    - ReactivePrimitives
     - BasicOperators
-    - FrameworkOverview
+    - Example.OnlineSearch
+    - RxComparison
+  - name: Advanced Topics
+    children:
+    - APIContracts
     - DebuggingTechniques
-    - DesignGuidelines
   - name: Signal
     children:
     - Signal

Documentation/DesignGuidelines.md Documentation/APIContracts.md

@@ -4,7 +4,7 @@ This document explains some of the most common operators used in ReactiveCocoa,
 and includes examples demonstrating their use.
 
 Note that “operators”, in this context, refers to functions that transform
-[signals][] and [signal producers][], _not_ custom Swift operators. In other
+[`Signal`s][Signal] and [`SignalProducer`s][SignalProducer], _not_ custom Swift operators. In other
 words, these are composable primitives provided by ReactiveCocoa for working
 with event streams.
 
@@ -513,7 +513,7 @@ because some operators to [combine streams](#combining-event-streams) require
 the inputs to have matching error types.
 
 
-[Signals]: FrameworkOverview.md#signals
-[Signal Producers]: FrameworkOverview.md#signal-producers
+[Signal]: Documentation/ReactivePrimitives.md#signal-a-unidirectional-stream-of-events
+[SignalProducer]: Documentation/ReactivePrimitives.md#signalproducer-deferred-work-that-creates-a-stream-of-values
 [Observation]: FrameworkOverview.md#observation
 

Documentation/BasicOperators.md

@@ -0,0 +1,173 @@
+# Example: Online Searching
+
+Let’s say you have a text field, and whenever the user types something into it,
+you want to make a network request which searches for that query.
+
+_Please note that the following examples use Cocoa extensions in [ReactiveCocoa][] for illustration._
+
+#### Observing text edits
+
+The first step is to observe edits to the text field, using a RAC extension to
+`UITextField` specifically for this purpose:
+
+```swift
+let searchStrings = textField.reactive.continuousTextValues
+```
+
+This gives us a [Signal][] which sends values of type `String?`.
+
+#### Making network requests
+
+With each string, we want to execute a network request. ReactiveSwift offers an
+`URLSession` extension for doing exactly that:
+
+```swift
+let searchResults = searchStrings
+    .flatMap(.latest) { (query: String?) -> SignalProducer<(Data, URLResponse), AnyError> in
+        let request = self.makeSearchRequest(escapedQuery: query)
+        return URLSession.shared.reactive.data(with: request)
+    }
+    .map { (data, response) -> [SearchResult] in
+        let string = String(data: data, encoding: .utf8)!
+        return self.searchResults(fromJSONString: string)
+    }
+    .observe(on: UIScheduler())
+```
+
+This has transformed our producer of `String`s into a producer of `Array`s
+containing the search results, which will be forwarded on the main thread
+(using the [`UIScheduler`][Schedulers]).
+
+Additionally, [`flatMap(.latest)`][flatMapLatest] here ensures that _only one search_—the
+latest—is allowed to be running. If the user types another character while the
+network request is still in flight, it will be cancelled before starting a new
+one. Just think of how much code that would take to do by hand!
+
+#### Receiving the results
+
+Since the source of search strings is a `Signal` which has a hot signal semantic,
+the transformations we applied are automatically evaluated whenever new values are
+emitted from `searchStrings`.
+
+Therefore, we can simply observe the signal using `Signal.observe(_:)`:
+
+```swift
+searchResults.observe { event in
+    switch event {
+    case let .value(results):
+        print("Search results: \(results)")
+
+    case let .failed(error):
+        print("Search error: \(error)")
+
+    case .completed, .interrupted:
+        break
+    }
+}
+```
+
+Here, we watch for the `Value` [event][Events], which contains our results, and
+just log them to the console. This could easily do something else instead, like
+update a table view or a label on screen.
+
+#### Handling failures
+
+In this example so far, any network error will generate a `Failed`
+[event][Events], which will terminate the event stream. Unfortunately, this
+means that future queries won’t even be attempted.
+
+To remedy this, we need to decide what to do with failures that occur. The
+quickest solution would be to log them, then ignore them:
+
+```swift
+    .flatMap(.latest) { (query: String) -> SignalProducer<(Data, URLResponse), AnyError> in
+        let request = self.makeSearchRequest(escapedQuery: query)
+
+        return URLSession.shared.reactive
+            .data(with: request)
+            .flatMapError { error in
+                print("Network error occurred: \(error)")
+                return SignalProducer.empty
+            }
+    }
+```
+
+By replacing failures with the `empty` event stream, we’re able to effectively
+ignore them.
+
+However, it’s probably more appropriate to retry at least a couple of times
+before giving up. Conveniently, there’s a [`retry`][retry] operator to do exactly that!
+
+Our improved `searchResults` producer might look like this:
+
+```swift
+let searchResults = searchStrings
+    .flatMap(.latest) { (query: String) -> SignalProducer<(Data, URLResponse), AnyError> in
+        let request = self.makeSearchRequest(escapedQuery: query)
+
+        return URLSession.shared.reactive
+            .data(with: request)
+            .retry(upTo: 2)
+            .flatMapError { error in
+                print("Network error occurred: \(error)")
+                return SignalProducer.empty
+            }
+    }
+    .map { (data, response) -> [SearchResult] in
+        let string = String(data: data, encoding: .utf8)!
+        return self.searchResults(fromJSONString: string)
+    }
+    .observe(on: UIScheduler())
+```
+
+#### Throttling requests
+
+Now, let’s say you only want to actually perform the search periodically,
+to minimize traffic.
+
+ReactiveCocoa has a declarative `throttle` operator that we can apply to our
+search strings:
+
+```swift
+let searchStrings = textField.reactive.continuousTextValues
+    .throttle(0.5, on: QueueScheduler.main)
+```
+
+This prevents values from being sent less than 0.5 seconds apart.
+
+To do this manually would require significant state, and end up much harder to
+read! With ReactiveCocoa, we can use just one operator to incorporate _time_ into
+our event stream.
+
+#### Debugging event streams
+
+Due to its nature, a stream's stack trace might have dozens of frames, which, more often than not, can make debugging a very frustrating activity.
+A naive way of debugging, is by injecting side effects into the stream, like so:
+
+```swift
+let searchString = textField.reactive.continuousTextValues
+    .throttle(0.5, on: QueueScheduler.main)
+    .on(event: { print ($0) }) // the side effect
+```
+
+This will print the stream's [events][Events], while preserving the original stream behaviour. Both [`SignalProducer`][SignalProducer]
+and [`Signal`][Signal] provide the `logEvents` operator, that will do this automatically for you:
+
+```swift
+let searchString = textField.reactive.continuousTextValues
+    .throttle(0.5, on: QueueScheduler.main)
+    .logEvents()
+```
+
+For more information and advance usage, check the [Debugging Techniques][] document.
+
+[SignalProducer]: Documentation/ReactivePrimitives.md#signalproducer-deferred-work-that-creates-a-stream-of-values
+[Schedulers]: Documentation/FrameworkOverview.md#Schedulers
+[Signal]: Documentation/ReactivePrimitives.md#signal-a-unidirectional-stream-of-events
+[Events]: Documentation/ReactivePrimitives.md#event-the-basic-transfer-unit-of-an-event-stream
+[Debugging Techniques]: Documentation/DebuggingTechniques.md
+
+[retry]: Documentation/BasicOperators.md#retrying
+[flatMapLatest]: Documentation/BasicOperators.md#combining-latest-values
+
+[ReactiveCocoa]: https://github.com/ReactiveCocoa/ReactiveCocoa/#readme

Documentation/Example.OnlineSearch.md

@@ -0,0 +1,115 @@
+# Core Reactive Primitives
+
+1. [`Signal`](#signal-a-unidirectional-stream-of-events)
+1. [`Event`](#event-the-basic-transfer-unit-of-an-event-stream)
+1. [`SignalProducer`](#signalproducer-deferred-work-that-creates-a-stream-of-values)
+1. [`Property`](#property-an-observable-box-that-always-holds-a-value)
+1. [`Action`](#action-a-serialized-worker-with-a-preset-action)
+1. [`Lifetime`](#lifetime-limits-the-scope-of-an-observation)
+
+#### `Signal`: a unidirectional stream of events.
+The owner of a `Signal` has unilateral control of the event stream. Observers may register their interests in the future events at any time, but the observation would have no side effect on the stream or its owner.
+
+It is like a live TV feed — you can observe and react to the content, but you cannot have a side effect on the live feed or the TV station.
+
+```swift
+let channel: Signal<Program, NoError> = tvStation.channelOne
+channel.observeValues { program in ... }
+```
+
+*See also: [The `Signal` overview](FrameworkOverview.md#signals), [The `Signal` contract](APIContracts.md#the-signal-contract), [The `Signal` API reference](http://reactivecocoa.io/reactiveswift/docs/latest/Classes/Signal.html)*
+
+
+#### `Event`: the basic transfer unit of an event stream.
+A `Signal` may have any arbitrary number of events carrying a value, following by an eventual terminal event of a specific reason.
+
+It is like a frame in a one-time live feed — seas of data frames carry the visual and audio data, but the feed would eventually be terminated with a special frame to indicate "end of stream".
+
+*See also: [The `Event` overview](FrameworkOverview.md#events), [The `Signal` contract](APIContracts.md#the-event-contract), [The `Event` API reference](http://reactivecocoa.io/reactiveswift/docs/latest/Enums/Event.html)*
+
+#### `SignalProducer`: deferred work that creates a stream of values.
+`SignalProducer` defers work — of which the output is represented as a stream of values — until it is started. For every invocation to start the `SignalProducer`, a new `Signal` is created and the deferred work is subsequently invoked.
+
+It is like a on-demand streaming service — even though the episode is streamed like a live TV feed, you can choose what you watch, when to start watching and when to interrupt it.
+
+
+```swift
+let frames: SignalProducer<VideoFrame, ConnectionError> = vidStreamer.streamAsset(id: tvShowId)
+let interrupter = frames.start { frame in ... }
+interrupter.dispose()
+```
+
+*See also: [The `SignalProducer` overview](FrameworkOverview.md#signal-producers), [The `SignalProducer` contract](APIContracts.md#the-signalproducer-contract), [The `SignalProducer` API reference](http://reactivecocoa.io/reactiveswift/docs/latest/Structs/SignalProducer.html)*
+
+#### `Property`: an observable box that always holds a value.
+`Property` is a variable that can be observed for its changes. In other words, it is a stream of values with a stronger guarantee than `Signal` — the latest value is always available, and the stream would never fail.
+
+It is like the continuously updated current time offset of a video playback — the playback is always at a certain time offset at any time, and it would be updated by the playback logic as the playback continues.
+
+```swift
+let currentTime: Property<TimeInterval> = video.currentTime
+print("Current time offset: \(currentTime.value)")
+currentTime.signal.observeValues { timeBar.timeLabel.text = "\($0)" }
+```
+
+*See also: [The `Property` overview](FrameworkOverview.md#properties), [The `Property` contract](APIContracts.md#the-property-contract), [The property API reference](http://reactivecocoa.io/reactiveswift/docs/latest/Property.html)*
+
+#### `Action`: a serialized worker with a preset action.
+When being invoked with an input, `Action` apply the input and the latest state to the preset action, and pushes the output to any interested parties.
+
+It is like an automatic vending machine — after choosing an option with coins inserted, the machine would process the order and eventually output your wanted snack. Notice that the entire process is mutually exclusive — you cannot have the machine to serve two customers concurrently.
+
+```swift
+// Purchase from the vending machine with a specific option.
+vendingMachine.purchase
+    .apply(snackId)
+    .startWithResult { result
+        switch result {
+        case let .success(snack):
+            print("Snack: \(snack)")
+
+        case let .failure(error):
+            // Out of stock? Insufficient fund?
+            print("Transaction aborted: \(error)")
+        }
+    }
+
+// The vending machine.
+class VendingMachine {
+    let purchase: Action<Int, Snack, VendingMachineError>
+    let coins: MutableProperty<Int>
+
+    // The vending machine is connected with a sales recorder.
+    init(_ salesRecorder: SalesRecorder) {
+        coins = MutableProperty(0)
+        purchase = Action(state: coins, enabledIf: { $0 > 0 }) { coins, snackId in
+            return SignalProducer { observer, _ in
+                // The sales magic happens here.
+                // Fetch a snack based on its id
+            }
+        }
+
+        // The sales recorders are notified for any successful sales.
+        purchase.values.observeValues(salesRecorder.record)
+    }
+}
+```
+
+*See also: [The `Action` overview](FrameworkOverview.md#actions), [The `Action` API reference](http://reactivecocoa.io/reactiveswift/docs/latest/Classes/Action.html)*
+
+#### `Lifetime`: limits the scope of an observation
+When observing a `Signal` or `SignalProducer`, it doesn't make sense to continue emitting values if there's no longer anyone observing them.
+Consider the video stream: once you stop watching the video, the stream can be automatically closed by providing a `Lifetime`:
+
+```swift
+class VideoPlayer {
+  private let (lifetime, token) = Lifetime.make()
+
+  func play() {
+    let frames: SignalProducer<VideoFrame, ConnectionError> = ...
+    frames.take(during: lifetime).start { frame in ... }
+  }
+}
+```
+
+*See also: [The `Lifetime` overview](FrameworkOverview.md#lifetimes), [The `Lifetime` API reference](http://reactivecocoa.io/reactiveswift/docs/latest/Classes/Lifetime.html)*