Merge pull request #148 from ReactiveCocoa/andersio-readme-patch

A more detailed intro in the README.

Author: mdiep

README.md

@@ -9,21 +9,108 @@
 ⚠️ [Still using Swift 2.x?][]
 
 ## What is ReactiveSwift?
-__ReactiveSwift__ offers composable, declarative and flexible primitives that are built around the grand concept of ___streams of values over time___. These primitives can be used to uniformly represent common Cocoa and generic programming patterns that are fundamentally an act of observation, e.g.:
+__ReactiveSwift__ offers composable, declarative and flexible primitives that are built around the grand concept of ___streams of values over time___.
 
- * Delegate methods
- * Callback blocks
- * Notifications
- * Control actions and responder chain events
- * [Futures and promises](https://en.wikipedia.org/wiki/Futures_and_promises)
- * [Key-value observing](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html) (KVO)
+These primitives can be used to uniformly represent common Cocoa and generic programming patterns that are fundamentally an act of observation, e.g. delegate pattern, callback closures, notifications, control actions, responder chain events, [futures/promises](https://en.wikipedia.org/wiki/Futures_and_promises) and [key-value observing](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html) (KVO).
 
 Because all of these different mechanisms can be represented in the _same_ way,
-it’s easy to declaratively chain and combine them together, with less spaghetti
+it’s easy to declaratively compose them together, with less spaghetti
 code and state to bridge the gap.
 
-For more information about the concepts in ReactiveSwift, see the [Framework
-Overview][].
+### Core Reactive Primitives
+#### `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 ... }
+```
+
+#### `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".
+
+#### `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()
+```
+
+#### `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.observeValues { timeBar.timeLabel.text = "\($0)" }
+```
+
+#### `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 snacks. 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)
+    .startWithResults { result
+        switch results {
+        case let .success(snacks):
+            print("Snack: \(snacks)")
+        
+        case let .failure(error):
+            // Out of stock? Insufficient fund?
+            print("Transaction aborted: \(error)")
+        }
+    }
+
+// The vending machine.
+class VendingMachine {
+    let purchase: Action<(), [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.
+            }
+        }
+        
+        // The sales recorders are notified for any successful sales.
+        purchase.values.observeValues(salesRecorder.record)
+    }
+}
+```
+
+#### References
+
+For more details about the concepts and primitives in ReactiveSwift, check these documentations out:
+
+1. **[Framework Overview][]**
+
+   An overview of the behaviors and the suggested use cases of the ReactiveSwift primitives and utilities.
+
+1. **[Basic Operators][]**
+
+   An overview of the operators provided to compose and transform these primitives.
+
+1. **[Design Guidelines][]**
+
+   Contracts of the ReactiveSwift primitives, Best Practices with ReactiveSwift, and Guidelines on implementing custom operators.
 
 ## Example: online search
 
@@ -335,6 +422,7 @@ If you need any help, please visit our [GitHub issues][] or [Stack Overflow][].
 [ReactiveCocoa]: https://github.com/ReactiveCocoa/ReactiveCocoa/#readme
 [Actions]: Documentation/FrameworkOverview.md#actions
 [Basic Operators]: Documentation/BasicOperators.md
+[Design Guidelines]: Documentation/DesignGuidelines.md
 [Carthage]: https://github.com/Carthage/Carthage/#readme
 [CocoaPods]: https://cocoapods.org/
 [CHANGELOG]: CHANGELOG.md