state_machine 0.7.5 → 0.7.6

data/CHANGELOG.rdoc

@@ -1,5 +1,15 @@
 == master
 
+== 0.7.6 / 2009-06-17
+
+* Allow multiple state machines on the same class to target the same attribute
+* Add support for :attribute to customize the attribute target, assuming the name is the first argument of #state_machine
+* Simplify reading from / writing to machine-related attributes on objects
+* Fix locale for ActiveRecord getting added to the i18n load path multiple times [Reiner Dieterich]
+* Fix callbacks, guards, and state-driven behaviors not always working on tainted classes [Brandon Dimcheff]
+* Use Ruby 1.9's built-in Object#instance_exec for bound callbacks when it's available
+* Improve performance of cached dynamic state lookups by 25%
+
 == 0.7.5 / 2009-05-25
 
 * Add built-in caching for dynamic state values when the value only needs to be generated once

data/README.rdoc

@@ -412,7 +412,7 @@ To generate multiple state machine graphs:
 
 *Note* that this will generate a different file for every state machine defined
 in the class.  The generated files will use an output filename of the format
-#{class_name}_#{attribute}.#{format}.
+#{class_name}_#{machine_name}.#{format}.
 
 For examples of actual images generated using this task, see those under the
 examples folder.

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'state_machine'
-  s.version           = '0.7.5'
+  s.version           = '0.7.6'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Adds support for creating state machines for attributes on any Ruby class'
   s.description       = s.summary
@@ -53,7 +53,14 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.options << '--line-numbers' << '--inline-source'
   rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb')
 end
-  
+
+desc 'Generate a gemspec file.'
+task :gemspec do
+  File.open("#{spec.name}.gemspec", 'w') do |f|
+    f.write spec.to_ruby
+  end
+end
+
 Rake::GemPackageTask.new(spec) do |p|
   p.gem_spec = spec
   p.need_tar = true

data/lib/state_machine.rb

@@ -5,10 +5,12 @@ require 'state_machine/machine'
 # functionality on any Ruby class.
 module StateMachine
   module MacroMethods
-    # Creates a new state machine for the given attribute.  The default
-    # attribute, if not specified, is <tt>:state</tt>.
+    # Creates a new state machine with the given name.  The default name, if not
+    # specified, is <tt>:state</tt>.
     # 
     # Configuration options:
+    # * <tt>:attribute</tt> - The name of the attribute to store the state value
+    #   in.  By default, this is the same as the name of the machine.
     # * <tt>:initial</tt> - The initial state of the attribute. This can be a
     #   static state or a lambda block which will be evaluated at runtime
     #   (e.g. lambda {|vehicle| vehicle.speed == 0 ? :parked : :idling}).
@@ -17,8 +19,9 @@ module StateMachine
     #   transitions. Default is nil unless otherwise specified by the
     #   configured integration.
     # * <tt>:namespace</tt> - The name to use for namespacing all generated
-    #   instance methods (e.g. "heater" would generate :turn_on_heater and
-    #   :turn_off_heater for the :turn_on/:turn_off events).  Default is nil.
+    #   state / event instance methods (e.g. "heater" would generate
+    #   :turn_on_heater and :turn_off_heater for the :turn_on/:turn_off events).
+    #   Default is nil.
     # * <tt>:integration</tt> - The name of the integration to use for adding
     #   library-specific behavior to the machine.  Built-in integrations
     #   include :data_mapper, :active_record, and :sequel.  By default, this
@@ -49,7 +52,7 @@ module StateMachine
     # 
     # == Examples
     # 
-    # With the default attribute and no configuration:
+    # With the default name/attribute and no configuration:
     # 
     #   class Vehicle
     #     state_machine do
@@ -59,13 +62,14 @@ module StateMachine
     #     end
     #   end
     # 
-    # The above example will define a state machine for the +state+ attribute
-    # on the class.  Every vehicle will start without an initial state.
+    # The above example will define a state machine named "state" that will
+    # store the value in the +state+ attribute.  Every vehicle will start
+    # without an initial state.
     # 
-    # With a custom attribute:
+    # With a custom name / attribute:
     # 
     #   class Vehicle
-    #     state_machine :status do
+    #     state_machine :status, :attribute => :status_value do
     #       ...
     #     end
     #   end
@@ -89,7 +93,8 @@ module StateMachine
     # == Instance Methods
     # 
     # The following instance methods will be automatically generated by the
-    # state machine.  Any existing methods will not be overwritten.
+    # state machine based on the *name* of the machine.  Any existing methods
+    # will not be overwritten.
     # * <tt>state</tt> - Gets the current value for the attribute
     # * <tt>state=(value)</tt> - Sets the current value for the attribute
     # * <tt>state?(name)</tt> - Checks the given state name against the current
@@ -294,14 +299,14 @@ module StateMachine
     # 
     # When a namespace is configured for a state machine, the name provided
     # will be used in generating the instance methods for interacting with
-    # events/states in the machine.  This is particularly useful when a class
+    # states/events in the machine.  This is particularly useful when a class
     # has multiple state machines and it would be difficult to differentiate
     # between the various states / events.
     # 
     # For example,
     # 
     #   class Vehicle
-    #     state_machine :heater_state, :initial => :off :namespace => 'heater' do
+    #     state_machine :heater_state, :initial => :off, :namespace => 'heater' do
     #       event :turn_on do
     #         transition all => :on
     #       end

data/lib/state_machine/assertions.rb

@@ -2,9 +2,8 @@ module StateMachine
   # Provides a set of helper methods for making assertions about the content
   # of various objects
   module Assertions
-    # Validates that all keys in the given hash *only* includes the specified
-    # valid keys.  If any invalid keys are found, an ArgumentError will be
-    # raised.
+    # Validates that the given hash *only* includes the specified valid keys.
+    # If any invalid keys are found, an ArgumentError will be raised.
     #
     # == Examples
     # 
@@ -18,8 +17,8 @@ module StateMachine
       raise ArgumentError, "Invalid key(s): #{invalid_keys.join(', ')}" unless invalid_keys.empty?
     end
     
-    # Validates that at *most* one of a set of exclusive keys is included in
-    # the given hash.  If more than one key is found, an ArgumentError will be
+    # Validates that the given hash only includes at *most* one of a set of
+    # exclusive keys.  If more than one key is found, an ArgumentError will be
     # raised.
     # 
     # == Examples

data/lib/state_machine/callback.rb

@@ -106,9 +106,9 @@ module StateMachine
     # * <tt>:bind_to_object</tt> - Whether to bind the callback to the object involved.
     #   If set to false, the object will be passed as a parameter instead.
     #   Default is integration-specific or set to the application default.
-    # * <tt>:terminator</tt> - A block/proc that determines what callback results
-    #   should cause the callback chain to halt (if not using the default
-    #   <tt>throw :halt</tt> technique).
+    # * <tt>:terminator</tt> - A block/proc that determines what callback
+    #   results should cause the callback chain to halt (if not using the
+    #   default <tt>throw :halt</tt> technique).
     # 
     # More information about how those options affect the behavior of the
     # callback can be found in their attribute definitions.
@@ -129,7 +129,6 @@ module StateMachine
       end
       
       @terminator = options.delete(:terminator)
-      
       @guard = Guard.new(options)
     end
     
@@ -142,8 +141,8 @@ module StateMachine
     # Runs the callback as long as the transition context matches the guard
     # requirements configured for this callback.
     # 
-    # If a terminator has been configured and it matches the result from
-    # the evaluated method, then the callback chain should be halted
+    # If a terminator has been configured and it matches the result from the
+    # evaluated method, then the callback chain should be halted
     def call(object, context = {}, *args)
       if @guard.matches?(object, context)
         @methods.each do |method|
@@ -161,22 +160,29 @@ module StateMachine
       # Generates a method that can be bound to the object being transitioned
       # when the callback is invoked
       def bound_method(block)
-        # Generate a thread-safe unbound method that can be used on any object
-        # This is essentially a workaround for not having Ruby 1.9's instance_exec
-        unbound_method = Object.class_eval do
-          time = Time.now
-          method_name = "__bind_#{time.to_i}_#{time.usec}"
-          define_method(method_name, &block)
-          method = instance_method(method_name)
-          remove_method(method_name)
-          method
-        end
-        arity = unbound_method.arity
+        arity = block.arity
         
-        # Proxy calls to the method so that the method can be bound *and*
-        # the arguments are adjusted
-        lambda do |object, *args|
-          unbound_method.bind(object).call(*(arity == 0 ? [] : args))
+        if RUBY_VERSION >= '1.9'
+          lambda do |object, *args|
+            object.instance_exec(*(arity == 0 ? [] : args), &block)
+          end
+        else
+          # Generate a thread-safe unbound method that can be used on any object.
+          # This is a workaround for not having Ruby 1.9's instance_exec
+          unbound_method = Object.class_eval do
+            time = Time.now
+            method_name = "__bind_#{time.to_i}_#{time.usec}"
+            define_method(method_name, &block)
+            method = instance_method(method_name)
+            remove_method(method_name)
+            method
+          end
+          
+          # Proxy calls to the method so that the method can be bound *and*
+          # the arguments are adjusted
+          lambda do |object, *args|
+            unbound_method.bind(object).call(*(arity == 0 ? [] : args))
+          end
         end
       end
   end

data/lib/state_machine/condition_proxy.rb

@@ -2,7 +2,7 @@ require 'state_machine/eval_helpers'
 
 module StateMachine
   # Represents a type of module in which class-level methods are proxied to
-  # another class, injecting a custom :if condition along with method.
+  # another class, injecting a custom <tt>:if</tt> condition along with method.
   # 
   # This is used for being able to automatically include conditionals which
   # check the current state in class-level methods that have configuration

data/lib/state_machine/eval_helpers.rb

@@ -53,8 +53,7 @@ module StateMachine
     def evaluate_method(object, method, *args)
       case method
         when Symbol
-          method = object.method(method)
-          method.arity == 0 ? method.call : method.call(*args)
+          object.method(method).arity == 0 ? object.send(method) : object.send(method, *args)
         when Proc, Method
           args.unshift(object)
           [0, 1].include?(method.arity) ? method.call(*args.slice(0, method.arity)) : method.call(*args)

data/lib/state_machine/event.rb

@@ -190,7 +190,7 @@ module StateMachine
       if transition = transition_for(object)
         transition.perform(*args)
       else
-        machine.invalidate(object, machine.attribute, :invalid_transition, [[:event, name]])
+        machine.invalidate(object, :state, :invalid_transition, [[:event, name]])
         false
       end
     end
@@ -205,7 +205,7 @@ module StateMachine
       guards.collect {|guard| guard.draw(graph, name, valid_states)}.flatten
     end
     
-    # Generates a nicely formatted description of this events's contents.
+    # Generates a nicely formatted description of this event's contents.
     # 
     # For example,
     # 
@@ -244,7 +244,7 @@ module StateMachine
         
         # Fires the event, raising an exception if it fails
         machine.define_instance_method("#{qualified_name}!") do |machine, object, *args|
-          object.send(qualified_name, *args) || raise(StateMachine::InvalidTransition, "Cannot transition #{machine.attribute} via :#{name} from #{machine.states.match(object).name.inspect}")
+          object.send(qualified_name, *args) || raise(StateMachine::InvalidTransition, "Cannot transition #{machine.name} via :#{name} from #{machine.states.match(object).name.inspect}")
         end
       end
   end

data/lib/state_machine/event_collection.rb

@@ -92,18 +92,17 @@ module StateMachine
       return unless machine.action
       
       result = nil
-      attribute = machine.attribute
       
-      if name = object.send("#{attribute}_event")
-        if event = self[name.to_sym, :name]
-          unless result = object.send("#{attribute}_event_transition") || event.transition_for(object)
+      if event_name = machine.read(object, :event)
+        if event = self[event_name.to_sym, :name]
+          unless result = machine.read(object, :event_transition) || event.transition_for(object)
             # No valid transition: invalidate
-            machine.invalidate(object, "#{attribute}_event", :invalid_event, [[:state, machine.states.match!(object).name]]) if invalidate
+            machine.invalidate(object, :event, :invalid_event, [[:state, machine.states.match!(object).name]]) if invalidate
             result = false
           end
         else
           # Event is unknown: invalidate
-          machine.invalidate(object, "#{attribute}_event", :invalid) if invalidate
+          machine.invalidate(object, :event, :invalid) if invalidate
           result = false
         end
       end

data/lib/state_machine/integrations/active_record.rb

@@ -84,14 +84,14 @@ module StateMachine
     # you can build two state machines (one public and one protected) like so:
     # 
     #   class Vehicle < ActiveRecord::Base
-    #     alias_attribute :public_state # Allow both machines to share the same state
     #     attr_protected :state_event # Prevent access to events in the first machine
     #     
     #     state_machine do
     #       # Define private events here
     #     end
     #     
-    #     state_machine :public_state do
+    #     # Public machine targets the same state as the private machine
+    #     state_machine :public_state, :attribute => :state do
     #       # Define public events here
     #     end
     #   end
@@ -274,11 +274,17 @@ module StateMachine
       # Loads additional files specific to ActiveRecord
       def self.extended(base) #:nodoc:
         require 'state_machine/integrations/active_record/observer'
-        I18n.load_path << "#{File.dirname(__FILE__)}/active_record/locale.rb" if Object.const_defined?(:I18n)
+        
+        if Object.const_defined?(:I18n)
+          locale = "#{File.dirname(__FILE__)}/active_record/locale.rb"
+          I18n.load_path << locale unless I18n.load_path.include?(locale)
+        end
       end
       
       # Adds a validation error to the given object 
       def invalidate(object, attribute, message, values = [])
+        attribute = self.attribute(attribute)
+        
         if Object.const_defined?(:I18n)
           options = values.inject({}) {|options, (key, value)| options[key] = value; options}
           object.errors.add(attribute, message, options.merge(
@@ -304,8 +310,10 @@ module StateMachine
         
         # Skips defining reader/writer methods since this is done automatically
         def define_state_accessor
+          name = self.name
+          
           owner_class.validates_each(attribute) do |record, attr, value|
-            machine = record.class.state_machine(attr)
+            machine = record.class.state_machine(name)
             machine.invalidate(record, attr, :invalid) unless machine.states.match(record)
           end
         end
@@ -314,13 +322,13 @@ module StateMachine
         # compatibility with the default predicate which determines whether
         # *anything* is set for the attribute's value
         def define_state_predicate
-          attribute = self.attribute
+          name = self.name
           
           # Still use class_eval here instance of define_instance_method since
           # we need to be able to call +super+
           @instance_helper_module.class_eval do
-            define_method("#{attribute}?") do |*args|
-              args.empty? ? super(*args) : self.class.state_machine(attribute).states.matches?(self, *args)
+            define_method("#{name}?") do |*args|
+              args.empty? ? super(*args) : self.class.state_machine(name).states.matches?(self, *args)
             end
           end
         end
@@ -381,17 +389,18 @@ module StateMachine
         # inheritance is respected properly.
         def define_scope(name, scope)
           name = name.to_sym
-          attribute = self.attribute
+          machine_name = self.name
           
-          # Created the scope and then override it with state translation
+          # Create 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_machine(attribute).states
+            machine_states = klass.state_machine(machine_name).states
             values = states.flatten.map {|state| machine_states.fetch(state).value}
             
             ::ActiveRecord::NamedScope::Scope.new(klass, scope.call(values))
           end
           
+          # Prevent the Machine class from wrapping the scope
           false
         end
         
@@ -402,22 +411,22 @@ module StateMachine
         # * #{type}_#{qualified_event}_from_#{from}
         # * #{type}_#{qualified_event}_to_#{to}
         # * #{type}_#{qualified_event}
-        # * #{type}_transition_#{attribute}_from_#{from}_to_#{to}
-        # * #{type}_transition_#{attribute}_from_#{from}
-        # * #{type}_transition_#{attribute}_to_#{to}
-        # * #{type}_transition_#{attribute}
+        # * #{type}_transition_#{machine_name}_from_#{from}_to_#{to}
+        # * #{type}_transition_#{machine_name}_from_#{from}
+        # * #{type}_transition_#{machine_name}_to_#{to}
+        # * #{type}_transition_#{machine_name}
         # * #{type}_transition
         # 
         # This will always return true regardless of the results of the
         # callbacks.
         def notify(type, object, transition)
-          attribute = transition.attribute
+          name = self.name
           event = transition.qualified_event
           from = transition.from_name
           to = transition.to_name
           
           # Machine-specific updates
-          ["#{type}_#{event}", "#{type}_transition_#{attribute}"].each do |event_segment|
+          ["#{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

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

@@ -2,6 +2,7 @@
   :activerecord => {
     :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}}']
       }

data/lib/state_machine/integrations/data_mapper.rb

@@ -94,16 +94,13 @@ module StateMachine
     #     include DataMapper::Resource
     #     ...
     #     
-    #     # Allow both machines to share the same state
-    #     alias_method :public_state, :state
-    #     alias_method :public_state=, :state=
-    #     
     #     state_machine do
     #       # Define private events here
     #     end
     #     protected :state_event= # Prevent access to events in the first machine
     #     
-    #     state_machine :public_state do
+    #     # Allow both machines to share the same state
+    #     state_machine :public_state, :attribute => :state do
     #       # Define public events here
     #     end
     #   end
@@ -112,7 +109,7 @@ module StateMachine
     # 
     # By default, the use of transactions during an event transition is
     # turned off to be consistent with DataMapper.  This means that if
-    # changes are made to the database during a before callback, but the the
+    # changes are made to the database during a before callback, but the
     # transition fails to complete, those changes will *not* be rolled back.
     # 
     # For example,
@@ -255,7 +252,7 @@ module StateMachine
       
       # Adds a validation error to the given object
       def invalidate(object, attribute, message, values = [])
-        object.errors.add(attribute, generate_message(message, values)) if supports_validations?
+        object.errors.add(self.attribute(attribute), generate_message(message, values)) if supports_validations?
       end
       
       # Resets any errors previously added when invalidating the given object
@@ -274,9 +271,9 @@ module StateMachine
           owner_class.property(attribute, String) unless owner_class.properties.has_property?(attribute)
           
           if supports_validations?
-            attribute = self.attribute
+            name = self.name
             owner_class.validates_with_block(attribute) do
-              machine = self.class.state_machine(attribute)
+              machine = self.class.state_machine(name)
               machine.states.match(self) ? true : [false, machine.generate_message(:invalid)]
             end
           end