state_machine 0.2.0 → 0.2.1

data/CHANGELOG.rdoc

@@ -1,5 +1,15 @@
 == master
 
+== 0.2.1 / 2008-07-05
+
+* Add more descriptive exceptions
+* Assume the default state attribute is "state" if one is not provided
+* Add :except_from option for transitions if you want to blacklist states
+* Add PluginAWeek::StateMachine::Machine#states
+* Add PluginAWeek::StateMachine::Event#transitions
+* Allow creating transitions with no from state (effectively allowing the transition for *any* from state)
+* Reduce the number of objects created for each transition
+
 == 0.2.0 / 2008-06-29
 
 * Add a non-bang version of events (e.g. park) that will return a boolean value for success

data/README.rdoc

@@ -1,6 +1,7 @@
 == state_machine
 
-+state_machine+ adds support for creating state machines for attributes within a model.
++state_machine+ adds support for creating state machines for attributes within
+a model.
 
 == Resources
 
@@ -28,15 +29,21 @@ and deciding how to behave based on the values in those columns.  This can becom
 cumbersome and difficult to maintain when the complexity of your models starts to
 increase.
 
-+state_machine+ simplifies this design by introducing the various parts of a state
-machine, including states, events, and transitions.  However, its api is designed
-to be similar to ActiveRecord in terms of validations and callbacks, making it
-so simple you don't even need to know what a state machine is :)
++state_machine+ simplifies this design by introducing the various parts of a real
+state machine, including states, events, and transitions.  However, the api is
+designed to be similar to ActiveRecord in terms of validations and callbacks,
+making it so simple you don't even need to know what a state machine is :)
 
 == Usage
 
 === Example
 
+Below is an example of many of the features offered by this plugin, including
+* Initial states
+* State callbacks
+* Event callbacks
+* Conditional transitions
+
   class Vehicle < ActiveRecord::Base
     state_machine :state, :initial => 'idling' do
       before_exit   'parked', :put_on_seatbelt
@@ -74,8 +81,32 @@ so simple you don't even need to know what a state machine is :)
         transition :to => 'parked', :from => 'stalled', :if => :auto_shop_busy?
       end
     end
+    
+    def tow!
+    end
+    
+    def fix!
+    end
+    
+    def auto_shop_busy?
+      false
+    end
   end
 
+Using the above model as an example, you can interact with the state machine
+like so:
+
+  vehicle = Vehicle.create    # => #<Vehicle id: 1, seatbelt_on: false, state: "parked">
+  vehicle.ignite              # => true
+  vehicle                     # => #<Vehicle id: 1, seatbelt_on: true, state: "idling">
+  vehicle.shift_up            # => true
+  vehicle                     # => #<Vehicle id: 1, seatbelt_on: true, state: "first_gear">
+  vehicle.shift_up            # => true
+  vehicle                     # => #<Vehicle id: 1, seatbelt_on: true, state: "second_gear">
+  
+  # The bang (!) operator can raise exceptions if the event fails
+  vehicle.park!               # => PluginAWeek::StateMachine::InvalidTransition: Cannot transition via :park from "second_gear"
+
 == Tools
 
 Jean Bovet - {Visual Automata Simulator}[http://www.cs.usfca.edu/~jbovet/vas.html].

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'state_machine'
-  s.version           = '0.2.0'
+  s.version           = '0.2.1'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Adds support for creating state machines for attributes within a model'
   

data/lib/state_machine.rb

@@ -12,29 +12,65 @@ module PluginAWeek #:nodoc:
     end
     
     module MacroMethods
-      # Creates a state machine for the given attribute.
+      # Creates a state machine for the given attribute.  The default attribute
+      # is "state".
       # 
       # Configuration options:
       # * +initial+ - The initial value of the attribute.  This can either be the actual value or a Proc for dynamic initial states.
       # 
-      # == Example
+      # This also requires a block which will be used to actually configure the
+      # events and transitions for the state machine.  *Note* that this block will
+      # be executed within the context of the state machine.  As a result, you will
+      # not be able to access any class methods on the model unless you refer to
+      # them directly (i.e. specifying the class name).
       # 
-      # With a static state:
+      # For examples on the types of configured state machines and blocks, see
+      # the section below.
+      # 
+      # == Examples
+      # 
+      # With the default attribute and no initial state:
+      # 
+      #   class Switch < ActiveRecord::Base
+      #     state_machine do
+      #       event :park do
+      #         ...
+      #       end
+      #     end
+      #   end
+      # 
+      # The above example will define a state machine for the attribute "state"
+      # on the model.  Every switch will start with no initial state.
+      # 
+      # With a custom attribute:
       # 
       #   class Switch < ActiveRecord::Base
-      #     state_machine :state, :initial => 'off' do
+      #     state_machine :status do
       #       ...
       #     end
       #   end
       # 
-      # With a dynamic state:
+      # With a static initial state:
       # 
       #   class Switch < ActiveRecord::Base
-      #     state_machine :state, :initial => Proc.new {|switch| (8..22).include?(Time.now.hour) ? 'on' : 'off'} do
+      #     state_machine :status, :initial => 'off' do
       #       ...
       #     end
       #   end
-      def state_machine(attribute, options = {}, &block)
+      # 
+      # With a dynamic initial state:
+      # 
+      #   class Switch < ActiveRecord::Base
+      #     state_machine :status, :initial => Proc.new {|switch| (8..22).include?(Time.now.hour) ? 'on' : 'off'} do
+      #       ...
+      #     end
+      #   end
+      # 
+      # == Events and Transitions
+      # 
+      # For more information about how to configure an event and its associated
+      # transitions, see PluginAWeek::StateMachine::Machine#event
+      def state_machine(*args, &block)
         unless included_modules.include?(PluginAWeek::StateMachine::InstanceMethods)
           write_inheritable_attribute :state_machines, {}
           class_inheritable_reader :state_machines
@@ -44,10 +80,12 @@ module PluginAWeek #:nodoc:
           include PluginAWeek::StateMachine::InstanceMethods
         end
         
+        options = args.extract_options!
+        attribute = args.any? ? args.first.to_s : 'state'
+        options[:initial] = state_machines[attribute].initial_state_without_processing if !options.include?(:initial) && state_machines[attribute]
+        
         # This will create a new machine for subclasses as well so that the owner_class and
         # initial state can be overridden
-        attribute = attribute.to_s
-        options[:initial] = state_machines[attribute].initial_state_without_processing if !options.include?(:initial) && state_machines[attribute]
         machine = state_machines[attribute] = PluginAWeek::StateMachine::Machine.new(self, attribute, options)
         machine.instance_eval(&block) if block
         machine

data/lib/state_machine/event.rb

@@ -11,16 +11,24 @@ module PluginAWeek #:nodoc:
       # The name of the action that fires the event
       attr_reader :name
       
+      # The list of transitions that can be made for this event
+      attr_reader :transitions
+      
       delegate  :owner_class,
                   :to => :machine
       
-      # Creates a new event with the given name
+      # Creates a new event within the context of the given machine.
+      # 
+      # Configuration options:
+      # * +before+ - Callbacks to invoke before the event is fired
+      # * +after+ - Callbacks to invoke after the event is fired
       def initialize(machine, name, options = {})
         options.assert_valid_keys(:before, :after)
         
         @machine = machine
         @name = name
         @options = options.stringify_keys
+        @transitions = []
         
         add_transition_actions
         add_transition_callbacks
@@ -31,55 +39,60 @@ module PluginAWeek #:nodoc:
       # 
       # Configuration options:
       # * +to+ - The state that being transitioned to
-      # * +from+ - A state or array of states that can be transitioned from
+      # * +from+ - A state or array of states that can be transitioned from. If not specified, then the transition can occur for *any* from state
+      # * +except_from+ - A state or array of states that *cannot* be transitioned from.
       # * +if+ - Specifies a method, proc or string to call to determine if the validation should occur (e.g. :if => :moving?, or :if => Proc.new {|car| car.speed > 60}). The method, proc or string should return or evaluate to a true or false value.
       # * +unless+ - Specifies a method, proc or string to call to determine if the transition should not occur (e.g. :unless => :stopped?, or :unless => Proc.new {|car| car.speed <= 60}). The method, proc or string should return or evaluate to a true or false value.
       # 
       # == Examples
       # 
+      #   transition :to => 'parked'
       #   transition :to => 'parked', :from => 'first_gear'
       #   transition :to => 'parked', :from => %w(first_gear reverse)
       #   transition :to => 'parked', :from => 'first_gear', :if => :moving?
       #   transition :to => 'parked', :from => 'first_gear', :unless => :stopped?
+      #   transition :to => 'parked', :except_from => 'parked'
       def transition(options = {})
+        # Slice out the callback options
         options.symbolize_keys!
-        options.assert_valid_keys(:to, :from, :if, :unless)
-        raise ArgumentError, ':to state must be specified' unless options.include?(:to)
+        callback_options = {:if => options.delete(:if), :unless => options.delete(:unless)}
         
-        # Get the states involved in the transition
-        to_state = options.delete(:to)
-        from_states = Array(options.delete(:from))
+        transition = Transition.new(self, options)
         
-        from_states.collect do |from_state|
-          # Create the actual transition that will update records when performed
-          transition = Transition.new(self, from_state, to_state)
-          
-          # Add the callback to the model. If the callback fails, then the next
-          # available callback for the event will run until one is successful.
-          callback = Proc.new {|record, *args| try_transition(transition, false, record, *args)}
-          owner_class.send("transition_on_#{name}", callback, options)
-          
-          # Add the callback! to the model similar to above
-          callback = Proc.new {|record, *args| try_transition(transition, true, record, *args)}
-          owner_class.send("transition_bang_on_#{name}", callback, options)
-          
-          transition
-        end
+        # Add the callback to the model. If the callback fails, then the next
+        # available callback for the event will run until one is successful.
+        callback = Proc.new {|record, *args| try_transition(transition, false, record, *args)}
+        owner_class.send("transition_on_#{name}", callback, callback_options)
+        
+        # Add the callback! to the model similar to above
+        callback = Proc.new {|record, *args| try_transition(transition, true, record, *args)}
+        owner_class.send("transition_bang_on_#{name}", callback, callback_options)
+        
+        transitions << transition
+        transition
       end
       
-      # Attempts to perform one of the event's transitions for the given record
+      # Attempts to perform one of the event's transitions for the given record.
+      # Any additional arguments will be passed to the event's callbacks.
       def fire(record, *args)
-        record.class.transaction {invoke_transition_callbacks(record, false, *args) || raise(ActiveRecord::Rollback)} || false
+        fire_with_optional_bang(record, false, *args) || false
       end
       
       # Attempts to perform one of the event's transitions for the given record.
       # If the transition cannot be made, then a PluginAWeek::StateMachine::InvalidTransition
       # error will be raised.
       def fire!(record, *args)
-        record.class.transaction {invoke_transition_callbacks(record, true, *args) || raise(ActiveRecord::Rollback)} || raise(PluginAWeek::StateMachine::InvalidTransition)
+        fire_with_optional_bang(record, true, *args) || raise(PluginAWeek::StateMachine::InvalidTransition, "Cannot transition via :#{name} from #{record.send(machine.attribute).inspect}")
       end
       
       private
+        # Fires the event
+        def fire_with_optional_bang(record, bang, *args)
+          record.class.transaction do
+            invoke_transition_callbacks(record, bang, *args) || raise(ActiveRecord::Rollback)
+          end
+        end
+        
         # Add the various instance methods that can transition the record using
         # the current event
         def add_transition_actions

data/lib/state_machine/machine.rb

@@ -2,19 +2,41 @@ require 'state_machine/event'
 
 module PluginAWeek #:nodoc:
   module StateMachine
-    # Represents a state machine for a particular attribute
+    # Represents a state machine for a particular attribute.  State machines
+    # consist of events (a.k.a. actions) and a set of transitions that define
+    # how the state changes after a particular event is fired.
     # 
-    # == State callbacks
+    # A state machine may not necessarily know all of the possible states for
+    # an object since they can be any arbitrary value.
     # 
-    # These callbacks are invoked in the following order:
-    # 1. before_exit (old state)
-    # 2. before_enter (new state)
-    # 3. after_exit (old state)
-    # 4. after_enter (new state)
+    # == Callbacks
+    # 
+    # Callbacks are supported for hooking into event calls and state transitions.
+    # The order in which these callbacks are invoked is shown below:
+    # * (1) before_exit (from state)
+    # * (2) before_enter (to state)
+    # * (3) before (event)
+    # * (-) update state
+    # * (4) after_exit (from state)
+    # * (5) after_enter (to state)
+    # * (6) after (event)
+    # 
+    # == Cancelling callbacks
+    # 
+    # If a <tt>before_*</tt> callback returns +false+, all the later callbacks
+    # and associated event are cancelled.  If an <tt>after_*</tt> callback returns
+    # false, all the later callbacks are cancelled.  Callbacks are run in the
+    # order in which they are defined.
+    # 
+    # Note that if a <tt>before_*</tt> callback fails and the bang version of an
+    # event was invoked, an exception will be raised instaed of returning false.
     class Machine
       # The events that trigger transitions
       attr_reader :events
       
+      # A list of the states defined in the transitions of all of the events
+      attr_reader :states
+      
       # The attribute for which the state machine is being defined
       attr_accessor :attribute
       
@@ -27,29 +49,30 @@ module PluginAWeek #:nodoc:
       # Creates a new state machine for the given attribute
       # 
       # Configuration options:
-      # * +initial+ - The initial value to set the attribute to
+      # * +initial+ - The initial value to set the attribute to. This can be an actual value or a proc, which will be evaluated at runtime.
       # 
       # == Scopes
       # 
-      # This will automatically created a named scope called with_#{attribute}
+      # This will automatically create a named scope called with_#{attribute}
       # that will find all records that have the attribute set to a given value.
       # For example,
       # 
       #   Switch.with_state('on') # => Finds all switches where the state is on
       #   Switch.with_states('on', 'off') # => Finds all switches where the state is either on or off
-      def initialize(owner_class, attribute, options = {})
+      def initialize(owner_class, attribute = 'state', options = {})
         options.assert_valid_keys(:initial)
         
         @owner_class = owner_class
         @attribute = attribute.to_s
         @initial_state = options[:initial]
         @events = {}
+        @states = []
         
         add_named_scopes
       end
       
       # Gets the initial state of the machine for the given record. The record
-      # is only used if a dynamic initial state is being used
+      # is only used if a dynamic initial state was configured.
       def initial_state(record)
         @initial_state.is_a?(Proc) ? @initial_state.call(record) : @initial_state
       end
@@ -60,25 +83,19 @@ module PluginAWeek #:nodoc:
       end
       
       # Defines an event of the system.  This can take an optional hash that
-      # defines callbacks which will be invoked when the object enters/exits
-      # the event.
+      # defines callbacks which will be invoked before and after the event is
+      # invoked on the object.
       # 
       # Configuration options:
-      # * +before+ - Invoked before the event has been executed
-      # * +after+ - Invoked after the event has been executed
-      # 
-      # == Callback order
-      # 
-      # These callbacks are invoked in the following order:
-      # 1. before
-      # 2. after
+      # * +before+ - One or more callbacks that will be invoked before the event has been fired
+      # * +after+ - One or more callbacks that will be invoked after the event has been fired
       # 
       # == Instance methods
       # 
       # The following instance methods are generated when a new event is defined
       # (the "park" event is used as an example):
-      # * <tt>park(*args)</tt> - Fires the "park" event, transitioning from the current state to the next valid state.  This takes an optional +args+ list which is passed to the event callbacks.
-      # * <tt>park!(*args)</tt> - Fires the "park" event, transitioning from the current state to the next valid state.  This takes an optional +args+ list which is passed to the event callbacks.  If the transition cannot happen (for validation, database, etc. reasons), then an error will be raised
+      # * <tt>park(*args)</tt> - Fires the "park" event, transitioning from the current state to the next valid state.  This takes an optional list of arguments which are passed to the event callbacks.
+      # * <tt>park!(*args)</tt> - Fires the "park" event, transitioning from the current state to the next valid state.  This takes an optional list of arguments which are passed to the event callbacks.  If the transition cannot happen (for validation, database, etc. reasons), then an error will be raised
       # 
       # == Defining transitions
       # 
@@ -96,6 +113,19 @@ module PluginAWeek #:nodoc:
       # See PluginAWeek::StateMachine::Event#transition for more information on
       # the possible options that can be passed in.
       # 
+      # *Note* that this block is executed within the context of the actual event
+      # object.  As a result, you will not be able to reference any class methods
+      # on the model without referencing the class itself.  For example,
+      # 
+      #   class Car < ActiveRecord::Base
+      #     def self.safe_states
+      #       %w(parked idling first_gear)
+      #     end
+      #     
+      #     state_machine :state do
+      #   event :park do
+      #     transition :to 
+      # 
       # == Example
       # 
       #   class Car < ActiveRecord::Base
@@ -110,6 +140,12 @@ module PluginAWeek #:nodoc:
         name = name.to_s
         event = events[name] = Event.new(self, name, options)
         event.instance_eval(&block)
+        
+        # Record the states
+        event.transitions.each do |transition|
+          @states |= ([transition.to_state] + transition.from_states)
+        end
+        
         event
       end
       

data/lib/state_machine/transition.rb

@@ -7,51 +7,70 @@ module PluginAWeek #:nodoc:
     # A transition indicates a state change and is described by a condition
     # that would need to be fulfilled to enable the transition.  Transitions
     # consist of:
-    # * The starting state
+    # * The starting state(s)
     # * The ending state
     # * A guard to check if the transition is allowed
     class Transition
-      # The state from which the transition is being made
-      attr_reader :from_state
-      
       # The state to which the transition is being made
       attr_reader :to_state
       
+      # The states from which the transition can be made
+      attr_reader :from_states
+      
       # The event that caused the transition
       attr_reader :event
       
       delegate  :machine,
                   :to => :event
       
-      def initialize(event, from_state, to_state) #:nodoc:
+      # Creates a new transition within the context of the given event.
+      # 
+      # Configuration options:
+      # * +to+ - The state being transitioned to
+      # * +from+ - One or more states being transitioned from.  Default is nil (can transition from any state)
+      # * +except_from+ - One or more states that *can't* be transitioned from.
+      def initialize(event, options) #:nodoc:
         @event = event
-        @from_state = from_state
-        @to_state = to_state
-        @loopback = from_state == to_state
+        
+        options.assert_valid_keys(:to, :from, :except_from)
+        raise ArgumentError, ':to state must be specified' unless options.include?(:to)
+        
+        # Get the states involved in the transition
+        @to_state = options[:to]
+        @from_states = Array(options[:from] || options[:except_from])
+        
+        # Should we be matching the from states?
+        @require_match = !options[:from].nil?
       end
       
       # Whether or not this is a loopback transition (i.e. from and to state are the same)
-      def loopback?(state = from_state)
-        state == to_state
+      def loopback?(from_state)
+        from_state == to_state
       end
       
       # Determines whether or not this transition can be performed on the given
-      # states
+      # record.  The transition can be performed if the record's state matches
+      # one of the states that are valid in this transition.
       def can_perform_on?(record)
-        !from_state || from_state == record.send(machine.attribute)
+        from_states.empty? || from_states.include?(record.send(machine.attribute)) == @require_match
       end
       
       # Runs the actual transition and any callbacks associated with entering
-      # and exiting the states
+      # and exiting the states.  Any additional arguments are passed to the
+      # callbacks.
+      # 
+      # *Note* that the caller should check <tt>can_perform_on?</tt> before calling
+      # perform.  This will *not* check whether transition should be performed.
       def perform(record, *args)
         perform_with_optional_bang(record, false, *args)
       end
       
       # Runs the actual transition and any callbacks associated with entering
       # and exiting the states. Any errors during validation or saving will be
-      # raised.
+      # raised.  If any +before+ callbacks fail, a PluginAWeek::StateMachine::InvalidTransition
+      # error will be raised.
       def perform!(record, *args)
-        perform_with_optional_bang(record, true, *args) || raise(PluginAWeek::StateMachine::InvalidTransition)
+        perform_with_optional_bang(record, true, *args) || raise(PluginAWeek::StateMachine::InvalidTransition, "Cannot transition via :#{event.name} from #{record.send(machine.attribute).inspect} to #{to_state.inspect}")
       end
       
       private

data/test/app_root/app/models/switch.rb

@@ -13,6 +13,9 @@ class Switch < ActiveRecord::Base
   attr_accessor :fail_save
   before_save Proc.new {|switch| !switch.fail_save}
   
+  # Arbitrary data associated with the switch
+  attr_accessor :data
+  
   def initialize(attributes = nil)
     @callbacks = []
     super

data/test/app_root/script/console

@@ -0,0 +1,8 @@
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+libs =  " -r irb/completion"
+libs << " -r test/app_root/script/rails_framework_root"
+libs << " -r test/test_helper"
+libs << " -r plugin_test_helper/console_with_fixtures"
+libs << " -r console_app"
+libs << " -r console_with_helpers"
+exec "#{irb} #{libs} --simple-prompt"

data/test/app_root/script/rails_framework_root.rb

@@ -0,0 +1 @@
+RAILS_FRAMEWORK_ROOT = '/home/aaron/Projects/Vendor/rails'

data/test/factory.rb

@@ -37,12 +37,7 @@ module Factory
   end
   
   build Car do |attributes|
-    attributes[:highway] = create_highway unless attributes.include?(:highway)
-    attributes[:auto_shop] = create_auto_shop unless attributes.include?(:auto_shop)
-    attributes.reverse_merge!(
-      :seatbelt_on => false,
-      :insurance_premium => 50
-    )
+    valid_vehicle_attributes(attributes)
   end
   
   build Highway do |attributes|
@@ -62,6 +57,11 @@ module Factory
   end
   
   build Vehicle do |attributes|
-    valid_car_attributes(attributes)
+    attributes[:highway] = create_highway unless attributes.include?(:highway)
+    attributes[:auto_shop] = create_auto_shop unless attributes.include?(:auto_shop)
+    attributes.reverse_merge!(
+      :seatbelt_on => false,
+      :insurance_premium => 50
+    )
   end
 end

data/test/unit/event_test.rb

@@ -14,6 +14,10 @@ class EventTest < Test::Unit::TestCase
     assert_equal 'turn_on', @event.name
   end
   
+  def test_should_not_have_any_transitions
+    assert @event.transitions.empty?
+  end
+  
   def test_should_define_an_event_action_on_the_owner_class
     switch = new_switch
     assert switch.respond_to?(:turn_on)
@@ -69,12 +73,21 @@ class EventWithTransitionsTest < Test::Unit::TestCase
     assert_nothing_raised {@event.transition(:to => 'on')}
   end
   
+  def test_should_allow_transitioning_without_a_state
+    assert @event.transition(:to => 'on')
+  end
+  
   def test_should_allow_transitioning_from_a_single_state
-    assert_equal [%w(off on)], @event.transition(:to => 'on', :from => 'off').map {|t| [t.from_state, t.to_state]}
+    assert @event.transition(:to => 'on', :from => 'off')
   end
   
   def test_should_allow_transitioning_from_multiple_states
-    assert_equal [%w(off on), %w(on on)], @event.transition(:to => 'on', :from => %w(off on)).map {|t| [t.from_state, t.to_state]}
+    assert @event.transition(:to => 'on', :from => %w(off on))
+  end
+  
+  def test_should_have_transitions
+    @event.transition(:to => 'on')
+    assert @event.transitions.any?
   end
   
   def teardown
@@ -124,12 +137,24 @@ class EventAfterBeingFiredWithTransitionsTest < Test::Unit::TestCase
     assert_equal 'off', @switch.state
   end
   
-  def test_should_fire_if_transition_is_matched
+  def test_should_fire_if_transition_with_no_from_state_is_matched
+    @event.transition :to => 'on'
+    assert @event.fire(@switch)
+    assert_equal 'on', @switch.state
+  end
+  
+  def test_should_fire_if_transition_with_from_state_is_matched
     @event.transition :to => 'on', :from => 'off'
     assert @event.fire(@switch)
     assert_equal 'on', @switch.state
   end
   
+  def test_should_fire_if_transition_with_multiple_from_states_is_matched
+    @event.transition :to => 'on', :from => %w(off on)
+    assert @event.fire(@switch)
+    assert_equal 'on', @switch.state
+  end
+  
   def test_should_not_fire_if_validation_failed
     @event.transition :to => 'on', :from => 'off'
     @switch.fail_validation = true
@@ -178,36 +203,59 @@ class EventAfterBeingFiredWithConditionalTransitionsTest < Test::Unit::TestCase
   def setup
     @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state', :initial => 'off')
     @event = PluginAWeek::StateMachine::Event.new(@machine, 'turn_on')
-    
-    # Verify that the callbacks are being invoked correctly; should not affect
-    # callback chain in tests
-    @event.transition :to => 'if_not_evaluated', :from => 'off', :if => Proc.new {false}
-    @event.transition :to => 'unless_not_evaluated', :from => 'off', :unless => Proc.new {true}
-    @event.transition :to => 'no_record', :from => 'off', :if => Proc.new {|record, value| record.nil?}
-    @event.transition :to => 'no_arguments', :from => 'off', :if => Proc.new {|record, value| value.nil?}
-    
     @switch = create_switch(:state => 'off')
   end
   
-  def test_should_not_fire_if_no_transitions_are_matched
-    assert !@event.fire(@switch, 1)
-    assert_equal 'off', @switch.state
+  def test_should_fire_if_if_is_true
+    @event.transition :to => 'on', :from => 'off', :if => Proc.new {true}
+    assert @event.fire(@switch)
   end
   
-  def test_should_raise_exception_if_no_transitions_are_matched
-    assert_raise(PluginAWeek::StateMachine::InvalidTransition) {@event.fire!(@switch, 1)}
-    assert_equal 'off', @switch.state
+  def test_should_not_fire_if_if_is_false
+    @event.transition :to => 'on', :from => 'off', :if => Proc.new {false}
+    assert !@event.fire(@switch)
   end
   
-  def test_should_fire_if_transition_is_matched
+  def test_should_fire_if_unless_is_false
+    @event.transition :to => 'on', :from => 'off', :unless => Proc.new {false}
+    assert @event.fire(@switch)
+  end
+  
+  def test_should_not_fire_if_unless_is_true
+    @event.transition :to => 'on', :from => 'off', :unless => Proc.new {true}
+    assert !@event.fire(@switch)
+  end
+  
+  def test_should_pass_in_record_as_argument
+    @event.transition :to => 'on', :from => 'off', :if => Proc.new {|record, value| !record.nil?}
+    assert @event.fire(@switch)
+  end
+  
+  def test_should_pass_in_value_as_argument
     @event.transition :to => 'on', :from => 'off', :if => Proc.new {|record, value| value == 1}
     assert @event.fire(@switch, 1)
-    assert_equal 'on', @switch.state
+  end
+  
+  def test_should_fire_if_method_evaluates_to_true
+    @switch.data = true
+    @event.transition :to => 'on', :from => 'off', :if => :data
+    assert @event.fire(@switch)
+  end
+  
+  def test_should_not_fire_if_method_evaluates_to_false
+    @switch.data = false
+    @event.transition :to => 'on', :from => 'off', :if => :data
+    assert !@event.fire(@switch)
+  end
+  
+  def test_should_raise_exception_if_no_transitions_are_matched
+    assert_raise(PluginAWeek::StateMachine::InvalidTransition) {@event.fire!(@switch, 1)}
+    assert_equal 'off', @switch.state
   end
   
   def test_should_not_raise_exception_if_transition_is_matched
-    @event.transition :to => 'on', :from => 'off', :if => Proc.new {|record, value| value == 1}
-    assert @event.fire!(@switch, 1)
+    @event.transition :to => 'on', :from => 'off', :if => Proc.new {true}
+    assert @event.fire!(@switch)
     assert_equal 'on', @switch.state
   end
   

data/test/unit/machine_test.rb

@@ -2,7 +2,7 @@ require File.expand_path(File.dirname(__FILE__) + '/../test_helper')
 
 class MachineByDefaultTest < Test::Unit::TestCase
   def setup
-    @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state')
+    @machine = PluginAWeek::StateMachine::Machine.new(Switch)
   end
   
   def test_should_have_an_attribute
@@ -20,6 +20,10 @@ class MachineByDefaultTest < Test::Unit::TestCase
   def test_should_not_have_any_events
     assert @machine.events.empty?
   end
+  
+  def test_should_not_have_any_states
+    assert @machine.states.empty?
+  end
 end
 
 class MachineWithInvalidOptionsTest < Test::Unit::TestCase
@@ -121,9 +125,27 @@ class MachineWithEventsTest < Test::Unit::TestCase
     assert responded
   end
   
-  def test_should_store_the_event
+  def test_should_have_events
     @machine.event(:turn_on) {}
-    assert_equal 1, @machine.events.size
+    assert_equal %w(turn_on), @machine.events.keys
+  end
+end
+
+class MachineWithEventsAndTransitionsTest < Test::Unit::TestCase
+  def setup
+    @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state')
+    @machine.event(:turn_on) do
+      transition :to => 'on', :from => 'off'
+      transition :to => 'error', :from => 'unknown'
+    end
+  end
+  
+  def test_should_have_events
+    assert_equal %w(turn_on), @machine.events.keys
+  end
+  
+  def test_should_have_states
+    assert_equal %w(on off error unknown), @machine.states
   end
 end
 

data/test/unit/transition_test.rb

@@ -4,34 +4,39 @@ class TransitionTest < Test::Unit::TestCase
   def setup
     @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state', :initial => 'off')
     @event = PluginAWeek::StateMachine::Event.new(@machine, 'turn_on')
-    @transition = PluginAWeek::StateMachine::Transition.new(@event, 'off', 'on')
+    @transition = PluginAWeek::StateMachine::Transition.new(@event, :to => 'on')
   end
   
-  def test_should_have_a_from_state
-    assert_equal 'off', @transition.from_state
+  def test_should_not_have_any_from_states
+    assert @transition.from_states.empty?
+  end
+  
+  def test_should_not_be_a_loopback_if_from_state_is_different
+    assert !@transition.loopback?('off')
   end
   
   def test_should_have_a_to_state
     assert_equal 'on', @transition.to_state
   end
   
-  def test_should_not_be_a_loopback
-    assert !@transition.loopback?
+  def test_should_be_loopback_if_from_state_is_same
+    assert @transition.loopback?('on')
   end
   
-  def test_should_not_be_able_to_perform_if_record_state_is_not_from_state
-    record = new_switch(:state => 'on')
-    assert !@transition.can_perform_on?(record)
-  end
-  
-  def test_should_be_able_to_perform_if_record_state_is_from_state
+  def test_should_be_able_to_perform_on_all_states
     record = new_switch(:state => 'off')
     assert @transition.can_perform_on?(record)
+    
+    record = new_switch(:state => 'on')
+    assert @transition.can_perform_on?(record)
   end
   
-  def test_should_perform_for_valid_from_state
+  def test_should_perform_for_all_states
     record = new_switch(:state => 'off')
     assert @transition.perform(record)
+    
+    record = new_switch(:state => 'on')
+    assert @transition.perform(record)
   end
   
   def test_should_not_raise_exception_if_not_valid_during_perform
@@ -61,68 +66,131 @@ class TransitionTest < Test::Unit::TestCase
     
     assert_raise(ActiveRecord::RecordNotSaved) {@transition.perform!(record)}
   end
+  
+  def test_should_raise_exception_if_invalid_option_specified
+    assert_raise(ArgumentError) {PluginAWeek::StateMachine::Transition.new(@event, :invalid => true)}
+  end
+  
+  def test_should_raise_exception_if_to_option_not_specified
+    assert_raise(ArgumentError) {PluginAWeek::StateMachine::Transition.new(@event, :from => 'off')}
+  end
 end
 
-class TransitionWithoutFromStateTest < Test::Unit::TestCase
+class TransitionWithLoopbackTest < Test::Unit::TestCase
   def setup
     @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state', :initial => 'off')
     @event = PluginAWeek::StateMachine::Event.new(@machine, 'turn_on')
-    @transition = PluginAWeek::StateMachine::Transition.new(@event, nil, 'on')
+    @transition = PluginAWeek::StateMachine::Transition.new(@event, :to => 'on', :from => 'on')
   end
   
-  def test_should_not_have_a_from_state
-    assert_nil @transition.from_state
+  def test_should_be_able_to_perform
+    record = new_switch(:state => 'on')
+    assert @transition.can_perform_on?(record)
   end
   
-  def test_should_be_able_to_perform_on_all_states
-    record = new_switch(:state => 'off')
-    assert @transition.can_perform_on?(record)
-    
+  def test_should_perform_for_valid_from_state
     record = new_switch(:state => 'on')
-    assert @transition.can_perform_on?(record)
+    assert @transition.perform(record)
   end
 end
 
-class TransitionWithLoopbackTest < Test::Unit::TestCase
+class TransitionWithFromStateTest < Test::Unit::TestCase
   def setup
     @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state', :initial => 'off')
     @event = PluginAWeek::StateMachine::Event.new(@machine, 'turn_on')
-    @transition = PluginAWeek::StateMachine::Transition.new(@event, 'on', 'on')
+    @transition = PluginAWeek::StateMachine::Transition.new(@event, :to => 'on', :from => 'off')
   end
   
   def test_should_have_a_from_state
-    assert_equal 'on', @transition.from_state
+    assert_equal ['off'], @transition.from_states
   end
   
-  def test_should_have_a_to_state
-    assert_equal 'on', @transition.to_state
+  def test_should_not_be_able_to_perform_if_record_state_is_not_from_state
+    record = new_switch(:state => 'on')
+    assert !@transition.can_perform_on?(record)
   end
   
-  def test_should_be_a_loopback
-    assert @transition.loopback?
+  def test_should_be_able_to_perform_if_record_state_is_from_state
+    record = new_switch(:state => 'off')
+    assert @transition.can_perform_on?(record)
   end
   
-  def test_should_not_be_able_to_perform_if_record_state_is_not_from_state
+  def test_should_perform_for_valid_from_state
     record = new_switch(:state => 'off')
+    assert @transition.perform(record)
+  end
+end
+
+class TransitionWithMultipleFromStatesTest < Test::Unit::TestCase
+  def setup
+    @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state', :initial => 'off')
+    @event = PluginAWeek::StateMachine::Event.new(@machine, 'turn_on')
+    @transition = PluginAWeek::StateMachine::Transition.new(@event, :to => 'on', :from => %w(off on))
+  end
+  
+  def test_should_have_multiple_from_states
+    assert_equal ['off', 'on'], @transition.from_states
+  end
+  
+  def test_should_not_be_able_to_perform_if_record_state_is_not_from_state
+    record = new_switch(:state => 'unknown')
     assert !@transition.can_perform_on?(record)
   end
   
-  def test_should_be_able_to_perform_if_record_is_in_from_state
+  def test_should_be_able_to_perform_if_record_state_is_any_from_state
+    record = new_switch(:state => 'off')
+    assert @transition.can_perform_on?(record)
+    
     record = new_switch(:state => 'on')
     assert @transition.can_perform_on?(record)
   end
   
-  def test_should_perform_for_valid_from_state
+  def test_should_perform_for_any_valid_from_state
+    record = new_switch(:state => 'off')
+    assert @transition.perform(record)
+    
     record = new_switch(:state => 'on')
     assert @transition.perform(record)
   end
 end
 
+class TransitionWithMismatchedFromStatesRequiredTest < Test::Unit::TestCase
+  def setup
+    @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state', :initial => 'off')
+    @event = PluginAWeek::StateMachine::Event.new(@machine, 'turn_on')
+    @transition = PluginAWeek::StateMachine::Transition.new(@event, :to => 'on', :except_from => 'on')
+  end
+  
+  def test_should_have_a_from_state
+    assert_equal ['on'], @transition.from_states
+  end
+  
+  def test_should_be_able_to_perform_if_record_state_is_not_from_state
+    record = new_switch(:state => 'off')
+    assert @transition.can_perform_on?(record)
+  end
+  
+  def test_should_not_be_able_to_perform_if_record_state_is_from_state
+    record = new_switch(:state => 'on')
+    assert !@transition.can_perform_on?(record)
+  end
+  
+  def test_should_perform_for_valid_from_state
+    record = new_switch(:state => 'off')
+    assert @transition.perform(record)
+  end
+  
+  def test_should_not_perform_for_invalid_from_state
+    record = new_switch(:state => 'on')
+    assert !@transition.can_perform_on?(record)
+  end
+end
+
 class TransitionAfterBeingPerformedTest < Test::Unit::TestCase
   def setup
     @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state', :initial => 'off')
     @event = PluginAWeek::StateMachine::Event.new(@machine, 'turn_on')
-    @transition = PluginAWeek::StateMachine::Transition.new(@event, 'off', 'on')
+    @transition = PluginAWeek::StateMachine::Transition.new(@event, :to => 'on', :from => 'off')
     
     @record = create_switch(:state => 'off')
     @transition.perform(@record)
@@ -142,7 +210,7 @@ class TransitionWithLoopbackAfterBeingPerformedTest < Test::Unit::TestCase
   def setup
     @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state', :initial => 'off')
     @event = PluginAWeek::StateMachine::Event.new(@machine, 'turn_on')
-    @transition = PluginAWeek::StateMachine::Transition.new(@event, 'on', 'on')
+    @transition = PluginAWeek::StateMachine::Transition.new(@event, :to => 'on', :from => 'on')
     
     @record = create_switch(:state => 'on')
     @transition.perform(@record)
@@ -162,7 +230,7 @@ class TransitionWithCallbacksTest < Test::Unit::TestCase
   def setup
     @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state', :initial => 'off')
     @event = PluginAWeek::StateMachine::Event.new(@machine, 'turn_on')
-    @transition = PluginAWeek::StateMachine::Transition.new(@event, 'off', 'on')
+    @transition = PluginAWeek::StateMachine::Transition.new(@event, :to => 'on', :from => 'off')
     @record = create_switch(:state => 'off')
     
     Switch.define_callbacks :before_exit_state_off, :before_enter_state_on, :after_exit_state_off, :after_enter_state_on
@@ -295,7 +363,7 @@ class TransitionWithoutFromStateAndCallbacksTest < Test::Unit::TestCase
   def setup
     @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state', :initial => 'off')
     @event = PluginAWeek::StateMachine::Event.new(@machine, 'turn_on')
-    @transition = PluginAWeek::StateMachine::Transition.new(@event, nil, 'on')
+    @transition = PluginAWeek::StateMachine::Transition.new(@event, :to => 'on')
     @record = create_switch(:state => 'off')
     
     Switch.define_callbacks :before_exit_state_off, :before_enter_state_on, :after_exit_state_off, :after_enter_state_on
@@ -397,7 +465,7 @@ class TransitionWithLoopbackAndCallbacksTest < Test::Unit::TestCase
   def setup
     @machine = PluginAWeek::StateMachine::Machine.new(Switch, 'state', :initial => 'off')
     @event = PluginAWeek::StateMachine::Event.new(@machine, 'turn_on')
-    @transition = PluginAWeek::StateMachine::Transition.new(@event, 'on', 'on')
+    @transition = PluginAWeek::StateMachine::Transition.new(@event, :to => 'on', :from => 'on')
     @record = create_switch(:state => 'on')
     
     Switch.define_callbacks :before_exit_state_off, :before_enter_state_on, :after_exit_state_off, :after_enter_state_on

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: state_machine
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Aaron Pfeifer
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-06-29 00:00:00 -04:00
+date: 2008-07-05 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -37,6 +37,9 @@ files:
 - test/app_root/app/models/vehicle.rb
 - test/app_root/app/models/car.rb
 - test/app_root/app/models/auto_shop.rb
+- test/app_root/script
+- test/app_root/script/rails_framework_root.rb
+- test/app_root/script/console
 - test/app_root/db
 - test/app_root/db/migrate
 - test/app_root/db/migrate/002_create_auto_shops.rb