state_machine 1.0.3 → 1.1.0

data/gemfiles/sequel-3.13.0.gemfile.lock

@@ -1,24 +1,26 @@
 PATH
   remote: /home/aaron/Projects/Personal/pluginaweek/state_machine
   specs:
-    state_machine (1.0.2)
+    state_machine (1.0.3)
 
 GEM
   remote: http://www.rubygems.org/
   specs:
-    appraisal (0.3.8)
+    appraisal (0.4.0)
       bundler
       rake
-    rake (0.9.2)
-    rcov (0.9.10)
+    rake (0.9.2.2)
+    rcov (0.9.11)
+    rcov (0.9.11-java)
     sequel (3.13.0)
     sqlite3-ruby (1.3.1)
 
 PLATFORMS
+  java
   ruby
 
 DEPENDENCIES
-  appraisal (~> 0.3.8)
+  appraisal (~> 0.4.0)
   rake
   rcov
   sequel (= 3.13.0)

data/gemfiles/sequel-3.14.0.gemfile.lock

@@ -1,24 +1,26 @@
 PATH
   remote: /home/aaron/Projects/Personal/pluginaweek/state_machine
   specs:
-    state_machine (1.0.2)
+    state_machine (1.0.3)
 
 GEM
   remote: http://www.rubygems.org/
   specs:
-    appraisal (0.3.8)
+    appraisal (0.4.0)
       bundler
       rake
-    rake (0.9.2)
-    rcov (0.9.10)
+    rake (0.9.2.2)
+    rcov (0.9.11)
+    rcov (0.9.11-java)
     sequel (3.14.0)
     sqlite3-ruby (1.3.1)
 
 PLATFORMS
+  java
   ruby
 
 DEPENDENCIES
-  appraisal (~> 0.3.8)
+  appraisal (~> 0.4.0)
   rake
   rcov
   sequel (= 3.14.0)

data/gemfiles/sequel-3.23.0.gemfile.lock

@@ -1,24 +1,26 @@
 PATH
   remote: /home/aaron/Projects/Personal/pluginaweek/state_machine
   specs:
-    state_machine (1.0.2)
+    state_machine (1.0.3)
 
 GEM
   remote: http://www.rubygems.org/
   specs:
-    appraisal (0.3.8)
+    appraisal (0.4.0)
       bundler
       rake
-    rake (0.9.2)
-    rcov (0.9.10)
+    rake (0.9.2.2)
+    rcov (0.9.11)
+    rcov (0.9.11-java)
     sequel (3.23.0)
     sqlite3-ruby (1.3.1)
 
 PLATFORMS
+  java
   ruby
 
 DEPENDENCIES
-  appraisal (~> 0.3.8)
+  appraisal (~> 0.4.0)
   rake
   rcov
   sequel (= 3.23.0)

data/gemfiles/sequel-3.24.0.gemfile.lock

@@ -1,24 +1,26 @@
 PATH
   remote: /home/aaron/Projects/Personal/pluginaweek/state_machine
   specs:
-    state_machine (1.0.2)
+    state_machine (1.0.3)
 
 GEM
   remote: http://www.rubygems.org/
   specs:
-    appraisal (0.3.8)
+    appraisal (0.4.0)
       bundler
       rake
-    rake (0.9.2)
-    rcov (0.9.10)
+    rake (0.9.2.2)
+    rcov (0.9.11)
+    rcov (0.9.11-java)
     sequel (3.24.0)
     sqlite3-ruby (1.3.1)
 
 PLATFORMS
+  java
   ruby
 
 DEPENDENCIES
-  appraisal (~> 0.3.8)
+  appraisal (~> 0.4.0)
   rake
   rcov
   sequel (= 3.24.0)

data/gemfiles/sequel-3.29.0.gemfile.lock

@@ -6,19 +6,21 @@ PATH
 GEM
   remote: http://www.rubygems.org/
   specs:
-    appraisal (0.3.8)
+    appraisal (0.4.0)
       bundler
       rake
-    rake (0.9.2)
+    rake (0.9.2.2)
     rcov (0.9.11)
+    rcov (0.9.11-java)
     sequel (3.29.0)
     sqlite3-ruby (1.3.1)
 
 PLATFORMS
+  java
   ruby
 
 DEPENDENCIES
-  appraisal (~> 0.3.8)
+  appraisal (~> 0.4.0)
   rake
   rcov
   sequel (= 3.29.0)

data/lib/state_machine.rb

@@ -141,6 +141,9 @@ module StateMachine
     #   transitions that can be made on the current object's state
     # * <tt>state_paths(requirements = {})</tt> - Gets the list of sequences of
     #   transitions that can be run from the current object's state
+    # * <tt>fire_state_event(name, *args)</tt> - Fires an arbitrary event with
+    #   the given argument list. This is essentially the same as calling the
+    #   actual event method itself.
     # 
     # The <tt>state_events</tt>, <tt>state_transitions</tt>, and <tt>state_paths</tt>
     # helpers all take an optional set of requirements for determining what's
@@ -188,7 +191,7 @@ module StateMachine
     #   vehicle.state_events(:to => :parked)      # => []
     #   
     #   vehicle.state_transitions                 # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
-    #   vehicle.ignite
+    #   vehicle.ignite                            # => true
     #   vehicle.state_transitions                 # => [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>]
     #   
     #   vehicle.state_transitions(:on => :ignite) # => []
@@ -202,6 +205,9 @@ module StateMachine
     #                                             #     [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>,
     #                                             #      #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
     #                                             #   ]
+    #   
+    #   # Fire arbitrary events
+    #   vehicle.fire_state_event(:park)           # => true
     # 
     # == Attribute initialization
     # 

data/lib/state_machine/eval_helpers.rb

@@ -57,25 +57,24 @@ module StateMachine
         when Proc, Method
           args.unshift(object)
           arity = method.arity
-          limit = [0, 1].include?(arity) ? arity : args.length
           
-          # Procs don't support blocks in < Ruby 1.8.6, so it's tacked on as an
-          # argument for consistency across versions of Ruby (even though 1.9
-          # supports yielding within blocks)
+          # Procs don't support blocks in < Ruby 1.9, so it's tacked on as an
+          # argument for consistency across versions of Ruby
           if block_given? && Proc === method && arity != 0
             if [1, 2].include?(arity)
               # Force the block to be either the only argument or the 2nd one
               # after the object (may mean additional arguments get discarded)
-              limit = arity
-              args.insert(limit - 1, block)
+              args = args[0, arity - 1] + [block]
             else
               # Tack the block to the end of the args
-              limit += 1 unless limit < 0
-              args.push(block)
+              args << block
             end
+          else
+            # These method types are only called with 0, 1, or n arguments
+            args = args[0, arity] if [0, 1].include?(arity)
           end
           
-          method.call(*args[0, limit], &block)
+          method.call(*args, &block)
         when String
           eval(method, object.instance_eval {binding}, &block)
         else

data/lib/state_machine/event.rb

@@ -55,8 +55,7 @@ module StateMachine
       @name = name
       @qualified_name = machine.namespace ? :"#{name}_#{machine.namespace}" : name
       @human_name = options[:human_name] || @name.to_s.tr('_', ' ')
-      @branches = []
-      @known_states = []
+      reset
       
       # Output a warning if another event has a conflicting qualified name
       if conflict = machine.owner_class.state_machines.detect {|name, other_machine| other_machine != @machine && other_machine.events[qualified_name, :qualified_name]}
@@ -186,6 +185,15 @@ module StateMachine
       Transition.new(object, machine, name, state.name, state.name).run_callbacks(:before => false)
     end
     
+    # Resets back to the initial state of the event, with no branches / known
+    # states associated.  This allows you to redefine an event in situations
+    # where you either are re-using an existing state machine implementation
+    # or are subclassing machines.
+    def reset
+      @branches = []
+      @known_states = []
+    end
+    
     # Draws a representation of this event on the given graph.  This will
     # create 1 or more edges on the graph for each branch (i.e. transition)
     # configured.

data/lib/state_machine/integrations.rb

@@ -43,7 +43,6 @@ module StateMachine
     #   end
     #   
     #   class ActiveModelVehicle
-    #     include ActiveModel::Dirty
     #     include ActiveModel::Observing
     #     include ActiveModel::Validations
     #   end

data/lib/state_machine/integrations/active_model.rb

@@ -7,7 +7,6 @@ module StateMachine
     # If using ActiveModel directly within your class, then any one of the
     # following features need to be included in order for the integration to be
     # detected:
-    # * ActiveModel::Dirty
     # * ActiveModel::Observing
     # * ActiveModel::Validations
     # 
@@ -15,7 +14,6 @@ module StateMachine
     # ActiveModel class:
     # 
     #   class Vehicle
-    #     include ActiveModel::Dirty
     #     include ActiveModel::Observing
     #     include ActiveModel::Validations
     #     
@@ -99,6 +97,14 @@ module StateMachine
     #   vehicle.ignite                # => false
     #   vehicle.errors.full_messages  # => ["State cannot transition via \"ignite\""]
     # 
+    # In addition, if you're using the <tt>ignite!</tt> version of the event,
+    # then the failure reason (such as the current validation errors) will be
+    # included in the exception that gets raised when the event fails.  For
+    # example, assuming there's a validation on a field called +name+ on the class:
+    # 
+    #   vehicle = Vehicle.new
+    #   vehicle.ignite!       # => StateMachine::InvalidTransition: Cannot transition state via :ignite from :parked (Reason(s): Name cannot be blank)
+    # 
     # === Security implications
     # 
     # Beware that public event attributes mean that events can be fired
@@ -279,28 +285,46 @@ module StateMachine
     # 
     # == Dirty Attribute Tracking
     # 
-    # In order to hook in validation support for your model, the
-    # ActiveModel::Validations feature must be included.  If this is included
-    # then state attributes will always be properly marked as changed whether
-    # they were a callback or not.
+    # When using the ActiveModel::Dirty extension, your model will keep track of
+    # any changes that are made to attributes.  Depending on your ORM, an object
+    # will only be saved when there are attributes that have changed on the
+    # object.  When integrating with state_machine, typically the +state+ field
+    # will be marked as dirty after a transition occurs.  In some situations,
+    # however, this isn't the case.
     # 
-    # For example,
+    # If you define loopback transitions in your state machine, the value for
+    # the machine's attribute (e.g. state) will not change.  Unless you explicitly
+    # indicate so, this means that your object won't persist anything on a
+    # loopback.  For example:
     # 
     #   class Vehicle
+    #     include ActiveModel::Validations
     #     include ActiveModel::Dirty
     #     attr_accessor :state
     #     
     #     state_machine :initial => :parked do
     #       event :park do
-    #         transition :parked => :parked
+    #         transition :parked => :parked, ...
+    #       end
+    #     end
+    #   end
+    # 
+    # If, instead, you'd like your object to always persist regardless of
+    # whether the value actually changed, you can do so by using the
+    # <tt>#{attribute}_will_change!</tt> helpers or defining a +before_transition+
+    # callback that actually changes an attribute on the model.  For example:
+    # 
+    #   class Vehicle
+    #     ...
+    #     state_machine :initial => :parked do
+    #       before_transition all => same do |vehicle|
+    #         vehicle.state_will_change!
+    #         
+    #         # Alternative solution, updating timestamp
+    #         # vehicle.updated_at = Time.curent
     #       end
     #     end
     #   end
-    #   
-    #   vehicle = Vehicle.new
-    #   vehicle.changed         # => []
-    #   vehicle.park            # => true
-    #   vehicle.changed         # => ["state"]
     # 
     # == Creating new integrations
     # 
@@ -349,23 +373,10 @@ module StateMachine
       end
       
       # Should this integration be used for state machines in the given class?
-      # Classes that include ActiveModel::Dirty,  ActiveModel::Observing, or
-      # ActiveModel::Validations will automatically use the ActiveModel
-      # integration.
+      # Classes that include ActiveModel::Observing or ActiveModel::Validations
+      # will automatically use the ActiveModel integration.
       def self.matches?(klass)
-        %w(Dirty Observing Validations).any? {|feature| ::ActiveModel.const_defined?(feature) && klass <= ::ActiveModel.const_get(feature)}
-      end
-      
-      # Forces the change in state to be recognized regardless of whether the
-      # state value actually changed
-      def write(object, attribute, value, *args)
-        result = super
-        
-        if (attribute == :state || attribute == :event && value) && supports_dirty_tracking?(object) && !object.send("#{self.attribute}_changed?")
-          object.send("#{self.attribute}_will_change!")
-        end
-        
-        result
+        %w(Observing Validations).any? {|feature| ::ActiveModel.const_defined?(feature) && klass <= ::ActiveModel.const_get(feature)}
       end
       
       # Adds a validation error to the given object 
@@ -382,6 +393,12 @@ module StateMachine
         end
       end
       
+      # Describes the current validation errors on the given object.  If none
+      # are specific, then the default error is interpeted as a "halt".
+      def errors_for(object)
+        object.errors.empty? ? 'Transition halted' : object.errors.full_messages * ', '
+      end
+      
       # Resets any errors previously added when invalidating the given object
       def reset(object)
         object.errors.clear if supports_validations?
@@ -407,12 +424,6 @@ module StateMachine
           false
         end
         
-        # Whether change (dirty) tracking is supported in the integration.
-        # Only true if the ActiveModel feature is enabled on the owner class.
-        def supports_dirty_tracking?(object)
-          defined?(::ActiveModel::Dirty) && owner_class <= ::ActiveModel::Dirty && object.respond_to?("#{self.attribute}_changed?")
-        end
-        
         # Gets the terminator to use for callbacks
         def callback_terminator
           @terminator ||= lambda {|result| result == false}

data/lib/state_machine/integrations/active_record.rb

@@ -195,6 +195,14 @@ module StateMachine
     # *not* because a matching transition was not available, no error messages
     # will be added to the state attribute.
     # 
+    # In addition, if you're using the <tt>ignite!</tt> version of the event,
+    # then the failure reason (such as the current validation errors) will be
+    # included in the exception that gets raised when the event fails.  For
+    # example, assuming there's a validation on a field called +name+ on the class:
+    # 
+    #   vehicle = Vehicle.new
+    #   vehicle.ignite!       # => StateMachine::InvalidTransition: Cannot transition state via :ignite from :parked (Reason(s): Name cannot be blank)
+    # 
     # == Scopes
     # 
     # To assist in filtering models with specific states, a series of named

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

@@ -97,26 +97,6 @@ module StateMachine
         end
       end
       
-      version '2.0.x' do
-        def self.active?
-          ::ActiveRecord::VERSION::MAJOR == 2 && ::ActiveRecord::VERSION::MINOR == 0
-        end
-        
-        def supports_dirty_tracking?(object)
-          false
-        end
-      end
-      
-      version '2.1.x - 2.3.x' do
-        def self.active?
-          ::ActiveRecord::VERSION::MAJOR == 2 && ::ActiveRecord::VERSION::MINOR > 0
-        end
-        
-        def supports_dirty_tracking?(object)
-          object.respond_to?("#{attribute}_changed?")
-        end
-      end
-      
       version '2.3.2 - 2.3.x' do
         def self.active?
           ::ActiveRecord::VERSION::MAJOR == 2 && ::ActiveRecord::VERSION::MINOR == 3 && ::ActiveRecord::VERSION::TINY >= 2

data/lib/state_machine/integrations/data_mapper.rb

@@ -178,6 +178,14 @@ module StateMachine
     # *not* because a matching transition was not available, no error messages
     # will be added to the state attribute.
     # 
+    # In addition, if you're using the <tt>ignite!</tt> version of the event,
+    # then the failure reason (such as the current validation errors) will be
+    # included in the exception that gets raised when the event fails.  For
+    # example, assuming there's a validation on a field called +name+ on the class:
+    # 
+    #   vehicle = Vehicle.new
+    #   vehicle.ignite!       # => StateMachine::InvalidTransition: Cannot transition state via :ignite from :parked (Reason(s): Name cannot be blank)
+    # 
     # == Scopes
     # 
     # To assist in filtering models with specific states, a series of class
@@ -322,24 +330,25 @@ module StateMachine
         super
       end
       
-      # Forces the change in state to be recognized regardless of whether the
-      # state value actually changed
-      def write(object, attribute, value, *args)
-        result = super
-        
-        if attribute == :state || attribute == :event && value
-          value = read(object, :state) if attribute == :event
-          mark_dirty(object, value)
-        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?
       end
       
+      # Describes the current validation errors on the given object.  If none
+      # are specific, then the default error is interpeted as a "halt".
+      def errors_for(object)
+        if object.errors.empty?
+          'Transition halted'
+        else
+          errors = []
+          object.errors.each_pair do |field_name, field_errors|
+            field_errors.each {|error| errors << "#{field_name} #{error}"}
+          end
+          errors * ', '
+        end
+      end
+      
       # Resets any errors previously added when invalidating the given object
       def reset(object)
         object.errors.clear if supports_validations?
@@ -434,14 +443,6 @@ module StateMachine
           options[:bind_to_object] = true
           super
         end
-        
-        # Marks the object's state as dirty so that the record will be saved
-        # even if no actual modifications have been made to the data
-        def mark_dirty(object, value)
-          object.persistence_state = ::DataMapper::Resource::PersistenceState::Dirty.new(object) if object.persistence_state.is_a?(::DataMapper::Resource::PersistenceState::Clean)
-          property = owner_class.properties[self.attribute]
-          object.persistence_state.original_attributes[property] = value unless object.persistence_state.original_attributes.include?(property)
-        end
     end
   end
 end