state_machine 0.2.1 → 0.3.0

data/CHANGELOG.rdoc

@@ -1,5 +1,20 @@
 == master
 
+== 0.3.0 / 2008-09-07
+
+* No longer allow additional arguments to be passed into event actions
+* Add support for can_#{event}? for checking whether an event can be fired based on the current state of the record
+* Don't use callbacks for performing transitions
+* Fix state machines in subclasses not knowing what states/events/transitions were defined by superclasses
+* Replace all before/after_exit/enter/loopback callback hooks and :before/:after options for events with before_transition/after_transition callbacks, e.g.
+  
+  before_transition :from => 'parked', :do => :lock_doors # was before_exit :parked, :lock_doors
+  after_transition :on => 'ignite', :do => :turn_on_radio # was event :ignite, :after => :turn_on_radio do
+  
+* Always save when an event is fired even if it results in a loopback [Jürgen Strobel]
+* Ensure initial state callbacks are invoked in the proper order when an event is fired on a new record
+* Add before_loopback and after_loopback hooks [Jürgen Strobel]
+
 == 0.2.1 / 2008-07-05
 
 * Add more descriptive exceptions

data/README.rdoc

@@ -40,14 +40,15 @@ making it so simple you don't even need to know what a state machine is :)
 
 Below is an example of many of the features offered by this plugin, including
 * Initial states
-* State callbacks
-* Event callbacks
+* Transition callbacks
 * Conditional transitions
 
   class Vehicle < ActiveRecord::Base
     state_machine :state, :initial => 'idling' do
-      before_exit   'parked', :put_on_seatbelt
-      after_enter   'parked', Proc.new {|vehicle| vehicle.update_attribute(:seatbelt_on, false)}
+      before_transition :from => %w(parked idling), :do => :put_on_seatbelt
+      after_transition :to => 'parked', :do => lambda {|vehicle| vehicle.update_attribute(:seatbelt_on, false)}
+      after_transition :on => 'crash', :do => :tow!
+      after_transition :on => 'repair', :do => :fix!
       
       event :park do
         transition :to => 'parked', :from => %w(idling first_gear)
@@ -73,19 +74,21 @@ Below is an example of many of the features offered by this plugin, including
         transition :to => 'first_gear', :from => 'second_gear'
       end
       
-      event :crash, :after => :tow! do
+      event :crash do
         transition :to => 'stalled', :from => %w(first_gear second_gear third_gear), :unless => :auto_shop_busy?
       end
       
-      event :repair, :after => :fix! do
+      event :repair do
         transition :to => 'parked', :from => 'stalled', :if => :auto_shop_busy?
       end
     end
     
     def tow!
+      # do something here
     end
     
     def fix!
+      # do something here
     end
     
     def auto_shop_busy?
@@ -96,16 +99,62 @@ Below is an example of many of the features offered by this plugin, including
 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">
+  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"
+  vehicle.park!             # => PluginAWeek::StateMachine::InvalidTransition: Cannot transition via :park from "second_gear"
+
+=== With enumerations
+
+Using the acts_as_enumeration[http://github.com/pluginaweek/acts_as_enumeration] plugin
+states can be transparently stored using record ids in the database like so:
+
+  class VehicleState < ActiveRecord::Base
+    acts_as_enumeration
+    
+    create :id => 1, :name => 'parked'
+    create :id => 2, :name => 'idling'
+    create :id => 3, :name => 'first_gear'
+    ...
+  end
+  
+  class Vehicle < ActiveRecord::Base
+    belongs_to :state, :class_name => 'VehicleState'
+    
+    state_machine :state, :initial => 'idling' do
+      ...
+      
+      event :park do
+        transition :to => 'parked', :from => %w(idling first_gear)
+      end
+      
+      event :ignite do
+        transition :to => 'stalled', :from => 'stalled'
+        transition :to => 'idling', :from => 'parked'
+      end
+    end
+    
+    ...
+  end
+
+Notice in the above example, the state machine definition remains *exactly* the
+same.  However, when interacting with the records, the actual state will be
+stored using the identifiers defined for the enumeration:
+
+  vehicle = Vehicle.create  # => #<Vehicle id: 1, seatbelt_on: false, state_id: 1>
+  vehicle.ignite            # => true
+  vehicle                   # => #<Vehicle id: 1, seatbelt_on: true, state_id: 2>
+  vehicle.shift_up          # => true
+  vehicle                   # => #<Vehicle id: 1, seatbelt_on: true, state_id: 3>
+
+This allows states to take on more complex functionality other than just being
+a string value.
 
 == Tools
 
@@ -130,3 +179,4 @@ To run against a specific version of Rails:
 == References
 
 * Scott Barron - acts_as_state_machine[http://elitists.textdriven.com/svn/plugins/acts_as_state_machine]
+* acts_as_enumeration[http://github.com/pluginaweek/acts_as_enumeration]

data/Rakefile

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

data/lib/state_machine.rb

@@ -1,9 +1,9 @@
 require 'state_machine/machine'
 
 module PluginAWeek #:nodoc:
-  # A state machine is a model of behavior composed of states, transitions,
-  # and events.  This helper adds support for defining this type of
-  # functionality within your ActiveRecord models.
+  # A state machine is a model of behavior composed of states, events, and
+  # transitions.  This helper adds support for defining this type of
+  # functionality within ActiveRecord models.
   module StateMachine
     def self.included(base) #:nodoc:
       base.class_eval do
@@ -19,10 +19,10 @@ module PluginAWeek #:nodoc:
       # * +initial+ - The initial value of the attribute.  This can either be the actual value or a Proc for dynamic initial states.
       # 
       # 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).
+      # 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).
       # 
       # For examples on the types of configured state machines and blocks, see
       # the section below.
@@ -61,7 +61,7 @@ module PluginAWeek #:nodoc:
       # 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
+      #     state_machine :status, :initial => lambda {|switch| (8..22).include?(Time.now.hour) ? 'on' : 'off'} do
       #       ...
       #     end
       #   end
@@ -70,24 +70,32 @@ module PluginAWeek #:nodoc:
       # 
       # For more information about how to configure an event and its associated
       # transitions, see PluginAWeek::StateMachine::Machine#event
+      # 
+      # == Defining callbacks
+      # 
+      # Within the +state_machine+ block, you can also define callbacks for
+      # particular states.  For more information about defining these callbacks,
+      # see PluginAWeek::StateMachine::Machine#before_transition and
+      # PluginAWeek::StateMachine::Machine#after_transition.
       def state_machine(*args, &block)
         unless included_modules.include?(PluginAWeek::StateMachine::InstanceMethods)
           write_inheritable_attribute :state_machines, {}
           class_inheritable_reader :state_machines
           
-          after_create :run_initial_state_machine_actions
-          
           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
-        machine = state_machines[attribute] = PluginAWeek::StateMachine::Machine.new(self, attribute, options)
+        # Creates the state machine for this class.  If a superclass has already
+        # defined the machine, then a copy of it will be used with its context
+        # changed to this class.  If no machine has been defined before for the
+        # attribute, a new one will be created.
+        original = state_machines[attribute]
+        machine = state_machines[attribute] = original ? original.within_context(self, options) : PluginAWeek::StateMachine::Machine.new(self, attribute, options)
         machine.instance_eval(&block) if block
+        
         machine
       end
     end
@@ -103,26 +111,15 @@ module PluginAWeek #:nodoc:
       def initialize_with_state_machine(attributes = nil)
         initialize_without_state_machine(attributes)
         
-        attribute_keys = (attributes || {}).keys.map!(&:to_s)
-        
         # Set the initial value of each state machine as long as the value wasn't
-        # included in the attribute hash passed in
+        # included in the initial attributes
+        attributes = (attributes || {}).stringify_keys
         self.class.state_machines.each do |attribute, machine|
-          unless attribute_keys.include?(attribute)
-            send("#{attribute}=", machine.initial_state(self))
-          end
+          send("#{attribute}=", machine.initial_state(self)) unless attributes.include?(attribute)
         end
         
         yield self if block_given?
       end
-      
-      # Records the transition for the record going into its initial state
-      def run_initial_state_machine_actions
-        self.class.state_machines.each do |attribute, machine|
-          callback = "after_enter_#{attribute}_#{self[attribute]}"
-          run_callbacks(callback) if self[attribute] && self.class.respond_to?(callback)
-        end
-      end
     end
   end
 end

data/lib/state_machine/event.rb

@@ -6,7 +6,7 @@ module PluginAWeek #:nodoc:
     # another
     class Event
       # The state machine for which this event is defined
-      attr_reader :machine
+      attr_accessor :machine
       
       # The name of the action that fires the event
       attr_reader :name
@@ -17,22 +17,20 @@ module PluginAWeek #:nodoc:
       delegate  :owner_class,
                   :to => :machine
       
-      # 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)
-        
+      # Creates a new event within the context of the given machine
+      def initialize(machine, name)
         @machine = machine
         @name = name
-        @options = options.stringify_keys
         @transitions = []
         
-        add_transition_actions
-        add_transition_callbacks
-        add_event_callbacks
+        add_actions
+      end
+      
+      # Creates a copy of this event in addition to the list of associated
+      # transitions to prevent conflicts across different events.
+      def initialize_copy(orig) #:nodoc:
+        super
+        @transitions = @transitions.dup
       end
       
       # Creates a new transition to the specified state.
@@ -41,7 +39,7 @@ module PluginAWeek #:nodoc:
       # * +to+ - The state that being transitioned to
       # * +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.
+      # * +if+ - Specifies a method, proc or string to call to determine if the transition 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
@@ -52,128 +50,66 @@ module PluginAWeek #:nodoc:
       #   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!
-        callback_options = {:if => options.delete(:if), :unless => options.delete(:unless)}
-        
-        transition = Transition.new(self, options)
-        
-        # 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
+      def transition(options)
+        transitions << transition = Transition.new(self, options)
         transition
       end
       
+      # Determines whether any transitions can be performed for this event based
+      # on the current state of the given record.
+      # 
+      # If the event can't be fired, then this will return false, otherwise true.
+      def can_fire?(record)
+        transitions.any? {|transition| transition.can_perform?(record)}
+      end
+      
       # 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)
-        fire_with_optional_bang(record, false, *args) || false
+      def fire(record)
+        run(record, false) || 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)
-        fire_with_optional_bang(record, true, *args) || raise(PluginAWeek::StateMachine::InvalidTransition, "Cannot transition via :#{name} from #{record.send(machine.attribute).inspect}")
+      def fire!(record)
+        run(record, true) || raise(PluginAWeek::StateMachine::InvalidTransition, "Cannot transition via :#{name} from \"#{record.send(machine.attribute)}\"")
       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
+        def add_actions
+          attribute = machine.attribute
           name = self.name
-          owner_class = self.owner_class
-          machine = self.machine
           
           owner_class.class_eval do
-            # Fires the event, returning true/false
-            define_method(name) do |*args|
-              owner_class.state_machines[machine.attribute].events[name].fire(self, *args)
-            end
-            
-            # Fires the event, raising an exception if it fails
-            define_method("#{name}!") do |*args|
-              owner_class.state_machines[machine.attribute].events[name].fire!(self, *args)
-            end
+            define_method(name) {self.class.state_machines[attribute].events[name].fire(self)}
+            define_method("#{name}!") {self.class.state_machines[attribute].events[name].fire!(self)}
+            define_method("can_#{name}?") {self.class.state_machines[attribute].events[name].can_fire?(self)}
           end
         end
         
-        # Defines callbacks for invoking transitions when this event is performed
-        def add_transition_callbacks
-          %W(transition transition_bang).each do |callback_name|
-            callback_name = "#{callback_name}_on_#{name}"
-            owner_class.define_callbacks(callback_name)
-          end
-        end
-        
-        # Adds the before/after callbacks for when the event is performed
-        def add_event_callbacks
-          %w(before after).each do |type|
-            callback_name = "#{type}_#{name}"
-            owner_class.define_callbacks(callback_name)
-            
-            # Add each defined callback
-            Array(@options[type]).each {|callback| owner_class.send(callback_name, callback)}
-          end
-        end
-        
-        # Attempts to perform the given transition. If it can't be performed based
-        # on the state of the given record, then the transition will be skipped
-        # and the next available one will be tried.
+        # Attempts to find a transition that can be performed for this event.
         # 
-        # If +bang+ is specified, then perform! will be called on the transition.
-        # Otherwise, the default +perform+ will be invoked.
-        def try_transition(transition, bang, record, *args)
-          if transition.can_perform_on?(record)
-            return false if invoke_event_callbacks(:before, record, *args) == false
-            result = bang ? transition.perform!(record, *args) : transition.perform(record, *args)
-            invoke_event_callbacks(:after, record, *args)
-            result
-          else
-            # Indicate that the transition cannot be performed
-            :skip
-          end
-        end
-        
-        # Invokes a particulary type of callback for the event
-        def invoke_event_callbacks(type, record, *args)
-          args = [record] + args
+        # +bang+ indicates whether +perform+ or <tt>perform!</tt> will be
+        # invoked on transitions.
+        def run(record, bang)
+          result = false
           
-          record.class.send("#{type}_#{name}_callback_chain").each do |callback|
-            result = callback.call(*args)
-            break result if result == false
+          record.class.transaction do
+            transitions.each do |transition|
+              if transition.can_perform?(record)
+                result = bang ? transition.perform!(record) : transition.perform(record)
+                break
+              end
+            end
+            
+            # Rollback any changes if the transition failed
+            raise ActiveRecord::Rollback unless result
           end
-        end
-        
-        # Invokes the callbacks for each transition in order to find one that
-        # completes successfully.
-        # 
-        # +bang+ indicates whether perform or perform! will be invoked on the
-        # transitions in the callback chain
-        def invoke_transition_callbacks(record, bang, *args)
-          args = [record] + args
-          callback_chain = "transition#{'_bang' if bang}_on_#{name}_callback_chain"
           
-          result = record.class.send(callback_chain).each do |callback|
-            result = callback.call(*args)
-            break result if [true, false].include?(result)
-          end
-          result == true
+          result
         end
     end
   end