state_machine 0.4.3 → 0.5.0

data/lib/state_machine/integrations/active_record.rb

@@ -8,9 +8,9 @@ module StateMachine
     # ActiveRecord model:
     # 
     #   class Vehicle < ActiveRecord::Base
-    #     state_machine :initial => 'parked' do
+    #     state_machine :initial => :parked do
     #       event :ignite do
-    #         transition :to => 'idling', :from => 'parked'
+    #         transition :to => :idling, :from => :parked
     #       end
     #     end
     #   end
@@ -28,7 +28,7 @@ module StateMachine
     # 
     # For example,
     # 
-    #   vehicle = Vehicle.create          # => #<Vehicle id: 1, name: nil, state: nil>
+    #   vehicle = Vehicle.create          # => #<Vehicle id: 1, name: nil, state: "parked">
     #   vehicle.name = 'Ford Explorer'
     #   vehicle.ignite                    # => true
     #   vehicle.reload                    # => #<Vehicle id: 1, name: "Ford Explorer", state: "idling">
@@ -51,7 +51,7 @@ module StateMachine
     #     end
     #   end
     #   
-    #   vehicle = Vehicle.create      # => #<Vehicle id: 1, name: nil, state: nil>
+    #   vehicle = Vehicle.create      # => #<Vehicle id: 1, name: nil, state: "parked">
     #   vehicle.ignite                # => false
     #   Message.count                 # => 0
     # 
@@ -66,21 +66,24 @@ module StateMachine
     # scopes are defined on the model for finding records with or without a
     # particular set of states.
     # 
-    # These named scopes are the functional equivalent of the following
-    # definitions:
+    # These named scopes are essentially the functional equivalent of the
+    # following definitions:
     # 
     #   class Vehicle < ActiveRecord::Base
-    #     named_scope :with_states, lambda {|*values| {:conditions => {:state => values.flatten}}}
+    #     named_scope :with_states, lambda {|*states| {:conditions => {:state => states}}}
     #     # with_states also aliased to with_state
     #     
-    #     named_scope :without_states, lambda {|*values| {:conditions => ['state NOT IN (?)', values.flatten]}}
+    #     named_scope :without_states, lambda {|*states| {:conditions => ['state NOT IN (?)', states]}}
     #     # without_states also aliased to without_state
     #   end
     # 
+    # *Note*, however, that the states are converted to their stored values
+    # before being passed into the query.
+    # 
     # Because of the way named scopes work in ActiveRecord, they can be
     # chained like so:
     # 
-    #   Vehicle.with_state('parked').all(:order => 'id DESC')
+    #   Vehicle.with_state(:parked).all(:order => 'id DESC')
     # 
     # == Callbacks
     # 
@@ -91,8 +94,8 @@ module StateMachine
     # For example,
     # 
     #   class Vehicle < ActiveRecord::Base
-    #     state_machine :initial => 'parked' do
-    #       before_transition :to => 'idling' do |vehicle|
+    #     state_machine :initial => :parked do
+    #       before_transition :to => :idling do |vehicle|
     #         vehicle.put_on_seatbelt
     #       end
     #       
@@ -101,7 +104,7 @@ module StateMachine
     #       end
     #       
     #       event :ignite do
-    #         transition :to => 'idling', :from => 'parked'
+    #         transition :to => :idling, :from => :parked
     #       end
     #     end
     #     
@@ -164,6 +167,11 @@ module StateMachine
         defined?(::ActiveRecord::Base) && klass <= ::ActiveRecord::Base
       end
       
+      # Loads additional files specific to ActiveRecord
+      def self.extended(base) #:nodoc:
+        require 'state_machine/integrations/active_record/observer'
+      end
+      
       # Runs a new database transaction, rolling back any changes by raising
       # an ActiveRecord::Rollback exception if the yielded block fails
       # (i.e. returns false).
@@ -188,24 +196,23 @@ module StateMachine
         # Forces all attribute methods to be generated for the model so that
         # the reader/writer methods for the attribute are available
         def define_attribute_accessor
-          if owner_class.table_exists?
+          # If an exception is raised while trying to access the connection, then
+          # the assumption is that there's an issue with the database (most likely
+          # doesn't exist yet), so we won't be able to check the table properties
+          connection_exists = begin; owner_class.connection; true; rescue Exception; false; end
+          
+          if connection_exists && owner_class.table_exists?
             owner_class.define_attribute_methods
             
             # Support attribute predicate for ActiveRecord columns
-            if owner_class.column_names.include?(attribute)
+            if owner_class.column_names.include?(attribute.to_s)
               attribute = self.attribute
               
               owner_class.class_eval do
+                # Checks whether the current state is a given value.  If there
+                # are no arguments, then this checks for the presence of the attribute.
                 define_method("#{attribute}?") do |*args|
-                  if args.empty?
-                    # No arguments: querying for presence of the attribute
-                    super
-                  else
-                    # Arguments: querying for the attribute's current value
-                    state = args.first
-                    raise ArgumentError, "#{state.inspect} is not a known #{attribute} value" unless self.class.state_machines[attribute].states.include?(state)
-                    send(attribute) == state
-                  end
+                  args.empty? ? super(*args) : self.class.state_machines[attribute].state?(self, *args)
                 end
               end
             end
@@ -214,18 +221,18 @@ module StateMachine
           super
         end
         
-        # Defines a scope for finding records *with* a particular value or
-        # values for the attribute
-        def define_with_scope(name)
+        # Creates a scope for finding records *with* a particular state or
+        # states for the attribute
+        def create_with_scope(name)
           attribute = self.attribute
-          owner_class.named_scope name.to_sym, lambda {|*values| {:conditions => {attribute => values.flatten}}}
+          define_scope(name, lambda {|values| {:conditions => {attribute => values}}})
         end
         
-        # Defines a scope for finding records *without* a particular value or
-        # values for the attribute
-        def define_without_scope(name)
+        # Creates a scope for finding records *without* a particular state or
+        # states for the attribute
+        def create_without_scope(name)
           attribute = self.attribute
-          owner_class.named_scope name.to_sym, lambda {|*values| {:conditions => ["#{attribute} NOT IN (?)", values.flatten]}}
+          define_scope(name, lambda {|values| {:conditions => ["#{attribute} NOT IN (?)", values]}})
         end
         
         # Creates a new callback in the callback chain, always inserting it
@@ -240,6 +247,28 @@ module StateMachine
         end
         
       private
+        # Defines a new named scope with the given name.  Since ActiveRecord
+        # does not allow direct access to the model being used within the
+        # evaluation of a dynamic named scope, the scope must be generated
+        # manually.  It's necessary to have access to the model so that the
+        # state names can be translated to their associated values and so that
+        # inheritance is respected properly.
+        def define_scope(name, scope)
+          name = name.to_sym
+          attribute = self.attribute
+          
+          # Created 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_machines[attribute].states
+            values = states.flatten.map {|state| machine_states.fetch(state).value}
+            
+            ::ActiveRecord::NamedScope::Scope.new(klass, scope.call(values))
+          end
+          
+          false
+        end
+        
         # Notifies observers on the given object that a callback occurred
         # involving the given transition.  This will attempt to call the
         # following methods on observers:
@@ -251,11 +280,8 @@ module StateMachine
         def notify(type, object, transition)
           qualified_event = namespace ? "#{transition.event}_#{namespace}" : transition.event
           ["#{type}_#{qualified_event}", "#{type}_transition"].each do |method|
-            object.class.class_eval do
-              @observer_peers.dup.each do |observer|
-                observer.send(method, object, transition) if observer.respond_to?(method)
-              end if defined?(@observer_peers)
-            end
+            object.class.changed
+            object.class.notify_observers(method, object, transition)
           end
           
           true

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

@@ -0,0 +1,41 @@
+module StateMachine
+  module Integrations #:nodoc:
+    module ActiveRecord
+      # Adds support for invoking callbacks on ActiveRecord observers with more
+      # than one argument (e.g. the record *and* the state transition).  By
+      # default, ActiveRecord only supports passing the record into the
+      # callbacks.
+      # 
+      # For example:
+      # 
+      #   class VehicleObserver < ActiveRecord::Observer
+      #     # The default behavior: only pass in the record
+      #     def after_save(vehicle)
+      #     end
+      #     
+      #     # Custom behavior: allow the transition to be passed in as well
+      #     def after_transition(vehicle, transition)
+      #       Audit.log(vehicle, transition)
+      #     end
+      #   end
+      module Observer
+        def self.included(base) #:nodoc:
+          base.class_eval do
+            alias_method :update_without_multiple_args, :update
+            alias_method :update, :update_with_multiple_args
+          end
+        end
+        
+        # Allows additional arguments other than the object to be passed to the
+        # observed methods
+        def update_with_multiple_args(observed_method, object, *args) #:nodoc:
+          send(observed_method, object, *args) if respond_to?(observed_method)
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Observer.class_eval do
+  include StateMachine::Integrations::ActiveRecord::Observer
+end

data/lib/state_machine/integrations/data_mapper.rb

@@ -2,19 +2,6 @@ module StateMachine
   module Integrations #:nodoc:
     # Adds support for integrating state machines with DataMapper resources.
     # 
-    # == Requirements
-    # 
-    # To use this feature of the DataMapper integration, the dm-observer library
-    # must be available.  This can be installed either directly or indirectly
-    # through dm-more.  When loading DataMapper, be sure to load the dm-observer
-    # library as well like so:
-    # 
-    #   require 'rubygems'
-    #   require 'dm-core'
-    #   require 'dm-observer'
-    # 
-    # If dm-observer is not available, then this feature will be skipped.
-    # 
     # == Examples
     # 
     # Below is an example of a simple state machine defined within a
@@ -27,9 +14,9 @@ module StateMachine
     #     property :name, String
     #     property :state, String
     #     
-    #     state_machine :initial => 'parked' do
+    #     state_machine :initial => :parked do
     #       event :ignite do
-    #         transition :to => 'idling', :from => 'parked'
+    #         transition :to => :idling, :from => :parked
     #       end
     #     end
     #   end
@@ -47,7 +34,7 @@ module StateMachine
     # 
     # For example,
     # 
-    #   vehicle = Vehicle.create          # => #<Vehicle id=1 name=nil state=nil>
+    #   vehicle = Vehicle.create          # => #<Vehicle id=1 name=nil state="parked">
     #   vehicle.name = 'Ford Explorer'
     #   vehicle.ignite                    # => true
     #   vehicle.reload                    # => #<Vehicle id=1 name="Ford Explorer" state="idling">
@@ -74,7 +61,7 @@ module StateMachine
     #     end
     #   end
     #   
-    #   vehicle = Vehicle.create      # => #<Vehicle id=1 name=nil state=nil>
+    #   vehicle = Vehicle.create      # => #<Vehicle id=1 name=nil state="parked">
     #   vehicle.ignite                # => false
     #   Message.all.count             # => 0
     # 
@@ -99,22 +86,25 @@ module StateMachine
     #     property :state, String
     #     
     #     class << self
-    #       def with_states(*values)
-    #         all(:state => values.flatten)
+    #       def with_states(*states)
+    #         all(:state => states.flatten)
     #       end
     #       alias_method :with_state, :with_states
     #       
-    #       def without_states(*values)
-    #         all(:state.not => values.flatten)
+    #       def without_states(*states)
+    #         all(:state.not => states.flatten)
     #       end
     #       alias_method :without_state, :without_states
     #     end
     #   end
     # 
+    # *Note*, however, that the states are converted to their stored values
+    # before being passed into the query.
+    # 
     # Because of the way scopes work in DataMapper, they can be chained like
     # so:
     # 
-    #   Vehicle.with_state('parked').all(:order => [:id.desc])
+    #   Vehicle.with_state(:parked).all(:order => [:id.desc])
     # 
     # == Callbacks / Observers
     # 
@@ -131,8 +121,8 @@ module StateMachine
     #     property :id, Serial
     #     property :state, String
     #     
-    #     state_machine :initial => 'parked' do
-    #       before_transition :to => 'idling' do
+    #     state_machine :initial => :parked do
+    #       before_transition :to => :idling do
     #         put_on_seatbelt
     #       end
     #       
@@ -141,7 +131,7 @@ module StateMachine
     #       end
     #       
     #       event :ignite do
-    #         transition :to => 'idling', :from => 'parked'
+    #         transition :to => :idling, :from => :parked
     #       end
     #     end
     #     
@@ -181,22 +171,18 @@ module StateMachine
           :save
         end
         
-        # Defines a scope for finding records *with* a particular value or
-        # values for the attribute
-        def define_with_scope(name)
+        # Creates a scope for finding records *with* a particular state or
+        # states for the attribute
+        def create_with_scope(name)
           attribute = self.attribute
-          (class << owner_class; self; end).class_eval do
-            define_method(name) {|*values| all(attribute => values.flatten)}
-          end
+          lambda {|resource, values| resource.all(attribute => values)}
         end
         
-        # Defines a scope for finding records *without* a particular value or
-        # values for the attribute
-        def define_without_scope(name)
+        # Creates a scope for finding records *without* a particular state or
+        # states for the attribute
+        def create_without_scope(name)
           attribute = self.attribute
-          (class << owner_class; self; end).class_eval do
-            define_method(name) {|*values| all(attribute.to_sym.not => values.flatten)}
-          end
+          lambda {|resource, values| resource.all(attribute.to_sym.not => values)}
         end
         
         # Creates a new callback in the callback chain, always ensuring that

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

@@ -22,6 +22,20 @@ module StateMachine
       #       Audit.log(self, transition) if saved
       #     end
       #   end
+      # 
+      # == Requirements
+      # 
+      # To use this feature of the DataMapper integration, the dm-observer library
+      # must be available.  This can be installed either directly or indirectly
+      # through dm-more.  When loading DataMapper, be sure to load the dm-observer
+      # library as well like so:
+      # 
+      #   require 'rubygems'
+      #   require 'dm-core'
+      #   require 'dm-observer'
+      # 
+      # If dm-observer is not available, then this feature will be skipped.
+      # 
       module Observer
         # Creates a callback that will be invoked *before* a transition is
         # performed, so long as the given configuration options match the
@@ -39,9 +53,9 @@ module StateMachine
         #     property :id, Serial
         #     property :state, :String
         #     
-        #     state_machine :initial => 'parked' do
+        #     state_machine :initial => :parked do
         #       event :ignite do
-        #         transition :to => 'idling', :from => 'parked'
+        #         transition :to => :idling, :from => :parked
         #       end
         #     end
         #   end
@@ -56,12 +70,12 @@ module StateMachine
         #     end
         #     
         #     # Target all state machines
-        #     before_transition :to => 'idling', :from => 'parked', :on => 'ignite' do
+        #     before_transition :to => :idling, :from => :parked, :on => :ignite do
         #       # put on seatbelt
         #     end
         #     
         #     # Target a specific state machine
-        #     before_transition :state, :to => 'idling' do
+        #     before_transition :state, :to => :idling do
         #       # put on seatbelt
         #     end
         #     
@@ -95,9 +109,9 @@ module StateMachine
         #     property :id, Serial
         #     property :state, :String
         #     
-        #     state_machine :initial => 'parked' do
+        #     state_machine :initial => :parked do
         #       event :ignite do
-        #         transition :to => 'idling', :from => 'parked'
+        #         transition :to => :idling, :from => :parked
         #       end
         #     end
         #   end
@@ -112,12 +126,12 @@ module StateMachine
         #     end
         #     
         #     # Target all state machines
-        #     after_transition :to => 'idling', :from => 'parked', :on => 'ignite' do
+        #     after_transition :to => :idling, :from => :parked, :on => :ignite do
         #       # put on seatbelt
         #     end
         #     
         #     # Target a specific state machine
-        #     after_transition :state, :to => 'idling' do
+        #     after_transition :state, :to => :idling do
         #       # put on seatbelt
         #     end
         #     
@@ -143,7 +157,7 @@ module StateMachine
           def add_transition_callback(type, *args, &block)
             if args.first && !args.first.is_a?(Hash)
               # Specific attribute is being targeted
-              attribute = args.first.to_s
+              attribute = args.first
               transition_args = args[1..-1]
             else
               # Target all state machines

data/lib/state_machine/integrations/sequel.rb

@@ -8,9 +8,9 @@ module StateMachine
     # Sequel model:
     # 
     #   class Vehicle < Sequel::Model
-    #     state_machine :initial => 'parked' do
+    #     state_machine :initial => :parked do
     #       event :ignite do
-    #         transition :to => 'idling', :from => 'parked'
+    #         transition :to => :idling, :from => :parked
     #       end
     #     end
     #   end
@@ -28,7 +28,7 @@ module StateMachine
     # 
     # For example,
     # 
-    #   vehicle = Vehicle.create          # => #<Vehicle id=1 name=nil state=nil>
+    #   vehicle = Vehicle.create          # => #<Vehicle id=1 name=nil state="parked">
     #   vehicle.name = 'Ford Explorer'
     #   vehicle.ignite                    # => true
     #   vehicle.refresh                   # => #<Vehicle id=1 name="Ford Explorer" state="idling">
@@ -51,7 +51,7 @@ module StateMachine
     #     end
     #   end
     #   
-    #   vehicle = Vehicle.create      # => #<Vehicle id=1 name=nil state=nil>
+    #   vehicle = Vehicle.create      # => #<Vehicle id=1 name=nil state="parked">
     #   vehicle.ignite                # => false
     #   Message.count                 # => 0
     # 
@@ -71,21 +71,24 @@ module StateMachine
     # 
     #   class Vehicle < Sequel::Model
     #     class << self
-    #       def with_states(*values)
-    #         filter(:state => values)
+    #       def with_states(*states)
+    #         filter(:state => states)
     #       end
     #       alias_method :with_state, :with_states
     #       
-    #       def without_states(*values)
-    #         filter(~{:state => values})
+    #       def without_states(*states)
+    #         filter(~{:state => states})
     #       end
     #       alias_method :without_state, :without_states
     #     end
     #   end
     # 
+    # *Note*, however, that the states are converted to their stored values
+    # before being passed into the query.
+    # 
     # Because of the way scopes work in Sequel, they can be chained like so:
     # 
-    #   Vehicle.with_state('parked').with_state('idling').order(:id.desc)
+    #   Vehicle.with_state(:parked).order(:id.desc)
     # 
     # == Callbacks
     # 
@@ -97,8 +100,8 @@ module StateMachine
     # For example,
     # 
     #   class Vehicle < Sequel::Model
-    #     state_machine :initial => 'parked' do
-    #       before_transition :to => 'idling' do
+    #     state_machine :initial => :parked do
+    #       before_transition :to => :idling do
     #         put_on_seatbelt
     #       end
     #       
@@ -107,7 +110,7 @@ module StateMachine
     #       end
     #       
     #       event :ignite do
-    #         transition :to => 'idling', :from => 'parked'
+    #         transition :to => :idling, :from => :parked
     #       end
     #     end
     #     
@@ -138,22 +141,18 @@ module StateMachine
           :save
         end
         
-        # Defines a scope for finding records *with* a particular value or
-        # values for the attribute
-        def define_with_scope(name)
+        # Creates a scope for finding records *with* a particular state or
+        # states for the attribute
+        def create_with_scope(name)
           attribute = self.attribute
-          (class << owner_class; self; end).class_eval do
-            define_method(name) {|*values| filter(attribute.to_sym => values.flatten)}
-          end
+          lambda {|model, values| model.filter(attribute.to_sym => values)}
         end
         
-        # Defines a scope for finding records *without* a particular value or
-        # values for the attribute
-        def define_without_scope(name)
+        # Creates a scope for finding records *without* a particular state or
+        # states for the attribute
+        def create_without_scope(name)
           attribute = self.attribute
-          (class << owner_class; self; end).class_eval do
-            define_method(name) {|*values| filter(~{attribute.to_sym => values.flatten})}
-          end
+          lambda {|model, values| model.filter(~{attribute.to_sym => values})}
         end
         
         # Creates a new callback in the callback chain, always ensuring that