pluginaweek-state_machine 0.7.6 → 0.8.0

data/CHANGELOG.rdoc

@@ -1,6 +1,26 @@
 == master
 
-* Add support for customizing generated methods like #{attribute}_name using :as instead of always prefixing with the attribute name
+== 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
+* Add support for :attribute to customize the attribute target, assuming the name is the first argument of #state_machine
 * Simplify reading from / writing to machine-related attributes on objects
 * Fix locale for ActiveRecord getting added to the i18n load path multiple times [Reiner Dieterich]
 * Fix callbacks, guards, and state-driven behaviors not always working on tainted classes [Brandon Dimcheff]

data/README.rdoc

@@ -412,7 +412,7 @@ To generate multiple state machine graphs:
 
 *Note* that this will generate a different file for every state machine defined
 in the class.  The generated files will use an output filename of the format
-#{class_name}_#{attribute}.#{format}.
+#{class_name}_#{machine_name}.#{format}.
 
 For examples of actual images generated using this task, see those under the
 examples folder.

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'state_machine'
-  s.version           = '0.7.5'
+  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

@@ -5,10 +5,12 @@ require 'state_machine/machine'
 # functionality on any Ruby class.
 module StateMachine
   module MacroMethods
-    # Creates a new state machine for the given attribute.  The default
-    # attribute, if not specified, is <tt>:state</tt>.
+    # Creates a new state machine with the given name.  The default name, if not
+    # specified, is <tt>:state</tt>.
     # 
     # Configuration options:
+    # * <tt>:attribute</tt> - The name of the attribute to store the state value
+    #   in.  By default, this is the same as the name of the machine.
     # * <tt>:initial</tt> - The initial state of the attribute. This can be a
     #   static state or a lambda block which will be evaluated at runtime
     #   (e.g. lambda {|vehicle| vehicle.speed == 0 ? :parked : :idling}).
@@ -16,10 +18,6 @@ module StateMachine
     # * <tt>:action</tt> - The instance method to invoke when an object
     #   transitions. Default is nil unless otherwise specified by the
     #   configured integration.
-    # * <tt>:as</tt> - The name to use for prefixing all generated machine
-    #   instance / class methods (e.g. if the attribute is +state_id+, then
-    #   "state" would generate :state_name, :state_transitions, etc. instead of
-    #   :state_id_name and :state_id_transitions)
     # * <tt>:namespace</tt> - The name to use for namespacing all generated
     #   state / event instance methods (e.g. "heater" would generate
     #   :turn_on_heater and :turn_off_heater for the :turn_on/:turn_off events).
@@ -49,12 +47,12 @@ 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
     # 
-    # With the default attribute and no configuration:
+    # With the default name/attribute and no configuration:
     # 
     #   class Vehicle
     #     state_machine do
@@ -64,13 +62,14 @@ module StateMachine
     #     end
     #   end
     # 
-    # The above example will define a state machine for the +state+ attribute
-    # on the class.  Every vehicle will start without an initial state.
+    # The above example will define a state machine named "state" that will
+    # store the value in the +state+ attribute.  Every vehicle will start
+    # without an initial state.
     # 
-    # With a custom attribute:
+    # With a custom name / attribute:
     # 
     #   class Vehicle
-    #     state_machine :status do
+    #     state_machine :status, :attribute => :status_value do
     #       ...
     #     end
     #   end
@@ -94,7 +93,8 @@ module StateMachine
     # == Instance Methods
     # 
     # The following instance methods will be automatically generated by the
-    # state machine.  Any existing methods will not be overwritten.
+    # state machine based on the *name* of the machine.  Any existing methods
+    # will not be overwritten.
     # * <tt>state</tt> - Gets the current value for the attribute
     # * <tt>state=(value)</tt> - Sets the current value for the attribute
     # * <tt>state?(name)</tt> - Checks the given state name against the current
@@ -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
@@ -295,55 +298,11 @@ module StateMachine
     # see StateMachine::Machine#before_transition and
     # StateMachine::Machine#after_transition.
     # 
-    # == Attribute aliases
-    # 
-    # When a state machine is defined, several methods are generated scoped by
-    # the name of the attribute, such as (if the attribute were "state"):
-    # * <tt>state_name</tt>
-    # * <tt>state_event</tt>
-    # * <tt>state_transitions</tt>
-    # * etc.
-    # 
-    # If the attribute for the machine were something less common, such as
-    # "state_id" or "state_value", this makes for more awkward scoped methods.
-    # 
-    # Rather than scope based on the attribute, these methods can be customized
-    # using the <tt>:as</tt> option as essentially an alias.
-    # 
-    # For example,
-    # 
-    #   class Vehicle
-    #     state_machine :state_id, :as => :state do
-    #       event :turn_on do
-    #         transition all => :on
-    #       end
-    #       
-    #       event :turn_off do
-    #         transition all => :off
-    #       end
-    #       
-    #       state :on, :value => 1
-    #       state :off, :value => 2
-    #     end
-    #   end
-    # 
-    # ...will generate the following methods:
-    # * <tt>state_name</tt>
-    # * <tt>state_event</tt>
-    # * <tt>state_transitions</tt>
-    # 
-    # ...instead of:
-    # * <tt>state_id_name</tt>
-    # * <tt>state_id_event</tt>
-    # * <tt>state_id_transitions</tt>
-    # 
-    # However, it will continue to read and write to the +state_id+ attribute.
-    # 
     # == Namespaces
     # 
     # When a namespace is configured for a state machine, the name provided
     # will be used in generating the instance methods for interacting with
-    # events/states in the machine.  This is particularly useful when a class
+    # states/events in the machine.  This is particularly useful when a class
     # has multiple state machines and it would be difficult to differentiate
     # between the various states / events.
     # 
@@ -398,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,
     # 
@@ -412,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
       
@@ -190,7 +191,7 @@ module StateMachine
       if transition = transition_for(object)
         transition.perform(*args)
       else
-        machine.invalidate(object, machine.attribute, :invalid_transition, [[:event, name]])
+        machine.invalidate(object, :state, :invalid_transition, [[:event, name]])
         false
       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

@@ -84,14 +84,14 @@ module StateMachine
     # you can build two state machines (one public and one protected) like so:
     # 
     #   class Vehicle < ActiveRecord::Base
-    #     alias_attribute :public_state # Allow both machines to share the same state
     #     attr_protected :state_event # Prevent access to events in the first machine
     #     
     #     state_machine do
     #       # Define private events here
     #     end
     #     
-    #     state_machine :public_state do
+    #     # Public machine targets the same state as the private machine
+    #     state_machine :public_state, :attribute => :state do
     #       # Define public events here
     #     end
     #   end
@@ -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,11 +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(attr)
-            machine.invalidate(record, attr, :invalid) unless machine.states.match(record)
+            machine = record.class.state_machine(name)
+            machine.invalidate(record, :state, :invalid) unless machine.states.match(record)
           end
         end
         
@@ -321,13 +359,12 @@ module StateMachine
         # *anything* is set for the attribute's value
         def define_state_predicate
           name = self.name
-          attribute = self.attribute
           
           # Still use class_eval here instance of define_instance_method since
           # we need to be able to call +super+
           @instance_helper_module.class_eval do
             define_method("#{name}?") do |*args|
-              args.empty? ? super(*args) : self.class.state_machine(attribute).states.matches?(self, *args)
+              args.empty? ? super(*args) : self.class.state_machine(name).states.matches?(self, *args)
             end
           end
         end
@@ -388,17 +425,18 @@ module StateMachine
         # inheritance is respected properly.
         def define_scope(name, scope)
           name = name.to_sym
-          attribute = self.attribute
+          machine_name = self.name
           
-          # Created the scope and then override it with state translation
+          # Create 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_machine(attribute).states
+            machine_states = klass.state_machine(machine_name).states
             values = states.flatten.map {|state| machine_states.fetch(state).value}
             
             ::ActiveRecord::NamedScope::Scope.new(klass, scope.call(values))
           end
           
+          # Prevent the Machine class from wrapping the scope
           false
         end
         
@@ -409,10 +447,10 @@ module StateMachine
         # * #{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_#{machine_name}_from_#{from}_to_#{to}
+        # * #{type}_transition_#{machine_name}_from_#{from}
+        # * #{type}_transition_#{machine_name}_to_#{to}
+        # * #{type}_transition_#{machine_name}
         # * #{type}_transition
         # 
         # This will always return true regardless of the results of the