state_machine 0.4.0 → 0.4.1

data/CHANGELOG.rdoc

@@ -1,5 +1,14 @@
 == master
 
+== 0.4.1 / 2008-12-16
+
+* Fix nil states not being handled properly in guards, known states, or visualizations
+* Fix the same node being used for different dynamic states in GraphViz output
+* Always include initial state in the list of known states even if it's dynamic
+* Use consistent naming scheme for dynamic states in GraphViz output
+* Allow blocks to be directly passed into machine class
+* Fix attribute predicates not working on attributes that represent columns in ActiveRecord
+
 == 0.4.0 / 2008-12-14
 
 * Remove the PluginAWeek namespace

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006 Scott Barron, 2006-2008 Aaron Pfefier
+Copyright (c) 2006-2008 Aaron Pfefier
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -335,10 +335,11 @@ To generate multiple state machine graphs:
   rake state_machine:draw FILE=vehicle.rb,car.rb CLASS=Vehicle,Car
 
 *Note* that this will generate a different file for every state machine defined
-in the class.  The generates files will an output filename of the format #{class_name}_#{attribute}.#{format}.
+in the class.  The generated files will use an output filename of the format
+#{class_name}_#{attribute}.#{format}.
 
 For examples of actual images generated using this task, see those under the
-test/examples folder.
+examples folder.
 
 ==== Ruby on Rails Integration
 
@@ -371,7 +372,7 @@ events for your models.  It is cross-platform, written in Java.
 == Testing
 
 To run the entire test suite (will test ActiveRecord, DataMapper, and Sequel
-integrations if available):
+integrations if the proper dependencies are available):
 
   rake test
 
@@ -386,5 +387,4 @@ dependencies are listed below.
 
 == References
 
-* Scott Barron - acts_as_state_machine[http://elitists.textdriven.com/svn/plugins/acts_as_state_machine]
 * acts_as_enumeration[http://github.com/pluginaweek/acts_as_enumeration]

data/Rakefile

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

data/lib/state_machine/event.rb

@@ -20,7 +20,7 @@ module StateMachine
     attr_reader :guards
     
     # A list of all of the states known to this event using the configured
-    # guards/transitions as the source.
+    # guards/transitions as the source
     attr_reader :known_states
     
     # Creates a new event within the context of the given machine
@@ -45,7 +45,7 @@ module StateMachine
     # 
     # 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
+    # * +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.
@@ -68,8 +68,10 @@ module StateMachine
     # 
     # == Examples
     # 
+    #   transition :from => nil, :to => 'parked'
     #   transition :from => %w(first_gear reverse)
     #   transition :except_from => 'parked'
+    #   transition :to => nil
     #   transition :to => 'parked'
     #   transition :to => lambda {Time.now}
     #   transition :to => 'parked', :from => 'first_gear'
@@ -100,7 +102,7 @@ module StateMachine
       
       if guard = guards.find {|guard| guard.matches?(object, :from => from)}
         # Guard allows for the transition to occur
-        to = guard.requirements[:to] || from
+        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

data/lib/state_machine/extensions.rb

@@ -33,7 +33,8 @@ module StateMachine
       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
+        # Re-defining +initialize+ instead of alias chaining is done in order to
+        # prevent +initialize+ from showing up in #instance_methods
         alias_method :initialize_without_state_machine, :initialize
         class_eval <<-end_eval, __FILE__, __LINE__
           def initialize(*args, &block)

data/lib/state_machine/guard.rb

@@ -27,7 +27,17 @@ module StateMachine
       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])}
+      @known_states = []
+      
+      # Normalize the requirements and track known states
+      [:to, :from, :on, :except_to, :except_from, :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)
+        end
+      end
     end
     
     # Determines whether the given object / query matches the requirements
@@ -45,10 +55,11 @@ module StateMachine
     # 
     # == Examples
     # 
-    #   guard = StateMachine::Guard.new(:on => 'ignite', :from => '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
@@ -67,10 +78,9 @@ module StateMachine
     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])
+        (!query || query.empty?) || [:from, :to, :on].all? do |option|
+          !query.include?(option) || find_match(query[option], requirements[option], requirements[:"except_#{option}"])
+        end
       end
       
       # Verify that the conditionals for this guard evaluate to true for the
@@ -87,26 +97,23 @@ module StateMachine
       
       # 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.
+      # is specified.  If neither lists are specified, then this will always
+      # find a match and return true.
       # 
       # == Examples
       # 
-      #   find_match(nil, %w(parked idling), nil)             # => true
+      #   find_match(nil, %w(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
       def find_match(value, whitelist, blacklist)
-        if value
-          if whitelist
-            Array(whitelist).include?(value)
-          elsif blacklist
-            !Array(blacklist).include?(value)
-          else
-            true
-          end
+        if whitelist
+          whitelist.include?(value)
+        elsif blacklist
+          !blacklist.include?(value)
         else
           true
         end

data/lib/state_machine/integrations/active_record.rb

@@ -188,7 +188,29 @@ module StateMachine
         # Forces all attribute methods to be generated for the model so that
         # the reader/writer methods for the attribute are available
         def define_attribute_accessor
-          owner_class.define_attribute_methods if owner_class.table_exists?
+          if owner_class.table_exists?
+            owner_class.define_attribute_methods
+            
+            # Support attribute predicate for ActiveRecord columns
+            if owner_class.column_names.include?(attribute)
+              attribute = self.attribute
+              
+              owner_class.class_eval do
+                define_method("#{attribute}?") do |*args|
+                  if args.empty?
+                    # No arguments: querying for presence of the attribute
+                    super
+                  else
+                    # Arguments: querying for the attribute's current value
+                    state = args.first
+                    raise ArgumentError, "#{state.inspect} is not a known #{attribute} value" unless self.class.state_machines[attribute].states.include?(state)
+                    send(attribute) == state
+                  end
+                end
+              end
+            end
+          end
+          
           super
         end
         

data/lib/state_machine/machine.rb

@@ -17,11 +17,11 @@ module StateMachine
   # an object since they can be any arbitrary value.  As a result, anything
   # that relies on a list of all possible states should keep in mind that if
   # a state has not been referenced *anywhere* in the state machine definition,
-  # then it will *not* be a known state unless the +other_states+ is used.
+  # then it will *not* be a known state unless the +other_states+ helper is used.
   # 
   # == State values
   # 
-  # While string are the most common object type used for setting values on
+  # While strings are the most common object type used for setting values on
   # the state of the machine, there are no restrictions on what can be used.
   # This means that symbols, integers, dates/times, etc. can all be used.
   # 
@@ -49,6 +49,8 @@ module StateMachine
   # 
   #   class Switch
   #     state_machine :activated_at
+  #       before_transition :to => nil, :do => lambda {...}
+  #       
   #       event :activate do
   #         transition :to => lambda {Time.now}
   #       end
@@ -219,16 +221,19 @@ module StateMachine
       # If a machine of the given name already exists in one of the class's
       # superclasses, then a copy of that machine will be created and stored
       # in the new owner class (the original will remain unchanged).
-      def find_or_create(owner_class, *args)
+      def find_or_create(owner_class, *args, &block)
         options = args.last.is_a?(Hash) ? args.pop : {}
-        attribute = args.any? ? args.first.to_s : 'state'
+        attribute = (args.first || 'state').to_s
         
         # Attempts to find an existing machine
         if owner_class.respond_to?(:state_machines) && machine = owner_class.state_machines[attribute]
           machine = machine.within_context(owner_class, options) unless machine.owner_class == owner_class
+          
+          # Evaluate caller block for DSL
+          machine.instance_eval(&block) if block_given?
         else
           # No existing machine: create a new one
-          machine = new(owner_class, attribute, options)
+          machine = new(owner_class, attribute, options, &block)
         end
         
         machine
@@ -283,7 +288,7 @@ module StateMachine
         include StateMachine::InstanceMethods
       end unless owner_class.included_modules.include?(StateMachine::InstanceMethods)
       
-      # Initialize the context of the machine
+      # Initialize the class context of the machine
       set_context(owner_class, :initial => options[:initial], :integration => options[:integration], &block)
       
       # Set integration-specific configurations
@@ -293,6 +298,9 @@ module StateMachine
       
       # Call after hook for integration-specific extensions
       after_initialize
+      
+      # Evaluate caller block for DSL
+      instance_eval(&block) if block_given?
     end
     
     # Creates a copy of this machine in addition to copies of each associated
@@ -313,7 +321,7 @@ module StateMachine
     
     # Creates a copy of this machine within the context of the given class.
     # This should be used for inheritance support of state machines.
-    def within_context(owner_class, options = {}) #:nodoc:
+    def within_context(owner_class, options = {}, &block) #:nodoc:
       machine = dup
       machine.set_context(owner_class, {:integration => @integration}.merge(options))
       machine
@@ -332,10 +340,8 @@ module StateMachine
       assert_valid_keys(options, :initial, :integration)
       
       @owner_class = owner_class
-      if options[:initial]
-        @initial_state = options[:initial]
-        add_states([@initial_state]) unless @initial_state.is_a?(Proc)
-      end
+      @initial_state = options[:initial] if options[:initial]
+      add_states([@initial_state])
       
       # Find an integration that can be used for implementing various parts
       # of the state machine that may behave differently in different libraries
@@ -351,12 +357,12 @@ module StateMachine
     
     # Gets the initial state of the machine for the given object. If a dynamic
     # initial state was configured for this machine, then the object will be
-    # passed into the proc to help determine the actual value of the initial
-    # state.
+    # passed into the lambda block to help determine the actual value of the
+    # initial state.
     # 
     # == Examples
     # 
-    # With static initial state:
+    # With a static initial state:
     # 
     #   class Vehicle
     #     state_machine :initial => 'parked' do
@@ -364,25 +370,36 @@ module StateMachine
     #     end
     #   end
     #   
+    #   vehicle = Vehicle.new
     #   Vehicle.state_machines['state'].initial_state(vehicle)   # => "parked"
     # 
-    # With dynamic initial state:
+    # With a dynamic initial state:
     # 
     #   class Vehicle
+    #     attr_accessor :force_idle
+    #     
     #     state_machine :initial => lambda {|vehicle| vehicle.force_idle ? 'idling' : 'parked'} do
     #       ...
     #     end
     #   end
     #   
+    #   vehicle = Vehicle.new
+    #   
+    #   vehicle.force_idle = true
     #   Vehicle.state_machines['state'].initial_state(vehicle)   # => "idling"
+    #   
+    #   vehicle.force_idle = false
+    #   Vehicle.state_machines['state'].initial_state(vehicle)   # => "parked"
     def initial_state(object)
       @initial_state.is_a?(Proc) ? @initial_state.call(object) : @initial_state
     end
     
     # Defines additional states that are possible in the state machine, but
     # which are derived outside of any events/transitions or possibly
-    # dynamically via Proc.  This allows the creation of state conditionals
-    # which are not defined in the standard :to or :from structure.
+    # dynamically via a lambda block.  This allows the given states to be:
+    # * Queried via instance-level predicates
+    # * Included in GraphViz visualizations
+    # * Used in :except_from and :except_to transition/callback conditionals
     # 
     # == Example
     # 
@@ -450,7 +467,7 @@ module StateMachine
     #     
     #     state_machine do
     #       event :park do
-    #         transition :to => 'parked', :from => Car.safe_states
+    #         transition :to => 'parked', :from => Vehicle.safe_states
     #       end
     #     end
     #   end 
@@ -685,23 +702,47 @@ module StateMachine
         
         graph = GraphViz.new('G', :output => options[:format], :file => File.join(options[:path], "#{options[:name]}.#{options[:format]}"))
         
+        # Tracks unique identifiers for dynamic states (via lambda blocks)
+        dynamic_states = {}
+        
         # Add nodes
         states.each do |state|
           shape = state == @initial_state ? 'doublecircle' : 'circle'
-          state = state.is_a?(Proc) ? 'lambda' : state.to_s
-          graph.add_node(state, :width => '1', :height => '1', :fixedsize => 'true', :shape => shape, :fontname => options[:font])
+          
+          # Use GraphViz-friendly name/label for dynamic/nil states
+          if state.is_a?(Proc)
+            name = "lambda#{dynamic_states.keys.length}"
+            label = '*'
+            dynamic_states[state] = name
+          else
+            name = label = state.nil? ? 'nil' : state.to_s
+          end
+          
+          graph.add_node(name, :label => label, :width => '1', :height => '1', :fixedsize => 'true', :shape => shape, :fontname => options[:font])
         end
         
         # Add edges
         events.values.each do |event|
           event.guards.each do |guard|
             # From states: :from, everything but :except states, or all states
-            from_states = Array(guard.requirements[:from]) || guard.requirements[:except_from] && (states - Array(guard.requirements[:except_from])) || states
-            to_state = guard.requirements[:to]
-            to_state = to_state.is_a?(Proc) ? 'lambda' : to_state.to_s if to_state
+            from_states = guard.requirements[:from] || guard.requirements[:except_from] && (states - guard.requirements[:except_from]) || states
+            if to_state = guard.requirements[:to]
+              to_state = to_state.first
+              
+              # Convert to GraphViz-friendly name
+              to_state = case to_state
+                when Proc; dynamic_states[to_state]
+                when nil; 'nil'
+                else; to_state.to_s; end
+            end
             
             from_states.each do |from_state|
-              from_state = from_state.to_s
+              # Convert to GraphViz-friendly name
+              from_state = case from_state
+                when Proc; dynamic_states[from_state]
+                when nil; 'nil'
+                else; from_state.to_s; end
+              
               graph.add_edge(from_state, to_state || from_state, :label => event.name, :fontname => options[:font])
             end
           end
@@ -728,8 +769,8 @@ module StateMachine
       def default_action
       end
       
-      # Adds reader/writer methods for accessing the attribute that this state
-      # machine is defined for.
+      # Adds reader/writer/prediate methods for accessing the attribute that
+      # this state machine is defined for.
       def define_attribute_accessor
         attribute = self.attribute
         
@@ -790,7 +831,7 @@ module StateMachine
         # Add state predicates
         attribute = self.attribute
         new_states.each do |state|
-          if state.is_a?(String) || state.is_a?(Symbol)
+          if state && (state.is_a?(String) || state.is_a?(Symbol))
             name = "#{state}?"
             
             owner_class.class_eval do

data/lib/state_machine.rb

@@ -156,9 +156,7 @@ module StateMachine
     # integrations and the individual integration docs for information about
     # the actual scopes that are generated.
     def state_machine(*args, &block)
-      machine = StateMachine::Machine.find_or_create(self, *args)
-      machine.instance_eval(&block) if block
-      machine
+      StateMachine::Machine.find_or_create(self, *args, &block)
     end
   end
 end