state_machine 0.6.3 → 0.7.0

data/lib/state_machine/guard.rb

@@ -20,7 +20,7 @@ module StateMachine
     # The requirement for verifying the event being guarded
     attr_reader :event_requirement
     
-    # One or more requrirements for verifying the states being guarded.  All
+    # One or more requirements for verifying the states being guarded.  All
     # requirements contain a mapping of {:from => matcher, :to => matcher}.
     attr_reader :state_requirements
     

data/lib/state_machine/integrations/active_record/locale.rb

@@ -2,7 +2,8 @@
   :activerecord => {
     :errors => {
       :messages => {
-        :invalid_transition => StateMachine::Machine.default_invalid_message % ['{{event}}', '{{value}}']
+        :invalid_event => StateMachine::Machine.default_messages[:invalid_event] % ['{{state}}'],
+        :invalid_transition => StateMachine::Machine.default_messages[:invalid_transition] % ['{{event}}']
       }
     }
   }

data/lib/state_machine/integrations/active_record.rb

@@ -33,6 +33,37 @@ module StateMachine
     #   vehicle.ignite                    # => true
     #   vehicle.reload                    # => #<Vehicle id: 1, name: "Ford Explorer", state: "idling">
     # 
+    # == Events
+    # 
+    # As described in StateMachine::InstanceMethods#state_machine, event
+    # attributes are created for every machine that allow transitions to be
+    # performed automatically when the object's action (in this case, :save)
+    # is called.
+    # 
+    # In ActiveRecord, these automated events are run in the following order:
+    # * before validation - Run before callbacks and persist new states, then validate
+    # * before save - If validation was skipped, run before callbacks and persist new states, then save
+    # * after save - Run after callbacks
+    # 
+    # For example,
+    # 
+    #   vehicle = Vehicle.create          # => #<Vehicle id: 1, name: nil, state: "parked">
+    #   vehicle.state_event               # => nil
+    #   vehicle.state_event = 'invalid'
+    #   vehicle.valid?                    # => false
+    #   vehicle.errors.full_messages      # => ["State event is invalid"]
+    #   
+    #   vehicle.state_event = 'ignite'
+    #   vehicle.valid?                    # => true
+    #   vehicle.save                      # => true
+    #   vehicle.state                     # => "idling"
+    #   vehicle.state_event               # => nil
+    # 
+    # Note that this can also be done on a mass-assignment basis:
+    # 
+    #   vehicle = Vehicle.create(:state_event => 'ignite')  # => #<Vehicle id: 1, name: nil, state: "idling">
+    #   vehicle.state                                       # => "idling"
+    # 
     # == Transactions
     # 
     # In order to ensure that any changes made during transition callbacks
@@ -60,6 +91,14 @@ module StateMachine
     # rolled back.  If an after callback halts the chain, the previous result
     # still applies and the transaction is *not* rolled back.
     # 
+    # To turn off transactions:
+    # 
+    #   class Vehicle < ActiveRecord::Base
+    #     state_machine :initial => :parked, :use_transactions => false do
+    #       ...
+    #     end
+    #   end
+    # 
     # == Validation errors
     # 
     # If an event fails to successfully fire because there are no matching
@@ -71,7 +110,7 @@ module StateMachine
     # 
     #   vehicle = Vehicle.create(:state => 'idling')  # => #<Vehicle id: 1, name: nil, state: "idling">
     #   vehicle.ignite                                # => false
-    #   vehicle.errors.full_messages                  # => ["State cannot be transitioned via :ignite from :idling"]
+    #   vehicle.errors.full_messages                  # => ["State cannot transition via \"ignite\""]
     # 
     # If an event fails to fire because of a validation error on the record and
     # *not* because a matching transition was not available, no error messages
@@ -138,9 +177,21 @@ module StateMachine
     # In addition to support for ActiveRecord-like hooks, there is additional
     # support for ActiveRecord observers.  Because of the way ActiveRecord
     # observers are designed, there is less flexibility around the specific
-    # transitions that can be hooked in.  As a result, observers can only
-    # hook into before/after callbacks for events and generic transitions
-    # like so:
+    # transitions that can be hooked in.  However, a large number of hooks
+    # *are* supported.  For example, if a transition for a record's +state+
+    # attribute changes the state from +parked+ to +idling+ via the +ignite+
+    # event, the following observer methods are supported:
+    # * before/after_ignite_from_parked_to_idling
+    # * before/after_ignite_from_parked
+    # * before/after_ignite_to_idling
+    # * before/after_ignite
+    # * before/after_transition_state_from_parked_to_idling
+    # * before/after_transition_state_from_parked
+    # * before/after_transition_state_to_idling
+    # * before/after_transition_state
+    # * before/after_transition
+    # 
+    # The following class shows an example of some of these hooks:
     # 
     #   class VehicleObserver < ActiveRecord::Observer
     #     def before_save(vehicle)
@@ -177,6 +228,10 @@ module StateMachine
     #     end
     #   end
     module ActiveRecord
+      # The default options to use for state machines using this integration
+      class << self; attr_reader :defaults; end
+      @defaults = {:action => :save}
+      
       # Should this integration be used for state machines in the given class?
       # Classes that inherit from ActiveRecord::Base will automatically use
       # the ActiveRecord integration.
@@ -190,61 +245,57 @@ module StateMachine
         I18n.load_path << "#{File.dirname(__FILE__)}/active_record/locale.rb" if Object.const_defined?(:I18n)
       end
       
-      # Adds a validation error to the given object after failing to fire a
-      # specific event
-      def invalidate(object, event)
+      # Adds a validation error to the given object 
+      def invalidate(object, attribute, message, values = [])
         if Object.const_defined?(:I18n)
-          object.errors.add(attribute, :invalid_transition,
-            :event => event.name,
-            :value => state_for(object).name,
-            :default => @invalid_message
-          )
+          options = values.inject({}) {|options, (key, value)| options[key] = value; options}
+          object.errors.add(attribute, message, options.merge(
+            :default => @messages[message]
+          ))
         else
-          object.errors.add(attribute, invalid_message(object, event))
+          object.errors.add(attribute, generate_message(message, values))
         end
       end
       
-      # Resets an errors previously added when invalidating the given object
+      # Resets any errors previously added when invalidating the given object
       def reset(object)
         object.errors.clear
       end
       
-      # Runs a new database transaction, rolling back any changes by raising
-      # an ActiveRecord::Rollback exception if the yielded block fails
-      # (i.e. returns false).
-      def within_transaction(object)
-        object.class.transaction {raise ::ActiveRecord::Rollback unless yield}
-      end
-      
       protected
         # Adds the default callbacks for notifying ActiveRecord observers
         # before/after a transition has been performed.
         def after_initialize
-          # Observer callbacks never halt the chain; result is ignored
           callbacks[:before] << Callback.new {|object, transition| notify(:before, object, transition)}
-          callbacks[:after] << Callback.new {|object, transition, result| notify(:after, object, transition)}
-        end
-        
-        # Sets the default action for all ActiveRecord state machines to +save+
-        def default_action
-          :save
+          callbacks[:after] << Callback.new {|object, transition| notify(:after, object, transition)}
         end
         
         # Skips defining reader/writer methods since this is done automatically
-        def define_attribute_accessor
+        def define_state_accessor
         end
         
         # Adds support for defining the attribute predicate, while providing
         # compatibility with the default predicate which determines whether
         # *anything* is set for the attribute's value
-        def define_attribute_predicate
+        def define_state_predicate
           attribute = self.attribute
           
           # Still use class_eval here instance of define_instance_method since
-          # we need to directly override the method defined in the model
-          owner_class.class_eval do
+          # we need to be able to call +super+
+          @instance_helper_module.class_eval do
             define_method("#{attribute}?") do |*args|
-              args.empty? ? super(*args) : self.class.state_machines[attribute].state?(self, *args)
+              args.empty? ? super(*args) : self.class.state_machine(attribute).states.matches?(self, *args)
+            end
+          end
+        end
+        
+        # Adds hooks into validation for automatically firing events
+        def define_action_helpers
+          if super && action == :save
+            @instance_helper_module.class_eval do
+              define_method(:valid?) do |*args|
+                self.class.state_machines.fire_attribute_events(self, :save, false) { super(*args) }
+              end
             end
           end
         end
@@ -263,6 +314,13 @@ module StateMachine
           define_scope(name, lambda {|values| {:conditions => ["#{attribute} NOT IN (?)", values]}})
         end
         
+        # Runs a new database transaction, rolling back any changes by raising
+        # an ActiveRecord::Rollback exception if the yielded block fails
+        # (i.e. returns false).
+        def transaction(object)
+          object.class.transaction {raise ::ActiveRecord::Rollback unless yield}
+        end
+        
         # Creates a new callback in the callback chain, always inserting it
         # before the default Observer callbacks that were created after
         # initialization.
@@ -288,7 +346,7 @@ module StateMachine
           # Created the scope and then override it with state translation
           owner_class.named_scope(name)
           owner_class.scopes[name] = lambda do |klass, *states|
-            machine_states = klass.state_machines[attribute].states
+            machine_states = klass.state_machine(attribute).states
             values = states.flatten.map {|state| machine_states.fetch(state).value}
             
             ::ActiveRecord::NamedScope::Scope.new(klass, scope.call(values))
@@ -300,18 +358,38 @@ module StateMachine
         # Notifies observers on the given object that a callback occurred
         # involving the given transition.  This will attempt to call the
         # following methods on observers:
-        # * #{type}_#{event}
+        # * #{type}_#{qualified_event}_from_#{from}_to_#{to}
+        # * #{type}_#{qualified_event}_from_#{from}
+        # * #{type}_#{qualified_event}_to_#{to}
+        # * #{type}_#{qualified_event}
+        # * #{type}_transition_#{attribute}_from_#{from}_to_#{to}
+        # * #{type}_transition_#{attribute}_from_#{from}
+        # * #{type}_transition_#{attribute}_to_#{to}
+        # * #{type}_transition_#{attribute}
         # * #{type}_transition
         # 
         # This will always return true regardless of the results of the
         # callbacks.
         def notify(type, object, transition)
-          qualified_event = namespace ? "#{transition.event}_#{namespace}" : transition.event
-          ["#{type}_#{qualified_event}", "#{type}_transition"].each do |method|
-            object.class.changed
-            object.class.notify_observers(method, object, transition)
+          attribute = transition.attribute
+          event = transition.qualified_event
+          from = transition.from_name
+          to = transition.to_name
+          
+          # Machine-specific updates
+          ["#{type}_#{event}", "#{type}_transition_#{attribute}"].each do |event_segment|
+            ["_from_#{from}", nil].each do |from_segment|
+              ["_to_#{to}", nil].each do |to_segment|
+                object.class.changed
+                object.class.notify_observers([event_segment, from_segment, to_segment].join, object, transition)
+              end
+            end
           end
           
+          # Generic updates
+          object.class.changed
+          object.class.notify_observers("#{type}_transition", object, transition)
+          
           true
         end
     end

data/lib/state_machine/integrations/data_mapper/observer.rb

@@ -2,7 +2,7 @@ module StateMachine
   module Integrations #:nodoc:
     module DataMapper
       # Adds support for creating before/after transition callbacks within a
-      # DataMapper observer.  These callbacks behave very similarly to
+      # DataMapper observer.  These callbacks behave very similar to
       # before/after hooks during save/update/destroy/etc., but with the
       # following modifications:
       # * Each callback can define a set of transition conditions (i.e. guards)
@@ -18,8 +18,8 @@ module StateMachine
       #     
       #     observe Vehicle, Switch, Project
       #     
-      #     after_transition do |transition, saved|
-      #       Audit.log(self, transition) if saved
+      #     after_transition do |transition|
+      #       Audit.log(self, transition)
       #     end
       #   end
       # 
@@ -35,7 +35,6 @@ module StateMachine
       #   require 'dm-observer'
       # 
       # If dm-observer is not available, then this feature will be skipped.
-      # 
       module Observer
         include MatcherHelpers
         
@@ -96,59 +95,11 @@ module StateMachine
         end
         
         # Creates a callback that will be invoked *after* a transition is
-        # performed, so long as the given configuration options match the
-        # transition.  Each part of the transition (event, to state, from state)
-        # must match in order for the callback to get invoked.
-        # 
-        # See StateMachine::Machine#after_transition for more
-        # information about the various configuration options available.
-        # 
-        # == Examples
-        # 
-        #   class Vehicle
-        #     include DataMapper::Resource
-        #     
-        #     property :id, Serial
-        #     property :state, :String
-        #     
-        #     state_machine :initial => :parked do
-        #       event :ignite do
-        #         transition :parked => :idling
-        #       end
-        #     end
-        #   end
-        #   
-        #   class VehicleObserver
-        #     include DataMapper::Observer
-        #     
-        #     observe Vehicle
-        #     
-        #     after :save do |saved|
-        #       # log message
-        #     end
-        #     
-        #     # Target all state machines
-        #     after_transition :parked => :idling, :on => :ignite do
-        #       # put on seatbelt
-        #     end
-        #     
-        #     # Target a specific state machine
-        #     after_transition :state, any => :idling do
-        #       # put on seatbelt
-        #     end
-        #     
-        #     # Target all state machines without requirements
-        #     after_transition do |transition, saved|
-        #       if saved
-        #         # log message
-        #       end
-        #     end
-        #   end
+        # performed so long as the given configuration options match the
+        # transition.
         # 
-        # *Note* that in each of the above +before_transition+ callbacks, the
-        # callback is executed within the context of the object (i.e. the
-        # Vehicle instance being transition).  This means that +self+ refers
-        # to the vehicle record within each callback block.
+        # See +before_transition+ for a description of the possible configurations
+        # for defining callbacks.
         def after_transition(*args, &block)
           add_transition_callback(:after, *args, &block)
         end
@@ -157,20 +108,25 @@ module StateMachine
           # Adds the transition callback to a specific machine or all of the
           # state machines for each observed class.
           def add_transition_callback(type, *args, &block)
-            if args.first && !args.first.is_a?(Hash)
-              # Specific attribute is being targeted
-              attribute = args.first
-              transition_args = args[1..-1]
+            if args.any? && !args.first.is_a?(Hash)
+              # Specific attribute(s) being targeted
+              attributes = args
+              args = args.last.is_a?(Hash) ? [args.pop] : []
             else
               # Target all state machines
-              attribute = nil
-              transition_args = args
+              attributes = nil
             end
             
             # Add the transition callback to each class being observed
             observing.each do |klass|
-              state_machines = attribute ? [klass.state_machines[attribute]] : klass.state_machines.values
-              state_machines.each {|machine| machine.send("#{type}_transition", *transition_args, &block)}
+              state_machines =
+                if attributes
+                  attributes.map {|attribute| klass.state_machines.fetch(attribute)}
+                else
+                  klass.state_machines.values
+                end
+              
+              state_machines.each {|machine| machine.send("#{type}_transition", *args, &block)}
             end if observing
           end
       end

data/lib/state_machine/integrations/data_mapper.rb

@@ -39,11 +39,43 @@ module StateMachine
     #   vehicle.ignite                    # => true
     #   vehicle.reload                    # => #<Vehicle id=1 name="Ford Explorer" state="idling">
     # 
+    # == Events
+    # 
+    # As described in StateMachine::InstanceMethods#state_machine, event
+    # attributes are created for every machine that allow transitions to be
+    # performed automatically when the object's action (in this case, :save)
+    # is called.
+    # 
+    # In DataMapper, these automated events are run in the following order:
+    # * before validation - If validation feature loaded, run before callbacks and persist new states, then validate
+    # * before save - If validation feature was skipped/not loaded, run before callbacks and persist new states, then save
+    # * after save - Run after callbacks
+    # 
+    # For example,
+    # 
+    #   vehicle = Vehicle.create          # => #<Vehicle id=1 name=nil state="parked">
+    #   vehicle.state_event               # => nil
+    #   vehicle.state_event = 'invalid'
+    #   vehicle.valid?                    # => false
+    #   vehicle.errors                    # => #<DataMapper::Validate::ValidationErrors:0xb7a48b54 @errors={"state_event"=>["is invalid"]}>
+    #   
+    #   vehicle.state_event = 'ignite'
+    #   vehicle.valid?                    # => true
+    #   vehicle.save                      # => true
+    #   vehicle.state                     # => "idling"
+    #   vehicle.state_event               # => nil
+    # 
+    # Note that this can also be done on a mass-assignment basis:
+    # 
+    #   vehicle = Vehicle.create(:state_event => 'ignite')  # => #<Vehicle id=1 name=nil state="idling">
+    #   vehicle.state                                       # => "idling"
+    # 
     # == Transactions
     # 
-    # In order to ensure that any changes made during transition callbacks
-    # are rolled back during a failed attempt, every transition is wrapped
-    # within a transaction.
+    # By default, the use of transactions during an event transition is
+    # turned off to be consistent with DataMapper.  This means that if
+    # changes are made to the database during a before callback, but the the
+    # transition fails to complete, those changes will *not* be rolled back.
     # 
     # For example,
     # 
@@ -63,12 +95,15 @@ module StateMachine
     #   
     #   vehicle = Vehicle.create      # => #<Vehicle id=1 name=nil state="parked">
     #   vehicle.ignite                # => false
-    #   Message.all.count             # => 0
+    #   Message.all.count             # => 1
     # 
-    # *Note* that only before callbacks that halt the callback chain and
-    # failed attempts to save the record will result in the transaction being
-    # rolled back.  If an after callback halts the chain, the previous result
-    # still applies and the transaction is *not* rolled back.
+    # To turn on transactions:
+    # 
+    #   class Vehicle < ActiveRecord::Base
+    #     state_machine :initial => :parked, :use_transactions => true do
+    #       ...
+    #     end
+    #   end
     # 
     # == Validation errors
     # 
@@ -81,7 +116,7 @@ module StateMachine
     # 
     #   vehicle = Vehicle.create(:state => 'idling')  # => #<Vehicle id=1 name=nil state="idling">
     #   vehicle.ignite                                # => false
-    #   vehicle.errors.full_messages                  # => ["cannot be transitioned via :ignite from :idling"]
+    #   vehicle.errors.full_messages                  # => ["cannot transition via \"ignite\""]
     # 
     # If an event fails to fire because of a validation error on the record and
     # *not* because a matching transition was not available, no error messages
@@ -164,6 +199,10 @@ module StateMachine
     # support for DataMapper observers.  See StateMachine::Integrations::DataMapper::Observer
     # for more information.
     module DataMapper
+      # The default options to use for state machines using this integration
+      class << self; attr_reader :defaults; end
+      @defaults = {:action => :save, :use_transactions => false}
+        
       # Should this integration be used for state machines in the given class?
       # Classes that include DataMapper::Resource will automatically use the
       # DataMapper integration.
@@ -176,31 +215,31 @@ module StateMachine
         require 'state_machine/integrations/data_mapper/observer' if ::DataMapper.const_defined?('Observer')
       end
       
-      # Adds a validation error to the given object after failing to fire a
-      # specific event
-      def invalidate(object, event)
-        object.errors.add(attribute, invalid_message(object, event)) if object.respond_to?(:errors)
+      # Adds a validation error to the given object
+      def invalidate(object, attribute, message, values = [])
+        object.errors.add(attribute, generate_message(message, values)) if object.respond_to?(:errors)
       end
       
-      # Resets an errors previously added when invalidating the given object
+      # Resets any errors previously added when invalidating the given object
       def reset(object)
-        object.errors.clear
-      end
-      
-      # Runs a new database transaction, rolling back any changes if the
-      # yielded block fails (i.e. returns false).
-      def within_transaction(object)
-        object.class.transaction {|t| t.rollback unless yield}
+        object.errors.clear if object.respond_to?(:errors)
       end
       
       protected
-        # Sets the default action for all DataMapper state machines to +save+
-        def default_action
-          :save
+        # Skips defining reader/writer methods since this is done automatically
+        def define_state_accessor
+          owner_class.property(attribute, String) unless owner_class.properties.has_property?(attribute)
         end
         
-        # Skips defining reader/writer methods since this is done automatically
-        def define_attribute_accessor
+        # Adds hooks into validation for automatically firing events
+        def define_action_helpers
+          if super && action == :save
+            @instance_helper_module.class_eval do
+              define_method(:valid?) do |*args|
+                self.class.state_machines.fire_attribute_events(self, :save, false) { super(*args) }
+              end
+            end
+          end
         end
         
         # Creates a scope for finding records *with* a particular state or
@@ -217,6 +256,12 @@ module StateMachine
           lambda {|resource, values| resource.all(attribute.to_sym.not => values)}
         end
         
+        # Runs a new database transaction, rolling back any changes if the
+        # yielded block fails (i.e. returns false).
+        def transaction(object)
+          object.class.transaction {|t| t.rollback unless yield}
+        end
+        
         # Creates a new callback in the callback chain, always ensuring that
         # it's configured to bind to the object as this is the convention for
         # DataMapper/Extlib callbacks