TransitionKit
https://github.com/blakewatters/TransitionKit
A simple, elegantly designed block based API for implementing State Machines in Objective-C
一套簡單,優雅的基於block設計的API,用以實現OC中的狀態機.
TransitionKit is a small Cocoa library that provides an API for implementing a state machine in Objective C. It is full-featured, completely documented, and very thoroughly unit tested. State machines are a great way to manage complexity in your application and TransitionKit provides you with an elegant API for implementing state machines in your next iOS or Mac OS X application.
TransitionKit是一個簡單的Cocoa庫,提供API用以實現OC的狀態機.它有著完整的特性,全面的文件以及經過了詳細的單元測試.狀態機是一個用以解決複雜的UI與資料來源業務互動邏輯的一種方案,也許就會用在你的下一款為iOS或者OS X設計的專案當中.
- Supports an arbitrary number of States and Events. 支援任意數目的狀態以及事件
- States and Events support a thorough set of block based callbacks for responding to state transitions. 狀態與事件支援一系列基於block的回撥,用以響應狀態的改變
- States, Events, and State Machines are NSCopying and NSCoding compliant, enabling easy integration with archiving and copying in your custom classes. 狀態,事件以及狀態機遵循NSCopying與NSCoding協議,即使你的類中需要支援NSCopying,NSCoding,你也可以方便的使用狀態機
- Strongly enforced. The state machine includes numerous runtime checks for misconfigurations, making it easy to debug and trust your state machines. 狀態機非常可靠,可以方便你debug,放行使用
- Transitions support the inclusion of arbitrary user data via a
userInfodictionary, making it easy to broadcast metadata across callbacks. Transitions支援你傳遞字典,你可以方便的將後設資料進行廣播,通過回撥的方式 - Completely Documented. The entire library is marked up with Appledoc. 有著完整的文件,方便你查詢
- Thorougly unit tested. You know it works and can make changes with confidence. 通過了單元測試,請相信,這個狀態機是非常可靠的
- Lightweight. TransitionKit has no dependencies beyond the Foundation library and works on iOS and Mac OS X. 輕量級,TransitionKit不依賴於Foundation框架,你可以便利的在iOS於Mac OS X中使用
The recommended approach for installing TransitionKit is via the CocoaPods package manager, as it provides flexible dependency management and dead simple installation. For best results, it is recommended that you install via CocoaPods >= 0.16.0 using Git >= 1.8.0 installed via Homebrew.
推薦的安裝方式是通過CocoaPods包來安裝,它提供了靈活的依賴關係,並讓安裝變得非常簡易.建議你通過Homebrew,使用CocoaPods >= 0.16.0或者是Git >= 1.8.0來安裝.
Install CocoaPods if not already available:
安裝CocoaPods,如果你還沒用過CocoaPods
$ [sudo] gem install cocoapods
$ pod setup
Change to the directory of your Xcode project, and Create and Edit your Podfile and add TransitionKit:
進入你的Xcode工程目錄,建立,編輯你的Podfile,然後新增TransitionKit:
$ cd /path/to/MyProject
$ touch Podfile
$ edit Podfile
platform :ios, '5.0'
# Or platform :osx, '10.7'
pod 'TransitionKit', '~> 2.0.0'
Install into your project:
安裝到你的專案當中:
$ pod install
Open your project in Xcode from the .xcworkspace file (not the usual project file)
然後,開啟.xcworkspace檔案即可
$ open MyProject.xcworkspace
The following example is a simple state machine that models the state of a Message in an Inbox.
以下示例是一個簡單的使用示例,用以反映狀態機的基本運作.
TKStateMachine *inboxStateMachine = [TKStateMachine new];
TKState *unread = [TKState stateWithName:@"Unread"];
[unread setDidEnterStateBlock:^(TKState *state, TKTransition *transition) {
[self incrementUnreadCount];
}];
TKState *read = [TKState stateWithName:@"Read"];
[read setDidExitStateBlock:^(TKState *state, TKTransition *transition) {
[self decrementUnreadCount];
}];
TKState *deleted = [TKState stateWithName:@"Deleted"];
[deleted setDidEnterStateBlock:^(TKState *state, TKTransition *transition) {
[self moveMessageToTrash];
}];
[inboxStateMachine addStates:@[ unread, read, deleted ]];
inboxStateMachine.initialState = unread;
TKEvent *viewMessage = [TKEvent eventWithName:@"View Message" transitioningFromStates:@[ unread ] toState:read];
TKEvent *deleteMessage = [TKEvent eventWithName:@"Delete Message" transitioningFromStates:@[ read, unread ] toState:deleted];
TKEvent *markAsUnread = [TKEvent eventWithName:@"Mark as Unread" transitioningFromStates:@[ read, deleted ] toState:unread];
[inboxStateMachine addEvents:@[ viewMessage, deleteMessage, markAsUnread ]];
// Activate the state machine
[inboxStateMachine activate];
[inboxStateMachine isInState:@"Unread"]; // YES, the initial state
// Fire some events
NSDictionary *userInfo = nil;
NSError *error = nil;
BOOL success = [inboxStateMachine fireEvent:@"View Message" userInfo:userInfo error:&error]; // YES
success = [inboxStateMachine fireEvent:@"Delete Message" userInfo:userInfo error:&error]; // YES
success = [inboxStateMachine fireEvent:@"Mark as Unread" userInfo:userInfo error:&error]; // YES
success = [inboxStateMachine canFireEvent:@"Mark as Unread"]; // NO
// Error. Cannot mark an Unread message as Unread
success = [inboxStateMachine fireEvent:@"Mark as Unread" userInfo:nil error:&error]; // NO
// error is an TKInvalidTransitionError with a descriptive error message and failure reason
TransitionKit is tested using the Kiwi BDD library. In order to run the tests, you must do the following:
TransitionKit使用了Kiwi BDD庫進行測試.為了執行這個測試,你需要做如下幾步:
- Install the dependencies via CocoaPods:
pod install 先通過CocoaPods來安裝依賴 - Open the workspace:
open TransitionKit.xcworkspace 然後開啟TransitionKit.xcworkspace - Run the specs via the Product menu > Test 然後選擇Product menu > Test 來執行
Blake Watters
TransitionKit is available under the Apache 2 License. See the LICENSE file for more info.
TransitionKit支援Apache 2 協議,請檢視Apache 2 協議瞭解更多.