transitions 0.0.9 → 0.0.10

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    transitions (0.0.9)
+    transitions (0.0.10)
 
 GEM
   remote: http://rubygems.org/

data/README.rdoc

@@ -1,41 +1,88 @@
-= transitions
+= What is transitions?
 
-The gem is based on Rick Olson's code of ActiveModel::StateMachine,
-axed from ActiveModel in {this
-commit}[http://github.com/rails/rails/commit/db49c706b62e7ea2ab93f05399dbfddf5087ee0c].
+transitions is a ruby state machine implementation based on Rick Olson’s
+ActiveModel::StateMachine. It was extracted from ActiveModel and turned
+into a gem when it got the axe in commit {db49c706b}[http://github.com/rails/rails/commit/db49c706b62e7ea2ab93f05399dbfddf5087ee0c].
 
-== Installation
+I really encourage you to try {state_machine}[https://github.com/pluginaweek/state_machine] before using this gem. Currently I have no time to maintain the gem, if you want to add some new features - contact with me.
 
-If you're using Rails + ActiveRecord + Bundler
+== Quick Example
 
-  # in your Gemfile
-  gem "transitions", :require => ["transitions", "active_record/transitions"]
+ require 'transitions'
+ 
+ class Product
+   include Transitions
+ 
+   state_machine do
+     state :available # first one is initial state
+     state :out_of_stock, :exit => :exit_out_of_stock
+     state :discontinued, :enter => lambda { |product| product.cancel_orders }
+   
+     event :discontinued do
+       transitions :to => :discontinued, :from => [:available, :out_of_stock], :on_transition => :do_discontinue
+     end
+     event :out_of_stock do
+       transitions :to => :out_of_stock, :from => [:available, :discontinued]
+     end
+     event :available do
+       transitions :to => :available, :from => [:out_of_stock], :guard => lambda { |product| product.in_stock > 0 }
+     end
+   end
+ end
 
-  # in your AR models that will use the state machine
-  include ::Transitions
-  include ActiveRecord::Transitions
+== Using on_transition
 
-  state_machine do
-    state :available # first one is initial state
-    state :out_of_stock
-    state :discontinue
+Each event definition takes an optional "on_transition" argument, which allows you to execute methods on transition.
+You can pass in a Symbol, a String, a Proc or an Array containing method names as Symbol or String like this:
 
-    event :discontinue do
-      transitions :to => :discontinue, :from => [:available, :out_of_stock], :on_transition => :do_discontinue
-    end
-    event :out_of_stock do
-      transitions :to => :out_of_stock, :from => [:available, :discontinue]
-    end
-    event :available do
-      transitions :to => :available, :from => [:out_of_stock], :on_transition => :send_alerts
-    end
+  event :discontinue do
+    transitions :to => :discontinued, :from => [:available, :out_of_stock], :on_transition => [:do_discontinue, :notify_clerk]
   end
 
-== Usage
+== Using with Rails
 
-Krzysiek Heród (aka {Netizer}[http://github.com/netizer]) wrote a nice {blog
-post}[http://dev.netizer.pl/transitions-state-machine-for-rails-3.html]
-about using Transitions in ActiveRecord.
+This goes into your Gemfile:
+
+ gem "transitions", :require => ["transitions", "active_record/transitions"]
+
+… and this into your AR model:
+
+ include ActiveRecord::Transitions
+
+=== A note about persistence
+The property used to persist the models’ state is named <tt>state</tt> (really!),
+which should be a string column wide enough to fit your longest state name.
+It should also be mentioned that <tt>#save!</tt> is called after every successful event.
+
+== Event execution flow
+
+On an event, with our quick example product going from <tt>:available</tt> to
+<tt>:discontinued</tt> it looks like this:
+
+1. <tt>baby_ninja.discontinue!(:reason => :pirates)</tt>
+2. call <tt>:exit</tt> handler of <tt>:available</tt> state
+3. call <tt>:guard</tt> of <tt>:available to :discontinue</tt> transition within <tt>#discontinue</tt> event
+4. call <tt>#event_failed(:event)</tt> and abort unless <tt>3.</tt> returned <tt>true</tt>
+5. call <tt>:on_transition(:reason => :pirates)</tt> of <tt>:available to :discontinue</tt> transition within <tt>#discontinue</tt> event
+6. call <tt>:enter</tt> handler of <tt>:discontinue</tt>
+7. call <tt>#event_fired(:available, :discontinue)</tt>
+8. call <tt>#write_state(machine, :discontinue)</tt>
+9. call <tt>#write_state_without_persistence(machine, :discontinue)</tt>
+10. call <tt>baby_ninja#:success</tt> handler method of <tt>#discontinue</tt> event
+
+=== A note about events
+
+When you declare an event <tt>discontinue</tt>, two methods are declared for
+you: <tt>discontinue</tt> and <tt>discontinue!</tt>. Both events will call
+<tt>write_state_without_persistence</tt> on successful transition, but only the
+bang(!)-version will call <tt>write_state</tt>.
+
+== Documentation, Guides & Examples
+
+- {Online API Documentation}[http://rdoc.info/github/qoobaa/transitions/master/Transitions]
+- Krzysiek Heród (aka {Netizer}[http://github.com/netizer]) wrote a nice
+  {blog post}[http://dev.netizer.pl/transitions-state-machine-for-rails-3.html]
+  about using Transitions in ActiveRecord.
 
 == Copyright
 

data/lib/active_record/transitions.rb

@@ -26,24 +26,39 @@ module ActiveRecord
 
     included do
       include ::Transitions
-      before_validation :set_initial_state
+      after_initialize :set_initial_state
       validates_presence_of :state
       validate :state_inclusion
     end
 
+    def reload
+      super.tap do
+        self.class.state_machines.values.each do |sm|
+          remove_instance_variable(sm.current_state_variable) if instance_variable_defined?(sm.current_state_variable)
+        end
+      end
+    end
+
     protected
 
     def write_state(state_machine, state)
+      ivar = state_machine.current_state_variable
+      prev_state = current_state(state_machine.name)
+      instance_variable_set(ivar, state)
       self.state = state.to_s
       save!
+    rescue ActiveRecord::RecordInvalid
+      self.state = prev_state.to_s
+      instance_variable_set(ivar, prev_state)
+      raise
     end
 
     def read_state(state_machine)
-      self.state.to_sym
+      self.state && self.state.to_sym
     end
 
     def set_initial_state
-      self.state ||= self.class.state_machine.initial_state.to_s
+      self.state ||= self.class.state_machine.initial_state.to_s if self.has_attribute?(:state)
     end
 
     def state_inclusion

data/lib/transitions.rb

@@ -27,7 +27,7 @@ require "transitions/state_transition"
 require "transitions/version"
 
 module Transitions
-  class InvalidTransition < Exception
+  class InvalidTransition < StandardError
 
   end
 

data/lib/transitions/state_transition.rb

@@ -46,6 +46,15 @@ module Transitions
         obj.send(@on_transition, *args)
       when Proc
         @on_transition.call(obj, *args)
+      when Array
+        @on_transition.each do |callback|
+          # Yes, we're passing always the same parameters for each callback in here.
+          # We should probably drop args altogether in case we get an array.
+          obj.send(callback, *args)
+        end
+      else
+        # TODO We probably should check for this in the constructor and not that late.
+        raise ArgumentError, "You can only pass a Symbol, a String, a Proc or an Array to 'on_transition' - got #{@on_transition.class}." unless @on_transition.nil?
       end
     end
 

data/lib/transitions/version.rb

@@ -1,3 +1,3 @@
 module Transitions
-  VERSION = "0.0.9"
+  VERSION = "0.0.10"
 end

data/test/test_active_record.rb

@@ -3,7 +3,10 @@ require 'active_support/core_ext/module/aliasing'
 
 class CreateTrafficLights < ActiveRecord::Migration
   def self.up
-    create_table(:traffic_lights) { |t| t.string :state }
+    create_table(:traffic_lights) do |t|
+      t.string :state
+      t.string :name
+    end
   end
 end
 
@@ -43,6 +46,10 @@ class ValidatingTrafficLight < TrafficLight
   validate {|t| errors.add(:base, 'This TrafficLight will never validate after creation') unless t.new_record? }
 end
 
+class ConditionalValidatingTrafficLight < TrafficLight
+  validates(:name, :presence => true, :if => :red?)
+end
+
 class TestActiveRecord < Test::Unit::TestCase
   def setup
     ActiveRecord::Base.establish_connection(:adapter  => "sqlite3", :database => ":memory:")
@@ -52,6 +59,11 @@ class TestActiveRecord < Test::Unit::TestCase
     @light = TrafficLight.create!
   end
 
+  test "new record has the initial state set" do
+    @light = TrafficLight.new
+    assert_equal "off", @light.state
+  end
+
   test "states initial state" do
     assert @light.off?
     assert_equal :off, @light.current_state
@@ -104,9 +116,37 @@ class TestActiveRecord < Test::Unit::TestCase
   end
 
   test "transition raises exception when model validation fails" do
-    validating_light = ValidatingTrafficLight.create!
+    validating_light = ValidatingTrafficLight.create!(:name => 'Foobar')
     assert_raise(ActiveRecord::RecordInvalid) do
       validating_light.reset!
     end
   end
+
+  test "state query method used in a validation condition" do
+    validating_light = ConditionalValidatingTrafficLight.create!
+    assert_raise(ActiveRecord::RecordInvalid) do
+      validating_light.reset!
+    end
+    assert(validating_light.off?)
+  end
+
+  test "reloading model resets current state" do
+    @light.reset
+    assert @light.red?
+    @light.update_attribute(:state, 'green')
+    assert @light.reload.green?, "reloaded state should come from database, not instance variable"
+  end
+
+end
+
+class TestNewActiveRecord < TestActiveRecord
+
+  def setup
+    @light = TrafficLight.new
+  end
+
+  test "new active records defaults current state to the initial state" do
+    assert_equal :off, @light.current_state
+  end
+
 end

data/test/test_state_transition_callbacks.rb

@@ -0,0 +1,43 @@
+require 'helper'
+
+class Car
+  include Transitions
+
+  state_machine do
+    state :parked
+    state :running
+    state :driving
+
+    event :turn_key do
+      transitions :from => :parked, :to => :running, :on_transition => :start_engine
+    end
+
+    event :start_driving do
+      transitions :from => :parked, :to => :driving, :on_transition => [:start_engine, :loosen_handbrake, :push_gas_pedal]
+    end
+  end
+
+  %w!start_engine loosen_handbrake push_gas_pedal!.each do |m|
+    define_method(m){}
+  end
+end
+
+class TestStateTransitionCallbacks < Test::Unit::TestCase
+  def setup
+    @car = Car.new
+  end
+
+  test "should execute callback defined via 'on_transition'" do
+    @car.expects(:start_engine)
+    @car.turn_key!
+  end
+
+  test "should execute multiple callbacks defined via 'on_transition' in the same order they were defined" do
+    on_transition_sequence = sequence('on_transition_sequence')
+
+    @car.expects(:start_engine).in_sequence(on_transition_sequence)
+    @car.expects(:loosen_handbrake).in_sequence(on_transition_sequence)
+    @car.expects(:push_gas_pedal).in_sequence(on_transition_sequence)
+    @car.start_driving!
+  end
+end

metadata

@@ -1,12 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: transitions
 version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 0
-  - 9
-  version: 0.0.9
+  prerelease: 
+  version: 0.0.10
 platform: ruby
 authors: 
 - "Jakub Ku\xC5\xBAma"
@@ -14,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-09-21 00:00:00 +02:00
+date: 2011-08-11 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -24,8 +20,6 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        segments: 
-        - 1
         version: "1"
   type: :development
   prerelease: false
@@ -37,8 +31,6 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        segments: 
-        - 2
         version: "2"
   type: :development
   prerelease: false
@@ -50,8 +42,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        segments: 
-        - 0
         version: "0"
   type: :development
   prerelease: false
@@ -63,8 +53,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        segments: 
-        - 0
         version: "0"
   type: :development
   prerelease: false
@@ -76,8 +64,6 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        segments: 
-        - 3
         version: "3"
   type: :development
   prerelease: false
@@ -112,6 +98,7 @@ files:
 - test/test_machine.rb
 - test/test_state.rb
 - test/test_state_transition.rb
+- test/test_state_transition_callbacks.rb
 - test/test_state_transition_guard_check.rb
 - transitions.gemspec
 has_rdoc: true
@@ -128,7 +115,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -568409294339076591
+      hash: 347067155
       segments: 
       - 0
       version: "0"
@@ -137,15 +124,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      segments: 
-      - 1
-      - 3
-      - 6
       version: 1.3.6
 requirements: []
 
 rubyforge_project: transitions
-rubygems_version: 1.3.7
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: State machine extracted from ActiveModel