state_machine 0.5.1 → 0.5.2

data/CHANGELOG.rdoc

@@ -1,5 +1,12 @@
 == master
 
+== 0.5.2 / 2009-02-17
+
+* Improve pretty-print of events
+* Simplify state/event matching design, improving guard performance by 30%
+* Add better error notification when conflicting guard options are defined
+* Fix scope name pluralization not being applied correctly
+
 == 0.5.1 / 2009-02-11
 
 * Allow states to be drawn as ellipses to accommodate long names

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'state_machine'
-  s.version           = '0.5.1'
+  s.version           = '0.5.2'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Adds support for creating state machines for attributes on any Ruby class'
   

data/lib/state_machine/assertions.rb

@@ -17,5 +17,21 @@ module StateMachine
       invalid_keys = hash.keys - valid_keys
       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
+    # raised.
+    # 
+    # == Examples
+    # 
+    #   options = {:only => :on, :except => :off}
+    #   assert_exclusive_keys(options, :only)                   # => nil
+    #   assert_exclusive_keys(options, :except)                 # => nil
+    #   assert_exclusive_keys(options, :only, :except)          # => ArgumentError: Conflicting keys: only, except
+    #   assert_exclusive_keys(options, :only, :except, :with)   # => ArgumentError: Conflicting keys: only, except
+    def assert_exclusive_keys(hash, *exclusive_keys)
+      conflicting_keys = exclusive_keys & hash.keys
+      raise ArgumentError, "Conflicting keys: #{conflicting_keys.join(', ')}" unless conflicting_keys.length <= 1
+    end
   end
 end

data/lib/state_machine/event.rb

@@ -98,7 +98,7 @@ module StateMachine
       
       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 = guard.state_requirement[:to].values.any? ? guard.state_requirement[:to].values.first : from
         Transition.new(object, machine, name, from, to)
       end
     end
@@ -140,10 +140,13 @@ module StateMachine
     # 
     #   event = StateMachine::Event.new(machine, :park)
     #   event.transition :to => :parked, :from => :idling
-    #   event   # => #<StateMachine::Event name=:park transitions=[{:to => [:parked], :from => [:idling]}]>
+    #   event   # => #<StateMachine::Event name=:park transitions=[:idling => :parked]>
     def inspect
-      attributes = [[:name, name], [:transitions, guards.map {|guard| guard.requirements}]]
-      "#<#{self.class} #{attributes.map {|name, value| "#{name}=#{value.inspect}"} * ' '}>"
+      transitions = guards.map do |guard|
+        "#{guard.state_requirement[:from].description} => #{guard.state_requirement[:to].description}"
+      end
+      
+      "#<#{self.class} name=#{name.inspect} transitions=[#{transitions * ', '}]>"
     end
     
     protected

data/lib/state_machine/guard.rb

@@ -1,3 +1,4 @@
+require 'state_machine/matcher'
 require 'state_machine/eval_helpers'
 require 'state_machine/assertions'
 
@@ -10,71 +11,81 @@ module StateMachine
     include Assertions
     include EvalHelpers
     
-    # The transition/condition options that must be met in order for the guard
-    # to match
-    attr_reader :requirements
+    # The condition that must be met on an object
+    attr_reader :if_condition
+    
+    # The condition that must *not* be met on an object
+    attr_reader :unless_condition
+    
+    # The requirement for verifying the event being guarded (includes :on and
+    # :except_on).
+    attr_reader :event_requirement
+    
+    # The requirement for verifying the states being guarded (includes :from,
+    # :to, :except_from, and :except_to).  All options map to
+    # either nil (if not specified) or an array of state names.
+    attr_reader :state_requirement
     
     # 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_from+
-    # * +to+
-    # * +except_to+
+    # from the following options in +state_requirements+ (in the same order):
+    # * +from+ / +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, :from, :to, :on, :except_from, :except_to, :except_on, :if, :unless)
+    # Creates a new guard
+    def initialize(options = {}) #:nodoc:
+      assert_valid_keys(options, :from, :to, :on, :except_from, :except_to, :except_on, :if, :unless)
       
-      @requirements = requirements
-      @known_states = []
+      # Build conditionals
+      assert_exclusive_keys(options, :if, :unless)
+      @if_condition = options.delete(:if)
+      @unless_condition = options.delete(:unless)
       
-      # 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 [:from, :to, :except_from, :except_to].include?(option)
-        end
-      end
+      # Build event/state requirements
+      @event_requirement = build_matcher(options, :on, :except_on)
+      @state_requirement = {:from => build_matcher(options, :from, :except_from), :to => build_matcher(options, :to, :except_to)}
+      
+      # Track known states.  The order that requirements are iterated is based
+      # on the priority in which tracked states should be added.
+      @known_states = []
+      [:from, :to].each {|option| @known_states |= @state_requirement[option].values}
     end
     
-    # Determines whether the given object / query matches the requirements
+    # Attempts to match the given object / query against the set of 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
     # conditions pass on the given object.
     # 
+    # This will return true or false depending on whether a match is found.
+    # 
     # Query options:
-    # * +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_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.
+    # * <tt>:from</tt> - One or more states being transitioned from.  If none
+    #   are specified, then this will always match.
+    # * <tt>:to</tt> - One or more states being transitioned to.  If none are
+    #   specified, then this will always match.
+    # * <tt>:on</tt> - One or more events that fired the transition.  If none
+    #   are specified, then this will always match.
     # 
     # == Examples
     # 
-    #   guard = StateMachine::Guard.new(:on => :ignite, :from => [nil, :parked], :to => :idling)
+    #   guard = StateMachine::Guard.new(:from => [nil, :parked], :to => :idling, :on => :ignite)
     #   
     #   # 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)
+      matches_query?(query) && matches_conditions?(object)
     end
     
     # Draws a representation of this guard on the given graph.  This will draw
@@ -97,64 +108,76 @@ module StateMachine
     # 
     # The collection of edges generated on the graph will be returned.
     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
+      edges = []
+      
+      # From states determined based on the known valid states
+      from_states = state_requirement[:from].filter(valid_states)
       
-      # To state can be optional, otherwise it's a loopback
-      to_state = requirements[:to] && requirements[:to].first
+      # If a to state is not specified, then it's a loopback and each from
+      # state maps back to itself
+      if state_requirement[:to].values.any?
+        to_state = state_requirement[:to].values.first
+        loopback = false
+      else
+        loopback = true
+      end
       
       # Generate an edge between each from and to state
-      from_states.collect do |from_state|
-        graph.add_edge(from_state.to_s, (to_state || from_state).to_s, :label => event.to_s)
+      from_states.each do |from_state|
+        edges << graph.add_edge(from_state.to_s, (loopback ? from_state : to_state).to_s, :label => event.to_s)
       end
+      
+      edges
     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.include?(option) || find_match(query[option], requirements[option], requirements[:"except_#{option}"])
+      # Builds a matcher strategy to use for the given options.  If neither a
+      # whitelist nor a blacklist option is specified, then an AllMatcher is
+      # built.
+      def build_matcher(options, whitelist_option, blacklist_option)
+        assert_exclusive_keys(options, whitelist_option, blacklist_option)
+        
+        if options.include?(whitelist_option)
+          WhitelistMatcher.new(options[whitelist_option])
+        elsif options.include?(blacklist_option)
+          BlacklistMatcher.new(options[blacklist_option])
+        else
+          AllMatcher.instance
         end
       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
+      # Verifies that all configured requirements (event and state) match the
+      # given query.  If a match is return, then a hash containing the
+      # event/state requirements that passed will be returned; otherwise, nil.
+      def matches_query?(query)
+        query ||= {}
+        matches_event?(query) && matches_states?(query)
+      end
+      
+      # Verifies that the event requirement matches the given query
+      def matches_event?(query)
+        matches_requirement?(query, :on, event_requirement)
       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, then this will always
-      # find a match and return true.
-      # 
-      # == Examples
-      # 
-      #   # 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, [: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)
-        elsif blacklist
-          !blacklist.include?(value)
+      # Verifies that the state requirements match the given query.  If a
+      # matching requirement is found, then it is returned.
+      def matches_states?(query)
+        [:from, :to].all? {|option| matches_requirement?(query, option, state_requirement[option])}
+      end
+      
+      # Verifies that an option in the given query matches the values required
+      # for that option
+      def matches_requirement?(query, option, requirement)
+        !query.include?(option) || requirement.matches?(query[option], query)
+      end
+      
+      # Verifies that the conditionals for this guard evaluate to true for the
+      # given object
+      def matches_conditions?(object)
+        if if_condition
+          evaluate_method(object, if_condition)
+        elsif unless_condition
+          !evaluate_method(object, unless_condition)
         else
           true
         end

data/lib/state_machine/machine.rb

@@ -1016,7 +1016,7 @@ module StateMachine
       # name or adding an "s" to the end of the name.
       def define_scopes(custom_plural = nil)
         attribute = self.attribute
-        plural = custom_plural || (attribute.respond_to?(:pluralize) ? attribute.pluralize : "#{attribute}s")
+        plural = custom_plural || (attribute.to_s.respond_to?(:pluralize) ? attribute.to_s.pluralize : "#{attribute}s")
         
         [attribute, plural].uniq.each do |name|
           [:with, :without].each do |kind|

data/lib/state_machine/matcher.rb

@@ -0,0 +1,123 @@
+require 'singleton'
+
+module StateMachine
+  # Provides a general strategy pattern for determining whether a match is found
+  # for a value.  The algorithm that actually determines the match depends on
+  # the matcher in use.
+  class Matcher
+    # The list of values against which queries are matched
+    attr_reader :values
+    
+    # Creates a new matcher for querying against the given set of values
+    def initialize(values = [])
+      @values = values.is_a?(Array) ? values : [values] 
+    end
+    
+    # Generates a subset of values that exists in both the set of values being
+    # filtered and the values configured for the matcher
+    def filter(values)
+      self.values & values
+    end
+  end
+  
+  # Matches any given value.  Since there is no configuration for this type of
+  # matcher, it must be used as a singleton.
+  class AllMatcher < Matcher
+    include Singleton
+    
+    # Generates a blacklist matcher based on the given set of values
+    # 
+    # == Examples
+    # 
+    #   matcher = StateMachine::AllMatcher.new - [:parked, :idling]
+    #   matcher.matches?(:parked)       # => false
+    #   matcher.matches?(:first_gear)   # => true
+    def -(blacklist)
+      BlacklistMatcher.new(blacklist)
+    end
+    
+    # Always returns true
+    def matches?(value, context = {})
+      true
+    end
+    
+    # Always returns the given set of values
+    def filter(values)
+      values
+    end
+    
+    # A human-readable description of this matcher.  Always "all".
+    def description
+      'all'
+    end
+  end
+  
+  # Matches a specific set of values
+  class WhitelistMatcher < Matcher
+    # Checks whether the given value exists within the whitelist configured
+    # for this matcher.
+    # 
+    # == Examples
+    # 
+    #   matcher = StateMachine::WhitelistMatcher.new([:parked, :idling])
+    #   matcher.matches?(:parked)       # => true
+    #   matcher.matches?(:first_gear)   # => false
+    def matches?(value, context = {})
+      values.include?(value)
+    end
+    
+    # A human-readable description of this matcher
+    def description
+      values.length == 1 ? values.first.inspect : values.inspect
+    end
+  end
+  
+  # Matches everything but a specific set of values
+  class BlacklistMatcher < Matcher
+    # Checks whether the given value exists outside the blacklist configured
+    # for this matcher.
+    # 
+    # == Examples
+    # 
+    #   matcher = StateMachine::BlacklistMatcher.new([:parked, :idling])
+    #   matcher.matches?(:parked)       # => false
+    #   matcher.matches?(:first_gear)   # => true
+    def matches?(value, context = {})
+      !values.include?(value)
+    end
+    
+    # Finds all values that are *not* within the blacklist configured for this
+    # matcher
+    def filter(values)
+      values - self.values
+    end
+    
+    # A human-readable description of this matcher
+    def description
+      "all - #{values.length == 1 ? values.first.inspect : values.inspect}"
+    end
+  end
+  
+  # Matches a loopback of two values within a context.  Since there is no
+  # configuration for this type of matcher, it must be used as a singleton.
+  class LoopbackMatcher < Matcher
+    include Singleton
+    
+    # Checks whether the given value matches what the value originally was.
+    # This value should be defined in the context.
+    # 
+    # == Examples
+    # 
+    #   matcher = StateMachine::LoopbackMatcher.new
+    #   matcher.matches?(:parked, :from => :parked)   # => true
+    #   matcher.matches?(:parked, :from => :idling)   # => false
+    def matches?(value, context)
+      context[:from] == value
+    end
+    
+    # A human-readable description of this matcher.  Always "same".
+    def description
+      'same'
+    end
+  end
+end