Add next_#{event}_transition for getting the next transition that wou…

…ld be performed if the event were fired

CHANGELOG.rdoc

@@ -1,5 +1,6 @@
 == master
 
+* Add next_#{event}_transition for getting the next transition that would be performed if the event were invoked
 * Add the ability to override the pluralized name of an attribute for creating scopes
 * Add the ability to halt callback chains by: throw :halt
 * Add support for dynamic to states in transitions (e.g. :to => lambda {Time.now})

lib/state_machine/event.rb

@@ -131,6 +131,11 @@ def add_actions
               self.class.state_machines[attribute].events[name].can_fire?(self)
             end
 
+            # Gets the next transition that would be performed if the event were to be fired now
+            define_method("next_#{name}_transition") do
+              self.class.state_machines[attribute].events[name].next_transition(self)
+            end
+
             # Fires the event
             define_method(name) do |*args|
               self.class.state_machines[attribute].events[name].fire(self, *args)

lib/state_machine/machine.rb

@@ -321,9 +321,10 @@ def states
       # 
       # The following instance methods are generated when a new event is defined
       # (the "park" event is used as an example):
+      # * <tt>can_park?</tt> - Checks whether the "park" event can be fired given the current state of the object.
+      # * <tt>next_park_transition</tt> -  Gets the next transition that would be performed if the "park" event were to be fired now on the object or nil if no transitions can be performed.
       # * <tt>park(run_action = true)</tt> - Fires the "park" event, transitioning from the current state to the next valid state.
       # * <tt>park!(run_action = true)</tt> - Fires the "park" event, transitioning from the current state to the next valid state.  If the transition fails, then a PluginAWeek::StateMachine::InvalidTransition error will be raised.
-      # * <tt>can_park?</tt> - Checks whether the "park" event can be fired given the current state of the object.
       # 
       # == Defining transitions
       # 

test/functional/state_machine_test.rb

@@ -184,6 +184,10 @@ def test_should_not_be_able_to_park
     assert !@vehicle.can_park?
   end
 
+  def test_should_not_have_a_next_transition_for_park
+    assert_nil @vehicle.next_park_transition
+  end
+
   def test_should_not_allow_park
     assert !@vehicle.park
   end
@@ -192,6 +196,16 @@ def test_should_be_able_to_ignite
     assert @vehicle.can_ignite?
   end
 
+  def test_should_have_a_next_transition_for_ignite
+    transition = @vehicle.next_ignite_transition
+    assert_not_nil transition
+    assert_equal 'parked', transition.from
+    assert_equal 'idling', transition.to
+    assert_equal 'ignite', transition.event
+    assert_equal 'state', transition.attribute
+    assert_equal @vehicle, transition.object
+  end
+
   def test_should_allow_ignite
     assert @vehicle.ignite
     assert_equal 'idling', @vehicle.state

test/unit/event_test.rb

@@ -48,6 +48,10 @@ def test_should_define_an_event_predicate_on_the_owner_class
     assert @object.respond_to?(:can_turn_on?)
   end
 
+  def test_should_define_an_event_transition_accessor_on_the_owner_class
+    assert @object.respond_to?(:next_turn_on_transition)
+  end
+
   def test_should_define_an_event_action_on_the_owner_class
     assert @object.respond_to?(:turn_on)
   end