state_machine 0.3.1 → 0.4.0

data/lib/state_machine/eval_helpers.rb

@@ -0,0 +1,67 @@
+module StateMachine
+  # Provides a set of helper methods for evaluating methods within the context
+  # of an object.
+  module EvalHelpers
+    # Evaluates one of several different types of methods within the context
+    # of the given object.  Methods can be one of the following types:
+    # * Symbol
+    # * Method / Proc
+    # * String
+    # 
+    # == Examples
+    # 
+    # Below are examples of the various ways that a method can be evaluated
+    # on an object:
+    # 
+    #   class Person
+    #     def initialize(name)
+    #       @name = name
+    #     end
+    #     
+    #     def name
+    #       @name
+    #     end
+    #   end
+    #   
+    #   class PersonCallback
+    #     def self.run(person)
+    #       person.name
+    #     end
+    #   end
+    # 
+    #   person = Person.new('John Smith')
+    #   
+    #   evaluate_method(person, :name)                            # => "John Smith"
+    #   evaluate_method(person, PersonCallback.method(:run))      # => "John Smith"
+    #   evaluate_method(person, Proc.new {|person| person.name})  # => "John Smith"
+    #   evaluate_method(person, lambda {|person| person.name})    # => "John Smith"
+    #   evaluate_method(person, '@name')                          # => "John Smith"
+    # 
+    # == Additional arguments
+    # 
+    # Additional arguments can be passed to the methods being evaluated.  If
+    # the method defines additional arguments other than the object context,
+    # then all arguments are required.
+    # 
+    # For example,
+    # 
+    #   person = Person.new('John Smith')
+    #   
+    #   evaluate_method(person, lambda {|person| person.name}, 21)                              # => "John Smith"
+    #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21)          # => "John Smith is 21"
+    #   evaluate_method(person, lambda {|person, age| "#{person.name} is #{age}"}, 21, 'male')  # => ArgumentError: wrong number of arguments (3 for 2)
+    def evaluate_method(object, method, *args)
+      case method
+        when Symbol
+          method = object.method(method)
+          method.arity == 0 ? method.call : 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'
+        end
+    end
+  end
+end

data/lib/state_machine/event.rb

@@ -1,116 +1,150 @@
 require 'state_machine/transition'
+require 'state_machine/guard'
+require 'state_machine/assertions'
 
-module PluginAWeek #:nodoc:
-  module StateMachine
-    # An event defines an action that transitions an attribute from one state to
-    # another
-    class Event
-      # The state machine for which this event is defined
-      attr_accessor :machine
+module StateMachine
+  # An event defines an action that transitions an attribute from one state to
+  # another.  The state that an attribute is transitioned to depends on the
+  # guards configured for the event.
+  class Event
+    include Assertions
+    
+    # The state machine for which this event is defined
+    attr_accessor :machine
+    
+    # The name of the action that fires the event
+    attr_reader :name
+    
+    # The list of guards that determine what state this event transitions
+    # objects to when fired
+    attr_reader :guards
+    
+    # A list of all of the states known to this event using the configured
+    # guards/transitions as the source.
+    attr_reader :known_states
+    
+    # Creates a new event within the context of the given machine
+    def initialize(machine, name) #:nodoc:
+      @machine = machine
+      @name = name
+      @guards = []
+      @known_states = []
       
-      # The name of the action that fires the event
-      attr_reader :name
-      
-      # The list of transitions that can be made for this event
-      attr_reader :transitions
-      
-      delegate  :owner_class,
-                  :to => :machine
-      
-      # Creates a new event within the context of the given machine
-      def initialize(machine, name)
-        @machine = machine
-        @name = name
-        @transitions = []
-        
-        add_actions
-      end
-      
-      # Creates a copy of this event in addition to the list of associated
-      # transitions to prevent conflicts across different events.
-      def initialize_copy(orig) #:nodoc:
-        super
-        @transitions = @transitions.dup
-      end
-      
-      # Creates a new transition to the specified state.
-      # 
-      # Configuration options:
-      # * +to+ - The state that being transitioned to
-      # * +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.
-      # 
-      # == Examples
-      # 
-      #   transition :to => 'parked'
-      #   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'
-      def transition(options)
-        transitions << transition = Transition.new(self, options)
-        transition
-      end
+      add_actions
+    end
+    
+    # Creates a copy of this event in addition to the list of associated
+    # guards to prevent conflicts across different events.
+    def initialize_copy(orig) #:nodoc:
+      super
+      @guards = @guards.dup
+      @known_states = @known_states.dup
+    end
+    
+    # Creates a new transition that will be evaluated when the event is fired.
+    # 
+    # Configuration options:
+    # * +to+ - The state that 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.
+    # 
+    # == Order of operations
+    # 
+    # Transitions are evaluated in the order in which they're defined.  As a
+    # 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 => %w(first_gear reverse)
+    #   transition :except_from => 'parked'
+    #   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'
+    def transition(options)
+      assert_valid_keys(options, :to, :from, :except_from, :if, :unless)
       
-      # Determines whether any transitions can be performed for this event based
-      # on the current state of the given record.
-      # 
-      # If the event can't be fired, then this will return false, otherwise true.
-      def can_fire?(record)
-        transitions.any? {|transition| transition.can_perform?(record)}
-      end
+      guards << guard = Guard.new(options)
+      @known_states |= guard.known_states
+      guard
+    end
+    
+    # Determines whether any transitions can be performed for this event based
+    # on the current state of the given object.
+    # 
+    # If the event can't be fired, then this will return false, otherwise true.
+    def can_fire?(object)
+      !next_transition(object).nil?
+    end
+    
+    # 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)
       
-      # Attempts to perform one of the event's transitions for the given record.
-      # Any additional arguments will be passed to the event's callbacks.
-      def fire(record)
-        run(record, false) || false
+      if guard = guards.find {|guard| guard.matches?(object, :from => from)}
+        # Guard allows for the transition to occur
+        to = guard.requirements[:to] || from
+        to = to.call if to.is_a?(Proc)
+        Transition.new(object, machine, name, from, to)
       end
-      
-      # Attempts to perform one of the event's transitions for the given record.
-      # If the transition cannot be made, then a PluginAWeek::StateMachine::InvalidTransition
-      # error will be raised.
-      def fire!(record)
-        run(record, true) || raise(PluginAWeek::StateMachine::InvalidTransition, "Cannot transition via :#{name} from \"#{record.send(machine.attribute)}\"")
+    end
+    
+    # Attempts to perform the next available transition on the given object.
+    # If no transitions can be made, then this will return false, otherwise
+    # true.
+    def fire(object, *args)
+      if transition = next_transition(object)
+        transition.perform(*args)
+      else
+        false
       end
-      
-      private
-        # Add the various instance methods that can transition the record using
-        # the current event
-        def add_actions
-          attribute = machine.attribute
-          name = self.name
+    end
+    
+    protected
+      # Add the various instance methods that can transition the object using
+      # the current event
+      def add_actions
+        attribute = machine.attribute
+        name = self.name
+        
+        machine.owner_class.class_eval do
+          # Checks whether the event can be fired on the current object
+          define_method("can_#{name}?") do
+            self.class.state_machines[attribute].events[name].can_fire?(self)
+          end
           
-          owner_class.class_eval do
-            define_method(name) {self.class.state_machines[attribute].events[name].fire(self)}
-            define_method("#{name}!") {self.class.state_machines[attribute].events[name].fire!(self)}
-            define_method("can_#{name}?") {self.class.state_machines[attribute].events[name].can_fire?(self)}
+          # Gets the next transition that would be performed if the event were to be fired now
+          define_method("next_#{name}_transition") do
+            self.class.state_machines[attribute].events[name].next_transition(self)
           end
-        end
-        
-        # Attempts to find a transition that can be performed for this event.
-        # 
-        # +bang+ indicates whether +perform+ or <tt>perform!</tt> will be
-        # invoked on transitions.
-        def run(record, bang)
-          result = false
           
-          record.class.transaction do
-            transitions.each do |transition|
-              if transition.can_perform?(record)
-                result = bang ? transition.perform!(record) : transition.perform(record)
-                break
-              end
-            end
-            
-            # Rollback any changes if the transition failed
-            raise ActiveRecord::Rollback unless result
+          # Fires the event
+          define_method(name) do |*args|
+            self.class.state_machines[attribute].events[name].fire(self, *args)
           end
           
-          result
+          # Fires the event, raising an exception if it fails to transition
+          define_method("#{name}!") do |*args|
+            send(name, *args) || raise(StateMachine::InvalidTransition, "Cannot transition via :#{name} from #{send(attribute).inspect}")
+          end
         end
-    end
+      end
   end
 end

data/lib/state_machine/extensions.rb

@@ -0,0 +1,83 @@
+module StateMachine
+  module ClassMethods
+    def self.extended(base) #:nodoc:
+      base.class_eval do
+        @state_machines = {}
+        
+        # method_added may get defined by the class, so instead it's chained
+        class << self
+          alias_method :method_added_without_state_machine, :method_added
+          alias_method :method_added, :method_added_with_state_machine
+        end
+      end
+    end
+    
+    # Ensures that the +initialize+ hook defined in StateMachine::InstanceMethods
+    # remains there even if the class defines its own +initialize+ method
+    # *after* the state machine has been defined.  For example,
+    # 
+    #   class Switch
+    #     state_machine do
+    #       ...
+    #     end
+    #     
+    #     def initialize(attributes = {})
+    #       ...
+    #     end
+    #   end
+    def method_added_with_state_machine(method) #:nodoc:
+      method_added_without_state_machine(method)
+      
+      # Aliasing the +initialize+ method also invokes +method_added+, so
+      # alias processing is tracked to prevent an infinite loop
+      if !@skip_initialize_hook && [:initialize, :initialize_with_state_machine].include?(method)
+        @skip_initialize_hook = true
+        
+        # +define_method+ is used to prevent it from showing up in #instance_methods
+        alias_method :initialize_without_state_machine, :initialize
+        class_eval <<-end_eval, __FILE__, __LINE__
+          def initialize(*args, &block)
+            initialize_with_state_machine(*args, &block)
+          end
+        end_eval
+        
+        @skip_initialize_hook = false
+      end
+    end
+    
+    # Gets the current list of state machines defined for this class.  This
+    # class-level attribute acts like an inheritable attribute.  The attribute
+    # is available to each subclass, each subclass having a copy of its
+    # superclass's attribute.
+    # 
+    # The hash of state machines maps +name+ => +machine+, e.g.
+    # 
+    #   Vehicle.state_machines # => {"state" => #<StateMachine::Machine:0xb6f6e4a4 ...>
+    def state_machines
+      @state_machines ||= superclass.state_machines.dup
+    end
+  end
+  
+  module InstanceMethods
+    def self.included(base) #:nodoc:
+      # Methods added from an included module don't invoke +method_added+,
+      # triggering the initialize alias, so it's done explicitly
+      base.method_added(:initialize_with_state_machine)
+    end
+    
+    # Defines the initial values for state machine attributes.  The values
+    # will be set *after* the original initialize method is invoked.  This is
+    # necessary in order to ensure that the object is initialized before
+    # dynamic initial attributes are evaluated.
+    def initialize_with_state_machine(*args, &block)
+      initialize_without_state_machine(*args, &block)
+      
+      self.class.state_machines.each do |attribute, machine|
+        # 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?
+      end
+    end
+  end
+end

data/lib/state_machine/guard.rb

@@ -0,0 +1,115 @@
+require 'state_machine/eval_helpers'
+require 'state_machine/assertions'
+
+module StateMachine
+  # Represents a set of requirements that must be met in order for a transition
+  # or callback to occur.  Guards verify that the event, from state, and to
+  # state of the transition match, in addition to if/unless conditionals for
+  # an object's state.
+  class Guard
+    include Assertions
+    include EvalHelpers
+    
+    # The transition/conditional 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
+    # names from the following requirements:
+    # * +to+
+    # * +from+
+    # * +except_to+
+    # * +except_from+
+    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)
+      
+      @requirements = requirements
+      @known_states = [:to, :from, :except_to, :except_from].inject([]) {|states, option| states |= Array(requirements[option])}
+    end
+    
+    # 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.
+    # 
+    # 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.
+    # * +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_on+ - One or more events that *did not* fire the transition.
+    # 
+    # == Examples
+    # 
+    #   guard = StateMachine::Guard.new(:on => 'ignite', :from => 'parked', :to => 'idling')
+    #   
+    #   # Successful
+    #   guard.matches?(object, :on => 'ignite')                                      # => 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
+    def matches?(object, query = {})
+      matches_query?(object, query) && matches_conditions?(object)
+    end
+    
+    protected
+      # Verify that the from state, to state, and event match the query
+      def matches_query?(object, query)
+        (!query || query.empty?) ||
+        find_match(query[:from], requirements[:from], requirements[:except_from]) &&
+        find_match(query[:to], requirements[:to], requirements[:except_to]) &&
+        find_match(query[:on], requirements[:on], requirements[:except_on])
+      end
+      
+      # Verify that the conditionals for this guard evaluate to true for the
+      # given object
+      def matches_conditions?(object)
+        if requirements[:if]
+          evaluate_method(object, requirements[:if])
+        elsif requirements[:unless]
+          !evaluate_method(object, requirements[:unless])
+        else
+          true
+        end
+      end
+      
+      # Attempts to find the given value in either a whitelist of values or
+      # a blacklist of values.  The whitelist will always be used first if it
+      # is specified.  If neither lists are specified or the value is blank,
+      # then this will always find a match and return true.
+      # 
+      # == Examples
+      # 
+      #   find_match(nil, %w(parked idling), 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
+      def find_match(value, whitelist, blacklist)
+        if value
+          if whitelist
+            Array(whitelist).include?(value)
+          elsif blacklist
+            !Array(blacklist).include?(value)
+          else
+            true
+          end
+        else
+          true
+        end
+      end
+  end
+end