finite_machine 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 88cd408cda756703b6665126580605500ad9273f
-  data.tar.gz: 93a8062b97cd5a0fed0367c091cbb06e45242b2c
+  metadata.gz: 29fd461f4bd19a780bac89bc363026b214db867f
+  data.tar.gz: 70e229f5f28433618f2408d35136aad7a0a1bb8e
 SHA512:
-  metadata.gz: fb7c16c1ec7e7238cfb5d2b37ab554741733b4957af9855878a0b35d7ef4e04f334542c8889d5829ed9d002ac9ef847c20f093590af44db7310ced42b33e53b1
-  data.tar.gz: 2963f9d98146612ae2a6d9c3ba5a690bb06d1f32f8fd6e1da1b817f8fdcb0923ec371f38ae48ce4e92ee553c65214f3a1dc34d095d523431a302b32b377008b9
+  metadata.gz: 00f1f997a94d5f5cb8571921d088a5bc4245001a45463f3b0fc57538094623d94e97c52df76780e957f16279c1bd43d8d0c004595a55a60005f70993fe4873d2
+  data.tar.gz: c62a75b03d74891a0f83bc91ef3bac4e22090f29b0adb9edc398f0290f39dfbcde36513d994373698be17554aa4618916bcd15018275d2afc197f93b0e6944b7

data/.rspec

@@ -1,2 +1,4 @@
 --color
 --format progress
+--order random
+--warnings

data/.ruby-gemset

@@ -0,0 +1 @@
+finite_machine

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+0.3.0 (March 30, 2014)
+
+* Move development dependencies to Gemfile
+* Increase test coverage to 95%
+* Fix bug with event methods dynamic redefinition
+* Change attr_threadsafe to accept default values
+* Fix observer respond_to
+* Add ability to specify callbacks on machine instance
+* Add once_on type of callback
+* Add off method for removing callbacks
+* Add async method to state_machine for asynchronous events firing
+* Fix Callable to correctly forward arguments
+* Add state helpers fsm.green? to allow easily check current state
+
 0.2.0 (March 01, 2014)
 
 * Ensure correct transition object state

data/Gemfile

@@ -1,4 +1,15 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in finite_machine.gemspec
 gemspec
+
+group :development do
+  gem 'rake',  '~> 10.1.0'
+  gem 'rspec', '~> 2.14.1'
+  gem 'yard',  '~> 0.8.7'
+end
+
+group :metrics do
+  gem 'coveralls', '~> 0.7.0'
+  gem 'simplecov', '~> 0.8.2'
+  gem 'yardstick', '~> 0.9.9'
+end

data/README.md

@@ -2,12 +2,16 @@
 [![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]
+[![Coverage Status](https://coveralls.io/repos/peter-murach/finite_machine/badge.png)][coverage]
+[![Inline docs](http://inch-pages.github.io/github/peter-murach/finite_machine.png)][inchpages]
 
 [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
+[coverage]: https://coveralls.io/r/peter-murach/finite_machine
+[inchpages]: http://inch-pages.github.io/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.
+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. The machine is event driven with a focus on passing synchronous and asynchronous messages to trigger state transitions.
 
 ## Features
 
@@ -18,6 +22,7 @@ A minimal finite state machine with a straightforward and intuitive syntax. You
 * ability to check reachable states
 * ability to check for terminal state
 * conditional transitions
+* sync and async transitions
 * sync and async callbacks (TODO - only sync)
 * nested/composable states (TODO)
 
@@ -176,6 +181,13 @@ fm.is?(:red)    # => true
 fm.is?(:yellow) # => false
 ```
 
+Moreover, you can use helper methods to check for current state using the state name itself like so
+
+```ruby
+fm.red?     # => true
+fm.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 **FiniteMachine** can fire a given event, returning true, otherwise, it will return false. `cannot?` is simply the inverse of `can?`.
@@ -246,9 +258,9 @@ method on the **FiniteMachine** instance. As a second parameter `event` accepts
 in the form of `:from` and `:to` hash keys or by using the state names themselves as key value pairs.
 
 ```ruby
-  event :start, from: :neutral, to: :first
-  or
-  event :start, :neutral => :first
+event :start, from: :neutral, to: :first
+or
+event :start, :neutral => :first
 ```
 
 Once specified, the **FiniteMachine** will create custom methods for transitioning between each state.
@@ -263,18 +275,35 @@ The following methods trigger transitions for the example state machine.
 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
+fm.ready
+fm.current       # => :yellow
 ```
 
 Furthermore, you can pass additional parameters with the method call that will be available in the triggered callback.
 
 ```ruby
-  fm.go('Piotr!')
-  fm.current       # => :green
+fm.go('Piotr!')
+fm.current       # => :green
 ```
 
-### 2.2 single event with multiple from states
+### 2.2 Asynchronous transitions
+
+By default the transitions will be fired synchronosuly.
+
+```ruby
+fm.ready
+or
+fm.sync.ready
+fm.current     # => :yellow
+```
+
+In order to fire the event transition asynchronously use the `async` scope like so
+
+```ruby
+fm.async.ready  # => executes in separate Thread
+```
+
+### 2.3 single event with multiple from states
 
 If an event transitions from multiple states to the same state then all the states can be grouped into an array.
 Altenatively, you can create separte events under the same name for each transition that needs combining.
@@ -302,49 +331,49 @@ Each event takes an optional `:if` and `:unless` options which act as a predicat
 You can associate the `:if` and `:unless` options with a Proc object that will get called right before transition happens. Proc object gives you ability to write inline condition instead of separate method.
 
 ```ruby
-  fm = FiniteMachine.define do
-    initial :green
+fm = FiniteMachine.define do
+  initial :green
 
-    events {
-      event :slow, :green => :yellow, if: -> { return false }
-    }
-  end
-  fm.slow    # doesn't transition to :yellow state
-  fm.current # => :green
+  events {
+    event :slow, :green => :yellow, if: -> { return false }
+  }
+end
+fm.slow    # doesn't transition to :yellow state
+fm.current # => :green
 ```
 
 You can also execute methods on an associated object by passing it as an argument to `target` helper.
 
 ```ruby
-  class Car
-    def turn_engine_on
-      @engine_on = true
-    end
+class Car
+  def turn_engine_on
+    @engine_on = true
+  end
 
-    def turn_engine_off
-      @engine_on = false
-    end
+  def turn_engine_off
+    @engine_on = false
+  end
 
-    def engine_on?
-      @engine_on
-    end
+  def engine_on?
+    @engine_on
   end
+end
 
-  car = Car.new
-  car.turn_engine_on
+car = Car.new
+car.turn_engine_on
 
-  fm = FiniteMachine.define do
-    initial :neutral
+fm = FiniteMachine.define do
+  initial :neutral
 
-    target car
+  target car
 
-    events {
-      event :start, :neutral => :one, if: "engine_on?"
-    }
-  end
+  events {
+    event :start, :neutral => :one, if: "engine_on?"
+  }
+end
 
-  fm.start
-  fm.current # => :one
+fm.start
+fm.current # => :one
 ```
 
 ### 3.2 Using a Symbol
@@ -352,15 +381,15 @@ You can also execute methods on an associated object by passing it as an argumen
 You can also use a symbol corresponding to the name of a method that will get called right before transition happens.
 
 ```ruby
-  fsm = FiniteMachine.define do
-    initial :neutral
+fsm = FiniteMachine.define do
+  initial :neutral
 
-    target car
+  target car
 
-    events {
-      event :start, :neutral => :one, if: :engine_on?
-    }
-  end
+  events {
+    event :start, :neutral => :one, if: :engine_on?
+  }
+end
 ```
 
 ### 3.3 Using a String
@@ -368,15 +397,15 @@ You can also use a symbol corresponding to the name of a method that will get ca
 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.
 
 ```ruby
-  fsm = FiniteMachine.define do
-    initial :neutral
+fsm = FiniteMachine.define do
+  initial :neutral
 
-    target car
+  target car
 
-    events {
-      event :start, :neutral => :one, if: "engine_on?"
-    }
-  end
+  events {
+    event :start, :neutral => :one, if: "engine_on?"
+  }
+end
 ```
 
 ### 3.4 Combining transition conditions
@@ -384,16 +413,16 @@ Finally, it's possible to use string that will be evaluated using `eval` and nee
 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
-    initial :green
+fsm = FiniteMachine.define do
+  initial :green
 
-    events {
-      event :slow, :green => :yellow,
-        if: [ -> { return true }, -> { return true} ],
-        unless: -> { return true }
-      event :stop, :yellow => :red
-    }
-  end
+  events {
+    event :slow, :green => :yellow,
+      if: [ -> { return true }, -> { return true} ],
+      unless: -> { return true }
+    event :stop, :yellow => :red
+  }
+end
 ```
 
 The transition only runs when all the `:if` conditions and none of the `unless` conditions are evaluated to `true`.
@@ -458,13 +487,21 @@ This method is executed after a given event or state change happens. If you prov
 
 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
+### 4.4 once_on
+
+**FiniteMachine** allows you to listen on initial state change or when the event is fired first time by using the following 3 types of callbacks:
+
+* `once_on_enter`
+* `once_on_transition`
+* `once_on_exit`
+
+### 4.5 Parameters
 
 All callbacks get the `TransitionEvent` object with the following attributes.
 
-* name    # the event name
-* from    # the state transitioning from
-* to      # the state transitioning to
+* `name    # the event name`
+* `from    # the state transitioning from`
+* `to      # the state transitioning to`
 
 followed by the rest of arguments that were passed to the event method.
 
@@ -486,7 +523,7 @@ end
 fm.ready(3)   #  => 'lights switching from red to yellow in 3 seconds'
 ```
 
-### 4.5 Same kind of callbacks
+### 4.6 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.
 
@@ -506,7 +543,7 @@ end
 fm.slow # => will invoke both callbacks
 ```
 
-### 4.6 Fluid callbacks
+### 4.7 Fluid callbacks
 
 Callbacks can also be specified as full method calls.
 
@@ -528,7 +565,7 @@ fm = FiniteMachine.define do
 end
 ```
 
-### 4.7 Executing methods inside callbacks
+### 4.8 Executing methods inside callbacks
 
 In order to execute method from another object use `target` helper.
 
@@ -586,13 +623,33 @@ fm.back   # => Go Piotr!
 
 For more complex example see [Integration](#6-integration) section.
 
+### 4.9 Defining callbacks
+
+When defining callbacks you are not limited to the `callbacks` helper. After **FiniteMachine** instance is created you can register callbacks the same way as before by calling `on` and supplying the type of notification and state/event you are interested in.
+
+```ruby
+fm = FiniteMachine.define do
+  initial :red
+
+  events {
+    event :ready, :red    => :yellow
+    event :go,    :yellow => :green
+    event :stop,  :green  => :red
+  }
+end
+
+fm.on_enter_yellow do |event|
+  ...
+end
+```
+
 ## 5 Errors
 
 By default, the **FiniteMachine** will throw an exception whenever the machine is in invalid state or fails to transition.
 
-* FiniteMachine::TransitionError
-* FiniteMachine::InvalidStateError
-* FiniteMachine::InvalidCallbackError
+* `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.
 
@@ -664,7 +721,7 @@ class Car
     @gears ||= FiniteMachine.define do
       initial :neutral
 
-      target: context
+      target context
 
       events {
         event :start, :neutral => :one
@@ -705,7 +762,7 @@ class Account < ActiveRecord::Base
 
   def manage
     context = self
-    @machine ||= FiniteMachine.define do
+    @manage ||= FiniteMachine.define do
       target context
 
       initial context.state

data/Rakefile

@@ -1,41 +1,8 @@
-require "bundler/gem_tasks"
-
-begin
-  require 'rspec/core/rake_task'
-
-  desc 'Run all specs'
-  RSpec::Core::RakeTask.new(:spec) do |task|
-    task.pattern = 'spec/{unit,integration}{,/*/**}/*_spec.rb'
-  end
+# encoding: utf-8
 
-  namespace :spec do
-    desc 'Run unit specs'
-    RSpec::Core::RakeTask.new(:unit) do |task|
-      task.pattern = 'spec/unit{,/*/**}/*_spec.rb'
-    end
-
-    desc 'Run integration specs'
-    RSpec::Core::RakeTask.new(:integration) do |task|
-      task.pattern = 'spec/integration{,/*/**}/*_spec.rb'
-    end
-  end
+require "bundler/gem_tasks"
 
-rescue LoadError
-  %w[spec spec:unit spec:integration].each do |name|
-    task name do
-      $stderr.puts "In order to run #{name}, do `gem install rspec`"
-    end
-  end
-end
+FileList['tasks/**/*.rake'].each(&method(:import))
 
 desc 'Run all specs'
 task ci: %w[ spec ]
-
-desc 'Load gem inside irb console'
-task :console do
-  require 'irb'
-  require 'irb/completion'
-  require File.join(__FILE__, '../lib/finite_machine')
-  ARGV.clear
-  IRB.start
-end