Skip to content

Commit 8eab0c7

Browse files
inamiyinamiy
authored
Merge pull request #52 from mattprowse/swift/3.0
Update documentation and comments for Swift 3.0
2 parents 49ec3d4 + 2736a7b commit 8eab0c7

14 files changed

+109
-109
lines changed

‎README.md‎

Lines changed: 68 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,20 @@ Elegant state machine for Swift.
1010

1111
```swift
1212
enum MyState: StateType {
13-
case State0, State1, State2
13+
case state0, state1, state2
1414
}
1515
```
1616

1717
```swift
1818
// setup state machine
19-
let machine = StateMachine<MyState, NoEvent>(state: .State0) { machine in
19+
let machine = StateMachine<MyState, NoEvent>(state: .state0) { machine in
2020

21-
machine.addRoute(.State0 => .State1)
22-
machine.addRoute(.Any => .State2) { context in print("Any => 2, msg=\(context.userInfo)") }
23-
machine.addRoute(.State2 => .Any) { context in print("2 => Any, msg=\(context.userInfo)") }
21+
machine.addRoute(.state0 => .state1)
22+
machine.addRoute(.any => .state2) { context in print("Any => 2, msg=\(context.userInfo)") }
23+
machine.addRoute(.state2 => .any) { context in print("2 => Any, msg=\(context.userInfo)") }
2424

2525
// add handler (`context = (event, fromState, toState, userInfo)`)
26-
machine.addHandler(.State0 => .State1) { context in
26+
machine.addHandler(.state0 => .state1) { context in
2727
print("0 => 1")
2828
}
2929

@@ -34,21 +34,21 @@ let machine = StateMachine<MyState, NoEvent>(state: .State0) { machine in
3434
}
3535

3636
// initial
37-
XCTAssertEqual(machine.state, MyState.State0)
37+
XCTAssertEqual(machine.state, MyState.state0)
3838

3939
// tryState 0 => 1 => 2 => 1 => 0
4040

41-
machine <- .State1
42-
XCTAssertEqual(machine.state, MyState.State1)
41+
machine <- .state1
42+
XCTAssertEqual(machine.state, MyState.state1)
4343

44-
machine <- (.State2, "Hello")
45-
XCTAssertEqual(machine.state, MyState.State2)
44+
machine <- (.state2, "Hello")
45+
XCTAssertEqual(machine.state, MyState.state2)
4646

47-
machine <- (.State1, "Bye")
48-
XCTAssertEqual(machine.state, MyState.State1)
47+
machine <- (.state1, "Bye")
48+
XCTAssertEqual(machine.state, MyState.state1)
4949

50-
machine <- .State0 // fail: no 1 => 0
51-
XCTAssertEqual(machine.state, MyState.State1)
50+
machine <- .state0 // fail: no 1 => 0
51+
XCTAssertEqual(machine.state, MyState.state1)
5252
```
5353

5454
This will print:
@@ -57,7 +57,7 @@ This will print:
5757
0 => 1
5858
Any => 2, msg=Optional("Hello")
5959
2 => Any, msg=Optional("Bye")
60-
[ERROR] State1 => State0
60+
[ERROR] state1 => state0
6161
```
6262

6363
### Transition by Event
@@ -66,39 +66,39 @@ Use `<-!` operator to try transition by `Event` rather than specifying target `S
6666

6767
```swift
6868
enum MyEvent: EventType {
69-
case Event0, Event1
69+
case event0, event1
7070
}
7171
```
7272

7373
```swift
74-
let machine = StateMachine<MyState, MyEvent>(state: .State0) { machine in
74+
let machine = StateMachine<MyState, MyEvent>(state: .state0) { machine in
7575

7676
// add 0 => 1 => 2
77-
machine.addRoutes(event: .Event0, transitions: [
78-
.State0 => .State1,
79-
.State1 => .State2,
77+
machine.addRoutes(event: .event0, transitions: [
78+
.state0 => .state1,
79+
.state1 => .state2,
8080
])
8181

8282
// add event handler
83-
machine.addHandler(event: .Event0) { context in
84-
print(".Event0 triggered!")
83+
machine.addHandler(event: .event0) { context in
84+
print(".event0 triggered!")
8585
}
8686
}
8787

8888
// initial
89-
XCTAssertEqual(machine.state, MyState.State0)
89+
XCTAssertEqual(machine.state, MyState.state0)
9090

9191
// tryEvent
92-
machine <-! .Event0
93-
XCTAssertEqual(machine.state, MyState.State1)
92+
machine <-! .event0
93+
XCTAssertEqual(machine.state, MyState.state1)
9494

9595
// tryEvent
96-
machine <-! .Event0
97-
XCTAssertEqual(machine.state, MyState.State2)
96+
machine <-! .event0
97+
XCTAssertEqual(machine.state, MyState.state2)
9898

9999
// tryEvent (fails)
100-
machine <-! .Event0
101-
XCTAssertEqual(machine.state, MyState.State2, "Event0 doesn't have 2 => Any")
100+
machine <-! .event0
101+
XCTAssertEqual(machine.state, MyState.state2, "event0 doesn't have 2 => Any")
102102
```
103103

104104
If there is no `Event`-based transition, use built-in `NoEvent` instead.
@@ -108,33 +108,33 @@ If there is no `Event`-based transition, use built-in `NoEvent` instead.
108108
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_:
109109

110110
- `machine.addRouteMapping(routeMapping)`
111-
- `RouteMapping`: `(event: E?, fromState: S, userInfo: Any?) -> S?`
111+
- `RouteMapping`: `(_ event: E?, _ fromState: S, _ userInfo: Any?) -> S?`
112112
- `machine.addStateRouteMapping(stateRouteMapping)`
113-
- `StateRouteMapping`: `(fromState: S, userInfo: Any?) -> [S]?`
113+
- `StateRouteMapping`: `(_ fromState: S, _ userInfo: Any?) -> [S]?`
114114

115115
For example:
116116

117117
```swift
118118
enum StrState: StateType {
119-
case Str(String) ...
119+
case str(String) ...
120120
}
121121
enum StrEvent: EventType {
122-
case Str(String) ...
122+
case str(String) ...
123123
}
124124

125-
let machine = Machine<StrState, StrEvent>(state: .Str("initial")) { machine in
125+
let machine = Machine<StrState, StrEvent>(state: .str("initial")) { machine in
126126

127127
machine.addRouteMapping { event, fromState, userInfo -> StrState? in
128128
// no route for no-event
129129
guard let event = event else { return nil }
130130

131131
switch (event, fromState) {
132-
case (.Str("gogogo"), .Str("initial")):
133-
return .Str("Phase 1")
134-
case (.Str("gogogo"), .Str("Phase 1")):
135-
return .Str("Phase 2")
136-
case (.Str("finish"), .Str("Phase 2")):
137-
return .Str("end")
132+
case (.str("gogogo"), .str("initial")):
133+
return .str("Phase 1")
134+
case (.str("gogogo"), .str("Phase 1")):
135+
return .str("Phase 2")
136+
case (.str("finish"), .str("Phase 2")):
137+
return .str("end")
138138
default:
139139
return nil
140140
}
@@ -143,31 +143,31 @@ let machine = Machine<StrState, StrEvent>(state: .Str("initial")) { machine in
143143
}
144144

145145
// initial
146-
XCTAssertEqual(machine.state, StrState.Str("initial"))
146+
XCTAssertEqual(machine.state, StrState.str("initial"))
147147

148148
// tryEvent (fails)
149-
machine <-! .Str("go?")
150-
XCTAssertEqual(machine.state, StrState.Str("initial"), "No change.")
149+
machine <-! .str("go?")
150+
XCTAssertEqual(machine.state, StrState.str("initial"), "No change.")
151151

152152
// tryEvent
153-
machine <-! .Str("gogogo")
154-
XCTAssertEqual(machine.state, StrState.Str("Phase 1"))
153+
machine <-! .str("gogogo")
154+
XCTAssertEqual(machine.state, StrState.str("Phase 1"))
155155

156156
// tryEvent (fails)
157-
machine <-! .Str("finish")
158-
XCTAssertEqual(machine.state, StrState.Str("Phase 1"), "No change.")
157+
machine <-! .str("finish")
158+
XCTAssertEqual(machine.state, StrState.str("Phase 1"), "No change.")
159159

160160
// tryEvent
161-
machine <-! .Str("gogogo")
162-
XCTAssertEqual(machine.state, StrState.Str("Phase 2"))
161+
machine <-! .str("gogogo")
162+
XCTAssertEqual(machine.state, StrState.str("Phase 2"))
163163

164164
// tryEvent (fails)
165-
machine <-! .Str("gogogo")
166-
XCTAssertEqual(machine.state, StrState.Str("Phase 2"), "No change.")
165+
machine <-! .str("gogogo")
166+
XCTAssertEqual(machine.state, StrState.str("Phase 2"), "No change.")
167167

168168
// tryEvent
169-
machine <-! .Str("finish")
170-
XCTAssertEqual(machine.state, StrState.Str("end"))
169+
machine <-! .str("finish")
170+
XCTAssertEqual(machine.state, StrState.str("end"))
171171
```
172172

173173
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`.
@@ -178,40 +178,40 @@ For more examples, please see XCTest cases.
178178
## Features
179179

180180
- Easy Swift syntax
181-
- Transition: `.State0 => .State1`, `[.State0, .State1] => .State2`
182-
- Try state: `machine <- .State1`
183-
- Try state + messaging: `machine <- (.State1, "GoGoGo")`
184-
- Try event: `machine <-! .Event1`
181+
- Transition: `.state0 => .state1`, `[.state0, .state1] => .state2`
182+
- Try state: `machine <- .state1`
183+
- Try state + messaging: `machine <- (.state1, "GoGoGo")`
184+
- Try event: `machine <-! .event1`
185185
- Highly flexible transition routing
186186
- Using `Condition`
187-
- Using `.Any` state
188-
- Entry handling: `.Any => .SomeState`
189-
- Exit handling: `.SomeState => .Any`
190-
- Blacklisting: `.Any => .Any` + `Condition`
191-
- Using `.Any` event
187+
- Using `.any` state
188+
- Entry handling: `.any => .someState`
189+
- Exit handling: `.someState => .any`
190+
- Blacklisting: `.any => .any` + `Condition`
191+
- Using `.any` event
192192

193193
- Route Mapping (closure-based routing): [#36](https://github.com/ReactKit/SwiftState/pull/36)
194194
- Success/Error handlers with `order: UInt8` (more flexible than before/after handlers)
195195
- Removable routes and handlers using `Disposable`
196-
- Route Chaining: `.State0 => .State1 => .State2`
196+
- Route Chaining: `.state0 => .state1 => .state2`
197197
- Hierarchical State Machine: [#10](https://github.com/ReactKit/SwiftState/pull/10)
198198

199199

200200
## Terms
201201

202202
Term | Type | Description
203203
------------- | ----------------------------- | ------------------------------------------
204-
State | `StateType` (protocol) | Mostly enum, describing each state e.g. `.State0`.
204+
State | `StateType` (protocol) | Mostly enum, describing each state e.g. `.state0`.
205205
Event | `EventType` (protocol) | Name for route-group. Transition can be fired via `Event` instead of explicitly targeting next `State`.
206206
State Machine | `Machine` | State transition manager which can register `Route`/`RouteMapping` and `Handler` separately for variety of transitions.
207-
Transition | `Transition` | `From-` and `to-` states represented as `.State1 => .State2`. Also, `.Any` can be used to represent _any state_.
207+
Transition | `Transition` | `From-` and `to-` states represented as `.state1 => .state2`. Also, `.any` can be used to represent _any state_.
208208
Route | `Route` | `Transition` + `Condition`.
209209
Condition | `Context -> Bool` | Closure for validating transition. If condition returns `false`, transition will fail and associated handlers will not be invoked.
210210
Route Mapping | `(event: E?, fromState: S, userInfo: Any?) -> S?` | Another way of defining routes **using closure instead of transition arrows (`=>`)**. This is useful when state & event are enum with associated values. Return value (`S?`) means preferred-`toState`, where passing `nil` means no routes available. See [#36](https://github.com/ReactKit/SwiftState/pull/36) for more info.
211-
State Route Mapping | `(fromState: S, userInfo: Any?) -> [S]?` | Another way of defining routes **using closure instead of transition arrows (`=>`)**. This is useful when state is enum with associated values. Return value (`[S]?`) means multiple `toState`s from single `fromState` (synonym for multiple routing e.g. `.State0 => [.State1, .State2]`). See [#36](https://github.com/ReactKit/SwiftState/pull/36) for more info.
211+
State Route Mapping | `(fromState: S, userInfo: Any?) -> [S]?` | Another way of defining routes **using closure instead of transition arrows (`=>`)**. This is useful when state is enum with associated values. Return value (`[S]?`) means multiple `toState`s from single `fromState` (synonym for multiple routing e.g. `.state0 => [.state1, .state2]`). See [#36](https://github.com/ReactKit/SwiftState/pull/36) for more info.
212212
Handler | `Context -> Void` | Transition callback invoked when state has been changed successfully.
213213
Context | `(event: E?, fromState: S, toState: S, userInfo: Any?)` | Closure argument for `Condition` & `Handler`.
214-
Chain | `TransitionChain` / `RouteChain` | Group of continuous routes represented as `.State1 => .State2 => .State3`
214+
Chain | `TransitionChain` / `RouteChain` | Group of continuous routes represented as `.state1 => .state2 => .state3`
215215

216216

217217
## Related Articles

‎Sources/EventType.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ public protocol EventType: Hashable {}
1010

1111
// MARK: Event
1212

13-
/// `EventType` wrapper for handling `.Any` event.
13+
/// `EventType` wrapper for handling `.any` event.
1414
public enum Event<E: EventType>
1515
{
1616
case some(E)

‎Sources/Machine.swift‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ public class Machine<S: StateType, E: EventType>
7373
guard let fromState = transition.fromState.rawValue,
7474
let toState = transition.toState.rawValue else
7575
{
76-
assertionFailure("State = `.Any` is not supported for `hasRoute()` (always returns `false`)")
76+
assertionFailure("State = `.any` is not supported for `hasRoute()` (always returns `false`)")
7777
return false
7878
}
7979

@@ -164,7 +164,7 @@ public class Machine<S: StateType, E: EventType>
164164
for (transition, keyConditionDict) in routeDict {
165165
if transition.fromState == .some(self.state) || transition.fromState == .any {
166166
for (_, condition) in keyConditionDict {
167-
// if toState is `.Any`, always treat as identity transition
167+
// if toState is `.any`, always treat as identity transition
168168
let toState = transition.toState.rawValue ?? self.state
169169

170170
if _canPassCondition(condition, forEvent: event, fromState: self.state, toState: toState, userInfo: userInfo) {

‎Sources/Route.swift‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,10 @@ public struct Route<S: StateType, E: EventType>
2323
// MARK: - Custom Operators
2424
//--------------------------------------------------
2525

26-
/// e.g. [.State0, .State1] => .State, allowing [0 => 2, 1 => 2]
26+
/// e.g. [.state0, .state1] => .state, allowing [0 => 2, 1 => 2]
2727
public func => <S: StateType, E: EventType>(leftStates: [S], right: State<S>) -> Route<S, E>
2828
{
29-
// NOTE: don't reuse ".Any => .Any + condition" for efficiency
29+
// NOTE: don't reuse ".any => .any + condition" for efficiency
3030
return Route(transition: .any => right, condition: { context -> Bool in
3131
return leftStates.contains(context.fromState)
3232
})
@@ -37,7 +37,7 @@ public func => <S: StateType, E: EventType>(leftStates: [S], right: S) -> Route<
3737
return leftStates => .some(right)
3838
}
3939

40-
/// e.g. .State0 => [.State1, .State], allowing [0 => 1, 0 => 2]
40+
/// e.g. .state0 => [.state1, .state], allowing [0 => 1, 0 => 2]
4141
public func => <S: StateType, E: EventType>(left: State<S>, rightStates: [S]) -> Route<S, E>
4242
{
4343
return Route(transition: left => .any, condition: { context -> Bool in
@@ -50,7 +50,7 @@ public func => <S: StateType, E: EventType>(left: S, rightStates: [S]) -> Route<
5050
return .some(left) => rightStates
5151
}
5252

53-
/// e.g. [.State0, .State1] => [.State, .State3], allowing [0 => 2, 0 => 3, 1 => 2, 1 => 3]
53+
/// e.g. [.state0, .state1] => [.state, .state3], allowing [0 => 2, 0 => 3, 1 => 2, 1 => 3]
5454
public func => <S: StateType, E: EventType>(leftStates: [S], rightStates: [S]) -> Route<S, E>
5555
{
5656
return Route(transition: .any => .any, condition: { context -> Bool in

‎Sources/StateMachine.swift‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
public final class StateMachine<S: StateType, E: EventType>: Machine<S, E>
1616
{
1717
/// Closure-based routes for `tryState()`.
18-
/// - Returns: Multiple `toState`s from single `fromState`, similar to `.State0 => [.State1, .State2]`
18+
/// - Returns: Multiple `toState`s from single `fromState`, similar to `.state0 => [.state1, .state2]`
1919
public typealias StateRouteMapping = (_ fromState: S, _ userInfo: Any?) -> [S]?
2020

2121
private lazy var _routes: _RouteDict = [:]
@@ -52,7 +52,7 @@ public final class StateMachine<S: StateType, E: EventType>: Machine<S, E>
5252
guard let fromState = transition.fromState.rawValue,
5353
let toState = transition.toState.rawValue else
5454
{
55-
assertionFailure("State = `.Any` is not supported for `hasRoute()` (always returns `false`)")
55+
assertionFailure("State = `.any` is not supported for `hasRoute()` (always returns `false`)")
5656
return false
5757
}
5858

‎Sources/StateType.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ public protocol StateType: Hashable {}
1010

1111
// MARK: State
1212

13-
/// `StateType` wrapper for handling `.Any` state.
13+
/// `StateType` wrapper for handling `.any` state.
1414
public enum State<S: StateType>
1515
{
1616
case some(S)

‎Sources/Transition.swift‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77
//
88

99
///
10-
/// "From-" and "to-" states represented as `.State1 => .State2`.
11-
/// Also, `.Any` can be used to represent _any state_.
10+
/// "From-" and "to-" states represented as `.state1 => .state2`.
11+
/// Also, `.any` can be used to represent _any state_.
1212
///
1313
public struct Transition<S: StateType>: Hashable
1414
{
@@ -54,7 +54,7 @@ public func == <S: StateType>(left: Transition<S>, right: Transition<S>) -> Bool
5454

5555
infix operator => : AdditionPrecedence
5656

57-
/// e.g. .State0 => .State1
57+
/// e.g. .state0 => .state1
5858
public func => <S: StateType>(left: State<S>, right: State<S>) -> Transition<S>
5959
{
6060
return Transition(fromState: left, toState: right)

‎Sources/TransitionChain.swift‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
// Copyright (c) 2014年 Yasuhiro Inami. All rights reserved.
77
//
88

9-
/// Group of continuous `Transition`s represented as `.State1 => .State2 => .State3`.
9+
/// Group of continuous `Transition`s represented as `.state1 => .state2 => .state3`.
1010
public struct TransitionChain<S: StateType>
1111
{
1212
public private(set) var states: [State<S>]
@@ -37,7 +37,7 @@ public struct TransitionChain<S: StateType>
3737
// MARK: - Custom Operators
3838
//--------------------------------------------------
3939

40-
// e.g. (.State0 => .State1) => .State
40+
// e.g. (.state0 => .state1) => .state
4141
public func => <S: StateType>(left: Transition<S>, right: State<S>) -> TransitionChain<S>
4242
{
4343
return TransitionChain(states: [left.fromState, left.toState]) => right
@@ -58,7 +58,7 @@ public func => <S: StateType>(left: TransitionChain<S>, right: S) -> TransitionC
5858
return left => .some(right)
5959
}
6060

61-
// e.g. .State0 => (.State1 => .State)
61+
// e.g. .state0 => (.state1 => .state)
6262
public func => <S: StateType>(left: State<S>, right: Transition<S>) -> TransitionChain<S>
6363
{
6464
return left => TransitionChain(states: [right.fromState, right.toState])

0 commit comments

Comments
 (0)