state_machine 0.4.3 → 0.5.0

data/lib/state_machine/assertions.rb

@@ -15,7 +15,7 @@ module StateMachine
     #   assert_valid_keys(options, :name, :age)     # => nil
     def assert_valid_keys(hash, *valid_keys)
       invalid_keys = hash.keys - valid_keys
-      raise ArgumentError, "Invalid key(s): #{invalid_keys.join(", ")}" unless invalid_keys.empty?
+      raise ArgumentError, "Invalid key(s): #{invalid_keys.join(', ')}" unless invalid_keys.empty?
     end
   end
 end

data/lib/state_machine/callback.rb

@@ -8,11 +8,11 @@ module StateMachine
     include EvalHelpers
     
     class << self
-      # Whether to automatically bind the callback to the object being
+      # Determines whether to automatically bind the callback to the object being
       # transitioned.  This only applies to callbacks that are defined as
-      # lambda blocks (or Procs).  Some libraries, such as Extlib, handle
+      # lambda blocks (or Procs).  Some integrations, such as DataMapper, handle
       # callbacks by executing them bound to the object involved, while other
-      # libraries, such as ActiveSupport, pass the object as an argument to
+      # integrations, such as ActiveRecord, pass the object as an argument to
       # the callback.  This can be configured on an application-wide basis by
       # setting this configuration to +true+ or +false+.  The default value
       # is +false+.
@@ -37,7 +37,7 @@ module StateMachine
       #     end
       #   end
       # 
-      # When bound to the object application-wide:
+      # When bound to the object:
       # 
       #   StateMachine::Callback.bind_to_object = true
       #   
@@ -96,12 +96,16 @@ module StateMachine
     # 
     # In addition to the possible configuration options for guards, the
     # following options can be configured:
-    # * +bind_to_object+ - 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.
-    # * +terminator+ - 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>: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).
     # 
     # More information about how those options affect the behavior of the
-    # callback can be found in their attr_accessor definitions.
-    def initialize(options = {}, &block) #:nodoc:
+    # callback can be found in their attribute definitions.
+    def initialize(options = {}, &block)
       if options.is_a?(Hash)
         @method = options.delete(:do) || block
       else
@@ -146,7 +150,7 @@ module StateMachine
     end
     
     private
-      # Generates an method that can be bound to the object being transitioned
+      # 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

data/lib/state_machine/eval_helpers.rb

@@ -55,12 +55,13 @@ module StateMachine
         when Symbol
           method = object.method(method)
           method.arity == 0 ? method.call : method.call(*args)
+        when Proc, Method
+          args.unshift(object)
+          [0, 1].include?(method.arity) ? method.call(*args.slice(0, method.arity)) : method.call(*args)
         when String
           eval(method, object.instance_eval {binding})
-        when Proc, Method
-          method.arity == 1 ? method.call(object) : method.call(object, *args)
         else
-          raise ArgumentError, 'Methods must be a symbol denoting the method to call, a string to be evaluated, or a block to be invoked'
+          raise ArgumentError, 'Methods must be a symbol denoting the method to call, a block to be invoked, or a string to be evaluated'
         end
     end
   end

data/lib/state_machine/event.rb

@@ -34,7 +34,7 @@ module StateMachine
     end
     
     # Creates a copy of this event in addition to the list of associated
-    # guards to prevent conflicts across different events.
+    # guards to prevent conflicts across events within a class hierarchy.
     def initialize_copy(orig) #:nodoc:
       super
       @guards = @guards.dup
@@ -44,11 +44,18 @@ module StateMachine
     # Creates a new transition that will be evaluated when the event is fired.
     # 
     # Configuration options:
-    # * +to+ - The state that's being transitioned to.  If not specified, then the transition will not change the state.
-    # * +from+ - A state or array of states that can be transitioned from. If not specified, then the transition can occur for *any* from state.
-    # * +except_from+ - A state or array of states that *cannot* be transitioned from.
-    # * +if+ - Specifies a method, proc or string to call to determine if the transition should occur (e.g. :if => :moving?, or :if => Proc.new {|car| car.speed > 60}). The method, proc or string should return or evaluate to a true or false value.
-    # * +unless+ - Specifies a method, proc or string to call to determine if the transition should not occur (e.g. :unless => :stopped?, or :unless => Proc.new {|car| car.speed <= 60}). The method, proc or string should return or evaluate to a true or false value.
+    # * <tt>:from</tt> - A state or array of states that can be transitioned from.
+    #   If not specified, then the transition can occur for *any* state.
+    # * <tt>:to</tt> - The state that's being transitioned to.  If not specified,
+    #   then the transition will simply loop back (i.e. the state will not change).
+    # * <tt>:except_from</tt> - A state or array of states that *cannot* be
+    #   transitioned from.
+    # * <tt>:if</tt> - A method, proc or string to call to determine if the
+    #   transition should occur (e.g. :if => :moving?, or :if => lambda {|vehicle| vehicle.speed > 60}).
+    #   The condition should return or evaluate to true or false.
+    # * <tt>:unless</tt> - A method, proc or string to call to determine if the
+    #   transition should not occur (e.g. :unless => :stopped?, or :unless => lambda {|vehicle| vehicle.speed <= 60}).
+    #   The condition should return or evaluate to true or false.
     # 
     # == Order of operations
     # 
@@ -56,31 +63,20 @@ module StateMachine
     # result, if more than one transition applies to a given object, then the
     # first transition that matches will be performed.
     # 
-    # == Dynamic states
-    # 
-    # There is limited support for using dynamically generated values for the
-    # +to+ state in transitions.  This is especially useful for times where
-    # the machine attribute represents a Time object.  In order to have a
-    # a transition be made to the current time, a lambda block can be passed
-    # in representing the state, such as:
-    # 
-    #   transition :to => lambda {Time.now}
-    # 
     # == Examples
     # 
-    #   transition :from => nil, :to => 'parked'
-    #   transition :from => %w(first_gear reverse)
-    #   transition :except_from => 'parked'
+    #   transition :from => nil, :to => :parked
+    #   transition :from => [:first_gear, :reverse]
+    #   transition :except_from => :parked
     #   transition :to => nil
-    #   transition :to => 'parked'
-    #   transition :to => lambda {Time.now}
-    #   transition :to => 'parked', :from => 'first_gear'
-    #   transition :to => 'parked', :from => %w(first_gear reverse)
-    #   transition :to => 'parked', :from => 'first_gear', :if => :moving?
-    #   transition :to => 'parked', :from => 'first_gear', :unless => :stopped?
-    #   transition :to => 'parked', :except_from => 'parked'
+    #   transition :to => :parked
+    #   transition :to => :parked, :from => :first_gear
+    #   transition :to => :parked, :from => [:first_gear, :reverse]
+    #   transition :to => :parked, :from => :first_gear, :if => :moving?
+    #   transition :to => :parked, :from => :first_gear, :unless => :stopped?
+    #   transition :to => :parked, :except_from => :parked
     def transition(options)
-      assert_valid_keys(options, :to, :from, :except_from, :if, :unless)
+      assert_valid_keys(options, :from, :to, :except_from, :if, :unless)
       
       guards << guard = Guard.new(options)
       @known_states |= guard.known_states
@@ -98,12 +94,11 @@ module StateMachine
     # Finds and builds the next transition that can be performed on the given
     # object.  If no transitions can be made, then this will return nil.
     def next_transition(object)
-      from = object.send(machine.attribute)
+      from = machine.state_for(object).name
       
       if guard = guards.find {|guard| guard.matches?(object, :from => from)}
         # Guard allows for the transition to occur
         to = guard.requirements[:to] ? guard.requirements[:to].first : from
-        to = to.call if to.is_a?(Proc)
         Transition.new(object, machine, name, from, to)
       end
     end
@@ -111,6 +106,9 @@ module StateMachine
     # Attempts to perform the next available transition on the given object.
     # If no transitions can be made, then this will return false, otherwise
     # true.
+    # 
+    # Any additional arguments are passed to the StateMachine::Transition#perform
+    # instance method.
     def fire(object, *args)
       if transition = next_transition(object)
         transition.perform(*args)
@@ -119,16 +117,35 @@ module StateMachine
       end
     end
     
+    # Attempts to perform the next available transition on the given object.
+    # If no transitions can be made, then a StateMachine::InvalidTransition
+    # exception will be raised, otherwise true will be returned.
+    def fire!(object, *args)
+      fire(object, *args) || raise(StateMachine::InvalidTransition, "Cannot transition #{machine.attribute} via :#{name} from #{machine.state_for(object).name.inspect}")
+    end
+    
     # Draws a representation of this event on the given graph.  This will
     # create 1 or more edges on the graph for each guard (i.e. transition)
     # configured.
     # 
     # A collection of the generated edges will be returned.
     def draw(graph)
-      valid_states = machine.states_order
+      valid_states = machine.states.by_priority.map {|state| state.name}
       guards.collect {|guard| guard.draw(graph, name, valid_states)}.flatten
     end
     
+    # Generates a nicely formatted description of this events's contents.
+    # 
+    # For example,
+    # 
+    #   event = StateMachine::Event.new(machine, :park)
+    #   event.transition :to => :parked, :from => :idling
+    #   event   # => #<StateMachine::Event name=:park transitions=[{:to => [:parked], :from => [:idling]}]>
+    def inspect
+      attributes = [[:name, name], [:transitions, guards.map {|guard| guard.requirements}]]
+      "#<#{self.class} #{attributes.map {|name, value| "#{name}=#{value.inspect}"} * ' '}>"
+    end
+    
     protected
       # Add the various instance methods that can transition the object using
       # the current event
@@ -143,7 +160,8 @@ module StateMachine
             self.class.state_machines[attribute].event(name).can_fire?(self)
           end
           
-          # Gets the next transition that would be performed if the event were to be fired now
+          # Gets the next transition that would be performed if the event were
+          # fired now
           define_method("next_#{qualified_name}_transition") do
             self.class.state_machines[attribute].event(name).next_transition(self)
           end
@@ -153,9 +171,9 @@ module StateMachine
             self.class.state_machines[attribute].event(name).fire(self, *args)
           end
           
-          # Fires the event, raising an exception if it fails to transition
+          # Fires the event, raising an exception if it fails
           define_method("#{qualified_name}!") do |*args|
-            send(qualified_name, *args) || raise(StateMachine::InvalidTransition, "Cannot transition #{attribute} via :#{name} from #{send(attribute).inspect}")
+            self.class.state_machines[attribute].event(name).fire!(self, *args)
           end
         end
       end

data/lib/state_machine/extensions.rb

@@ -13,7 +13,7 @@ module StateMachine
     # 
     # The hash of state machines maps +attribute+ => +machine+, e.g.
     # 
-    #   Vehicle.state_machines # => {"state" => #<StateMachine::Machine:0xb6f6e4a4 ...>
+    #   Vehicle.state_machines # => {:state => #<StateMachine::Machine:0xb6f6e4a4 ...>
     def state_machines
       @state_machines ||= superclass.state_machines.dup
     end
@@ -35,7 +35,7 @@ module StateMachine
           # Set the initial value of the machine's attribute unless it already
           # exists (which must mean the defaults are being skipped)
           value = send(attribute)
-          send("#{attribute}=", machine.initial_state(self)) if value.nil? || value.respond_to?(:empty?) && value.empty?
+          send("#{attribute}=", machine.initial_state(self).value) if value.nil? || value.respond_to?(:empty?) && value.empty?
         end
       end
   end

data/lib/state_machine/guard.rb

@@ -10,32 +10,34 @@ module StateMachine
     include Assertions
     include EvalHelpers
     
-    # The transition/conditional options that must be met in order for the
-    # guard to match
+    # The transition/condition options that must be met in order for the guard
+    # to match
     attr_reader :requirements
     
-    # A list of all of the states known to this guard.  This will pull state
-    # values from the following requirements:
-    # * +to+
+    # A list of all of the states known to this guard.  This will pull states
+    # from the following requirements (in the same order):
     # * +from+
-    # * +except_to+
     # * +except_from+
+    # * +to+
+    # * +except_to+
     attr_reader :known_states
     
     # Creates a new guard with the given requirements
     def initialize(requirements = {}) #:nodoc:
-      assert_valid_keys(requirements, :to, :from, :on, :except_to, :except_from, :except_on, :if, :unless)
+      assert_valid_keys(requirements, :from, :to, :on, :except_from, :except_to, :except_on, :if, :unless)
       
       @requirements = requirements
       @known_states = []
       
-      # Normalize the requirements and track known states
-      [:to, :from, :on, :except_to, :except_from, :except_on].each do |option|
+      # Normalize the requirements and track known states.  The order that
+      # requirements are iterated is based on the priority in which tracked
+      # states should be added (from followed by to states).
+      [:from, :except_from, :to, :except_to, :on, :except_on].each do |option|
         if @requirements.include?(option)
           values = @requirements[option]
           
           @requirements[option] = values = [values] unless values.is_a?(Array)
-          @known_states |= values if [:to, :from, :except_to, :except_from].include?(option)
+          @known_states |= values if [:from, :to, :except_from, :except_to].include?(option)
         end
       end
     end
@@ -43,34 +45,34 @@ module StateMachine
     # Determines whether the given object / query matches the requirements
     # configured for this guard.  In addition to matching the event, from state,
     # and to state, this will also check whether the configured :if/:unless
-    # conditionals pass on the given object.
+    # conditions pass on the given object.
     # 
     # Query options:
-    # * +to+ - One or more states being transitioned to.  If none are specified, then this will always match.
     # * +from+ - One or more states being transitioned from.  If none are specified, then this will always match.
+    # * +to+ - One or more states being transitioned to.  If none are specified, then this will always match.
     # * +on+ - One or more events that fired the transition.  If none are specified, then this will always match.
-    # * +except_to+ - One more states *not* being transitioned to
     # * +except_from+ - One or more states *not* being transitioned from
+    # * +except_to+ - One more states *not* being transitioned to
     # * +except_on+ - One or more events that *did not* fire the transition.
     # 
     # == Examples
     # 
-    #   guard = StateMachine::Guard.new(:on => 'ignite', :from => [nil, 'parked'], :to => 'idling')
+    #   guard = StateMachine::Guard.new(:on => :ignite, :from => [nil, :parked], :to => :idling)
     #   
     #   # Successful
-    #   guard.matches?(object, :on => 'ignite')                                      # => true
-    #   guard.matches?(object, :from => nil)                                         # => true
-    #   guard.matches?(object, :from => 'parked')                                    # => true
-    #   guard.matches?(object, :to => 'idling')                                      # => true
-    #   guard.matches?(object, :from => 'parked', :to => 'idling')                   # => true
-    #   guard.matches?(object, :on => 'ignite', :from => 'parked', :to => 'idling')  # => true
+    #   guard.matches?(object, :on => :ignite)                                     # => true
+    #   guard.matches?(object, :from => nil)                                       # => true
+    #   guard.matches?(object, :from => :parked)                                   # => true
+    #   guard.matches?(object, :to => :idling)                                     # => true
+    #   guard.matches?(object, :from => :parked, :to => :idling)                   # => true
+    #   guard.matches?(object, :on => :ignite, :from => :parked, :to => :idling)   # => true
     #   
     #   # Unsuccessful
-    #   guard.matches?(object, :on => 'park')                                        # => false
-    #   guard.matches?(object, :from => 'idling')                                    # => false
-    #   guard.matches?(object, :to => 'first_gear')                                  # => false
-    #   guard.matches?(object, :from => 'parked', :to => 'first_gear')               # => false
-    #   guard.matches?(object, :on => 'park', :from => 'parked', :to => 'idling')    # => false
+    #   guard.matches?(object, :on => :park)                                       # => false
+    #   guard.matches?(object, :from => :idling)                                   # => false
+    #   guard.matches?(object, :to => :first_gear)                                 # => false
+    #   guard.matches?(object, :from => :parked, :to => :first_gear)               # => false
+    #   guard.matches?(object, :on => :park, :from => :parked, :to => :idling)     # => false
     def matches?(object, query = {})
       matches_query?(object, query) && matches_conditions?(object)
     end
@@ -81,39 +83,36 @@ module StateMachine
     # state.
     # 
     # For example, if the following from states are configured:
-    # * +first_gear+
     # * +idling+
+    # * +first_gear+
     # * +backing_up+
     # 
-    # ...and the to state is "parked", then the following edges will be created:
-    # * +first_gear+  -> +parked+
+    # ...and the to state is +parked+, then the following edges will be created:
     # * +idling+      -> +parked+
+    # * +first_gear+  -> +parked+
     # * +backing_up+  -> +parked+
     # 
     # Each edge will be labeled with the name of the event that would cause the
     # transition.
     # 
     # The collection of edges generated on the graph will be returned.
-    def draw(graph, event_name, valid_states)
+    def draw(graph, event, valid_states)
       # From states: :from, everything but :except states, or all states
       from_states = requirements[:from] || requirements[:except_from] && (valid_states - requirements[:except_from]) || valid_states
       
       # To state can be optional, otherwise it's a loopback
-      if to_state = requirements[:to]
-        to_state = State.id_for(to_state.first)
-      end
+      to_state = requirements[:to] && requirements[:to].first
       
       # Generate an edge between each from and to state
       from_states.collect do |from_state|
-        from_state = State.id_for(from_state)
-        graph.add_edge(from_state, to_state || from_state, :label => event_name)
+        graph.add_edge(from_state.to_s, (to_state || from_state).to_s, :label => event.to_s)
       end
     end
     
     protected
       # Verify that the from state, to state, and event match the query
       def matches_query?(object, query)
-        (!query || query.empty?) || [:from, :to, :on].all? do |option|
+        !query || query.empty? || [:from, :to, :on].all? do |option|
           !query.include?(option) || find_match(query[option], requirements[option], requirements[:"except_#{option}"])
         end
       end
@@ -137,13 +136,20 @@ module StateMachine
       # 
       # == Examples
       # 
-      #   find_match(nil, %w(parked idling), nil)             # => false
+      #   # No list
+      #   find_match(:parked, nil, nil)                       # => true
+      #   
+      #   # Whitelist
+      #   find_match(nil, [:parked, :idling], nil)            # => false
       #   find_match(nil, [nil], nil)                         # => true
-      #   find_match('parked', nil, nil)                      # => true
-      #   find_match('parked', %w(parked idling), nil)        # => true
-      #   find_match('first_gear', %w(parked idling, nil)     # => false
-      #   find_match('parked', nil, %w(parked idling))        # => false
-      #   find_match('first_gear', nil, %w(parked idling))    # => true
+      #   find_match(:parked, [:parked, :idling], nil)        # => true
+      #   find_match(:first_gear, [:parked, :idling], nil)    # => false
+      #   
+      #   # Blacklist
+      #   find_match(nil, nil, [:parked, :idling])            # => true
+      #   find_match(nil, nil, [nil])                         # => false
+      #   find_match(:parked, nil, [:parked, idling])         # => false
+      #   find_match(:first_gear, nil, [:parked, :idling])    # => true
       def find_match(value, whitelist, blacklist)
         if whitelist
           whitelist.include?(value)

data/lib/state_machine/integrations.rb

@@ -0,0 +1,67 @@
+# Load each available integration
+Dir["#{File.dirname(__FILE__)}/integrations/*.rb"].sort.each do |path|
+  require "state_machine/integrations/#{File.basename(path)}"
+end
+
+module StateMachine
+  # Integrations allow state machines to take advantage of features within the
+  # context of a particular library.  This is currently most useful with
+  # database libraries.  For example, the various database integrations allow
+  # state machines to hook into features like:
+  # * Saving
+  # * Transactions
+  # * Observers
+  # * Scopes
+  # * Callbacks
+  # 
+  # This type of integration allows the user to work with state machines in a
+  # fashion similar to other object models in their application.
+  # 
+  # The integration interface is loosely defined by various unimplemented
+  # methods in the StateMachine::Machine class.  See that class or the various
+  # built-in integrations for more information about how to define additional
+  # integrations.
+  module Integrations
+    # Attempts to find an integration that matches the given class.  This will
+    # look through all of the built-in integrations under the StateMachine::Integrations
+    # namespace and find one that successfully matches the class.
+    # 
+    # == Examples
+    # 
+    #   class Vehicle
+    #   end
+    #   
+    #   class ARVehicle < ActiveRecord::Base
+    #   end
+    #   
+    #   class DMVehicle
+    #     include DataMapper::Resource
+    #   end
+    #   
+    #   class SequelVehicle < Sequel::Model
+    #   end
+    #   
+    #   StateMachine::Integrations.match(Vehicle)         # => nil
+    #   StateMachine::Integrations.match(ARVehicle)       # => StateMachine::Integrations::ActiveRecord
+    #   StateMachine::Integrations.match(DMVehicle)       # => StateMachine::Integrations::DataMapper
+    #   StateMachine::Integrations.match(SequelVehicle)   # => StateMachine::Integrations::Sequel
+    def self.match(klass)
+      if integration = constants.find {|name| const_get(name).matches?(klass)}
+        find(integration)
+      end
+    end
+    
+    # Finds an integration with the given name.  If the integration cannot be
+    # found, then a NameError exception will be raised.
+    # 
+    # == Examples
+    # 
+    #   StateMachine::Integrations.find(:active_record)   # => StateMachine::Integrations::ActiveRecord
+    #   StateMachine::Integrations.find(:data_mapper)     # => StateMachine::Integrations::DataMapper
+    #   StateMachine::Integrations.find(:sequel)          # => StateMachine::Integrations::Sequel
+    #   StateMachine::Integrations.find(:invalid)         # => NameError: wrong constant name Invalid
+    def self.find(name)
+      const_get(name.to_s.gsub(/(?:^|_)(.)/) {$1.upcase})
+    end
+  end
+end