state_machine 0.8.1 → 0.9.0

data/lib/state_machine/integrations/sequel.rb

@@ -64,6 +64,9 @@ module StateMachine
     #   vehicle = Vehicle.create(:state_event => 'ignite')  # => #<Vehicle @values={:state=>"idling", :name=>nil, :id=>1}>
     #   vehicle.state                                       # => "idling"
     # 
+    # This technique is always used for transitioning states when the +save+
+    # action (which is the default) is configured for the machine.
+    # 
     # === Security implications
     # 
     # Beware that public event attributes mean that events can be fired
@@ -131,6 +134,9 @@ module StateMachine
     #     end
     #   end
     # 
+    # If using the +save+ action for the machine, this option will be ignored as
+    # the transaction will be created by Sequel within +save+.
+    # 
     # == Validation errors
     # 
     # If an event fails to successfully fire because there are no matching
@@ -278,14 +284,34 @@ module StateMachine
           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_event_attributes(self, :save, false) { super(*args) }
+        # Adds hooks into validation for automatically firing events.  This is
+        # a bit more complicated than other integrations since Sequel doesn't
+        # provide an easy way to hook around validation / save calls
+         def define_action_helpers
+           if action == :save
+             @instance_helper_module.class_eval do
+               define_method(:valid?) do |*args|
+                yielded = false
+                result = self.class.state_machines.transitions(self, :save, :after => false).perform do
+                  yielded = true
+                  super(*args)
+                end
+                
+                raise_on_save_failure && !yielded && !result ? save_failure(:validation) : result
               end
-            end
+              
+              define_method(defined?(::Sequel::MAJOR) && (::Sequel::MAJOR >= 3 || ::Sequel::MAJOR == 2 && ::Sequel::MINOR == 12) ? :_save : :save) do |*args|
+                yielded = false
+                result = self.class.state_machines.transitions(self, :save).perform do
+                  yielded = true
+                  super(*args)
+                end
+                
+                yielded || result ? result : save_failure(:save)
+              end
+            end unless owner_class.state_machines.any? {|name, machine| machine.action == :save && machine != self}
+          else
+            super
           end
         end
         

data/lib/state_machine/machine.rb

@@ -90,17 +90,17 @@ module StateMachine
   # action being invoked (and not a superclass), then it must manually run the
   # StateMachine hook that checks for event attributes.
   # 
-  # For example, in ActiveRecord, DataMapper, and Sequel, the default action
-  # (+save+) is already defined in a base class.  As a result, when a state
-  # machine is defined in a model / resource, StateMachine can automatically
-  # hook into the +save+ action.
+  # For example, in ActiveRecord, DataMapper, MongoMapper, and Sequel, the
+  # default action (+save+) is already defined in a base class.  As a result,
+  # when a state machine is defined in a model / resource, StateMachine can
+  # automatically hook into the +save+ action.
   # 
   # On the other hand, the Vehicle class from above defined its own +save+
   # method (and there is no +save+ method in its superclass).  As a result, it
   # must be modified like so:
   # 
   #     def save
-  #       self.class.state_machines.fire_event_attributes(self, :save) do
+  #       self.class.state_machines.transitions(self, :save).perform do
   #         @saving_state = state
   #         fail != true
   #       end
@@ -156,6 +156,11 @@ module StateMachine
   # later callbacks are canceled.  If an +after+ callback halts the chain,
   # the later callbacks are canceled, but the transition is still successful.
   # 
+  # These same rules apply to +around+ callbacks with the exception that any
+  # +around+ callback that doesn't yield will essentially result in :halt being
+  # thrown.  Any code executed after the yield will behave in the same way as
+  # +after+ callbacks.
+  # 
   # *Note* that if a +before+ callback fails and the bang version of an event
   # was invoked, an exception will be raised instead of returning false.  For
   # example,
@@ -207,6 +212,10 @@ module StateMachine
   #     def self.after_transition(vehicle, transition)
   #       logger.info "#{vehicle} instructed to #{transition.event}... #{transition.attribute} was: #{transition.from}, #{transition.attribute} is: #{transition.to}"
   #     end
+  #     
+  #     def self.around_transition(vehicle, transition)
+  #       logger.info Benchmark.measure { yield }
+  #     end
   #   end
   #   
   #   Vehicle.state_machine do
@@ -215,6 +224,8 @@ module StateMachine
   #     
   #     after_transition :on => :park, :do => VehicleObserver.method(:after_park)
   #     after_transition VehicleObserver.method(:after_transition)
+  #     
+  #     around_transition VehicleObserver.method(:around_transition)
   #   end
   # 
   # One common callback is to record transitions for all models in the system
@@ -279,11 +290,13 @@ module StateMachine
   # 
   # When a state machine is defined for classes using any of the above libraries,
   # it will try to automatically determine the integration to use (Agnostic,
-  # ActiveRecord, DataMapper, or Sequel) based on the class definition.  To
-  # see how each integration affects the machine's behavior, refer to all
-  # constants defined under the StateMachine::Integrations namespace.
+  # ActiveModel, ActiveRecord, DataMapper, MongoMapper, or Sequel) based on the
+  # class definition.  To see how each integration affects the machine's
+  # behavior, refer to all constants defined under the StateMachine::Integrations
+  # namespace.
   class Machine
     include Assertions
+    include EvalHelpers
     include MatcherHelpers
     
     class << self
@@ -489,6 +502,12 @@ module StateMachine
       states.each {|state| state.initial = (state.name == @initial_state)}
     end
     
+    # Initializes the state on the given object.  This will always write to the
+    # attribute regardless of whether a value is already present.
+    def initialize_state(object)
+      write(object, :state, initial_state(object).value)
+    end
+    
     # Gets the actual name of the attribute on the machine's owner class that
     # stores data with the given name.
     def attribute(name = :state)
@@ -569,7 +588,7 @@ 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(dynamic_initial_state? ? @initial_state.call(object) : @initial_state)
+      states.fetch(dynamic_initial_state? ? evaluate_method(object, @initial_state) : @initial_state)
     end
     
     # Whether a dynamic initial state is being used in the machine
@@ -917,6 +936,7 @@ module StateMachine
     #   
     #   event :first_gear do
     #     transition :parked => :first_gear, :if => :seatbelt_on?
+    #     transition :parked => same # Allow to loopback if seatbelt is off
     #   end
     # 
     # See StateMachine::Event#transition for more information on
@@ -983,6 +1003,7 @@ module StateMachine
     #       
     #       event :ignite do
     #         transition :parked => :idling
+    #         transition :idling => same # Allow ignite while still idling
     #       end
     #     end
     #   end
@@ -1084,15 +1105,20 @@ module StateMachine
     # 
     # == Result requirements
     # 
-    # By default, after_transition callbacks will only be run if the transition
+    # By default, +after_transition+ callbacks and code executed after an
+    # +around_transition+ callback yields 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:
+    # In order to include failed attempts when running an +after_transition+ or
+    # +around_transition+ callback, the <tt>:include_failures</tt> 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
     # 
+    #   around_transition :include_failures => true, :do => ... # Runs on all attempts to transition, including failures
+    #   around_transition :do => ...                            # Runs only on successful attempts to transition
+    # 
     # == Verbose Requirements
     # 
     # Requirements can also be defined using verbose options rather than the
@@ -1203,6 +1229,67 @@ module StateMachine
       add_callback(:after, options, &block)
     end
     
+    # Creates a callback that will be invoked *around* a transition so long as
+    # the given requirements match the transition.
+    # 
+    # == The callback
+    # 
+    # Around callbacks wrap transitions, executing code both before and after.
+    # These callbacks are defined in the exact same manner as before / after
+    # callbacks with the exception that the transition must be yielded to in
+    # order to finish running it.
+    # 
+    # If defining +around+ callbacks using blocks, you must yield within the
+    # transition by directly calling the block (since yielding is not allowed
+    # within blocks).
+    # 
+    # For example,
+    # 
+    #   class Vehicle
+    #     state_machine do
+    #       around_transition do |block|
+    #         Benchmark.measure { block.call }
+    #       end
+    #       
+    #       around_transition do |vehicle, block|
+    #         logger.info "vehicle was #{state}..."
+    #         block.call
+    #         logger.info "...and is now #{state}"
+    #       end
+    #       
+    #       around_transition do |vehicle, transition, block|
+    #         logger.info "before #{transition.event}: #{vehicle.state}"
+    #         block.call
+    #         logger.info "after #{transition.event}: #{vehicle.state}"
+    #       end
+    #     end
+    #   end
+    # 
+    # Notice that referencing the block is similar to doing so within an
+    # actual method definition in that it is always the last argument.
+    # 
+    # On the other hand, if you're defining +around+ callbacks using method
+    # references, you can yield like normal:
+    # 
+    #   class Vehicle
+    #     state_machine do
+    #       around_transition :benchmark
+    #       ...
+    #     end
+    #     
+    #     def benchmark
+    #       Benchmark.measure { yield }
+    #     end
+    #   end
+    # 
+    # See +before_transition+ for a description of the possible configurations
+    # for defining callbacks.
+    def around_transition(*args, &block)
+      options = (args.last.is_a?(Hash) ? args.pop : {})
+      options[:do] = args if args.any?
+      add_callback(:around, options, &block)
+    end
+    
     # Marks the given object as invalid with the given message.
     # 
     # By default, this is a no-op.
@@ -1265,6 +1352,7 @@ module StateMachine
       begin
         # Load the graphviz library
         require 'rubygems'
+        gem 'ruby-graphviz', '>=0.9.0'
         require 'graphviz'
         
         graph = GraphViz.new('G', :rankdir => options[:orientation] == 'landscape' ? 'LR' : 'TB')
@@ -1284,7 +1372,7 @@ module StateMachine
         # Generate the graph
         graphvizVersion = Constants::RGV_VERSION.split('.')
         
-        if graphvizVersion[0] == '0' && (graphvizVersion[1] < '9' || graphvizVersion[1] == '9' && graphvizVersion[2] == '0')
+        if graphvizVersion[1] == '9' && graphvizVersion[2] == '0'
           outputOptions = {
             :output => options[:format],
             :file => File.join(options[:path], "#{options[:name]}.#{options[:format]}")
@@ -1298,11 +1386,17 @@ module StateMachine
         graph.output(outputOptions)
         graph
       rescue LoadError
-        $stderr.puts 'Cannot draw the machine. `gem install ruby-graphviz` and try again.'
+        $stderr.puts 'Cannot draw the machine. `gem install ruby-graphviz` >= v0.9.0 and try again.'
         false
       end
     end
     
+    # Determines whether a helper method was defined for firing attribute-based
+    # event transitions when the configuration action gets called.
+    def action_helper_defined?
+      @action_helper_defined
+    end
+    
     protected
       # Runs additional initialization hooks.  By default, this is a no-op.
       def after_initialize
@@ -1389,23 +1483,27 @@ module StateMachine
       # Adds helper methods for automatically firing events when an action
       # is invoked
       def define_action_helpers(action_hook = self.action)
-        action = self.action
-        private_method = owner_class.private_method_defined?(action_hook)
+        private_action = owner_class.private_method_defined?(action_hook)
+        action_defined = @action_helper_defined = owner_class.ancestors.any? do |ancestor|
+          ancestor != owner_class && (ancestor.method_defined?(action_hook) || ancestor.private_method_defined?(action_hook))
+        end
+        action_overridden = owner_class.state_machines.any? {|name, machine| machine.action == action && machine != self}
         
-        if (owner_class.method_defined?(action_hook) || private_method) && !owner_class.state_machines.any? {|name, machine| machine.action == action && machine != self}
-          # Action is defined and hasn't already been overridden by another machine
+        # Only define helper if:
+        # 1. Action was originally defined somewhere other than the owner class
+        # 2. It hasn't already been overridden by another machine
+        if action_defined && !action_overridden
+          action = self.action
           @instance_helper_module.class_eval do
-            # Override the default action to invoke the before / after hooks
             define_method(action_hook) do |*args|
-              self.class.state_machines.fire_event_attributes(self, action) { super(*args) }
+              self.class.state_machines.transitions(self, action).perform { super(*args) }
             end
             
-            private action_hook if private_method
+            private action_hook if private_action
           end
           
           true
         else
-          # Action already defined: don't add integration-specific hooks
           false
         end
       end
@@ -1466,7 +1564,7 @@ module StateMachine
       
       # Adds a new transition callback of the given type.
       def add_callback(type, options, &block)
-        callbacks[type] << callback = Callback.new(options, &block)
+        callbacks[type == :around ? :before : type] << callback = Callback.new(type, options, &block)
         add_states(callback.known_states)
         callback
       end

data/lib/state_machine/machine_collection.rb

@@ -6,13 +6,13 @@ module StateMachine
     # (which must mean the defaults are being skipped)
     def initialize_states(object, options = {})
       if ignore = options[:ignore]
-        ignore.map! {|attribute| attribute.to_sym}
+        ignore = ignore.map {|attribute| attribute.to_sym}
       end
       
       each_value do |machine|
         if (!ignore || !ignore.include?(machine.attribute)) && (!options.include?(:dynamic) || machine.dynamic_initial_state? == options[:dynamic])
           value = machine.read(object, :state)
-          machine.write(object, :state, machine.initial_state(object).value) if ignore || value.nil? || value.respond_to?(:empty?) && value.empty?
+          machine.initialize_state(object) if ignore || value.nil? || value.respond_to?(:empty?) && value.empty?
         end
       end
     end
@@ -26,9 +26,7 @@ module StateMachine
       transitions = events.collect do |event_name|
         # Find the actual event being run
         event = nil
-        detect do |name, machine|
-          event = machine.events[event_name, :qualified_name]
-        end
+        detect {|name, machine| event = machine.events[event_name, :qualified_name]}
         
         raise InvalidEvent, "#{event_name.inspect} is an unknown state machine event" unless event
         
@@ -44,112 +42,23 @@ module StateMachine
       # Run the events in parallel only if valid transitions were found for
       # all of them
       if events.length == transitions.length
-        Transition.perform_within_transaction(transitions, :action => run_action)
+        TransitionCollection.new(transitions, :actions => run_action).perform
       else
         false
       end
     end
     
-    # Runs one or more event attributes in parallel during the invocation of
-    # an action on the given object.  after_transition callbacks can be
-    # optionally disabled if the events are being only partially fired (for
-    # example, when validating records in ORM integrations).
-    # 
-    # The event attributes that will be fired are based on which machines
-    # match the action that is being invoked.
-    # 
-    # == Examples
-    # 
-    #   class Vehicle
-    #     include DataMapper::Resource
-    #     property :id, Serial
-    #     
-    #     state_machine :initial => :parked do
-    #       event :ignite do
-    #         transition :parked => :idling
-    #       end
-    #     end
-    #     
-    #     state_machine :alarm_state, :namespace => 'alarm', :initial => :active do
-    #       event :disable do
-    #         transition all => :off
-    #       end
-    #     end
-    #   end
-    # 
-    # With valid events:
-    # 
-    #   vehicle = Vehicle.create                      # => #<Vehicle id=1 state="parked" alarm_state="active">
-    #   vehicle.state_event = 'ignite'
-    #   vehicle.alarm_state_event = 'disable'
-    #   
-    #   Vehicle.state_machines.fire_event_attributes(vehicle, :save) { true }
-    #   vehicle.state                                 # => "idling"
-    #   vehicle.state_event                           # => nil
-    #   vehicle.alarm_state                           # => "off"
-    #   vehicle.alarm_state_event                     # => nil
-    # 
-    # With invalid events:
-    #   
-    #   vehicle = Vehicle.create                      # => #<Vehicle id=1 state="parked" alarm_state="active">
-    #   vehicle.state_event = 'park'
-    #   vehicle.alarm_state_event = 'disable'
-    #   
-    #   Vehicle.state_machines.fire_event_attributes(vehicle, :save) { true }
-    #   vehicle.state                                 # => "parked"
-    #   vehicle.state_event                           # => nil
-    #   vehicle.alarm_state                           # => "active"
-    #   vehicle.alarm_state_event                     # => nil
-    #   vehicle.errors                                # => #<DataMapper::Validate::ValidationErrors:0xb7af9abc @errors={"state_event"=>["is invalid"]}>
-    # 
-    # With partial firing:
+    # Builds the collection of transitions for all event attributes defined on
+    # the given object.  This will only include events whose machine actions
+    # match the one specified.
     # 
-    #   vehicle = Vehicle.create                      # => #<Vehicle id=1 state="parked" alarm_state="active">
-    #   vehicle.state_event = 'ignite'
-    #   
-    #   Vehicle.state_machines.fire_event_attributes(vehicle, :save, false) { true }
-    #   vehicle.state                                 # => "idling"
-    #   vehicle.state_event                           # => "ignite"
-    #   vehicle.state_event_transition                # => #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
-    def fire_event_attributes(object, action, complete = true)
-      # Get the transitions to fire for each applicable machine
-      transitions = map {|name, machine| machine.action == action ? machine.events.attribute_transition_for(object, true) : nil}.compact
-      return yield if transitions.empty?
-      
-      # The value generated by the yielded block (the actual action)
-      action_value = nil
-      
-      # Make sure all events were valid
-      if result = transitions.all? {|transition| transition != false}
-        # Clear any traces of the event since transitions are available and to
-        # prevent from being evaluated multiple times if actions are nested
-        transitions.each do |transition|
-          transition.machine.write(object, :event, nil)
-          transition.machine.write(object, :event_transition, nil)
-        end
-        
-        # Perform the transitions
-        begin
-          result = Transition.perform(transitions, :after => complete) { action_value = yield }
-        rescue Exception
-          # Reset the event attribute so it can be re-evaluated if attempted again
-          transitions.each do |transition|
-            transition.machine.write(object, :event, transition.event)
-          end
-          
-          raise
-        end
-        
-        transitions.each do |transition|
-          # Revert event if failed (to allow for more attempts)
-          transition.machine.write(object, :event, transition.event) unless result
-          
-          # Track transition if partial transition was successful
-          transition.machine.write(object, :event_transition, transition) if !complete && result
-        end
+    # These should only be fired as a result of the action being run.
+    def transitions(object, action, options = {})
+      transitions = map do |name, machine|
+        machine.events.attribute_transition_for(object, true) if machine.action == action
       end
       
-      action_value.nil? ? result : action_value
+      AttributeTransitionCollection.new(transitions.compact, options)
     end
   end
 end