state_machine 1.0.2 → 1.0.3

data/lib/state_machine.rb

@@ -306,6 +306,51 @@ module StateMachine
     # Each predicate method will return true if it matches the object's
     # current state.  Otherwise, it will return false.
     # 
+    # == Attribute access
+    # 
+    # The actual value for a state is stored in the attribute configured for the
+    # state machine.  In most cases, this is the same as the name of the state
+    # machine.  For example:
+    # 
+    #   class Vehicle
+    #     attr_accessor :state
+    #     
+    #     state_machine :state, :initial => :parked do
+    #       ...
+    #       state :parked, :value => 0
+    #       start :idling, :value => 1
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.new # => #<Vehicle:0xb712da60 @state=0>
+    #   vehicle.state         # => 0
+    #   vehicle.parked?       # => true
+    #   vehicle.state = 1
+    #   vehicle.idling?       # => true
+    # 
+    # The most important thing to note from the example above is what it means
+    # to read from and write to the state machine's attribute.  In particular,
+    # state_machine treats the attribute (+state+ in this case) like a basic
+    # attr_accessor that's been defined on the class.  There are no special
+    # behaviors added, such as allowing the attribute to be written to based on
+    # the name of a state in the machine.  This is the case for a few reasons:
+    # * Setting the attribute directly is an edge case that is meant to only be
+    #   used when you want to skip state_machine altogether.  This means that
+    #   state_machine shouldn't have any effect on the attribute accessor
+    #   methods.  If you want to change the state, you should be using one of
+    #   the events defined in the state machine.
+    # * Many ORMs provide custom behavior for the attribute reader / writer - it
+    #   may even be defined by your own framework / method implementation just
+    #   the example above showed.  In order to avoid having to worry about the
+    #   different ways an attribute can get written, state_machine just makes
+    #   sure that the configured value for a state is always used when writing
+    #   to the attribute.
+    # 
+    # If you were interested in accessing the name of a state (instead of its
+    # actual value through the attribute), you could do the following:
+    # 
+    #   vehicle.state_name    # => :idling
+    # 
     # == Events and Transitions
     # 
     # Events defined on the machine are the interface to transitioning states

data/lib/state_machine/event.rb

@@ -67,6 +67,11 @@ module StateMachine
       end
     end
     
+    # Converts the name of this event to a string
+    def name_to_s
+      name.to_s
+    end
+    
     # Creates a copy of this event in addition to the list of associated
     # branches to prevent conflicts across events within a class hierarchy.
     def initialize_copy(orig) #:nodoc:
@@ -81,6 +86,12 @@ module StateMachine
       @human_name.is_a?(Proc) ? @human_name.call(self, klass) : @human_name
     end
     
+    # Evaluates the given block within the context of this event.  This simply
+    # provides a DSL-like syntax for defining transitions.
+    def context(&block)
+      instance_eval(&block)
+    end
+    
     # Creates a new transition that determines what to change the current state
     # to when this event fires.
     # 
@@ -113,6 +124,10 @@ module StateMachine
     # on the current state of the given object.
     # 
     # If the event can't be fired, then this will return false, otherwise true.
+    # 
+    # *Note* that this will not take the object context into account.  Although
+    # a transition may be possible based on the state machine definition,
+    # object-specific behaviors (like validations) may prevent it from firing.
     def can_fire?(object, requirements = {})
       !transition_for(object, requirements).nil?
     end
@@ -165,10 +180,10 @@ module StateMachine
     # Marks the object as invalid and runs any failure callbacks associated with
     # this event.  This should get called anytime this event fails to transition.
     def on_failure(object)
-      machine.invalidate(object, :state, :invalid_transition, [[:event, human_name(object.class)]])
+      state = machine.states.match!(object)
+      machine.invalidate(object, :state, :invalid_transition, [[:event, human_name(object.class)], [:state, state.human_name(object.class)]])
       
-      state = machine.states.match!(object).name
-      Transition.new(object, machine, name, state, state).run_callbacks(:before => false)
+      Transition.new(object, machine, name, state.name, state.name).run_callbacks(:before => false)
     end
     
     # Draws a representation of this event on the given graph.  This will

data/lib/state_machine/event_collection.rb

@@ -2,7 +2,7 @@ module StateMachine
   # Represents a collection of events in a state machine
   class EventCollection < NodeCollection
     def initialize(machine) #:nodoc:
-      super(machine, :index => [:name, :qualified_name])
+      super(machine, :index => [:name, :name_to_s, :qualified_name])
     end
     
     # Gets the list of events that can be fired on the given object.

data/lib/state_machine/integrations/active_model.rb

@@ -227,6 +227,56 @@ module StateMachine
     #     end
     #   end
     # 
+    # == Internationalization
+    # 
+    # Any error message that is generated from performing invalid transitions
+    # can be localized.  The following default translations are used:
+    # 
+    #   en:
+    #     activemodel:
+    #       errors:
+    #         messages:
+    #           invalid: "is invalid"
+    #           # %{value} = attribute value, %{state} = Human state name
+    #           invalid_event: "cannot transition when %{state}"
+    #           # %{value} = attribute value, %{event} = Human event name, %{state} = Human current state name
+    #           invalid_transition: "cannot transition via %{event}"
+    # 
+    # You can override these for a specific model like so:
+    # 
+    #   en:
+    #     activemodel:
+    #       errors:
+    #         models:
+    #           user:
+    #             invalid: "is not valid"
+    # 
+    # In addition to the above, you can also provide translations for the
+    # various states / events in each state machine.  Using the Vehicle example,
+    # state translations will be looked for using the following keys, where
+    # +model_name+ = "vehicle", +machine_name+ = "state" and +state_name+ = "parked":
+    # * <tt>activemodel.state_machines.#{model_name}.#{machine_name}.states.#{state_name}</tt>
+    # * <tt>activemodel.state_machines.#{model_name}.states.#{state_name}</tt>
+    # * <tt>activemodel.state_machines.#{machine_name}.states.#{state_name}</tt>
+    # * <tt>activemodel.state_machines.states.#{state_name}</tt>
+    # 
+    # Event translations will be looked for using the following keys, where
+    # +model_name+ = "vehicle", +machine_name+ = "state" and +event_name+ = "ignite":
+    # * <tt>activemodel.state_machines.#{model_name}.#{machine_name}.events.#{event_name}</tt>
+    # * <tt>activemodel.state_machines.#{model_name}.events.#{event_name}</tt>
+    # * <tt>activemodel.state_machines.#{machine_name}.events.#{event_name}</tt>
+    # * <tt>activemodel.state_machines.events.#{event_name}</tt>
+    # 
+    # An example translation configuration might look like so:
+    # 
+    #   es:
+    #     activemodel:
+    #       state_machines:
+    #         states:
+    #           parked: 'estacionado'
+    #         events:
+    #           park: 'estacionarse'
+    # 
     # == Dirty Attribute Tracking
     # 
     # In order to hook in validation support for your model, the
@@ -255,9 +305,9 @@ module StateMachine
     # == Creating new integrations
     # 
     # If you want to integrate state_machine with an ORM that implements parts
-    # or all of the ActiveModel API, the following features must be specified:
-    # * i18n scope (locale)
-    # * Machine defaults
+    # or all of the ActiveModel API, only the machine defaults need to be
+    # specified.  Otherwise, the implementation is similar to any other
+    # integration.
     # 
     # For example,
     # 
@@ -270,19 +320,10 @@ module StateMachine
     #       defined?(::MyORM::Base) && klass <= ::MyORM::Base
     #     end
     #     
-    #     def self.extended(base)
-    #       locale = "#{File.dirname(__FILE__)}/my_orm/locale.rb"
-    #       I18n.load_path << locale unless I18n.load_path.include?(locale)
-    #     end
-    #     
     #     protected
     #       def runs_validations_on_action?
     #         action == :persist
     #       end
-    #       
-    #       def i18n_scope
-    #         :myorm
-    #       end
     #   end
     # 
     # If you wish to implement other features, such as attribute initialization
@@ -391,6 +432,7 @@ module StateMachine
         # Translates the given key / value combo.  Translation keys are looked
         # up in the following order:
         # * <tt>#{i18n_scope}.state_machines.#{model_name}.#{machine_name}.#{plural_key}.#{value}</tt>
+        # * <tt>#{i18n_scope}.state_machines.#{model_name}.#{plural_key}.#{value}</tt>
         # * <tt>#{i18n_scope}.state_machines.#{machine_name}.#{plural_key}.#{value}</tt>
         # * <tt>#{i18n_scope}.state_machines.#{plural_key}.#{value}</tt>
         # 
@@ -402,6 +444,7 @@ module StateMachine
           
           # 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.concat([:"#{name}.#{group}.#{value}", :"#{group}.#{value}", value.humanize.downcase])
           I18n.translate(translations.shift, :default => translations, :scope => [i18n_scope(klass), :state_machines])
         end
@@ -513,22 +556,22 @@ module StateMachine
         def notify(type, object, transition)
           name = self.name
           event = transition.qualified_event
-          from = transition.from_name
-          to = transition.to_name
+          from = transition.from_name || 'nil'
+          to = transition.to_name || 'nil'
           
           # Machine-specific updates
           ["#{type}_#{event}", "#{type}_transition_#{name}"].each do |event_segment|
             ["_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([event_segment, from_segment, to_segment].join, object, transition)
+                object.class.notify_observers('update_with_transition', [[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("#{type}_transition", object, transition)
+          object.class.notify_observers('update_with_transition', ["#{type}_transition", object, transition])
           
           true
         end

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

@@ -19,21 +19,9 @@ module StateMachine
       #     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:
-          if args.any?
-            send(observed_method, object, *args) if respond_to?(observed_method)
-          else
-            update_without_multiple_args(observed_method, object)
-          end
+        def update_with_transition(args)
+          observed_method, object, transition = args
+          send(observed_method, object, transition) if respond_to?(observed_method)
         end
       end
     end

data/lib/state_machine/integrations/active_record.rb

@@ -220,6 +220,11 @@ module StateMachine
     # 
     #   Vehicle.with_state(:parked).all(:order => 'id DESC')
     # 
+    # Note that states can also be referenced by the string version of their
+    # name:
+    # 
+    #   Vehicle.with_state('parked')
+    # 
     # == Callbacks
     # 
     # All before/after transition callbacks defined for ActiveRecord models
@@ -251,6 +256,32 @@ module StateMachine
     # Note, also, that the transition can be accessed by simply defining
     # additional arguments in the callback block.
     # 
+    # === Failure callbacks
+    # 
+    # +after_failure+ callbacks allow you to execute behaviors when a transition
+    # is allowed, but fails to save.  This could be useful for something like
+    # auditing transition attempts.  Since callbacks run within transactions in
+    # ActiveRecord, a save failure will cause any records that get created in
+    # your callback to roll back.  You can work around this issue like so:
+    # 
+    #   class TransitionLog < ActiveRecord::Base
+    #     establish_connection Rails.env.to_sym
+    #   end
+    #   
+    #   class Vehicle < ActiveRecord::Base
+    #     state_machine do
+    #       after_failure do |vehicle, transition|
+    #         TransitionLog.create(:vehicle => vehicle, :transition => transition)
+    #       end
+    #       
+    #       ...
+    #     end
+    #   end
+    # 
+    # The +TransitionLog+ model establishes a second connection to the database
+    # that allows new records to be saved without being affected by rollbacks
+    # in the +Vehicle+ model's transaction.
+    # 
     # == Observers
     # 
     # In addition to support for ActiveRecord-like hooks, there is additional
@@ -317,7 +348,9 @@ module StateMachine
     #       errors:
     #         messages:
     #           invalid: "is invalid"
+    #           # %{value} = attribute value, %{state} = Human state name
     #           invalid_event: "cannot transition when %{state}"
+    #           # %{value} = attribute value, %{event} = Human event name, %{state} = Human current state name
     #           invalid_transition: "cannot transition via %{event}"
     # 
     # Notice that the interpolation syntax is %{key} in Rails 3+.  In Rails 2.x,
@@ -334,15 +367,19 @@ module StateMachine
     # 
     # In addition to the above, you can also provide translations for the
     # various states / events in each state machine.  Using the Vehicle example,
-    # state translations will be looked for using the following keys:
-    # * <tt>activerecord.state_machines.vehicle.state.states.parked</tt>
-    # * <tt>activerecord.state_machines.state.states.parked
-    # * <tt>activerecord.state_machines.states.parked</tt>
-    # 
-    # Event translations will be looked for using the following keys:
-    # * <tt>activerecord.state_machines.vehicle.state.events.ignite</tt>
-    # * <tt>activerecord.state_machines.state.events.ignite
-    # * <tt>activerecord.state_machines.events.ignite</tt>
+    # state translations will be looked for using the following keys, where
+    # +model_name+ = "vehicle", +machine_name+ = "state" and +state_name+ = "parked":
+    # * <tt>activerecord.state_machines.#{model_name}.#{machine_name}.states.#{state_name}</tt>
+    # * <tt>activerecord.state_machines.#{model_name}.states.#{state_name}</tt>
+    # * <tt>activerecord.state_machines.#{machine_name}.states.#{state_name}</tt>
+    # * <tt>activerecord.state_machines.states.#{state_name}</tt>
+    # 
+    # Event translations will be looked for using the following keys, where
+    # +model_name+ = "vehicle", +machine_name+ = "state" and +event_name+ = "ignite":
+    # * <tt>activerecord.state_machines.#{model_name}.#{machine_name}.events.#{event_name}</tt>
+    # * <tt>activerecord.state_machines.#{model_name}.events.#{event_name}</tt>
+    # * <tt>activerecord.state_machines.#{machine_name}.events.#{event_name}</tt>
+    # * <tt>activerecord.state_machines.events.#{event_name}</tt>
     # 
     # An example translation configuration might look like so:
     # 

data/lib/state_machine/integrations/data_mapper.rb

@@ -214,6 +214,11 @@ module StateMachine
     # 
     #   Vehicle.with_state(:parked).all(:order => [:id.desc])
     # 
+    # Note that states can also be referenced by the string version of their
+    # name:
+    # 
+    #   Vehicle.with_state('parked')
+    # 
     # == Callbacks / Observers
     # 
     # All before/after transition callbacks defined for DataMapper resources
@@ -254,6 +259,41 @@ module StateMachine
     # In addition to support for DataMapper-like hooks, there is additional
     # support for DataMapper observers.  See StateMachine::Integrations::DataMapper::Observer
     # for more information.
+    # 
+    # === Failure callbacks
+    # 
+    # +after_failure+ callbacks allow you to execute behaviors when a transition
+    # is allowed, but fails to save.  This could be useful for something like
+    # auditing transition attempts.  Since callbacks run within transactions in
+    # DataMapper, a save failure will cause any records that get created in
+    # your callback to roll back.  *Note* that this is only a problem if the
+    # machine is configured to use transactions.  If it is, you can work around
+    # this issue like so:
+    # 
+    #   DataMapper.setup(:default, 'mysql://localhost/app')
+    #   DataMapper.setup(:logs, 'mysql://localhost/app')
+    #   
+    #   class TransitionLog
+    #     include DataMapper::Resource
+    #   end
+    #   
+    #   class Vehicle < ActiveRecord::Base
+    #     include DataMapper::Resource
+    #     
+    #     state_machine :use_transactions => true do
+    #       after_failure do |transition|
+    #         DataMapper.repository(:logs) do
+    #           TransitionLog.create(:vehicle => vehicle, :transition => transition)
+    #         end
+    #       end
+    #       
+    #       ...
+    #     end
+    #   end
+    # 
+    # The failure callback creates +TransitionLog+ records using a second
+    # connection to the database, allowing them to be saved without being
+    # affected by rollbacks in the +Vehicle+ resource's transaction.
     module DataMapper
       include Base
       
@@ -398,9 +438,9 @@ module StateMachine
         # 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.persisted_state = ::DataMapper::Resource::State::Dirty.new(object) if object.persisted_state.is_a?(::DataMapper::Resource::State::Clean)
+          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.persisted_state.original_attributes[property] = value unless object.persisted_state.original_attributes.include?(property)
+          object.persistence_state.original_attributes[property] = value unless object.persistence_state.original_attributes.include?(property)
         end
     end
   end

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

@@ -25,16 +25,6 @@ module StateMachine
         end
       end
       
-      version '1.0.0' do
-        def self.active?
-          ::DataMapper::VERSION == '1.0.0'
-        end
-        
-        def pluralize(word)
-          (defined?(::ActiveSupport::Inflector) ? ::ActiveSupport::Inflector : ::Extlib::Inflection).pluralize(word.to_s)
-        end
-      end
-      
       version '0.9.4 - 0.9.6' do
         def self.active?
           ::DataMapper::VERSION =~ /^0\.9\.[4-6]/
@@ -57,6 +47,28 @@ module StateMachine
           object.original_attributes[property] = "#{value}-ignored" unless object.original_attributes.include?(property)
         end
       end
+      
+      version '1.0.x - 1.1.x' do
+        def self.active?
+          ::DataMapper::VERSION =~ /^1\.[01]\./
+        end
+        
+        def mark_dirty(object, value)
+          object.persisted_state = ::DataMapper::Resource::State::Dirty.new(object) if object.persisted_state.is_a?(::DataMapper::Resource::State::Clean)
+          property = owner_class.properties[self.attribute]
+          object.persisted_state.original_attributes[property] = value unless object.persisted_state.original_attributes.include?(property)
+        end
+      end
+      
+      version '1.0.0' do
+        def self.active?
+          ::DataMapper::VERSION == '1.0.0'
+        end
+        
+        def pluralize(word)
+          (defined?(::ActiveSupport::Inflector) ? ::ActiveSupport::Inflector : ::Extlib::Inflection).pluralize(word.to_s)
+        end
+      end
     end
   end
 end