[翻译] TransitionKit

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设计的项目当中.

Features

• 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 userInfo dictionary, 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中使用

Installation via CocoaPods

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

Examples

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

Unit Tests

TransitionKit is tested using the Kiwi BDD library. In order to run the tests, you must do the following:

TransitionKit使用了Kiwi BDD库进行测试.为了运行这个测试,你需要做如下几步:

1. Install the dependencies via CocoaPods: pod install 先通过CocoaPods来安装依赖
2. Open the workspace: open TransitionKit.xcworkspace 然后打开TransitionKit.xcworkspace
3. Run the specs via the Product menu > Test 然后选择Product menu > Test 来运行

Contact

Blake Watters

• http://github.com/blakewatters
• http://twitter.com/blakewatters
• blakewatters@gmail.com

License

TransitionKit is available under the Apache 2 License. See the LICENSE file for more info.

TransitionKit支持Apache 2 协议,请查看Apache 2 协议了解更多.