state_machine 0.9.2 → 0.9.3

data/lib/state_machine/machine.rb

@@ -612,6 +612,9 @@ module StateMachine
     # * <tt>:if</tt> - Determines whether an object's value matches the state
     #   (e.g. :value => lambda {Time.now}, :if => lambda {|state| !state.nil?}).
     #   By default, the configured value is matched.
+    # * <tt>:human_name</tt> - The human-readable version of this state's name.
+    #   By default, this is either defined by the integration or stringifies the
+    #   name and converts underscores to spaces.
     # 
     # == Customizing the stored value
     # 
@@ -846,7 +849,7 @@ module StateMachine
     # options hash which contains at least <tt>:if</tt> condition support.
     def state(*names, &block)
       options = names.last.is_a?(Hash) ? names.pop : {}
-      assert_valid_keys(options, :value, :cache, :if)
+      assert_valid_keys(options, :value, :cache, :if, :human_name)
       
       states = add_states(names)
       states.each do |state|
@@ -855,6 +858,7 @@ module StateMachine
           self.states.update(state)
         end
         
+        state.human_name = options[:human_name] if options.include?(:human_name)
         state.cache = options[:cache] if options.include?(:cache)
         state.matcher = options[:if] if options.include?(:if)
         state.context(&block) if block_given?
@@ -907,6 +911,11 @@ module StateMachine
     # This method is also aliased as +on+ for improved compatibility with
     # using a domain-specific language.
     # 
+    # Configuration options:
+    # * <tt>:human_name</tt> - The human-readable version of this event's name.
+    #   By default, this is either defined by the integration or stringifies the
+    #   name and converts underscores to spaces.
+    # 
     # == Instance methods
     # 
     # The following instance methods are generated when a new event is defined
@@ -1014,10 +1023,12 @@ module StateMachine
     #     end
     #   end
     def event(*names, &block)
-      events = names.collect do |name|
-        unless event = self.events[name]
-          self.events << event = Event.new(self, name)
-        end
+      options = names.last.is_a?(Hash) ? names.pop : {}
+      assert_valid_keys(options, :human_name)
+      
+      events = add_events(names)
+      events.each do |event|
+        event.human_name = options[:human_name] if options.include?(:human_name)
         
         if block_given?
           event.instance_eval(&block)
@@ -1415,11 +1426,7 @@ module StateMachine
         define_state_predicate
         define_event_helpers
         define_action_helpers if action
-        
-        # Gets the state name for the current value
-        define_instance_method(attribute(:name)) do |machine, object|
-          machine.states.match!(object).name
-        end
+        define_name_helpers
       end
       
       # Defines the initial values for state machine attributes.  Static values
@@ -1514,6 +1521,30 @@ module StateMachine
         end
       end
       
+      # Adds helper methods for accessing naming information about states and
+      # events on the owner class
+      def define_name_helpers
+        # Gets the humanized version of a state
+        define_class_method("human_#{attribute(:name)}") do |machine, klass, state|
+          machine.states.fetch(state).human_name(klass)
+        end
+        
+        # Gets the humanized version of an event
+        define_class_method("human_#{attribute(:event_name)}") do |machine, klass, event|
+          machine.events.fetch(event).human_name(klass)
+        end
+        
+        # Gets the state name for the current value
+        define_instance_method(attribute(:name)) do |machine, object|
+          machine.states.match!(object).name
+        end
+        
+        # Gets the human state name for the current value
+        define_instance_method("human_#{attribute(:name)}") do |machine, object|
+          machine.states.match!(object).human_name(object.class)
+        end
+      end
+      
       # Defines the with/without scope helpers for this attribute.  Both the
       # singular and plural versions of the attribute are defined for each
       # scope helper.  A custom plural can be specified if it cannot be
@@ -1586,5 +1617,17 @@ module StateMachine
           state
         end
       end
+      
+      # Tracks the given set of events in the list of all known events for
+      # this machine
+      def add_events(new_events)
+        new_events.map do |new_event|
+          unless event = events[new_event]
+            events << event = Event.new(self, new_event)
+          end
+          
+          event
+        end
+      end
   end
 end

data/lib/state_machine/machine_collection.rb

@@ -33,7 +33,7 @@ module StateMachine
         # Get the transition that will be performed for the event
         unless transition = event.transition_for(object)
           machine = event.machine
-          machine.invalidate(object, :state, :invalid_transition, [[:event, event_name]])
+          machine.invalidate(object, :state, :invalid_transition, [[:event, event.human_name]])
         end
         
         transition

data/lib/state_machine/state.rb

@@ -23,6 +23,9 @@ module StateMachine
     # namespace
     attr_reader :qualified_name
     
+    # The human-readable name for the state
+    attr_writer :human_name
+    
     # The value that is written to a machine's attribute when an object
     # transitions into this state
     attr_writer :value
@@ -56,12 +59,14 @@ module StateMachine
     # * <tt>:if</tt> - Determines whether a value matches this state
     #   (e.g. :value => lambda {Time.now}, :if => lambda {|state| !state.nil?}).
     #   By default, the configured value is matched.
+    # * <tt>:human_name</tt> - The human-readable version of this state's name
     def initialize(machine, name, options = {}) #:nodoc:
-      assert_valid_keys(options, :initial, :value, :cache, :if)
+      assert_valid_keys(options, :initial, :value, :cache, :if, :human_name)
       
       @machine = machine
       @name = name
       @qualified_name = name && machine.namespace ? :"#{machine.namespace}_#{name}" : name
+      @human_name = options[:human_name] || (@name ? @name.to_s.tr('_', ' ') : 'nil')
       @value = options.include?(:value) ? options[:value] : name && name.to_s
       @cache = options[:cache]
       @matcher = options[:if]
@@ -92,6 +97,12 @@ module StateMachine
       end
     end
     
+    # Transforms the state name into a more human-readable format, such as
+    # "first gear" instead of "first_gear"
+    def human_name(klass = @machine.owner_class)
+      @human_name.is_a?(Proc) ? @human_name.call(self, klass) : @human_name
+    end
+    
     # Generates a human-readable description of this state's name / value:
     # 
     # For example,

data/lib/state_machine/transition.rb

@@ -18,30 +18,12 @@ module StateMachine
     # The state machine for which this transition is defined
     attr_reader :machine
     
-    # The event that triggered the transition
-    attr_reader :event
-    
-    # The fully-qualified name of the event that triggered the transition
-    attr_reader :qualified_event
-    
     # The original state value *before* the transition
     attr_reader :from
     
-    # The original state name *before* the transition
-    attr_reader :from_name
-    
-    # The original fully-qualified state name *before* transition
-    attr_reader :qualified_from_name
-    
     # The new state value *after* the transition
     attr_reader :to
     
-    # The new state name *after* the transition
-    attr_reader :to_name
-    
-    # The new fully-qualified state name *after* the transition
-    attr_reader :qualified_to_name
-    
     # The arguments passed in to the event that triggered the transition
     # (does not include the +run_action+ boolean argument if specified)
     attr_accessor :args
@@ -59,22 +41,11 @@ module StateMachine
       @args = []
       @transient = false
       
-      # Event information
-      event = machine.events.fetch(event)
-      @event = event.name
-      @qualified_event = event.qualified_name
-      
-      # From state information
-      from_state = machine.states.fetch(from_name)
-      @from = read_state ? machine.read(object, :state) : from_state.value
-      @from_name = from_state.name
-      @qualified_from_name = from_state.qualified_name
-      
-      # To state information
-      to_state = machine.states.fetch(to_name)
-      @to = to_state.value
-      @to_name = to_state.name
-      @qualified_to_name = to_state.qualified_name
+      @event = machine.events.fetch(event)
+      @from_state = machine.states.fetch(from_name)
+      @from = read_state ? machine.read(object, :state) : @from_state.value
+      @to_state = machine.states.fetch(to_name)
+      @to = @to_state.value
       
       reset
     end
@@ -89,6 +60,51 @@ module StateMachine
       machine.action
     end
     
+    # The event that triggered the transition
+    def event
+      @event.name
+    end
+    
+    # The fully-qualified name of the event that triggered the transition
+    def qualified_event
+      @event.qualified_name
+    end
+    
+    # The human-readable name of the event that triggered the transition
+    def human_event
+      @event.human_name(@object.class)
+    end
+    
+    # The state name *before* the transition
+    def from_name
+      @from_state.name
+    end
+    
+    # The fully-qualified state name *before* the transition
+    def qualified_from_name
+      @from_state.qualified_name
+    end
+    
+    # The human-readable state name *before* the transition
+    def human_from_name
+      @from_state.human_name(@object.class)
+    end
+    
+    # The new state name *after* the transition
+    def to_name
+      @to_state.name
+    end
+    
+    # The new fully-qualified state name *after* the transition
+    def qualified_to_name
+      @to_state.qualified_name
+    end
+    
+    # The new human-readable state name *after* the transition
+    def human_to_name
+      @to_state.human_name(@object.class)
+    end
+    
     # Does this transition represent a loopback (i.e. the from and to state
     # are the same)
     # 

data/test/files/en.yml

@@ -0,0 +1,9 @@
+en:
+  activerecord:
+    errors:
+      messages:
+        invalid_transition: "cannot transition"
+  activemodel:
+    errors:
+      messages:
+        invalid_transition: "cannot %{event}"

data/test/functional/state_machine_test.rb

@@ -234,6 +234,14 @@ class VehicleTest < Test::Unit::TestCase
   def test_should_not_allow_access_to_subclass_events
     assert !@vehicle.respond_to?(:reverse)
   end
+  
+  def test_should_have_human_state_names
+    assert_equal 'parked', Vehicle.human_state_name(:parked)
+  end
+  
+  def test_should_have_human_state_event_names
+    assert_equal 'park', Vehicle.human_state_event_name(:park)
+  end
 end
 
 class VehicleUnsavedTest < Test::Unit::TestCase
@@ -258,6 +266,7 @@ class VehicleUnsavedTest < Test::Unit::TestCase
     assert @vehicle.parked?
     assert @vehicle.state?(:parked)
     assert_equal :parked, @vehicle.state_name
+    assert_equal 'parked', @vehicle.human_state_name
   end
   
   def test_should_not_be_idling

data/test/unit/event_collection_test.rb

@@ -250,7 +250,7 @@ class EventCollectionWithValidationsTest < Test::Unit::TestCase
     @events = StateMachine::EventCollection.new(@machine)
     
     @machine.event :ignite
-    @machine.state :parked, :idling
+    @parked, @idling = @machine.state :parked, :idling
     @events << @ignite = StateMachine::Event.new(@machine, :ignite)
     
     @object = @klass.new
@@ -271,15 +271,13 @@ class EventCollectionWithValidationsTest < Test::Unit::TestCase
     assert_equal ['cannot transition when idling'], @object.errors
   end
   
-  def test_should_invalidate_with_friendly_name_if_invalid_event_specified
-    # Add a valid nil state
-    @machine.state nil
-    
-    @object.state = nil
+  def test_should_invalidate_with_human_name_if_invalid_event_specified
+    @idling.human_name = 'waiting'
+    @object.state = 'idling'
     @object.state_event = 'ignite'
     @events.attribute_transition_for(@object, true)
     
-    assert_equal ['cannot transition when nil'], @object.errors
+    assert_equal ['cannot transition when waiting'], @object.errors
   end
   
   def test_should_not_invalidate_event_can_be_fired

data/test/unit/event_test.rb

@@ -21,6 +21,10 @@ class EventByDefaultTest < Test::Unit::TestCase
     assert_equal :ignite, @event.qualified_name
   end
   
+  def test_should_have_a_human_name
+    assert_equal 'ignite', @event.human_name
+  end
+  
   def test_should_not_have_any_guards
     assert @event.guards.empty?
   end
@@ -67,6 +71,11 @@ class EventTest < Test::Unit::TestCase
     assert_equal new_machine, @event.machine
   end
   
+  def test_should_allow_changing_human_name
+    @event.human_name = 'Stop'
+    assert_equal 'Stop', @event.human_name
+  end
+  
   def test_should_provide_matcher_helpers_during_initialization
     matchers = []
     
@@ -82,6 +91,42 @@ class EventTest < Test::Unit::TestCase
   end
 end
 
+class EventWithHumanNameTest < Test::Unit::TestCase
+  def setup
+    @klass = Class.new
+    @machine = StateMachine::Machine.new(@klass)
+    @event = StateMachine::Event.new(@machine, :ignite, :human_name => 'start')
+  end
+  
+  def test_should_use_custom_human_name
+    assert_equal 'start', @event.human_name
+  end
+end
+
+class EventWithDynamicHumanNameTest < Test::Unit::TestCase
+  def setup
+    @klass = Class.new
+    @machine = StateMachine::Machine.new(@klass)
+    @event = StateMachine::Event.new(@machine, :ignite, :human_name => lambda {|event, object| ['start', object]})
+  end
+  
+  def test_should_use_custom_human_name
+    human_name, klass = @event.human_name
+    assert_equal 'start', human_name
+    assert_equal @klass, klass
+  end
+  
+  def test_should_allow_custom_class_to_be_passed_through
+    human_name, klass = @event.human_name(1)
+    assert_equal 'start', human_name
+    assert_equal 1, klass
+  end
+  
+  def test_should_not_cache_value
+    assert_not_same @event.human_name, @event.human_name
+  end
+end
+
 class EventWithConflictingHelpersTest < Test::Unit::TestCase
   def setup
     @klass = Class.new do
@@ -389,6 +434,12 @@ class EventWithMatchingDisabledTransitionsTest < Test::Unit::TestCase
     assert_equal ['cannot transition via "ignite"'], @object.errors
   end
   
+  def test_should_invalidate_with_human_event_name
+    @event.human_name = 'start'
+    @event.fire(@object)
+    assert_equal ['cannot transition via "start"'], @object.errors
+  end
+  
   def test_should_reset_existing_error
     @object.errors = ['invalid']
     

data/test/unit/integrations/active_model_test.rb

@@ -119,6 +119,18 @@ module ActiveModelTest
     end
   end
   
+  class MachineWithStatesTest < BaseTestCase
+    def setup
+      @model = new_model
+      @machine = StateMachine::Machine.new(@model)
+      @machine.state :first_gear
+    end
+    
+    def test_should_humanize_name
+      assert_equal 'first gear', @machine.state(:first_gear).human_name
+    end
+  end
+  
   class MachineWithStaticInitialStateTest < BaseTestCase
     def setup
       @model = new_model
@@ -144,6 +156,18 @@ module ActiveModelTest
     end
   end
   
+  class MachineWithEventsTest < BaseTestCase
+    def setup
+      @model = new_model
+      @machine = StateMachine::Machine.new(@model)
+      @machine.event :shift_up
+    end
+    
+    def test_should_humanize_name
+      assert_equal 'shift up', @machine.event(:shift_up).human_name
+    end
+  end
+  
   class MachineWithModelStateAttributeTest < BaseTestCase
     def setup
       @model = new_model
@@ -523,7 +547,7 @@ module ActiveModelTest
       I18n.backend = I18n::Backend::Simple.new if Object.const_defined?(:I18n)
       @record.state = 'parked'
       
-      @machine.invalidate(@record, :state, :invalid_transition, [[:event, :park]])
+      @machine.invalidate(@record, :state, :invalid_transition, [[:event, 'park']])
       assert_equal ['State cannot transition via "park"'], @record.errors.full_messages
     end
     
@@ -784,7 +808,7 @@ module ActiveModelTest
     
     def test_should_use_defaults
       I18n.backend.store_translations(:en, {
-        :activemodel => {:errors => {:messages => {:invalid_transition => 'cannot {{event}}'}}}
+        :activemodel => {:errors => {:messages => {:invalid_transition => 'cannot %{event}'}}}
       })
       
       machine = StateMachine::Machine.new(@model, :action => :save)
@@ -793,13 +817,13 @@ module ActiveModelTest
       
       record = @model.new(:state => 'idling')
       
-      machine.invalidate(record, :state, :invalid_transition, [[:event, :ignite]])
+      machine.invalidate(record, :state, :invalid_transition, [[:event, 'ignite']])
       assert_equal ['State cannot ignite'], record.errors.full_messages
     end
     
     def test_should_allow_customized_error_key
       I18n.backend.store_translations(:en, {
-        :activemodel => {:errors => {:messages => {:bad_transition => 'cannot {{event}}'}}}
+        :activemodel => {:errors => {:messages => {:bad_transition => 'cannot %{event}'}}}
       })
       
       machine = StateMachine::Machine.new(@model, :action => :save, :messages => {:invalid_transition => :bad_transition})
@@ -808,17 +832,17 @@ module ActiveModelTest
       record = @model.new
       record.state = 'idling'
       
-      machine.invalidate(record, :state, :invalid_transition, [[:event, :ignite]])
+      machine.invalidate(record, :state, :invalid_transition, [[:event, 'ignite']])
       assert_equal ['State cannot ignite'], record.errors.full_messages
     end
     
     def test_should_allow_customized_error_string
-      machine = StateMachine::Machine.new(@model, :action => :save, :messages => {:invalid_transition => 'cannot {{event}}'})
+      machine = StateMachine::Machine.new(@model, :action => :save, :messages => {:invalid_transition => 'cannot %{event}'})
       machine.state :parked, :idling
       
       record = @model.new(:state => 'idling')
       
-      machine.invalidate(record, :state, :invalid_transition, [[:event, :ignite]])
+      machine.invalidate(record, :state, :invalid_transition, [[:event, 'ignite']])
       assert_equal ['State cannot ignite'], record.errors.full_messages
     end
     
@@ -827,11 +851,10 @@ module ActiveModelTest
         :activemodel => {:state_machines => {:'active_model_test/foo' => {:state => {:states => {:parked => 'shutdown'}}}}}
       })
       
-      machine = StateMachine::Machine.new(@model, :initial => :parked, :action => :save)
-      record = @model.new
+      machine = StateMachine::Machine.new(@model)
+      machine.state :parked
       
-      machine.invalidate(record, :event, :invalid_event, [[:state, :parked]])
-      assert_equal ['State event cannot transition when shutdown'], record.errors.full_messages
+      assert_equal 'shutdown', machine.state(:parked).human_name
     end
     
     def test_should_allow_customized_state_key_scoped_to_machine
@@ -839,11 +862,10 @@ module ActiveModelTest
         :activemodel => {:state_machines => {:state => {:states => {:parked => 'shutdown'}}}}
       })
       
-      machine = StateMachine::Machine.new(@model, :initial => :parked, :action => :save)
-      record = @model.new
+      machine = StateMachine::Machine.new(@model)
+      machine.state :parked
       
-      machine.invalidate(record, :event, :invalid_event, [[:state, :parked]])
-      assert_equal ['State event cannot transition when shutdown'], record.errors.full_messages
+      assert_equal 'shutdown', machine.state(:parked).human_name
     end
     
     def test_should_allow_customized_state_key_unscoped
@@ -851,11 +873,10 @@ module ActiveModelTest
         :activemodel => {:state_machines => {:states => {:parked => 'shutdown'}}}
       })
       
-      machine = StateMachine::Machine.new(@model, :initial => :parked, :action => :save)
-      record = @model.new
+      machine = StateMachine::Machine.new(@model)
+      machine.state :parked
       
-      machine.invalidate(record, :event, :invalid_event, [[:state, :parked]])
-      assert_equal ['State event cannot transition when shutdown'], record.errors.full_messages
+      assert_equal 'shutdown', machine.state(:parked).human_name
     end
     
     def test_should_allow_customized_event_key_scoped_to_class_and_machine
@@ -863,12 +884,10 @@ module ActiveModelTest
         :activemodel => {:state_machines => {:'active_model_test/foo' => {:state => {:events => {:park => 'stop'}}}}}
       })
       
-      machine = StateMachine::Machine.new(@model, :action => :save)
+      machine = StateMachine::Machine.new(@model)
       machine.event :park
-      record = @model.new
       
-      machine.invalidate(record, :state, :invalid_transition, [[:event, :park]])
-      assert_equal ['State cannot transition via "stop"'], record.errors.full_messages
+      assert_equal 'stop', machine.event(:park).human_name
     end
     
     def test_should_allow_customized_event_key_scoped_to_machine
@@ -876,12 +895,10 @@ module ActiveModelTest
         :activemodel => {:state_machines => {:state => {:events => {:park => 'stop'}}}}
       })
       
-      machine = StateMachine::Machine.new(@model, :action => :save)
+      machine = StateMachine::Machine.new(@model)
       machine.event :park
-      record = @model.new
       
-      machine.invalidate(record, :state, :invalid_transition, [[:event, :park]])
-      assert_equal ['State cannot transition via "stop"'], record.errors.full_messages
+      assert_equal 'stop', machine.event(:park).human_name
     end
     
     def test_should_allow_customized_event_key_unscoped
@@ -889,21 +906,51 @@ module ActiveModelTest
         :activemodel => {:state_machines => {:events => {:park => 'stop'}}}
       })
       
-      machine = StateMachine::Machine.new(@model, :action => :save)
+      machine = StateMachine::Machine.new(@model)
       machine.event :park
-      record = @model.new
       
-      machine.invalidate(record, :state, :invalid_transition, [[:event, :park]])
-      assert_equal ['State cannot transition via "stop"'], record.errors.full_messages
+      assert_equal 'stop', machine.event(:park).human_name
     end
     
     def test_should_only_add_locale_once_in_load_path
-      assert_equal 1, I18n.load_path.select {|path| path =~ %r{state_machine/integrations/active_model/locale\.rb$}}.length
+      assert_equal 1, I18n.load_path.select {|path| path =~ %r{active_model/locale\.rb$}}.length
       
       # Create another ActiveRecord model that will triger the i18n feature
       new_model
       
-      assert_equal 1, I18n.load_path.select {|path| path =~ %r{state_machine/integrations/active_model/locale\.rb$}}.length
+      assert_equal 1, I18n.load_path.select {|path| path =~ %r{active_model/locale\.rb$}}.length
+    end
+    
+    def test_should_add_locale_to_beginning_of_load_path
+      @original_load_path = I18n.load_path
+      I18n.backend = I18n::Backend::Simple.new
+      
+      app_locale = File.dirname(__FILE__) + '/../../files/en.yml'
+      default_locale = File.dirname(__FILE__) + '/../../../lib/state_machine/integrations/active_model/locale.rb'
+      I18n.load_path = [app_locale]
+      
+      StateMachine::Machine.new(@model)
+      
+      assert_equal [default_locale, app_locale].map {|path| File.expand_path(path)}, I18n.load_path.map {|path| File.expand_path(path)}
+    ensure
+      I18n.load_path = @original_load_path
+    end
+    
+    def test_should_prefer_other_locales_first
+      @original_load_path = I18n.load_path
+      I18n.backend = I18n::Backend::Simple.new
+      I18n.load_path = [File.dirname(__FILE__) + '/../../files/en.yml']
+      
+      machine = StateMachine::Machine.new(@model)
+      machine.state :parked, :idling
+      machine.event :ignite
+      
+      record = @model.new(:state => 'idling')
+      
+      machine.invalidate(record, :state, :invalid_transition, [[:event, 'ignite']])
+      assert_equal ['State cannot ignite'], record.errors.full_messages
+    ensure
+      I18n.load_path = @original_load_path
     end
   end
 end