state_machine 0.9.2 → 0.9.3

data/CHANGELOG.rdoc

@@ -1,5 +1,15 @@
 == master
 
+== 0.9.3 / 2010-06-26
+
+* Allow access to human state / event names in transitions and for the current state
+* Use human state / event names in error messages
+* Fix event names being used inconsistently in error messages
+* Allow access to the humanized version of state / event names via human_state_name / human_state_event_name
+* Allow MongoMapper 0.8.0+ scopes to be chainable
+* Fix i18n deprecation warnings in ActiveModel / ActiveRecord 3.0.0.beta4
+* Fix default error message translations overriding existing locales in ActiveModel / ActiveRecord
+
 == 0.9.2 / 2010-05-24
 
 * Fix MongoMapper integration failing in Ruby 1.9.2

data/README.rdoc

@@ -181,6 +181,7 @@ like so:
   vehicle = Vehicle.new           # => #<Vehicle:0xb7cf4eac @state="parked", @seatbelt_on=false>
   vehicle.state                   # => "parked"
   vehicle.state_name              # => :parked
+  vehicle.human_state_name        # => "parked"
   vehicle.parked?                 # => true
   vehicle.can_ignite?             # => true
   vehicle.ignite_transition       # => #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
@@ -228,6 +229,13 @@ like so:
   vehicle.alarm_state_name                        # => :active
   
   vehicle.fire_events!(:ignite, :enable_alarm)    # => StateMachine::InvalidTransition: Cannot run events in parallel: ignite, enable_alarm
+  
+  # Human-friendly names can be accessed for states/events
+  Vehicle.human_state_name(:first_gear)               # => "first gear"
+  Vehicle.human_alarm_state_name(:active)             # => "active"
+  
+  Vehicle.human_state_event_name(:shift_down)         # => "shift down"
+  Vehicle.human_alarm_state_event_name(:enable_alarm) # => "enable alarm"
 
 == Integrations
 

data/Rakefile

@@ -6,7 +6,7 @@ require 'rake/gempackagetask'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'state_machine'
-  s.version           = '0.9.2'
+  s.version           = '0.9.3'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Adds support for creating state machines for attributes on any Ruby class'
   s.description       = s.summary

data/examples/merb-rest/view_edit.html.erb

@@ -9,12 +9,12 @@
   
   <p>
     <%= label :state %><br />
-    <%= select :state_event, :selected => @user.state_event.to_s, :collection => @user.state_transitions, :value_method => :event, :text_method => :to_name, :prompt => @user.state_name.to_s %>
+    <%= select :state_event, :selected => @user.state_event.to_s, :collection => @user.state_transitions, :value_method => :event, :text_method => :human_to_name, :prompt => @user.human_state_name %>
   </p>
   
   <p>
     <%= label :access_state %><br />
-    <%= select :access_state_event, :selected => @user.access_state_event.to_s, :collection => @user.access_state_transitions, :value_method => :event, :text_method => :event, :prompt => "don't change" %>
+    <%= select :access_state_event, :selected => @user.access_state_event.to_s, :collection => @user.access_state_transitions, :value_method => :event, :text_method => :human_event, :prompt => "don't change" %>
   </p>
   
   <p><%= submit 'Update' %></p>

data/examples/merb-rest/view_index.html.erb

@@ -10,8 +10,8 @@
 <% @users.each do |user| %>
   <tr>
     <td><%=h user.name %></td>
-    <td><%=h user.state %></td>
-    <td><%=h user.access_state %></td>
+    <td><%=h user.human_state_name %></td>
+    <td><%=h user.human_access_state_name %></td>
     <td><%= link_to 'Show', resource(user) %></td>
     <td><%= link_to 'Edit', resource(user, :edit) %></td>
   </tr>

data/examples/merb-rest/view_show.html.erb

@@ -5,12 +5,12 @@
 
 <p>
   <b>State:</b>
-  <%=h @user.state %>
+  <%=h @user.human_state_name %>
 </p>
 
 <p>
   <b>Access State:</b>
-  <%=h @user.access_state %>
+  <%=h @user.human_access_state_name %>
 </p>
 
 <%= link_to 'Edit', resource(@user, :edit) %> |

data/examples/rails-rest/view_edit.html.erb

@@ -10,12 +10,12 @@
   
   <p>
     <%= f.label :state %><br />
-    <%= f.collection_select :state_event, @user.state_transitions, :event, :to_name, :include_blank => @user.state_name.to_s %>
+    <%= f.collection_select :state_event, @user.state_transitions, :event, :human_to_name, :include_blank => @user.human_state_name %>
   </p>
   
   <p>
     <%= f.label :access_state %><br />
-    <%= f.collection_select :access_state_event, @user.access_state_transitions, :event, :event, :include_blank => "don't change" %>
+    <%= f.collection_select :access_state_event, @user.access_state_transitions, :event, :human_event, :include_blank => "don't change" %>
   </p>
   
   <p><%= f.submit 'Update' %></p>

data/examples/rails-rest/view_index.html.erb

@@ -10,8 +10,8 @@
 <% @users.each do |user| %>
   <tr>
     <td><%=h user.name %></td>
-    <td><%=h user.state %></td>
-    <td><%=h user.access_state %></td>
+    <td><%=h user.human_state_name %></td>
+    <td><%=h user.human_access_state_name %></td>
     <td><%= link_to 'Show', user %></td>
     <td><%= link_to 'Edit', edit_user_path(user) %></td>
   </tr>

data/examples/rails-rest/view_show.html.erb

@@ -5,12 +5,12 @@
 
 <p>
   <b>State:</b>
-  <%=h @user.state %>
+  <%=h @user.human_state_name %>
 </p>
 
 <p>
   <b>Access State:</b>
-  <%=h @user.access_state %>
+  <%=h @user.human_access_state_name %>
 </p>
 
 <%= link_to 'Edit', edit_user_path(@user) %> |

data/lib/state_machine.rb

@@ -90,6 +90,37 @@ module StateMachine
     #     end
     #   end
     # 
+    # == Class Methods
+    # 
+    # The following class methods will be automatically generated by the
+    # state machine based on the *name* of the machine.  Any existing methods
+    # will not be overwritten.
+    # * <tt>human_state_name(state)</tt> - Gets the humanized value for the
+    #   given state.  This may be generated by internationalization libraries if
+    #   supported by the integration.
+    # * <tt>human_state_event_name(event)</tt> - Gets the humanized value for
+    #   the given event.  This may be generated by internationalization
+    #   libraries if supported by the integration.
+    # 
+    # For example,
+    # 
+    #   class Vehicle
+    #     state_machine :state, :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #       
+    #       event :shift_up do
+    #         transition :idling => :first_gear
+    #       end
+    #     end
+    #   end
+    #   
+    #   Vehicle.human_state_name(:parked)         # => "parked"
+    #   Vehicle.human_state_name(:first_gear)     # => "first gear"
+    #   Vehicle.human_state_event_name(:park)     # => "park"
+    #   Vehicle.human_state_event_name(:shift_up) # => "shift up"
+    # 
     # == Instance Methods
     # 
     # The following instance methods will be automatically generated by the
@@ -100,6 +131,8 @@ module StateMachine
     # * <tt>state?(name)</tt> - Checks the given state name against the current
     #   state.  If the name is not a known state, then an ArgumentError is raised.
     # * <tt>state_name</tt> - Gets the name of the state for the current value
+    # * <tt>human_state_name</tt> - Gets the human-readable name of the state
+    #   for the current value
     # * <tt>state_events</tt> - Gets the list of events that can be fired on
     #   the current object's state (uses the *unqualified* event names)
     # * <tt>state_transitions(requirements = {})</tt> - Gets the list of possible
@@ -125,6 +158,7 @@ module StateMachine
     #   vehicle = Vehicle.new
     #   vehicle.state                     # => "parked"
     #   vehicle.state_name                # => :parked
+    #   vehicle.human_state_name          # => "parked"
     #   vehicle.state?(:parked)           # => true
     #   
     #   # Changing state

data/lib/state_machine/event.rb

@@ -24,6 +24,9 @@ module StateMachine
     # The fully-qualified name of the event, scoped by the machine's namespace 
     attr_reader :qualified_name
     
+    # The human-readable name for the event
+    attr_writer :human_name
+    
     # The list of guards that determine what state this event transitions
     # objects to when fired
     attr_reader :guards
@@ -33,10 +36,16 @@ module StateMachine
     attr_reader :known_states
     
     # Creates a new event within the context of the given machine
-    def initialize(machine, name) #:nodoc:
+    # 
+    # Configuration options:
+    # * <tt>:human_name</tt> - The human-readable version of this event's name
+    def initialize(machine, name, options = {}) #:nodoc:
+      assert_valid_keys(options, :human_name)
+      
       @machine = machine
       @name = name
       @qualified_name = machine.namespace ? :"#{name}_#{machine.namespace}" : name
+      @human_name = options[:human_name] || @name.to_s.tr('_', ' ')
       @guards = []
       @known_states = []
       
@@ -51,6 +60,12 @@ module StateMachine
       @known_states = @known_states.dup
     end
     
+    # Transforms the event name into a more human-readable format, such as
+    # "turn on" instead of "turn_on"
+    def human_name(klass = @machine.owner_class)
+      @human_name.is_a?(Proc) ? @human_name.call(self, klass) : @human_name
+    end
+    
     # Creates a new transition that determines what to change the current state
     # to when this event fires.
     # 
@@ -191,7 +206,7 @@ module StateMachine
       if transition = transition_for(object)
         transition.perform(*args)
       else
-        machine.invalidate(object, :state, :invalid_transition, [[:event, name]])
+        machine.invalidate(object, :state, :invalid_transition, [[:event, human_name(object.class)]])
         false
       end
     end

data/lib/state_machine/event_collection.rb

@@ -106,7 +106,7 @@ module StateMachine
         if event = self[event_name.to_sym, :name]
           event.transition_for(object) || begin
             # No valid transition: invalidate
-            machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).name || 'nil']]) if invalidate
+            machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).human_name(object.class)]]) if invalidate
             false
           end
         else

data/lib/state_machine/integrations/active_model.rb

@@ -224,7 +224,7 @@ module StateMachine
           
           if Object.const_defined?(:I18n)
             locale = "#{File.dirname(__FILE__)}/active_model/locale.rb"
-            I18n.load_path << locale unless I18n.load_path.include?(locale)
+            I18n.load_path.unshift(locale) unless I18n.load_path.include?(locale)
           end
         end
       end
@@ -262,15 +262,8 @@ module StateMachine
       def invalidate(object, attribute, message, values = [])
         if supports_validations?
           attribute = self.attribute(attribute)
-          ancestors = ancestors_for(object.class)
-          
           options = values.inject({}) do |options, (key, value)|
-            # Generate all possible translation keys
-            group = key.to_s.pluralize
-            translations = ancestors.map {|ancestor| :"#{ancestor.model_name.underscore}.#{name}.#{group}.#{value}"}
-            translations.concat([:"#{name}.#{group}.#{value}", :"#{group}.#{value}", value.to_s])
-            
-            options[key] = I18n.translate(translations.shift, :default => translations, :scope => [i18n_scope, :state_machines])
+            options[key] = value
             options
           end
           
@@ -309,22 +302,40 @@ module StateMachine
           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}
+        end
+        
         # Determines the base scope to use when looking up translations
         def i18n_scope
           owner_class.i18n_scope
         end
         
+        # 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.#{machine_name}.#{plural_key}.#{value}
+        # * <tt>#{i18n_scope}.state_machines.#{plural_key}.#{value}</tt>
+        # 
+        # If no keys are found, then the humanized value will be the fallback.
+        def translate(klass, key, value)
+          ancestors = ancestors_for(klass)
+          group = key.to_s.pluralize
+          value = value ? value.to_s : 'nil'
+          
+          # Generate all possible translation keys
+          translations = ancestors.map {|ancestor| :"#{ancestor.model_name.underscore}.#{name}.#{group}.#{value}"}
+          translations.concat([:"#{name}.#{group}.#{value}", :"#{group}.#{value}", value.humanize.downcase])
+          I18n.translate(translations.shift, :default => translations, :scope => [i18n_scope, :state_machines])
+        end
+        
         # Build a list of ancestors for the given class to use when
         # determining which localization key to use for a particular string.
         def ancestors_for(klass)
           klass.lookup_ancestors
         end
         
-        # Gets the terminator to use for callbacks
-        def callback_terminator
-          @terminator ||= lambda {|result| result == false}
-        end
-        
         # Adds the default callbacks for notifying ActiveModel observers
         # before/after a transition has been performed.
         def after_initialize
@@ -371,7 +382,20 @@ module StateMachine
           end
         end
         
-      private
+        # 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)}
+          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)}
+          end
+        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:

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

@@ -3,8 +3,8 @@
     :errors => {
       :messages => {
         :invalid => StateMachine::Machine.default_messages[:invalid],
-        :invalid_event => StateMachine::Machine.default_messages[:invalid_event] % ['{{state}}'],
-        :invalid_transition => StateMachine::Machine.default_messages[:invalid_transition] % ['{{event}}']
+        :invalid_event => StateMachine::Machine.default_messages[:invalid_event] % ['%{state}'],
+        :invalid_transition => StateMachine::Machine.default_messages[:invalid_transition] % ['%{event}']
       }
     }
   }

data/lib/state_machine/integrations/active_record.rb

@@ -276,8 +276,11 @@ module StateMachine
     #       errors:
     #         messages:
     #           invalid: "is invalid"
-    #           invalid_event: "cannot transition when {{state}}"
-    #           invalid_transition: "cannot transition via {{event}}"
+    #           invalid_event: "cannot transition when %{state}"
+    #           invalid_transition: "cannot transition via %{event}"
+    # 
+    # Notice that the interpolation syntax is %{key} in Rails 3+.  In Rails 2.x,
+    # the appropriate syntax is {{key}}.
     # 
     # You can override these for a specific model like so:
     # 
@@ -332,7 +335,7 @@ module StateMachine
         
         if Object.const_defined?(:I18n)
           locale = "#{File.dirname(__FILE__)}/active_record/locale.rb"
-          I18n.load_path << locale unless I18n.load_path.include?(locale)
+          I18n.load_path.unshift(locale) unless I18n.load_path.include?(locale)
         end
       end
       
@@ -371,6 +374,15 @@ module StateMachine
           :activerecord
         end
         
+        # Only allows translation of I18n is available
+        def translate(klass, key, value)
+          if Object.const_defined?(:I18n)
+            super
+          else
+            value ? value.to_s.humanize.downcase : 'nil'
+          end
+        end
+        
         # Attempts to look up a class's ancestors via:
         # * #lookup_ancestors
         # * #self_and_descendants_from_active_record

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

@@ -1,4 +1,20 @@
 filename = "#{File.dirname(__FILE__)}/../active_model/locale.rb"
 translations = eval(IO.read(filename), binding, filename)
 translations[:en][:activerecord] = translations[:en].delete(:activemodel)
+
+# Only ActiveRecord 2.3.5+ can pull i18n >= 0.1.3 from system-wide gems (and
+# therefore possibly have I18n::VERSION available)
+begin
+  require 'i18n/version'
+rescue Exception => ex
+end unless ::ActiveRecord::VERSION::MAJOR == 2 && (::ActiveRecord::VERSION::MINOR < 3 || ::ActiveRecord::VERSION::TINY < 5)
+
+# Only i18n 0.4.0+ has the new %{key} syntax
+if !defined?(I18n::VERSION) || I18n::VERSION < '0.4.0'
+  translations[:en][:activerecord][:errors][:messages].each do |key, message|
+    message.gsub!('%{', '{{')
+    message.gsub!('}', '}}')
+  end
+end
+
 translations

data/lib/state_machine/integrations/mongo_mapper.rb

@@ -226,6 +226,11 @@ module StateMachine
         def callback_terminator
         end
         
+        # Don't allow translations
+        def translate(klass, key, value)
+          value.to_s.humanize.downcase
+        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
@@ -282,13 +287,22 @@ module StateMachine
         # Creates a scope for finding records *with* a particular state or
         # states for the attribute
         def create_with_scope(name)
-          lambda {|model, values| model.all(:conditions => {attribute => {'$in' => values}})}
+          define_scope(name, lambda {|values| {:conditions => {attribute => {'$in' => values}}}})
         end
         
         # Creates a scope for finding records *without* a particular state or
         # states for the attribute
         def create_without_scope(name)
-          lambda {|model, values| model.all(:conditions => {attribute => {'$nin' => values}})}
+          define_scope(name, lambda {|values| {:conditions => {attribute => {'$nin' => values}}}})
+        end
+        
+        # Defines a new scope with the given name
+        def define_scope(name, scope)
+          if defined?(::MongoMapper::Version) && ::MongoMapper::Version >= '0.8.0'
+            lambda {|model, values| model.query.merge(model.query(scope.call(values)))}
+          else
+            lambda {|model, values| model.all(scope.call(values))}
+          end
         end
     end
   end