state_machine 0.7.6 → 0.8.0

data/CHANGELOG.rdoc

@@ -1,5 +1,22 @@
 == master
 
+== 0.8.0 / 2009-08-15
+
+* Add support for DataMapper 0.10.0
+* Always interpet nil return values from actions as failed attempts
+* Fix loopbacks not causing records to save in ORM integrations if no other fields were changed
+* Fix events not failing with useful errors when an object's state is invalid
+* Use more friendly NoMethodError messages for state-driven behaviors
+* Fix before_transition callbacks getting run twice when using event attributes in ORM integrations
+* Add the ability to query for the availability of specific transitions on an object
+* Allow after_transition callbacks to be explicitly run on failed attempts
+* By default, don't run after_transition callbacks on failed attempts
+* Fix not allowing multiple methods to be specified as arguments in callbacks
+* Fix initial states being set when loading records from the database in Sequel integration
+* Allow static initial states to be set earlier in the initialization of an object
+* Use friendly validation errors for nil states
+* Fix states not being validated properly when using custom names in ActiveRecord / DataMapper integrations
+
 == 0.7.6 / 2009-06-17
 
 * Allow multiple state machines on the same class to target the same attribute

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'state_machine'
-  s.version           = '0.7.6'
+  s.version           = '0.8.0'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Adds support for creating state machines for attributes on any Ruby class'
   s.description       = s.summary

data/lib/state_machine.rb

@@ -47,7 +47,7 @@ module StateMachine
     # result, you will not be able to access any class methods unless you refer
     # to them directly (i.e. specifying the class name).
     # 
-    # For examples on the types of configured state machines and blocks, see
+    # For examples on the types of state machine configurations and blocks, see
     # the section below.
     # 
     # == Examples
@@ -102,8 +102,11 @@ module StateMachine
     # * <tt>state_name</tt> - Gets the name of the state for the current value
     # * <tt>state_events</tt> - Gets the list of events that can be fired on
     #   the current object's state (uses the *unqualified* event names)
-    # * <tt>state_transitions</tt> - Gets the list of possible transitions
-    #   that can be made on the current object's state
+    # * <tt>state_transitions(requirements = {})</tt> - Gets the list of possible
+    #   transitions that can be made on the current object's state.  Additional
+    #   requirements, such as the :from / :to state and :on event can be specified
+    #   to restrict the transitions to select.  By default, the current state
+    #   will be used for the :from state.
     # 
     # For example,
     # 
@@ -253,7 +256,7 @@ module StateMachine
     # 
     #   class Vehicle
     #     include DataMapper::Resource
-    #     property :id, Integer, :serial => true
+    #     property :id, Serial
     #     
     #     state_machine :initial => :parked do
     #       event :ignite do
@@ -354,7 +357,7 @@ module StateMachine
     # 
     # For integrations that support it, a group of default scope filters will
     # be automatically created for assisting in finding objects that have the
-    # attribute set to the value for a given set of states.
+    # attribute set to one of a given set of states.
     # 
     # For example,
     # 
@@ -368,9 +371,9 @@ module StateMachine
     # :with_state, :with_states, :without_state, or :without_states), then a
     # scope will not be defined for that name.
     # 
-    # See StateMachine::Machine for more information about using
-    # integrations and the individual integration docs for information about
-    # the actual scopes that are generated.
+    # See StateMachine::Machine for more information about using integrations
+    # and the individual integration docs for information about the actual
+    # scopes that are generated.
     def state_machine(*args, &block)
       StateMachine::Machine.find_or_create(self, *args, &block)
     end

data/lib/state_machine/callback.rb

@@ -142,7 +142,7 @@ module StateMachine
     # requirements configured for this callback.
     # 
     # If a terminator has been configured and it matches the result from the
-    # evaluated method, then the callback chain should be halted
+    # evaluated method, then the callback chain should be halted.
     def call(object, context = {}, *args)
       if @guard.matches?(object, context)
         @methods.each do |method|

data/lib/state_machine/event.rb

@@ -65,8 +65,8 @@ module StateMachine
     # state to be +idling+ if it's current state is +parked+ or +first_gear+
     # if it's current state is +idling+.
     # 
-    # To help defining these implicit transitions, a set of helpers are available
-    # for defining slightly more complex matching:
+    # To help define these implicit transitions, a set of helpers are available
+    # for slightly more complex matching:
     # * <tt>all</tt> - Matches every state in the machine
     # * <tt>all - [:parked, :idling, ...]</tt> - Matches every state except those specified
     # * <tt>any</tt> - An alias for +all+ (matches every state in the machine)
@@ -147,7 +147,7 @@ module StateMachine
       # requirements
       assert_valid_keys(options, :from, :to, :except_from, :if, :unless) if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
       
-      guards << guard = Guard.new(options)
+      guards << guard = Guard.new(options.merge(:on => name))
       @known_states |= guard.known_states
       guard
     end
@@ -162,15 +162,16 @@ module StateMachine
     
     # Finds and builds the next transition that can be performed on the given
     # object.  If no transitions can be made, then this will return nil.
-    def transition_for(object)
-      from = machine.states.match(object).name
+    def transition_for(object, requirements = {})
+      requirements[:from] = machine.states.match!(object).name unless custom_from_state = requirements.include?(:from)
       
       guards.each do |guard|
-        if match = guard.match(object, :from => from)
+        if match = guard.match(object, requirements)
           # Guard allows for the transition to occur
+          from = requirements[:from]
           to = match[:to].values.empty? ? from : match[:to].values.first
           
-          return Transition.new(object, machine, name, from, to)
+          return Transition.new(object, machine, name, from, to, !custom_from_state)
         end
       end
       
@@ -244,7 +245,7 @@ module StateMachine
         
         # Fires the event, raising an exception if it fails
         machine.define_instance_method("#{qualified_name}!") do |machine, object, *args|
-          object.send(qualified_name, *args) || raise(StateMachine::InvalidTransition, "Cannot transition #{machine.name} via :#{name} from #{machine.states.match(object).name.inspect}")
+          object.send(qualified_name, *args) || raise(StateMachine::InvalidTransition, "Cannot transition #{machine.name} via :#{name} from #{machine.states.match!(object).name.inspect}")
         end
       end
   end

data/lib/state_machine/event_collection.rb

@@ -34,6 +34,14 @@ module StateMachine
     
     # Gets the list of transitions that can be run on the given object.
     # 
+    # Valid requirement options:
+    # * <tt>:from</tt> - One or more states being transitioned from.  If none
+    #   are specified, then this will be the object's current state.
+    # * <tt>:to</tt> - One or more states being transitioned to.  If none are
+    #   specified, then this will match any to state.
+    # * <tt>:on</tt> - One or more events that fire the transition.  If none
+    #   are specified, then this will match any event.
+    # 
     # == Examples
     # 
     #   class Vehicle
@@ -50,22 +58,25 @@ module StateMachine
     #   
     #   events = Vehicle.state_machine.events
     #   
-    #   vehicle = Vehicle.new                   # => #<Vehicle:0xb7c464b0 @state="parked">
-    #   events.transitions_for(vehicle)         # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+    #   vehicle = Vehicle.new                             # => #<Vehicle:0xb7c464b0 @state="parked">
+    #   events.transitions_for(vehicle)                   # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
     #   
     #   vehicle.state = 'idling'
-    #   events.transitions_for(vehicle)         # => [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>]
-    def transitions_for(object)
-      map {|event| event.transition_for(object)}.compact
+    #   events.transitions_for(vehicle)                   # => [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>]
+    #   
+    #   # Search for explicit transitions regardless of the current state
+    #   events.transitions_for(vehicle, :from => :parked) # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+    def transitions_for(object, requirements = {})
+      map {|event| event.transition_for(object, requirements)}.compact
     end
     
     # Gets the transition that should be performed for the event stored in the
     # given object's event attribute.  This also takes an additional parameter
-    # for automatically invalidating the object if the event or transition
-    # are invalid.  By default, this is turned off.
+    # for automatically invalidating the object if the event or transition are
+    # invalid.  By default, this is turned off.
     # 
-    # *Note* that if a transition has already been generated for the event,
-    # then that transition will be used.
+    # *Note* that if a transition has already been generated for the event, then
+    # that transition will be used.
     # 
     # == Examples
     # 
@@ -97,7 +108,7 @@ module StateMachine
         if event = self[event_name.to_sym, :name]
           unless result = machine.read(object, :event_transition) || event.transition_for(object)
             # No valid transition: invalidate
-            machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).name]]) if invalidate
+            machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).name || 'nil']]) if invalidate
             result = false
           end
         else

data/lib/state_machine/extensions.rb

@@ -22,15 +22,6 @@ module StateMachine
   end
   
   module InstanceMethods
-    # Defines the initial values for state machine attributes.  The values
-    # will be set *after* the original initialize method is invoked.  This is
-    # necessary in order to ensure that the object is initialized before
-    # dynamic initial attributes are evaluated.
-    def initialize(*args, &block)
-      super
-      initialize_state_machines
-    end
-    
     # Runs one or more events in parallel.  All events will run through the
     # following steps:
     # * Before callbacks
@@ -151,8 +142,8 @@ module StateMachine
     end
     
     protected
-      def initialize_state_machines #:nodoc:
-        self.class.state_machines.initialize_states(self)
+      def initialize_state_machines(options = {}) #:nodoc:
+        self.class.state_machines.initialize_states(self, options)
       end
   end
 end

data/lib/state_machine/guard.rb

@@ -24,6 +24,9 @@ module StateMachine
     # requirements contain a mapping of {:from => matcher, :to => matcher}.
     attr_reader :state_requirements
     
+    # The requirement for verifying the success of the event
+    attr_reader :success_requirement
+    
     # A list of all of the states known to this guard.  This will pull states
     # from the following options (in the same order):
     # * +from+ / +except_from+
@@ -39,6 +42,9 @@ module StateMachine
       # Build event requirement
       @event_requirement = build_matcher(options, :on, :except_on)
       
+      # Build success requirement
+      @success_requirement = options.delete(:include_failures) ? AllMatcher.instance : WhitelistMatcher.new([true])
+      
       if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on]).empty?
         # Explicit from/to requirements specified
         @state_requirements = [{:from => build_matcher(options, :from, :except_from), :to => build_matcher(options, :to, :except_to)}]
@@ -185,11 +191,16 @@ module StateMachine
       def match_query(query)
         query ||= {}
         
-        if match_event(query) && (state_requirement = match_states(query))
+        if match_success(query) && match_event(query) && (state_requirement = match_states(query))
           state_requirement.merge(:on => event_requirement)
         end
       end
       
+      # Verifies that the success requirement matches the given query
+      def match_success(query)
+        matches_requirement?(query, :success, success_requirement)
+      end
+      
       # Verifies that the event requirement matches the given query
       def match_event(query)
         matches_requirement?(query, :on, event_requirement)

data/lib/state_machine/integrations/active_record.rb

@@ -281,6 +281,14 @@ module StateMachine
         end
       end
       
+      # Forces the change in state to be recognized regardless of whether the
+      # state value actually changed
+      def write(object, attribute, value)
+        result = super
+        object.send("#{self.attribute}_will_change!") if attribute == :state && object.respond_to?("#{self.attribute}_will_change!")
+        result
+      end
+      
       # Adds a validation error to the given object 
       def invalidate(object, attribute, message, values = [])
         attribute = self.attribute(attribute)
@@ -308,13 +316,41 @@ module StateMachine
           callbacks[:after] << Callback.new {|object, transition| notify(:after, object, transition)}
         end
         
+        # Defines an initialization hook into the owner class for setting the
+        # initial state of the machine *before* any attributes are set on the
+        # object
+        def define_state_initializer
+          @instance_helper_module.class_eval <<-end_eval, __FILE__, __LINE__
+            # Ensure that the attributes setter gets used to force initialization
+            # of the state machines
+            def initialize(attributes = nil, *args)
+              attributes ||= {}
+              super
+            end
+            
+            # Hooks in to attribute initialization to set the states *prior*
+            # to the attributes being set
+            def attributes=(*args)
+              if new_record? && !@initialized_state_machines
+                @initialized_state_machines = true
+                
+                initialize_state_machines(:dynamic => false)
+                super
+                initialize_state_machines(:dynamic => true)
+              else
+                super
+              end
+            end
+          end_eval
+        end
+        
         # Skips defining reader/writer methods since this is done automatically
         def define_state_accessor
           name = self.name
           
           owner_class.validates_each(attribute) do |record, attr, value|
             machine = record.class.state_machine(name)
-            machine.invalidate(record, attr, :invalid) unless machine.states.match(record)
+            machine.invalidate(record, :state, :invalid) unless machine.states.match(record)
           end
         end
         

data/lib/state_machine/integrations/data_mapper.rb

@@ -247,9 +247,24 @@ module StateMachine
       
       # Loads additional files specific to DataMapper
       def self.extended(base) #:nodoc:
+        require 'dm-core/version' unless ::DataMapper.const_defined?('VERSION')
         require 'state_machine/integrations/data_mapper/observer' if ::DataMapper.const_defined?('Observer')
       end
       
+      # Forces the change in state to be recognized regardless of whether the
+      # state value actually changed
+      def write(object, attribute, value)
+        result = super
+        if attribute == :state && owner_class.properties.detect {|property| property.name == self.attribute}
+          if ::DataMapper::VERSION =~ /^(0\.\d\.)/ # Match anything < 0.10
+            object.original_values[self.attribute] = "#{value}-ignored"
+          else
+            object.original_attributes[owner_class.properties[self.attribute]] = "#{value}-ignored"
+          end
+        end
+        result
+      end
+      
       # Adds a validation error to the given object
       def invalidate(object, attribute, message, values = [])
         object.errors.add(self.attribute(attribute), generate_message(message, values)) if supports_validations?
@@ -257,7 +272,7 @@ module StateMachine
       
       # Resets any errors previously added when invalidating the given object
       def reset(object)
-        object.errors.clear if object.respond_to?(:errors)
+        object.errors.clear if supports_validations?
       end
       
       protected
@@ -268,7 +283,7 @@ module StateMachine
         
         # 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)
+          owner_class.property(attribute, String) unless owner_class.properties.detect {|property| property.name == attribute}
           
           if supports_validations?
             name = self.name

data/lib/state_machine/integrations/sequel.rb

@@ -226,6 +226,15 @@ module StateMachine
         require 'sequel/extensions/inflector' if ::Sequel.const_defined?('VERSION') && ::Sequel::VERSION >= '2.12.0'
       end
       
+      # Forces the change in state to be recognized regardless of whether the
+      # state value actually changed
+      def write(object, attribute, value)
+        result = super
+        column = self.attribute.to_sym
+        object.changed_columns << column if attribute == :state && owner_class.columns.include?(column) && !object.changed_columns.include?(column)
+        result
+      end
+      
       # Adds a validation error to the given object
       def invalidate(object, attribute, message, values = [])
         object.errors.add(self.attribute(attribute), generate_message(message, values))
@@ -237,12 +246,34 @@ module StateMachine
       end
       
       protected
+        # Defines an initialization hook into the owner class for setting the
+        # initial state of the machine *before* any attributes are set on the
+        # object
+        def define_state_initializer
+          @instance_helper_module.class_eval <<-end_eval, __FILE__, __LINE__
+            # Hooks in to attribute initialization to set the states *prior*
+            # to the attributes being set
+            def set(*args)
+              if new? && !@initialized_state_machines
+                @initialized_state_machines = true
+                
+                initialize_state_machines(:dynamic => false)
+                result = super
+                initialize_state_machines(:dynamic => true)
+                result
+              else
+                super
+              end
+            end
+          end_eval
+        end
+        
         # Skips defining reader/writer methods since this is done automatically
         def define_state_accessor
           name = self.name
           owner_class.validates_each(attribute) do |record, attr, value|
             machine = record.class.state_machine(name)
-            machine.invalidate(record, attr, :invalid) unless machine.states.match(record)
+            machine.invalidate(record, :state, :invalid) unless machine.states.match(record)
           end
         end
         

data/lib/state_machine/machine.rb

@@ -455,12 +455,6 @@ module StateMachine
     def owner_class=(klass)
       @owner_class = klass
       
-      # Add class-/instance-level methods to the owner class for state initialization
-      owner_class.class_eval do
-        extend StateMachine::ClassMethods
-        include StateMachine::InstanceMethods
-      end unless owner_class.included_modules.include?(StateMachine::InstanceMethods)
-      
       # Create modules for extending the class with state/event-specific methods
       class_helper_module = @class_helper_module = Module.new
       instance_helper_module = @instance_helper_module = Module.new
@@ -469,6 +463,16 @@ module StateMachine
         include instance_helper_module
       end
       
+      # Add class-/instance-level methods to the owner class for state initialization
+      unless owner_class.included_modules.include?(StateMachine::InstanceMethods)
+        owner_class.class_eval do
+          extend StateMachine::ClassMethods
+          include StateMachine::InstanceMethods
+        end
+        
+        define_state_initializer
+      end
+      
       # Record this machine as matched to the name in the current owner class.
       # This will override any machines mapped to the same name in any superclasses.
       owner_class.state_machines[name] = self
@@ -479,7 +483,7 @@ module StateMachine
     # creation time.
     def initial_state=(new_initial_state)
       @initial_state = new_initial_state
-      add_states([@initial_state]) unless @initial_state.is_a?(Proc)
+      add_states([@initial_state]) unless dynamic_initial_state?
       
       # Update all states to reflect the new initial state
       states.each {|state| state.initial = (state.name == @initial_state)}
@@ -565,7 +569,12 @@ module StateMachine
     #   vehicle.force_idle = false
     #   Vehicle.state_machine.initial_state(vehicle)  # => #<StateMachine::State name=:parked value="parked" initial=false>
     def initial_state(object)
-      states.fetch(@initial_state.is_a?(Proc) ? @initial_state.call(object) : @initial_state)
+      states.fetch(dynamic_initial_state? ? @initial_state.call(object) : @initial_state)
+    end
+    
+    # Whether a dynamic initial state is being used in the machine
+    def dynamic_initial_state?
+      @initial_state.is_a?(Proc)
     end
     
     # Customizes the definition of one or more states in the machine.
@@ -595,7 +604,7 @@ module StateMachine
     # 
     # In the above state machine, there are two states automatically discovered:
     # :parked and :idling.  These states, by default, will store their stringified
-    # equivalents when an object moves into that states (e.g. "parked" / "idling").
+    # equivalents when an object moves into that state (e.g. "parked" / "idling").
     # 
     # For legacy systems or when tying state machines into existing frameworks,
     # it's oftentimes necessary to need to store a different value for a state
@@ -878,7 +887,10 @@ module StateMachine
     # 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.
+    #   the current state of the object.  This will *not* run validations in
+    #   ORM integrations.  To check whether an event can fire *and* passes
+    #   validations, use event attributes (e.g. state_event) as described in the
+    #   "Events" documentation of each ORM integration.
     # * <tt>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.
@@ -1070,6 +1082,17 @@ module StateMachine
     #   before_transition :on => all - :ignite, :do => ...                  # Matches on every event except ignite
     #   before_transition :parked => :idling, :on => :ignite, :do => ...    # Matches from parked to idling on ignite
     # 
+    # == Result requirements
+    # 
+    # By default, after_transition callbacks will only be run if the transition
+    # was performed successfully.  A transition is successful if the machine's
+    # action is not configured or does not return false when it is invoked.
+    # In order to include failed attempts when running an after_transition
+    # callback, the :include_failures option can be specified like so:
+    # 
+    #   after_transition :include_failures => true, :do => ...  # Runs on all attempts to transition, including failures
+    #   after_transition :do => ...                             # Runs only on successful attempts to transition
+    # 
     # == Verbose Requirements
     # 
     # Requirements can also be defined using verbose options rather than the
@@ -1163,8 +1186,10 @@ module StateMachine
     # 
     # As can be seen, any number of transitions can be created using various
     # combinations of configuration options.
-    def before_transition(options = {}, &block)
-      add_callback(:before, options.is_a?(Hash) ? options : {:do => options}, &block)
+    def before_transition(*args, &block)
+      options = (args.last.is_a?(Hash) ? args.pop : {})
+      options[:do] = args if args.any?
+      add_callback(:before, options, &block)
     end
     
     # Creates a callback that will be invoked *after* a transition is
@@ -1172,8 +1197,10 @@ module StateMachine
     # 
     # See +before_transition+ for a description of the possible configurations
     # for defining callbacks.
-    def after_transition(options = {}, &block)
-      add_callback(:after, options.is_a?(Hash) ? options : {:do => options}, &block)
+    def after_transition(*args, &block)
+      options = (args.last.is_a?(Hash) ? args.pop : {})
+      options[:do] = args if args.any?
+      add_callback(:after, options, &block)
     end
     
     # Marks the given object as invalid with the given message.
@@ -1182,7 +1209,7 @@ module StateMachine
     def invalidate(object, attribute, message, values = [])
     end
     
-    # Resets an errors previously added when invalidating the given object
+    # Resets any errors previously added when invalidating the given object.
     # 
     # By default, this is a no-op.
     def reset(object)
@@ -1197,7 +1224,7 @@ module StateMachine
     # Runs a transaction, rolling back any changes if the yielded block fails.
     # 
     # This is only applicable to integrations that involve databases.  By
-    # default, this will not run any transactions, since the changes aren't
+    # default, this will not run any transactions since the changes aren't
     # taking place within the context of a database.
     def within_transaction(object)
       if use_transactions
@@ -1287,6 +1314,19 @@ module StateMachine
         end
       end
       
+      # Defines the initial values for state machine attributes.  Static values
+      # are set prior to the original initialize method and dynamic values are
+      # set *after* the initialize method in case it is dependent on it.
+      def define_state_initializer
+        @instance_helper_module.class_eval <<-end_eval, __FILE__, __LINE__
+          def initialize(*args)
+            initialize_state_machines(:dynamic => false)
+            super
+            initialize_state_machines(:dynamic => true)
+          end
+        end_eval
+      end
+      
       # Adds reader/writer methods for accessing the state attribute
       def define_state_accessor
         attribute = self.attribute