state_machine 1.1.2 → 1.2.0

data/lib/state_machine/core_ext.rb

@@ -1 +1,2 @@
+# Loads all of the extensions to be made to Ruby core classes
 require 'state_machine/core_ext/class/state_machine'

data/lib/state_machine/eval_helpers.rb

@@ -53,7 +53,9 @@ module StateMachine
     def evaluate_method(object, method, *args, &block)
       case method
         when Symbol
-          object.method(method).arity == 0 ? object.send(method, &block) : object.send(method, *args, &block)
+          klass = (class << object; self; end)
+          args = [] if (klass.method_defined?(method) || klass.private_method_defined?(method)) && object.method(method).arity == 0
+          object.send(method, *args, &block)
         when Proc, Method
           args.unshift(object)
           arity = method.arity
@@ -74,12 +76,12 @@ module StateMachine
             args = args[0, arity] if [0, 1].include?(arity)
           end
           
-          method.call(*args, &block)
+          method.is_a?(Proc) ? method.call(*args) : method.call(*args, &block)
         when String
           eval(method, object.instance_eval {binding}, &block)
         else
           raise ArgumentError, 'Methods must be a symbol denoting the method to call, a block to be invoked, or a string to be evaluated'
-        end
+      end
     end
   end
 end

data/lib/state_machine/event.rb

@@ -58,7 +58,7 @@ module StateMachine
       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]}
+      if conflict = machine.owner_class.state_machines.detect {|other_name, other_machine| other_machine != @machine && other_machine.events[qualified_name, :qualified_name]}
         name, other_machine = conflict
         warn "Event #{qualified_name.inspect} for #{machine.name.inspect} is already defined in #{other_machine.name.inspect}"
       else
@@ -107,7 +107,7 @@ module StateMachine
       
       # Only a certain subset of explicit options are allowed for transition
       # 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?
+      assert_valid_keys(options, :from, :to, :except_from, :except_to, :if, :unless) if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
       
       branches << branch = Branch.new(options.merge(:on => name))
       @known_states |= branch.known_states
@@ -144,7 +144,12 @@ module StateMachine
         if match = branch.match(object, requirements)
           # Branch allows for the transition to occur
           from = requirements[:from]
-          to = match[:to].values.empty? ? from : match[:to].values.first
+          to = if match[:to].is_a?(LoopbackMatcher)
+            from
+          else
+            values = requirements.include?(:to) ? [requirements[:to]].flatten : [from] | machine.states.keys(:name)
+            match[:to].filter(values).first
+          end
           
           return Transition.new(object, machine, name, from, to, !custom_from_state)
         end
@@ -193,10 +198,16 @@ module StateMachine
     # create 1 or more edges on the graph for each branch (i.e. transition)
     # configured.
     # 
-    # A collection of the generated edges will be returned.
-    def draw(graph)
+    # Configuration options:
+    # * <tt>:human_name</tt> - Whether to use the event's human name for the
+    #   node's label that gets drawn on the graph
+    def draw(graph, options = {})
       valid_states = machine.states.by_priority.map {|state| state.name}
-      branches.collect {|branch| branch.draw(graph, name, valid_states)}.flatten
+      branches.each do |branch|
+        branch.draw(graph, options[:human_name] ? human_name : name, valid_states)
+      end
+      
+      true
     end
     
     # Generates a nicely formatted description of this event's contents.

data/lib/state_machine/graph.rb

@@ -0,0 +1,92 @@
+begin
+  require 'rubygems'
+  gem 'ruby-graphviz', '>=0.9.17'
+  require 'graphviz'
+rescue LoadError => ex
+  $stderr.puts "Cannot draw the machine (#{ex.message}). `gem install ruby-graphviz` >= v0.9.17 and try again."
+  raise
+end
+
+require 'state_machine/assertions'
+
+module StateMachine
+  # Provides a set of higher-order features on top of the raw GraphViz graphs
+  class Graph < GraphViz
+    include Assertions
+    
+    # The name of the font to draw state names in
+    attr_reader :font
+    
+    # The graph's full filename
+    attr_reader :file_path
+    
+    # The image format to generate the graph in
+    attr_reader :file_format
+    
+    # Creates a new graph with the given name.
+    # 
+    # Configuration options:
+    # * <tt>:path</tt> - The path to write the graph file to.  Default is the
+    #   current directory (".").
+    # * <tt>:format</tt> - The image format to generate the graph in.
+    #   Default is "png'.
+    # * <tt>:font</tt> - The name of the font to draw state names in.
+    #   Default is "Arial".
+    # * <tt>:orientation</tt> - The direction of the graph ("portrait" or
+    #   "landscape").  Default is "portrait".
+    def initialize(name, options = {})
+      options = {:path => '.', :format => 'png', :font => 'Arial', :orientation => 'portrait'}.merge(options)
+      assert_valid_keys(options, :path, :format, :font, :orientation)
+      
+      @font = options[:font]
+      @file_path = File.join(options[:path], "#{name}.#{options[:format]}")
+      @file_format = options[:format]
+      
+      super('G', :rankdir => options[:orientation] == 'landscape' ? 'LR' : 'TB')
+    end
+    
+    # Generates the actual image file based on the nodes / edges added to the
+    # graph.  The path to the file is based on the configuration options for
+    # this graph.
+    def output
+      super(@file_format => @file_path)
+    end
+    
+    # Adds a new node to the graph.  The font for the node will be automatically
+    # set based on the graph configuration.  The generated node will be returned.
+    # 
+    # For example,
+    # 
+    #   graph = StateMachine::Graph.new('test')
+    #   graph.add_nodes('parked', :label => 'Parked', :width => '1', :height => '1', :shape => 'ellipse')
+    def add_nodes(*args)
+      node = v0_api? ? add_node(*args) : super
+      node.fontname = @font
+      node
+    end
+    
+    # Adds a new edge to the graph.  The font for the edge will be automatically
+    # set based on the graph configuration.  The generated edge will be returned.
+    # 
+    # For example,
+    # 
+    #   graph = StateMachine::Graph.new('test')
+    #   graph.add_edges('parked', 'idling', :label => 'ignite')
+    def add_edges(*args)
+      edge = v0_api? ? add_edge(*args) : super
+      edge.fontname = @font
+      edge
+    end
+    
+    private
+    # Determines whether the old v0 api is in use
+    def v0_api?
+      version[0] == '0' || version[0] == '1' && version[1] == '0' && version[2] <= '2'
+    end
+    
+    # The ruby-graphviz version data
+    def version
+      Constants::RGV_VERSION.split('.')
+    end
+  end
+end

data/lib/state_machine/integrations.rb

@@ -73,7 +73,19 @@ module StateMachine
     #   StateMachine::Integrations.match(MongoMapperVehicle)  # => StateMachine::Integrations::MongoMapper
     #   StateMachine::Integrations.match(SequelVehicle)       # => StateMachine::Integrations::Sequel
     def self.match(klass)
-      all.detect {|integration| integration.available? && integration.matches?(klass)}
+      all.detect {|integration| integration.matches?(klass)}
+    end
+    
+    # Attempts to find an integration that matches the given list of ancestors.
+    # This will look through all of the built-in integrations under the StateMachine::Integrations
+    # namespace and find one that successfully matches one of the ancestors.
+    # 
+    # == Examples
+    # 
+    #   StateMachine::Integrations.match([])                    # => nil
+    #   StateMachine::Integrations.match(['ActiveRecord::Base') # => StateMachine::Integrations::ActiveModel
+    def self.match_ancestors(ancestors)
+      all.detect {|integration| integration.matches_ancestors?(ancestors)}
     end
     
     # Finds an integration with the given name.  If the integration cannot be

data/lib/state_machine/integrations/active_model.rb

@@ -366,26 +366,19 @@ module StateMachine
       
       @defaults = {}
       
-      # Whether this integration is available.  Only true if ActiveModel is
-      # defined.
-      def self.available?
-        defined?(::ActiveModel)
-      end
-      
-      # Should this integration be used for state machines in the given class?
       # Classes that include ActiveModel::Observing or ActiveModel::Validations
       # will automatically use the ActiveModel integration.
-      def self.matches?(klass)
-        %w(Observing Validations).any? {|feature| ::ActiveModel.const_defined?(feature) && klass <= ::ActiveModel.const_get(feature)}
+      def self.matching_ancestors
+        %w(ActiveModel ActiveModel::Observing ActiveModel::Validations)
       end
       
       # Adds a validation error to the given object 
       def invalidate(object, attribute, message, values = [])
         if supports_validations?
           attribute = self.attribute(attribute)
-          options = values.inject({}) do |options, (key, value)|
-            options[key] = value
-            options
+          options = values.inject({}) do |h, (key, value)|
+            h[key] = value
+            h
           end
           
           default_options = default_error_message_options(object, attribute, message)
@@ -454,8 +447,8 @@ module StateMachine
           value = value ? value.to_s : 'nil'
           
           # Generate all possible translation keys
-          translations = ancestors.map {|ancestor| :"#{ancestor.model_name.underscore}.#{name}.#{group}.#{value}"}
-          translations.concat(ancestors.map {|ancestor| :"#{ancestor.model_name.underscore}.#{group}.#{value}"})
+          translations = ancestors.map {|ancestor| :"#{ancestor.model_name.to_s.underscore}.#{name}.#{group}.#{value}"}
+          translations.concat(ancestors.map {|ancestor| :"#{ancestor.model_name.to_s.underscore}.#{group}.#{value}"})
           translations.concat([:"#{name}.#{group}.#{value}", :"#{group}.#{value}", value.humanize.downcase])
           I18n.translate(translations.shift, :default => translations, :scope => [i18n_scope(klass), :state_machines])
         end
@@ -482,6 +475,7 @@ module StateMachine
         # Loads extensions to ActiveModel's Observers
         def load_observer_extensions
           require 'state_machine/integrations/active_model/observer'
+          require 'state_machine/integrations/active_model/observer_update'
         end
         
         # Adds a set of default callbacks that utilize the Observer extensions
@@ -537,15 +531,15 @@ module StateMachine
         
         # Configures new states with the built-in humanize scheme
         def add_states(new_states)
-          super.each do |state|
-            state.human_name = lambda {|state, klass| translate(klass, :state, state.name)}
+          super.each do |new_state|
+            new_state.human_name = lambda {|state, klass| translate(klass, :state, state.name)}
           end
         end
         
         # Configures new event with the built-in humanize scheme
         def add_events(new_events)
-          super.each do |event|
-            event.human_name = lambda {|event, klass| translate(klass, :event, event.name)}
+          super.each do |new_event|
+            new_event.human_name = lambda {|event, klass| translate(klass, :event, event.name)}
           end
         end
         
@@ -575,14 +569,14 @@ module StateMachine
             ["_from_#{from}", nil].each do |from_segment|
               ["_to_#{to}", nil].each do |to_segment|
                 object.class.changed if object.class.respond_to?(:changed)
-                object.class.notify_observers('update_with_transition', [[event_segment, from_segment, to_segment].join, object, transition])
+                object.class.notify_observers('update_with_transition', ObserverUpdate.new([event_segment, from_segment, to_segment].join, object, transition))
               end
             end
           end
           
           # Generic updates
           object.class.changed if object.class.respond_to?(:changed)
-          object.class.notify_observers('update_with_transition', ["#{type}_transition", object, transition])
+          object.class.notify_observers('update_with_transition', ObserverUpdate.new("#{type}_transition", object, transition))
           
           true
         end

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

@@ -19,9 +19,9 @@ module StateMachine
       #     end
       #   end
       module Observer
-        def update_with_transition(args)
-          observed_method, object, transition = args
-          send(observed_method, object, transition) if respond_to?(observed_method)
+        def update_with_transition(observer_update)
+          method = observer_update.method
+          send(method, *observer_update.args) if respond_to?(method)
         end
       end
     end

data/lib/state_machine/integrations/active_model/observer_update.rb

@@ -0,0 +1,42 @@
+module StateMachine
+  module Integrations #:nodoc:
+    module ActiveModel
+      # Represents the encapsulation of all of the details to be included in an
+      # update to state machine observers.  This allows multiple arguments to
+      # get passed to an observer method (instead of just a single +object+)
+      # while still respecting the way in which ActiveModel checks for the
+      # object's list of observers.
+      class ObserverUpdate
+        # The method to invoke on the observer
+        attr_reader :method
+        
+        # The object being transitioned
+        attr_reader :object
+        
+        # The transition being run
+        attr_reader :transition
+        
+        def initialize(method, object, transition) #:nodoc:
+          @method, @object, @transition = method, object, transition
+        end
+        
+        # The arguments to pass into the method
+        def args
+          [object, transition]
+        end
+        
+        # The class of the object being transitioned.  Normally the object
+        # getting passed into observer methods is the actual instance of the
+        # ActiveModel class.  ActiveModel uses that instance's class to check
+        # for enabled / disabled observers.
+        # 
+        # Since state_machine is passing an ObserverUpdate instance into observer
+        # methods, +class+ needs to be overridden so that ActiveModel can still
+        # get access to the enabled / disabled observers.
+        def class
+          object.class
+        end
+      end
+    end
+  end
+end

data/lib/state_machine/integrations/active_record.rb

@@ -136,18 +136,6 @@ module StateMachine
     #     end
     #   end
     # 
-    # If using the +save+ action for the machine, this option will be ignored as
-    # the transaction will be created by ActiveRecord within +save+.  To avoid
-    # this, use a different action like so:
-    # 
-    #   class Vehicle < ActiveRecord::Base
-    #     state_machine :initial => :parked, :use_transactions => false, :action => :save_state do
-    #       ...
-    #     end
-    #     
-    #     alias_method :save_state, :save
-    #   end
-    # 
     # == Validations
     # 
     # As mentioned in StateMachine::Machine#state, you can define behaviors,
@@ -290,6 +278,27 @@ module StateMachine
     # that allows new records to be saved without being affected by rollbacks
     # in the +Vehicle+ model's transaction.
     # 
+    # === Callback Order
+    # 
+    # Callbacks occur in the following order.  Callbacks specific to state_machine
+    # are bolded.  The remaining callbacks are part of ActiveRecord.
+    # 
+    # * (-) save
+    # * (-) begin transaction (if enabled)
+    # * (1) *before_transition*
+    # * (-) valid
+    # * (2) before_validation
+    # * (-) validate
+    # * (3) after_validation
+    # * (4) before_save
+    # * (5) before_create
+    # * (-) create
+    # * (6) after_create
+    # * (7) after_save
+    # * (8) *after_transition*
+    # * (-) end transaction (if enabled)
+    # * (9) after_commit
+    # 
     # == Observers
     # 
     # In addition to support for ActiveRecord-like hooks, there is additional
@@ -407,17 +416,10 @@ module StateMachine
       # The default options to use for state machines using this integration
       @defaults = {:action => :save}
       
-      # Whether this integration is available.  Only true if ActiveRecord::Base
-      # is defined.
-      def self.available?
-        defined?(::ActiveRecord::Base)
-      end
-      
-      # Should this integration be used for state machines in the given class?
       # Classes that inherit from ActiveRecord::Base will automatically use
       # the ActiveRecord integration.
-      def self.matches?(klass)
-        klass <= ::ActiveRecord::Base
+      def self.matching_ancestors
+        %w(ActiveRecord::Base)
       end
       
       def self.extended(base) #:nodoc:
@@ -431,6 +433,13 @@ module StateMachine
           action == :save
         end
         
+        # Gets the db default for the machine's attribute
+        def owner_class_attribute_default
+          if owner_class.connected? && owner_class.table_exists? && column = owner_class.columns_hash[attribute.to_s]
+            column.default
+          end
+        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
@@ -448,7 +457,7 @@ module StateMachine
             def column_defaults(*) #:nodoc:
               result = super
               # No need to pass in an object, since the overrides will be forced
-              self.state_machines.initialize_states(nil, :dynamic => false, :to => result)
+              self.state_machines.initialize_states(nil, :static => :force, :dynamic => false, :to => result)
               result
             end
           end_eval
@@ -469,7 +478,19 @@ module StateMachine
         # Uses around callbacks to run state events if using the :save hook
         def define_action_hook
           if action_hook == :save
-            owner_class.set_callback(:save, :around, self, :prepend => true)
+            define_helper :instance, <<-end_eval, __FILE__, __LINE__ + 1
+              def save(*)
+                self.class.state_machine(#{name.inspect}).send(:around_save, self) { super }
+              end
+              
+              def save!(*)
+                self.class.state_machine(#{name.inspect}).send(:around_save, self) { super } || raise(ActiveRecord::RecordInvalid.new(self))
+              end
+              
+              def changed_for_autosave?
+                super || self.class.state_machines.any? {|name, machine| machine.action == :save && machine.read(self, :event)}
+              end
+            end_eval
           else
             super
           end
@@ -477,7 +498,9 @@ module StateMachine
         
         # Runs state events around the machine's :save action
         def around_save(object)
-          object.class.state_machines.transitions(object, action).perform { yield }
+          transaction(object) do
+            object.class.state_machines.transitions(object, action).perform { yield }
+          end
         end
         
         # Creates a scope for finding records *with* a particular state or
@@ -502,7 +525,11 @@ module StateMachine
         # an ActiveRecord::Rollback exception if the yielded block fails
         # (i.e. returns false).
         def transaction(object)
-          object.class.transaction {raise ::ActiveRecord::Rollback unless yield}
+          result = nil
+          object.class.transaction do
+            raise ::ActiveRecord::Rollback unless result = yield
+          end
+          result
         end
         
         # Defines a new named scope with the given name