Add addStateRouteMapping() & rename EventRouteMapping to RouteMapping.

Author: inamiy

README.md

@@ -100,10 +100,13 @@ If there is no `Event`-based transition, use built-in `NoEvent` instead.
 
 ### State & Event enums with associated values
 
-Above examples use _arrow-style routing_ which are easy to understand, but it lacks in ability to handle state & event enums with associated values. In such cases, use `machine.addRouteMapping()` and pass either of the following closure types (_closure-style routing_):
+Above examples use _arrow-style routing_ which are easy to understand, but it lacks in ability to handle state & event enums with associated values. In such cases, use either of the following functions to apply _closure-style routing_:
 
-- `EventRouteMapping`: `(event: E?, fromState: S, userInfo: Any?) -> S?`
-- `StateRouteMapping`: `(fromState: S, userInfo: Any?) -> [S]?`
+- `machine.addRouteMapping(routeMapping)`
+  - `RouteMapping`: `(event: E?, fromState: S, userInfo: Any?) -> S?`
+- `machine.addStateRouteMapping(stateRouteMapping)`
+  - `StateRouteMapping`: `(fromState: S, userInfo: Any?) -> [S]?`
+  - This is a synonym for multiple routing e.g. `.State0 => [.State1, .State2]`
 
 For example:
 
@@ -117,7 +120,6 @@ enum StrEvent: EventType {
 
 let machine = Machine<StrState, StrEvent>(state: .Str("initial")) { machine in
 
-    // add EventRouteMapping
     machine.addRouteMapping { event, fromState, userInfo -> StrState? in
         // no route for no-event
         guard let event = event else { return nil }
@@ -164,7 +166,7 @@ machine <-! .Str("finish")
 XCTAssertEqual(machine.state, StrState.Str("end"))
 ```
 
-This behaves very similar to JavaScript's safe state-container [rackt/Redux](https://github.com/rackt/redux), where `EventRouteMapping` can be interpretted as `Redux.Reducer`.
+This behaves very similar to JavaScript's safe state-container [rackt/Redux](https://github.com/rackt/redux), where `RouteMapping` can be interpretted as `Redux.Reducer`.
 
 For more examples, please see XCTest cases.
 

Sources/Machine.swift

@@ -12,7 +12,7 @@
 /// This is a superclass (simpler version) of `StateMachine` that doesn't allow `tryState()` (direct state change).
 ///
 /// This class can be used as a safe state-container in similar way as [rackt/Redux](https://github.com/rackt/redux),
-/// where `EventRouteMapping` can be interpretted as `Redux.Reducer`.
+/// where `RouteMapping` can be interpretted as `Redux.Reducer`.
 ///
 public class Machine<S: StateType, E: EventType>
 {
@@ -28,12 +28,12 @@ public class Machine<S: StateType, E: EventType>
 
     /// Closure-based route, mainly for `tryEvent()` (and also works for subclass's `tryState()`).
     /// - Returns: Preferred `toState`.
-    public typealias EventRouteMapping = (event: E?, fromState: S, userInfo: Any?) -> S?
+    public typealias RouteMapping = (event: E?, fromState: S, userInfo: Any?) -> S?
 
     internal typealias _RouteDict = [Transition<S> : [String : Condition?]]
 
     private lazy var _routes: [Event<E> : _RouteDict] = [:]
-    private lazy var _routeMappings: [String : EventRouteMapping] = [:]
+    private lazy var _routeMappings: [String : RouteMapping] = [:]
 
     /// `tryEvent()`-based handler collection.
     private lazy var _handlers: [Event<E> : [_HandlerInfo<S, E>]] = [:]
@@ -356,12 +356,12 @@ public class Machine<S: StateType, E: EventType>
     }
 
     //--------------------------------------------------
-    // MARK: - EventRouteMapping
+    // MARK: - RouteMapping
     //--------------------------------------------------
 
     // MARK: addRouteMapping
 
-    public func addRouteMapping(routeMapping: EventRouteMapping) -> Disposable
+    public func addRouteMapping(routeMapping: RouteMapping) -> Disposable
     {
         let key = _createUniqueString()
 
@@ -376,7 +376,7 @@ public class Machine<S: StateType, E: EventType>
 
     // MARK: addRouteMapping + conditional handler
 
-    public func addRouteMapping(routeMapping: EventRouteMapping, order: HandlerOrder = _defaultOrder, handler: Machine.Handler) -> Disposable
+    public func addRouteMapping(routeMapping: RouteMapping, order: HandlerOrder = _defaultOrder, handler: Machine.Handler) -> Disposable
     {
         let routeDisposable = self.addRouteMapping(routeMapping)
 

Sources/StateMachine.swift

@@ -15,11 +15,11 @@
 public final class StateMachine<S: StateType, E: EventType>: Machine<S, E>
 {
     /// Closure-based routes for `tryState()`.
-    /// - Returns: Multiple `toState`s from single `fromState`.
+    /// - Returns: Multiple `toState`s from single `fromState`, similar to `.State0 => [.State1, .State2]`
     public typealias StateRouteMapping = (fromState: S, userInfo: Any?) -> [S]?
 
     private lazy var _routes: _RouteDict = [:]
-    private lazy var _routeMappings: [String : StateRouteMapping] = [:] // NOTE: `StateRouteMapping`, not `EventRouteMapping`
+    private lazy var _routeMappings: [String : StateRouteMapping] = [:] // NOTE: `StateRouteMapping`, not `RouteMapping`
 
     /// `tryState()`-based handler collection.
     private lazy var _handlers: [Transition<S> : [_HandlerInfo<S, E>]] = [:]
@@ -442,9 +442,9 @@ public final class StateMachine<S: StateType, E: EventType>: Machine<S, E>
     // MARK: - StateRouteMapping
     //--------------------------------------------------
 
-    // MARK: addRouteMapping
+    // MARK: addStateRouteMapping
 
-    public func addRouteMapping(routeMapping: StateRouteMapping) -> Disposable
+    public func addStateRouteMapping(routeMapping: StateRouteMapping) -> Disposable
     {
         let key = _createUniqueString()
 
@@ -453,15 +453,15 @@ public final class StateMachine<S: StateType, E: EventType>: Machine<S, E>
         let routeMappingID = _RouteMappingID(key: key)
 
         return ActionDisposable.init { [weak self] in
-            self?._removeRouteMapping(routeMappingID)
+            self?._removeStateRouteMapping(routeMappingID)
         }
     }
 
-    // MARK: addRouteMapping + conditional handler
+    // MARK: addStateRouteMapping + conditional handler
 
-    public func addRouteMapping(routeMapping: StateRouteMapping, handler: Handler) -> Disposable
+    public func addStateRouteMapping(routeMapping: StateRouteMapping, handler: Handler) -> Disposable
     {
-        let routeDisposable = self.addRouteMapping(routeMapping)
+        let routeDisposable = self.addStateRouteMapping(routeMapping)
 
         let handlerDisposable = self.addHandler(.Any => .Any) { context in
             if self._hasRouteMappingInDict(fromState: context.fromState, toState: context.toState, userInfo: context.userInfo) != nil {
@@ -475,9 +475,9 @@ public final class StateMachine<S: StateType, E: EventType>: Machine<S, E>
         }
     }
 
-    // MARK: removeRouteMapping
+    // MARK: removeStateRouteMapping
 
-    private func _removeRouteMapping(routeMappingID: _RouteMappingID) -> Bool
+    private func _removeStateRouteMapping(routeMappingID: _RouteMappingID) -> Bool
     {
         if self._routeMappings[routeMappingID.key] != nil {
             self._routeMappings[routeMappingID.key] = nil

Tests/BasicTests.swift

@@ -80,7 +80,6 @@ class BasicTests: _TestCase
     {
         let machine = Machine<StrState, StrEvent>(state: .Str("initial")) { machine in
 
-            // add EventRouteMapping
             machine.addRouteMapping { event, fromState, userInfo -> StrState? in
                 // no route for no-event
                 guard let event = event else { return nil }

Tests/MachineTests.swift

@@ -299,16 +299,15 @@ class MachineTests: _TestCase
     }
 
     //--------------------------------------------------
-    // MARK: - EventRouteMapping
+    // MARK: - RouteMapping
     //--------------------------------------------------
 
-    func testAddEventRouteMapping()
+    func testAddRouteMapping()
     {
         var invokeCount = 0
 
         let machine = Machine<StrState, StrEvent>(state: .Str("initial")) { machine in
 
-            // add EventRouteMapping
             machine.addRouteMapping { event, fromState, userInfo -> StrState? in
                 // no route for no-event
                 guard let event = event else { return nil }

Tests/RouteMappingTests.swift

@@ -80,7 +80,6 @@ class RouteMappingTests: _TestCase
 
         let machine = StateMachine<_State, _Event>(state: .Pending) { machine in
 
-            // add EventRouteMapping
             machine.addRouteMapping { event, fromState, userInfo in
                 // no routes for no event
                 guard let event = event else {
@@ -138,8 +137,11 @@ class RouteMappingTests: _TestCase
 
         let machine = StateMachine<_State, _Event>(state: .Pending) { machine in
 
-            // add StateRouteMapping
-            machine.addRouteMapping { fromState, userInfo in
+            // Add following routes:
+            // - `.Pending => .Loading(1)`
+            // - `.Loading(x) => .Loading(x+10)`
+            // - `.Loading(x) => .Loading(x+100)`
+            machine.addStateRouteMapping { fromState, userInfo in
                 switch fromState {
                     case .Pending:
                         return [.Loading(1)]

Tests/StateMachineTests.swift

@@ -554,8 +554,8 @@ class StateMachineTests: _TestCase
 
         let machine = StateMachine<MyState, NoEvent>(state: .State0) { machine in
 
-            // add 0 => 1 & 0 => 2 (using `StateRouteMapping` closure)
-            routeMappingDisposable = machine.addRouteMapping { fromState, userInfo -> [MyState]? in
+            // add 0 => 1 & 0 => 2
+            routeMappingDisposable = machine.addStateRouteMapping { fromState, userInfo -> [MyState]? in
                 if fromState == .State0 {
                     return [.State1, .State2]
                 }
@@ -564,7 +564,7 @@ class StateMachineTests: _TestCase
                 }
             }
 
-            // add 1 => 0 (can also use `EventRouteMapping` closure for single-`toState`)
+            // add 1 => 0 (can also use `RouteMapping` closure for single-`toState`)
             machine.addRouteMapping { event, fromState, userInfo -> MyState? in
                 guard event == nil else { return nil }