blakewatters / transitionkit Goto Github PK

An Objective-C library for elegantly implementing state machines.

License: Apache License 2.0

Objective-C 96.21% Ruby 3.79%

transitionkit's Introduction

TransitionKit

A simple, elegantly designed block based API for implementing State Machines in Objective-C

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.

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.
States, Events, and State Machines are NSCopying and NSCoding compliant, enabling easy integration with archiving and copying in your custom classes.
Strongly enforced. The state machine includes numerous runtime checks for misconfigurations, making it easy to debug and trust your state machines.
Transitions support the inclusion of arbitrary user data via a userInfo dictionary, making it easy to broadcast metadata across callbacks.
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.

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.

Install CocoaPods if not already available:

$ [sudo] gem install cocoapods
$ pod setup

Change to the directory of your Xcode project, and Create and Edit your Podfile and add 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)

$ open MyProject.xcworkspace

Examples

Simple Example

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:

Install the dependencies via CocoaPods: pod install
Open the workspace: open TransitionKit.xcworkspace
Run the specs via the Product menu > Test

Contact

Blake Watters

License

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

transitionkit's People

Contributors

Stargazers

Watchers

Forkers

github-forks listrophy aboduo artfeel jcoleman ycditchf wetransferarchive breezeworks chris838 phpdotsql nicolastinkl phamquy samkrishna marcjay ipmcc croath ajones katt coghealthtech nachosoto cummings tfaehnle zendeskarchive jasonzengj mackross nam1cob xuvw bblionel lieu-woxinxiangni sninjay fyn6417 donny2g theewind zvjerka24 djlycit bellchen happy10086 windwild marotan3 gaopeng9090 celor wuxu 0xced rw121rw rockyz patrickbelon chanelten zerobitzero gp-zhang sunfei kimbin iosapplist zilaiyedaren fermion42 juanjo-ramos smyrgl mrredvenom montadigital raumfeld xiaodai suxinde2009 longhuawhu weissazool viktorblazhevych zcill puliaiev kb100824 rakutou tommeier csv007 583175259 duk42111 gd362660870 jiaqisun jeffasd lewis-smith softwarenerd ithoughts jiyee ggthedev dvlprliu qiki twi-star quanhua-guan arturgrigor happycrise armcknight 983563622 terry-au yywdark nscodemonkey zqdreamer iplaycloud arkilis lisa718 zslzhappy gongzhen annabelle1024 zhenshub fyhsky

transitionkit's Issues

Tag a new release

Could you please tag a new release with the changes introduced in #27?

Without a new tagged version, it is impossible to have a podspec that depends on TransitionKit and use the new TKStateMachineDidChangeStateTransitionUserInfoKey.

Event destination state should be state dependent

As I understand it, events in TransitionKit can only have a single destination state. This is a result of the set of valid event transitions being state-independent, rather than a function of the current state.

As an example, here's the state machine from the README:

All of the events have a single destination state, regardless of the current state. So, the following state machine is currently impossible to model:

Well, not impossible. You can create two "View Message" events, two "Mark as Unread" events, and two "Delete Message" events... And then fire the correct one in a if/else if block by checking the current state. But that quickly becomes unwieldy in a larger state machine.

Is my understanding correct that this is a limitation of the current API?
Is this something that you would be willing to accept a pull request for, or is this part of the design that you wouldn't be open to changing?
If you are open to a pull request, how open are you to API changes? The API will have to change, but hopefully not too much. Something along the lines of:

TKState *S1 = [TKState stateWithName:@"S1"];
TKState *S2 = [TKState stateWithName:@"S2"];
TKState *S3 = [TKState stateWithName:@"S3"];

// Simple transition
TKEvent *simple = [TKEvent eventWithName:@"Simple Event" transitioningFromStates:@[S1, S2] toState:S3];

// Add more transitions to existing event
[simple addTransitionFromStates:@[S3] toState:S1];

// Or add them all at once
TKEvent *complex = [TKEvent eventWithName:@"Complex Event" transitions:@{ @[S1, S2]: S3, @[S3]: S1 }];

dotDescription not available in the 2.2.1 published on Pod.

Installing 2.2.1 version with Pod TKStateMachine.h and TKStateMachine.m are different from what I see in Github and dotDescription property is not available.

Add userInfo

What a wonderful framework! Thank you for your efforts=)))

I am implementing a library for authentication via OAuth based on AFNetworking. The mechanism of the state machine I ported from facebook-ios-sdk (I mean "ported", it looks like "O my go-sh..."). There must pass userInfo in the event with a new access_token.

Is it possible to add userInfo to fireEvent:error:, notifications and blocks (including events and states)?

No Spec in CocoaPods

There is missing spec for transitionkit in cocoapods :(

`pod 'TransitionKit'` installs version 2.0.0 where sample code doesn't work

I used pod 'TransitionKit' and I get these compile errors when trying to run the sample code:

receiver 'TKState' for class message is a forward declaration
no known class method for selector 'stateWithName:'

Someone trying out the library for the first time (like me) might get confused by this.

Looks like two events with the same name can be added.

How to deactive the state machine

I only found the activate method, can't found the deactivate method

Add transaction

Is it possible to add transaction-style event or transaction itself?

For example, OAuth 2 implicit grant flow:

stateMachine.initialState = @"Empty"
Init login transaction with @"NewCredential" state and start it. [stateMachine inTransaction] == YES, stateMachine.newState == @"NewCredential"
Create URL and open it in Safari

Return in app with

access_token and transaction will commit: stateMachine.currentState = stateMachine.newState (e.g., stateMachine.currentState == @"NewCredential"), stateMachine.newState = nil
error and transaction will rollback: stateMachine.currentState == stateMachine.initialState (e.g. stateMachine.currentState == @"Empty"), stateMachine.newState = nil

We can fire event from many states to the new one, but we can't rollback to initial state if something going wrong, because of fireEvent is an atomic operation.
In this case we must create more than one event to "unfire" "wrong" event.

[TKEvent eventWithName:@"CreateSession" transitioningFromStates:@[ stateEmpty, stateFound, stateExpired ] toState:stateNewTransitive];

// complex logic about which event to fire
[TKEvent eventWithName:@"AbortCreateSession1" transitioningFromStates:@[ stateNewTransitive ] toState:stateEmpty];
[TKEvent eventWithName:@"AbortCreateSession2" transitioningFromStates:@[ stateNewTransitive ] toState:stateFound];
[TKEvent eventWithName:@"AbortCreateSession3" transitioningFromStates:@[ stateNewTransitive ] toState:stateExpired];

Carthage support

Is there any interest in adding Carthage support?

At a glance, it seems like it should be compatible with TransitionKit's current use of CocoaPods, since it's used only for test targets rather than being a dependency.

As far as I can tell, the changes necessary would be to add a framework target and a shared scheme.

In latest version (2.2.1), TKState doesn't have the userInfo property

v2.2.1 was released here 8a07aec

and the PR containing the change on TKState merged here 4c4b69f

Are you planning on releasing v2.2.2 with the latest changes added?

Thanks.

is this repository active?

It is a special implementation in some kind.
Many people try to make tons of code in swift in super fast network / json parsing / DI / etc.

I can't find any appropriate implementation of state machine for objective-c.

This one is the best. ( Or even only one )

I would like to help.

Readme pod install error

The readme says to install transition kit as version ~> 1.0.0 - which is out of date. It should be 2.0.0, otherwise the example code does not work.