finite_machine 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7582fc3410fbb09056dee6ed167b505ebe6febaf
-  data.tar.gz: 3d6336949ace9e8ce3ef3c469346ae6ea1c69044
+  metadata.gz: 88cd408cda756703b6665126580605500ad9273f
+  data.tar.gz: 93a8062b97cd5a0fed0367c091cbb06e45242b2c
 SHA512:
-  metadata.gz: a1e6145d24909b4762a5be15a85f85c8eac2a07239d3f350ac1eba4283bfe9d4dd517fada486f4b749b97234d32c5b9957b82ccf8bc1ba57441f67a9ba6957d4
-  data.tar.gz: 0c948fa0384294b6ead78ae12b6e367d033bd6adf69be4c32420e4ac67cff4a07f565f1870c9d8f62653ccdce51c606cc9f828572e5dcf15ce5d471c80ec6438
+  metadata.gz: fb7c16c1ec7e7238cfb5d2b37ab554741733b4957af9855878a0b35d7ef4e04f334542c8889d5829ed9d002ac9ef847c20f093590af44db7310ced42b33e53b1
+  data.tar.gz: 2963f9d98146612ae2a6d9c3ba5a690bb06d1f32f8fd6e1da1b817f8fdcb0923ec371f38ae48ce4e92ee553c65214f3a1dc34d095d523431a302b32b377008b9

data/.travis.yml

@@ -6,13 +6,17 @@ rvm:
   - 2.0.0
   - 2.1.0
   - ruby-head
-  - rbx
 matrix:
   include:
     - rvm: jruby-19mode
     - rvm: jruby-20mode
     - rvm: jruby-21mode
     - rvm: jruby-head
+    - rvm: rbx
   allow_failures:
-    - rvm: 2.1.0
+    - rvm: ruby-head
+    - rvm: jruby-head
+    - rvm: rbx
   fast_finish: true
+branches:
+  only: master

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+0.2.0 (March 01, 2014)
+
+* Ensure correct transition object state
+* Add methods synchronization for thread safety
+* Fix bug - callback event object returns correct from state
+* Add ability to define custom initial event
+* Add hooks class for callbacks registration
+* Extend threadable accessors
+* Add generic state and event listeners
+* Add target to allow integration with external objects,
+  and allow easy method lookup through callback context
+* Add ability to specify custom handlers for error conditions

data/README.md

@@ -1,8 +1,13 @@
 # FiniteMachine
+[![Gem Version](https://badge.fury.io/rb/finite_machine.png)][gem]
+[![Build Status](https://secure.travis-ci.org/peter-murach/finite_machine.png?branch=master)][travis]
+[![Code Climate](https://codeclimate.com/github/peter-murach/finite_machine.png)][codeclimate]
 
-A minimal finite state machine with a straightforward syntax. With intuitive
-syntax you can quickly model states and add callbacks that can be triggered
-synchronously or asynchronously.
+[gem]: http://badge.fury.io/rb/finite_machine
+[travis]: http://travis-ci.org/peter-murach/finite_machine
+[codeclimate]: https://codeclimate.com/github/peter-murach/finite_machine
+
+A minimal finite state machine with a straightforward and intuitive syntax. You can quickly model states and add callbacks that can be triggered synchronously or asynchronously.
 
 ## Features
 
@@ -22,7 +27,7 @@ Add this line to your application's Gemfile:
 
     gem 'finite_machine'
 
-And then execute:
+Then execute:
 
     $ bundle
 
@@ -30,6 +35,16 @@ Or install it yourself as:
 
     $ gem install finite_machine
 
+## Contents
+
+* [1. Usage](#1-usage)
+* [2. Transitions](#2-transitions)
+* [3. Conditional transitions](#3-conditional-transitions)
+* [4. Callbacks](#4-callbacks)
+* [5. Errors](#5-errors)
+* [6. Integration](#6-integration)
+* [7. Tips](#7-tips)
+
 ## 1 Usage
 
 Here is a very simple example of a state machine:
@@ -52,11 +67,11 @@ fm = FiniteMachine.define do
 end
 ```
 
-As the example demonstrates, by calling the `define` method on **FiniteMachine** one gets to create an instance of finite state machine. The `events` and `callbacks` scopes help to define the behaviour of the machine. Read [Transitions](#transitions) and [Callbacks](#callbacks) sections for more detail.
+As the example demonstrates, by calling the `define` method on **FiniteMachine** you create an instance of finite state machine. The `events` and `callbacks` scopes help to define the behaviour of the machine. Read [Transitions](#2-transitions) and [Callbacks](#4-callbacks) sections for more details.
 
 ### 1.1 current
 
-The **FiniteMachine** allows to query the current state by calling `current` method. 
+The **FiniteMachine** allows you to query the current state by calling the `current` method.
 
 ```ruby
   fm.current  # => :red
@@ -64,105 +79,120 @@ The **FiniteMachine** allows to query the current state by calling `current` met
 
 ### 1.2 initial
 
-There are number of ways to provide initial state  **FiniteMachine** depending on your requirements.
+There are number of ways to provide the initial state  **FiniteMachine** depending on your requirements.
 
-By default the **FiniteMachine** will be in `:none` state and you would need to provide event to transition out of this state.
+By default the **FiniteMachine** will be in the `:none` state and you will need to provide an event to transition out of this state.
 
 ```ruby
-  fm = FiniteMachine.define do
-    events {
-      event :start, :none   => :green
-      event :slow,  :green  => :yellow
-      event :stop,  :yellow => :red
-    }
-  end
+fm = FiniteMachine.define do
+  events {
+    event :start, :none   => :green
+    event :slow,  :green  => :yellow
+    event :stop,  :yellow => :red
+  }
+end
 
-  fm.current # => :none
+fm.current # => :none
 ```
 
-If you specify initial state using `initial` helper then an `init` event will be created and triggered when the state machine is constructed.
+If you specify initial state using the `initial` helper, an `init` event will be created and triggered when the state machine is created.
 
 ```ruby
-  fm = FiniteMachine.define do
-    initial :green
+fm = FiniteMachine.define do
+  initial :green
 
-    events {
-      event :slow,  :green  => :yellow
-      event :stop,  :yellow => :red
-    }
-  end
+  events {
+    event :slow,  :green  => :yellow
+    event :stop,  :yellow => :red
+  }
+end
 
-  fm.current # => :green
+fm.current # => :green
 ```
 
-Finally, if you want to defer calling the initial state method pass the `:defer` option to `initial` helper.
+If your target object already has `init` method or one of the events names redefines `init`, you can use different name by passing `:event` option to `initial` helper.
 
 ```ruby
-  fm = FiniteMachine.define do
-    initial state: :green, defer: true
+fm = FiniteMachine.define do
+  initial :green, event: :start
 
-    events {
-      event :slow,  :green  => :yellow
-      event :stop,  :yellow => :red
-    }
-  end
-  fm.current # => :none
-  fm.init
-  fm.current # => :green
+  events {
+    event :slow,  :green  => :yellow
+    event :stop,  :yellow => :red
+  }
+end
+
+fm.current # => :green
+```
+
+If you want to defer calling the initial state method pass the `:defer` option to the `initial` helper.
+
+```ruby
+fm = FiniteMachine.define do
+  initial state: :green, defer: true
+
+  events {
+    event :slow,  :green  => :yellow
+    event :stop,  :yellow => :red
+  }
+end
+fm.current # => :none
+fm.init
+fm.current # => :green
 ```
 
 ### 1.3 terminal
 
-To specify a final state **FiniteMachine** uses `terminal` method.
+To specify a final state **FiniteMachine** uses the `terminal` method.
 
 ```ruby
-  fm = FiniteMachine.define do
-    initial :green
-    terminal :red
+fm = FiniteMachine.define do
+  initial :green
+  terminal :red
 
-    events {
-      event :slow, :green  => :yellow
-      event :stop, :yellow => :red
-    }
-  end
+  events {
+    event :slow, :green  => :yellow
+    event :stop, :yellow => :red
+  }
+end
 ```
 
-After terminal state has been specified, you can use `finished?` method on the state machine instance to verify if the terminal state has been reached or not. 
+When the terminal state has been specified, you can use `finished?` method on the state machine instance to verify if the terminal state has been reached or not.
 
 ```ruby
-  fm.finished?  # => false
-  fm.slow
-  fm.finished?  # => false
-  fm.stop
-  fm.finished?  # => true
+fm.finished?  # => false
+fm.slow
+fm.finished?  # => false
+fm.stop
+fm.finished?  # => true
 ```
 
 ### 1.4 is?
 
-To verify whether or not a state machine is in a given state, **FiniteMachine** uses `is?` method. It returns `true` if machien is found to be in a state, and `false` otherwise.
+To verify whether or not a state machine is in a given state, **FiniteMachine** uses `is?` method. It returns `true` if the machine is found to be in the given state, or `false` otherwise.
 
 ```ruby
-  fm.is?(:red)    # => true
-  fm.is?(:yellow) # => false
+fm.is?(:red)    # => true
+fm.is?(:yellow) # => false
 ```
 
 ### 1.5 can? and cannot?
 
-To verify whether or not an event can be fired, **FiniteMachine** provides `can?` or `cannot?` methods. `can?` checks if transition can be performed and returns true if state change can happend, and false otherwise. `cannot?` is simply the inverse of `can?`.
+To verify whether or not an event can be fired, **FiniteMachine** provides `can?` or `cannot?` methods. `can?` checks if **FiniteMachine** can fire a given event, returning true, otherwise, it will return false. `cannot?` is simply the inverse of `can?`.
 
 ```ruby
-  fm.can?(:ready)    # => true
-  fm.can?(:go)       # => false
-  fm.cannot?(:ready) # => false
-  fm.cannot?(:go)    # => true
+fm.can?(:ready)    # => true
+fm.can?(:go)       # => false
+fm.cannot?(:ready) # => false
+fm.cannot?(:go)    # => true
 ```
 
 ### 1.6 states
 
-You can use `states` method to query for all states. It returns an array of all the states for the current state machine.
+You can use the `states` method to return an array of all the states for a given state machine.
 
 ```ruby
-  fm.states # => [:none, :green, :yellow, :red]
+fm.states # => [:none, :green, :yellow, :red]
 ```
 
 ### 1.7 target
@@ -170,20 +200,43 @@ You can use `states` method to query for all states. It returns an array of all
 If you need to execute some external code in the context of the current state machine use `target` helper.
 
 ```ruby
-  car = Car.new
+car = Car.new
 
-  fm = FiniteMachine.define do
-    initial :neutral
+fm = FiniteMachine.define do
+  initial :neutral
 
-    target car
+  target car
 
-    events {
-      event :start, :neutral => :one, if: "engine_on?"
-      event :shift, :one => :two
-    }
-  end
+  events {
+    event :start, :neutral => :one, if: "engine_on?"
+    event :shift, :one => :two
+  }
+end
+```
+
+Furthermore, the context created through `target` helper will allow you to reference and call methods from another object.
+
+```ruby
+car = Car.new
+
+fm = FiniteMachine.define do
+  initial :neutral
+
+  target car
+
+  events {
+    event :start, :neutral => :one, if: "engine_on?"
+  }
+
+  callbacks {
+    on_enter_start do |event| turn_engine_on end
+    on_exit_start  do |event| turn_engine_off end
+  }
+end
 ```
 
+For more complex example see [Integration](#6-integration) section.
+
 ## 2 Transitions
 
 The `events` scope exposes the `event` helper to define possible state transitions.
@@ -198,7 +251,7 @@ in the form of `:from` and `:to` hash keys or by using the state names themselve
   event :start, :neutral => :first
 ```
 
-Once specified the **FiniteMachine** will create custom methods for transitioning between the states.
+Once specified, the **FiniteMachine** will create custom methods for transitioning between each state.
 The following methods trigger transitions for the example state machine.
 
 * ready
@@ -207,14 +260,14 @@ The following methods trigger transitions for the example state machine.
 
 ### 2.1 Performing transitions
 
-In order to transition to the next reachable state simply call the event name on the **FiniteMachine** instance.
+In order to transition to the next reachable state, simply call the event's name on the **FiniteMachine** instance.
 
 ```ruby
   fm.ready
   fm.current       # => :yellow
 ```
 
-Further, you can pass additional parameters with the method call that will be available in the triggered callback.
+Furthermore, you can pass additional parameters with the method call that will be available in the triggered callback.
 
 ```ruby
   fm.go('Piotr!')
@@ -278,7 +331,7 @@ You can also execute methods on an associated object by passing it as an argumen
   end
 
   car = Car.new
-  car.trun_engine_on
+  car.turn_engine_on
 
   fm = FiniteMachine.define do
     initial :neutral
@@ -310,7 +363,7 @@ You can also use a symbol corresponding to the name of a method that will get ca
   end
 ```
 
-### 3.2 Using a String
+### 3.3 Using a String
 
 Finally, it's possible to use string that will be evaluated using `eval` and needs to contain valid Ruby code. It should only be used when the string represents a short condition.
 
@@ -328,7 +381,7 @@ Finally, it's possible to use string that will be evaluated using `eval` and nee
 
 ### 3.4 Combining transition conditions
 
-When multiple conditions define whether or not a transition should happen, an Array can be used. Moreover, you can apply both `:if` and `:unless` to the same transition.
+When multiple conditions define whether or not a transition should happen, an Array can be used. Furthermore, you can apply both `:if` and `:unless` to the same transition.
 
 ```ruby
   fsm = FiniteMachine.define do
@@ -347,15 +400,24 @@ The transition only runs when all the `:if` conditions and none of the `unless`
 
 ## 4 Callbacks
 
-You can consume state machine events and the information they provide by registering a callback. The following main 3 types of callbacks are available in **FiniteMachine**:
+You can watch state machine events and the information they provide by registering a callback. The following 3 types of callbacks are available in **FiniteMachine**:
 
 * `on_enter`
 * `on_transition`
 * `on_exit`
 
-Use `callbacks` scope to introduce the listeners. You can register a callback to listen for state changes or events being triggered. Use the state or event name as a first parameter to the callback followed by a list arguments that you expect to receive.
+In addition, you can listen for generic state changes or events fired by using the following 6 callbacks:
 
-When you subscribe to `:green` state event, the callback will be called whenever someone instruments change for that state. The same will happend upon subscription to event `ready`, namely, the callback will be called each time the state transition method is called.
+* `on_enter_state`
+* `on_enter_event`
+* `on_transition_state`
+* `on_transition_event`
+* `on_exit_state`
+* `on_exit_event`
+
+Use the `callbacks` scope to introduce the listeners. You can register a callback to listen for state changes or events being triggered. Use the state or event name as a first parameter to the callback followed by a list arguments that you expect to receive.
+
+When you subscribe to the `:green` state event, the callback will be called whenever someone instruments change for that state. The same will happend on subscription to event `ready`, namely, the callback will be called each time the state transition method is called.
 
 ```ruby
 fm = FiniteMachine.define do
@@ -380,19 +442,25 @@ fm.go('Piotr!')
 
 ### 4.1 on_enter
 
-This method is executed before given event or state change happens. If you provide only a callback without the name for the state or event to listen for, then `any` state and event will be observered.
+This method is executed before given event or state change. If you provide only a callback without the name of the state or event to listen out for, then `:any` state and `:any` event will be observered.
+
+You can further narrow down the listener to only watch enter state changes using `on_enter_state` callback. Similarly, use `on_enter_event` to only watch for event changes.
 
 ### 4.2 on_transition
 
-This method is executed when given event or state change happens. If you provide only a callback without the name for the state or event to listen for, then `any` state and event will be observered.
+This method is executed when given event or state change happens. If you provide only a callback without the name of the state or event to listen out for, then `:any` state and `:any` event will be observered.
+
+You can further narrow down the listener to only watch state transition changes using `on_transition_state` callback. Similarly, use `on_transition_event` to only watch for event transition changes.
 
 ### 4.3 on_exit
 
-This method is executed after given event or state change happens. If you provide only a callback without the name for the state or event to listen for, then `any` state and event will be observered.
+This method is executed after a given event or state change happens. If you provide only a callback without the name of the state or event to listen for, then `:any` state and `:any` event will be observered.
+
+You can further narrow down the listener to only watch state exit changes using `on_exit_state` callback. Similarly, use `on_exit_event` to only watch for event exit changes.
 
 ### 4.4 Parameters
 
-All callbacks are passed `TransitionEvent` object with the following attributes.
+All callbacks get the `TransitionEvent` object with the following attributes.
 
 * name    # the event name
 * from    # the state transitioning from
@@ -400,24 +468,42 @@ All callbacks are passed `TransitionEvent` object with the following attributes.
 
 followed by the rest of arguments that were passed to the event method.
 
+```ruby
+fm = FiniteMachine.define do
+  initial :red
+
+  events {
+    event :ready, :red => :yellow
+  }
+
+  callbacks {
+    on_enter_ready { |event, time|
+      puts "lights switching from #{event.from} to #{event.to} in #{time} seconds"
+    }
+  }
+end
+
+fm.ready(3)   #  => 'lights switching from red to yellow in 3 seconds'
+```
+
 ### 4.5 Same kind of callbacks
 
 You can define any number of the same kind of callback. These callbacks will be executed in the order they are specified.
 
 ```ruby
-  fm = FiniteMachine.define do
-    initial :green
+fm = FiniteMachine.define do
+  initial :green
 
-    events {
-      event :slow, :green => :yellow
-    }
+  events {
+    event :slow, :green => :yellow
+  }
 
-    callbacks {
-      on_enter(:yellow) { this_is_run_first }
-      on_enter(:yellow) { then_this }
-    }
-  end
-  fm.slow # => will invoke both callbacks
+  callbacks {
+    on_enter(:yellow) { this_is_run_first }
+    on_enter(:yellow) { then_this }
+  }
+end
+fm.slow # => will invoke both callbacks
 ```
 
 ### 4.6 Fluid callbacks
@@ -442,30 +528,143 @@ fm = FiniteMachine.define do
 end
 ```
 
+### 4.7 Executing methods inside callbacks
+
+In order to execute method from another object use `target` helper.
+
+```ruby
+class Car
+  attr_accessor :reverse_lights
+
+  def turn_reverse_lights_off
+    @reverse_lights = false
+  end
+
+  def turn_reverse_lights_on
+    @reverse_lights = true
+  end
+end
+
+car = Car.new
+
+fm = FiniteMachine.define do
+  initial :neutral
+
+  target car
+
+  events {
+    event :forward, [:reverse, :neutral] => :one
+    event :back,    [:neutral, :one] => :reverse
+  }
+
+  callbacks {
+    on_enter_reverse { |event| turn_reverse_lights_on }
+    on_exit_reverse  { |event| turn_reverse_lights_off }
+  }
+end
+```
+
+Note that you can also fire events from callbacks.
+
+```ruby
+fm = FiniteMachine.define do
+  initial :neutral
+
+  target car
+events {
+    event :forward, [:reverse, :neutral] => :one
+    event :back,    [:neutral, :one] => :reverse
+  }
+
+  callbacks {
+    on_enter_reverse { |event| forward('Piotr!') }
+    on_exit_reverse  { |event, name| puts "Go #{name}" }
+  }
+end
+fm.back   # => Go Piotr!
+```
+
+For more complex example see [Integration](#6-integration) section.
+
 ## 5 Errors
 
-## 6 Integration
+By default, the **FiniteMachine** will throw an exception whenever the machine is in invalid state or fails to transition.
 
-Since **FiniteMachine** is an object in its own right it leaves integration with other systems up to you. In contrast to other Ruby libraries, it does not extend from models(e.i.ActiveRecord) to transform them into state machine or require mixing into exisiting class.
+* FiniteMachine::TransitionError
+* FiniteMachine::InvalidStateError
+* FiniteMachine::InvalidCallbackError
+
+You can attach specific error handler inside the `handlers` scope by passing the name of the error and actual callback to be executed when the error happens inside the `handle` method. The `handle` receives a list of exception class or exception class names, and an option `:with` with a name of the method or a Proc object to be called to handle the error. As an alternative, you can pass a block.
 
 ```ruby
+fm = FiniteMachine.define do
+  initial :green, event: :start
+
+  events {
+    event :slow,  :green  => :yellow
+    event :stop,  :yellow => :red
+  }
+
+  handlers {
+    handle FiniteMachine::InvalidStateError do |exception|
+      # run some custom logging
+      raise exception
+    end
+
+    handle FiniteMachine::TransitionError, with: proc { |exception| ... }
+  }
+end
+```
+
+### 5.1 Using target
+
+You can pass an external context via `target` helper that will be the receiver for the handler. The handler method needs to take one argument that will be called with the exception.
+
+```ruby
+class Logger
+  def log_error(exception)
+    puts "Exception : #{exception.message}"
+  end
+end
+
+fm = FiniteMachine.define do
+  target logger
+
+  initial :green
+
+  events {
+    event :slow, :green  => :yellow
+    event :stop, :yellow => :red
+  }
+
+  handlers {
+    handle 'InvalidStateError', with: :log_error
+  }
+end
+```
+
+## 6 Integration
 
+Since **FiniteMachine** is an object in its own right it leaves integration with other systems up to you. In contrast to other Ruby libraries, it does not extend from models (i.e. ActiveRecord) to transform them into a state machine or require mixing into exisiting classes.
+
+```ruby
 class Car
   attr_accessor :reverse_lights
 
   def turn_reverse_lights_off
-    reverse_lights = false
+    @reverse_lights = false
   end
 
   def turn_reverse_lights_on
-    reverse_lights = true
+    @reverse_lights = true
   end
 
   def gears
+    context = self
     @gears ||= FiniteMachine.define do
       initial :neutral
 
-      target: self
+      target: context
 
       events {
         event :start, :neutral => :one
@@ -475,27 +674,68 @@ class Car
       }
 
       callbacks {
-        on_enter :reverse do |car, event|
-          car.turnReverseLightsOn
+        on_enter :reverse do |event|
+          turn_reverse_lights_on
         end
 
-        on_exit :reverse do |car, event|
-          car.turnReverseLightsOff
+        on_exit :reverse do |event|
+          turn_reverse_lights_off
         end
 
-        on_transition do |car, event|
+        on_transition do |event|
           puts "shifted from #{event.from} to #{event.to}"
         end
       }
     end
   end
 end
+```
+
+### 6.1 ActiveRecord
+
+In order to integrate **FiniteMachine** with ActiveRecord use the `target` helper to reference the current class and call ActiveRecord methods inside the callbacks to persist the state.
+
+```ruby
+class Account < ActiveRecord::Base
+  validates :state, presence: true
+
+  def initialize
+    self.state = :unapproved
+  end
+
+  def manage
+    context = self
+    @machine ||= FiniteMachine.define do
+      target context
+
+      initial context.state
+
+      events {
+        event :enqueue, :unapproved => :pending
+        event :authorize, :pending => :access
+      }
+
+      callbacks {
+        on_enter_state do |event|
+          state = event.to
+          save
+        end
+      }
+    end
+  end
+end
 
+account = Account.new
+account.state   # => :unapproved
+account.manage.enqueue
+account.state   # => :pending
+account.manage.authorize
+account.state   # => :access
 ```
 
 ## 7 Tips
 
-Creating standalone **FiniteMachine** brings few benefits, one of them being easier testing. This is especially true if the state machine is extremely complex itself.
+Creating a standalone **FiniteMachine** brings few benefits, one of them being easier testing. This is especially true if the state machine is extremely complex itself. Ideally, you would test the machine in isolation and then integrate it with other objects or ORMs.
 
 ## Contributing