state_machine 0.7.6 → 0.8.0

data/lib/state_machine/machine_collection.rb

@@ -4,10 +4,12 @@ module StateMachine
     # Initializes the state of each machine in the given object.  Initial
     # values are only set if the machine's attribute doesn't already exist
     # (which must mean the defaults are being skipped)
-    def initialize_states(object)
+    def initialize_states(object, options = {})
       each_value do |machine|
-        value = machine.read(object, :state)
-        machine.write(object, :state, machine.initial_state(object).value) if value.nil? || value.respond_to?(:empty?) && value.empty?
+        if !options.include?(:dynamic) || machine.dynamic_initial_state? == options[:dynamic]
+          value = machine.read(object, :state)
+          machine.write(object, :state, machine.initial_state(object).value) if value.nil? || value.respond_to?(:empty?) && value.empty?
+        end
       end
     end
     
@@ -45,7 +47,7 @@ module StateMachine
     end
     
     # Runs one or more event attributes in parallel during the invocation of
-    # an action on the given object.  After transition callbacks can be
+    # an action on the given object.  after_transition callbacks can be
     # optionally disabled if the events are being only partially fired (for
     # example, when validating records in ORM integrations).
     # 
@@ -56,7 +58,7 @@ module StateMachine
     # 
     #   class Vehicle
     #     include DataMapper::Resource
-    #     property :id, Integer, :serial => true
+    #     property :id, Serial
     #     
     #     state_machine :initial => :parked do
     #       event :ignite do

data/lib/state_machine/state.rb

@@ -191,7 +191,7 @@ module StateMachine
         context_method.bind(object).call(*args, &block)
       else
         # Raise exception as if the method never existed on the original object
-        raise NoMethodError, "undefined method '#{method}' for #{object} in state #{machine.states.match(object).name.inspect}"
+        raise NoMethodError, "undefined method '#{method}' for #{object} with #{name || 'nil'} #{machine.name}"
       end
     end
     

data/lib/state_machine/transition.rb

@@ -16,8 +16,8 @@ module StateMachine
       # 1. Before callbacks
       # 2. Persist state
       # 3. Invoke action
-      # 4. After callbacks if configured
-      # 5. Rollback if action is unsuccessful
+      # 4. After callbacks (if configured)
+      # 5. Rollback (if action is unsuccessful)
       # 
       # Configuration options:
       # * <tt>:action</tt> - Whether to run the action configured for each transition
@@ -46,7 +46,7 @@ module StateMachine
                 # Block was given: use the result for each transition
                 result = yield
                 transitions.each {|transition| results[transition.action] = result}
-                result
+                !!result
               elsif options[:action] == false
                 # Skip the action
                 true
@@ -64,8 +64,9 @@ module StateMachine
             raise
           end
           
-          # Always run after callbacks regardless of whether the actions failed
-          transitions.each {|transition| transition.after(results[transition.action])} unless options[:after] == false
+          # Run after callbacks even when the actions failed. The :after option
+          # is ignored if the transitions were unsuccessful.
+          transitions.each {|transition| transition.after(results[transition.action], success)} unless options[:after] == false && success
           
           # Rollback the transitions if the transaction was unsuccessful
           transitions.each {|transition| transition.rollback} unless success
@@ -124,7 +125,7 @@ module StateMachine
     attr_reader :result
     
     # Creates a new, specific transition
-    def initialize(object, machine, event, from_name, to_name) #:nodoc:
+    def initialize(object, machine, event, from_name, to_name, read_state = true) #:nodoc:
       @object = object
       @machine = machine
       @args = []
@@ -136,7 +137,7 @@ module StateMachine
       
       # From state information
       from_state = machine.states.fetch(from_name)
-      @from = machine.read(object, :state)
+      @from = read_state ? machine.read(object, :state) : from_state.value
       @from_name = from_state.name
       @qualified_from_name = from_state.qualified_name
       
@@ -218,6 +219,9 @@ module StateMachine
     # callbacks that are configured to match the event, from state, and to
     # state will be invoked.
     # 
+    # Once the callbacks are run, they cannot be run again until this transition
+    # is reset.
+    # 
     # == Example
     # 
     #   class Vehicle
@@ -233,7 +237,11 @@ module StateMachine
       result = false
       
       catch(:halt) do
-        callback(:before)
+        unless @before_run
+          callback(:before)
+          @before_run = true
+        end
+        
         result = true
       end
       
@@ -241,7 +249,8 @@ module StateMachine
     end
     
     # Transitions the current value of the state to that specified by the
-    # transition.
+    # transition.  Once the state is persisted, it cannot be persisted again
+    # until this transition is reset.
     # 
     # == Example
     # 
@@ -259,16 +268,22 @@ module StateMachine
     #   
     #   vehicle.state   # => 'idling'
     def persist
-      machine.write(object, :state, to)
+      unless @persisted
+        machine.write(object, :state, to)
+        @persisted = true
+      end
     end
     
     # Runs the machine's +after+ callbacks for this transition.  Only
     # callbacks that are configured to match the event, from state, and to
     # state will be invoked.
     # 
-    # The result is used to indicate whether the associated machine action
+    # The result can be used to indicate whether the associated machine action
     # was executed successfully.
     # 
+    # Once the callbacks are run, they cannot be run again until this transition
+    # is reset.
+    # 
     # == Halting
     # 
     # If any callback throws a <tt>:halt</tt> exception, it will be caught
@@ -291,11 +306,14 @@ module StateMachine
     #   vehicle = Vehicle.new
     #   transition = StateMachine::Transition.new(vehicle, Vehicle.state_machine, :ignite, :parked, :idling)
     #   transition.after(true)
-    def after(result = nil)
+    def after(result = nil, success = true)
       @result = result
       
       catch(:halt) do
-        callback(:after)
+        unless @after_run
+          callback(:after, :success => success)
+          @after_run = true
+        end
       end
       
       true
@@ -326,9 +344,16 @@ module StateMachine
     #   transition.rollback
     #   vehicle.state             # => "parked"
     def rollback
+      reset
       machine.write(object, :state, from)
     end
     
+    # Resets any tracking of which callbacks have already been run and whether
+    # the state has already been persisted
+    def reset
+      @before_run = @persisted = @after_run = false
+    end
+    
     # Generates a nicely formatted description of this transitions's contents.
     # 
     # For example,
@@ -358,7 +383,9 @@ module StateMachine
       # 
       # Additional callback parameters can be specified.  By default, this
       # transition is also passed into callbacks.
-      def callback(type)
+      def callback(type, context = {})
+        context = self.context.merge(context)
+        
         machine.callbacks[type].each do |callback|
           callback.call(object, context, self)
         end

data/test/unit/assertions_test.rb

@@ -1,13 +1,13 @@
 require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
 
-class AssertionsTest < Test::Unit::TestCase
+class AssertionsBaseTest < Test::Unit::TestCase
   include StateMachine::Assertions
   
   def default_test
   end
 end
 
-class AssertValidKeysTest < AssertionsTest
+class AssertValidKeysTest < AssertionsBaseTest
   def test_should_not_raise_exception_if_key_is_valid
     assert_nothing_raised { assert_valid_keys({:name => 'foo', :value => 'bar'}, :name, :value, :force) }
   end
@@ -18,7 +18,7 @@ class AssertValidKeysTest < AssertionsTest
   end
 end
 
-class AssertExclusiveKeysTest < AssertionsTest
+class AssertExclusiveKeysTest < AssertionsBaseTest
   def test_should_not_raise_exception_if_no_keys_found
     assert_nothing_raised { assert_exclusive_keys({:on => :park}, :only, :except) }
   end

data/test/unit/eval_helpers_test.rb

@@ -1,8 +1,13 @@
 require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
 
-class EvalHelpersTest < Test::Unit::TestCase
+class EvalHelpersBaseTest < Test::Unit::TestCase
   include StateMachine::EvalHelpers
   
+  def default_test
+  end
+end
+
+class EvalHelpersTest < EvalHelpersBaseTest
   def setup
     @object = Object.new
   end
@@ -13,9 +18,7 @@ class EvalHelpersTest < Test::Unit::TestCase
   end
 end
 
-class EvalHelpersSymbolTest < Test::Unit::TestCase
-  include StateMachine::EvalHelpers
-  
+class EvalHelpersSymbolTest < EvalHelpersBaseTest
   def setup
     class << (@object = Object.new)
       def callback
@@ -29,9 +32,7 @@ class EvalHelpersSymbolTest < Test::Unit::TestCase
   end
 end
 
-class EvalHelpersSymbolWithArgumentsTest < Test::Unit::TestCase
-  include StateMachine::EvalHelpers
-  
+class EvalHelpersSymbolWithArgumentsTest < EvalHelpersBaseTest
   def setup
     class << (@object = Object.new)
       def callback(*args)
@@ -45,9 +46,7 @@ class EvalHelpersSymbolWithArgumentsTest < Test::Unit::TestCase
   end
 end
 
-class EvalHelpersSymbolTaintedMethodTest < Test::Unit::TestCase
-  include StateMachine::EvalHelpers
-  
+class EvalHelpersSymbolTaintedMethodTest < EvalHelpersBaseTest
   def setup
     class << (@object = Object.new)
       def callback
@@ -63,9 +62,7 @@ class EvalHelpersSymbolTaintedMethodTest < Test::Unit::TestCase
   end
 end
 
-class EvalHelpersStringTest < Test::Unit::TestCase
-  include StateMachine::EvalHelpers
-  
+class EvalHelpersStringTest < EvalHelpersBaseTest
   def setup
     @object = Object.new
   end
@@ -84,9 +81,7 @@ class EvalHelpersStringTest < Test::Unit::TestCase
   end
 end
 
-class EvalHelpersProcTest < Test::Unit::TestCase
-  include StateMachine::EvalHelpers
-  
+class EvalHelpersProcTest < EvalHelpersBaseTest
   def setup
     @object = Object.new
     @proc = lambda {|obj| obj}
@@ -97,9 +92,7 @@ class EvalHelpersProcTest < Test::Unit::TestCase
   end
 end
 
-class EvalHelpersProcWithoutArgumentsTest < Test::Unit::TestCase
-  include StateMachine::EvalHelpers
-  
+class EvalHelpersProcWithoutArgumentsTest < EvalHelpersBaseTest
   def setup
     @object = Object.new
     @proc = lambda {|*args| args}
@@ -115,9 +108,7 @@ class EvalHelpersProcWithoutArgumentsTest < Test::Unit::TestCase
   end
 end
 
-class EvalHelpersProcWithArgumentsTest < Test::Unit::TestCase
-  include StateMachine::EvalHelpers
-  
+class EvalHelpersProcWithArgumentsTest < EvalHelpersBaseTest
   def setup
     @object = Object.new
     @proc = lambda {|*args| args}

data/test/unit/event_collection_test.rb

@@ -81,6 +81,12 @@ class EventCollectionWithEventsWithTransitionsTest < Test::Unit::TestCase
     object.state = 'idling'
     assert_equal [], @events.transitions_for(object)
   end
+  
+  def test_should_filter_valid_transitions_for_an_object_if_requirements_specified
+    object = @klass.new
+    assert_equal [{:object => object, :attribute => :state, :event => :ignite, :from => 'stalled', :to => 'idling'}], @events.transitions_for(object, :from => :stalled).map {|transition| transition.attributes}
+    assert_equal [], @events.transitions_for(object, :from => :idling).map {|transition| transition.attributes}
+  end
 end
 
 class EventCollectionWithMultipleEventsTest < Test::Unit::TestCase
@@ -166,6 +172,13 @@ class EventCollectionAttributeWithMachineActionTest < Test::Unit::TestCase
     
     assert_instance_of StateMachine::Transition, @events.attribute_transition_for(@object)
   end
+  
+  def test_should_have_valid_transition_if_already_defined_in_transition_cache
+    @object.state_event = nil
+    @object.send(:state_event_transition=, transition = @ignite.transition_for(@object))
+    
+    assert_equal transition, @events.attribute_transition_for(@object)
+  end
 end
 
 class EventCollectionAttributeWithNamespacedMachineTest < Test::Unit::TestCase
@@ -249,6 +262,17 @@ class EventCollectionWithValidationsTest < Test::Unit::TestCase
     assert_equal ['cannot transition when idling'], @object.errors
   end
   
+  def test_should_invalidate_with_friendly_name_if_invalid_event_specified
+    # Add a valid nil state
+    @machine.state nil
+    
+    @object.state = nil
+    @object.state_event = 'ignite'
+    @events.attribute_transition_for(@object, true)
+    
+    assert_equal ['cannot transition when nil'], @object.errors
+  end
+  
   def test_should_not_invalidate_event_can_be_fired
     @ignite.transition :parked => :idling
     @object.state_event = 'ignite'

data/test/unit/event_test.rb

@@ -201,6 +201,12 @@ class EventTransitionsTest < Test::Unit::TestCase
     assert_equal 'Invalid key(s): on', exception.message
   end
   
+  def test_should_automatically_set_on_option
+    guard = @event.transition(:to => :idling)
+    assert_instance_of StateMachine::WhitelistMatcher, guard.event_requirement
+    assert_equal [:ignite], guard.event_requirement.values
+  end
+  
   def test_should_not_allow_except_to_option
     exception = assert_raise(ArgumentError) {@event.transition(:except_to => :parked)}
     assert_equal 'Invalid key(s): except_to', exception.message
@@ -542,6 +548,7 @@ class EventWithMultipleTransitionsTest < Test::Unit::TestCase
     @event = StateMachine::Event.new(@machine, :ignite)
     @event.transition(:idling => :idling)
     @event.transition(:parked => :idling) # This one should get used
+    @event.transition(:parked => :parked)
     
     @object = @klass.new
     @object.state = 'parked'
@@ -559,6 +566,32 @@ class EventWithMultipleTransitionsTest < Test::Unit::TestCase
     assert_equal :ignite, transition.event
   end
   
+  def test_should_allow_specific_transition_selection_using_from
+    transition = @event.transition_for(@object, :from => :idling)
+    
+    assert_not_nil transition
+    assert_equal 'idling', transition.from
+    assert_equal 'idling', transition.to
+    assert_equal :ignite, transition.event
+  end
+  
+  def test_should_allow_specific_transition_selection_using_to
+    transition = @event.transition_for(@object, :from => :parked, :to => :parked)
+    
+    assert_not_nil transition
+    assert_equal 'parked', transition.from
+    assert_equal 'parked', transition.to
+    assert_equal :ignite, transition.event
+  end
+  
+  def test_should_allow_specific_transition_selection_using_on
+    transition = @event.transition_for(@object, :on => :park)
+    assert_nil transition
+    
+    transition = @event.transition_for(@object, :on => :ignite)
+    assert_not_nil transition
+  end
+  
   def test_should_fire
     assert @event.fire(@object)
   end
@@ -569,6 +602,67 @@ class EventWithMultipleTransitionsTest < Test::Unit::TestCase
   end
 end
 
+class EventWithMachineActionTest < Test::Unit::TestCase
+  def setup
+    @klass = Class.new do
+      attr_reader :saved
+      
+      def save
+        @saved = true
+      end
+    end
+    
+    @machine = StateMachine::Machine.new(@klass, :action => :save)
+    @machine.state :parked, :idling
+    
+    @machine.events << @event = StateMachine::Event.new(@machine, :ignite)
+    @event.transition(:parked => :idling)
+    
+    @object = @klass.new
+    @object.state = 'parked'
+  end
+  
+  def test_should_run_action_on_fire
+    @event.fire(@object)
+    assert @object.saved
+  end
+  
+  def test_should_not_run_action_if_configured_to_skip
+    @event.fire(@object, false)
+    assert !@object.saved
+  end
+end
+
+class EventWithInvalidCurrentStateTest < Test::Unit::TestCase
+  def setup
+    @klass = Class.new
+    @machine = StateMachine::Machine.new(@klass)
+    @machine.state :parked, :idling
+    @machine.event :ignite
+    
+    @event = StateMachine::Event.new(@machine, :ignite)
+    @event.transition(:parked => :idling)
+    
+    @object = @klass.new
+    @object.state = 'invalid'
+  end
+  
+  def test_should_raise_exception_when_checking_availability
+    exception = assert_raise(ArgumentError) { @event.can_fire?(@object) }
+    assert_equal '"invalid" is not a known state value', exception.message
+  end
+  
+  def test_should_raise_exception_when_finding_transition
+    exception = assert_raise(ArgumentError) { @event.transition_for(@object) }
+    assert_equal '"invalid" is not a known state value', exception.message
+  end
+  
+  def test_should_raise_exception_when_firing
+    exception = assert_raise(ArgumentError) { @event.fire(@object) }
+    assert_equal '"invalid" is not a known state value', exception.message
+  end
+end
+
 begin
   # Load library
   require 'rubygems'