state_machine 0.4.1 → 0.4.2

data/lib/state_machine/guard.rb

@@ -15,7 +15,7 @@ module StateMachine
     attr_reader :requirements
     
     # A list of all of the states known to this guard.  This will pull state
-    # names from the following requirements:
+    # values from the following requirements:
     # * +to+
     # * +from+
     # * +except_to+
@@ -75,6 +75,41 @@ module StateMachine
       matches_query?(object, query) && matches_conditions?(object)
     end
     
+    # Draws a representation of this guard on the given graph.  This will draw
+    # an edge between every state this guard matches *from* to either the
+    # configured to state or, if none specified, then a loopback to the from
+    # state.
+    # 
+    # For example, if the following from states are configured:
+    # * +first_gear+
+    # * +idling+
+    # * +backing_up+
+    # 
+    # ...and the to state is "parked", then the following edges will be created:
+    # * +first_gear+  -> +parked+
+    # * +idling+      -> +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)
+      # 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
+      
+      # 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)
+      end
+    end
+    
     protected
       # Verify that the from state, to state, and event match the query
       def matches_query?(object, query)

data/lib/state_machine/integrations/active_record.rb

@@ -249,7 +249,8 @@ module StateMachine
         # This will always return true regardless of the results of the
         # callbacks.
         def notify(type, object, transition)
-          ["#{type}_#{transition.event}", "#{type}_transition"].each do |method|
+          qualified_event = namespace ? "#{transition.event}_#{namespace}" : transition.event
+          ["#{type}_#{qualified_event}", "#{type}_transition"].each do |method|
             object.class.class_eval do
               @observer_peers.dup.each do |observer|
                 observer.send(method, object, transition) if observer.respond_to?(method)

data/lib/state_machine/integrations/data_mapper/observer.rb

@@ -55,10 +55,17 @@ module StateMachine
         #       # log message
         #     end
         #     
+        #     # Target all state machines
         #     before_transition :to => 'idling', :from => 'parked', :on => 'ignite' do
         #       # put on seatbelt
         #     end
         #     
+        #     # Target a specific state machine
+        #     before_transition :state, :to => 'idling' do
+        #       # put on seatbelt
+        #     end
+        #     
+        #     # Target all state machines without requirements
         #     before_transition do |transition|
         #       # log message
         #     end
@@ -104,10 +111,17 @@ module StateMachine
         #       # log message
         #     end
         #     
+        #     # Target all state machines
         #     after_transition :to => 'idling', :from => 'parked', :on => 'ignite' do
         #       # put on seatbelt
         #     end
         #     
+        #     # Target a specific state machine
+        #     after_transition :state, :to => 'idling' do
+        #       # put on seatbelt
+        #     end
+        #     
+        #     # Target all state machines without requirements
         #     after_transition do |transition, saved|
         #       if saved
         #         # log message

data/lib/state_machine/machine.rb

@@ -1,4 +1,5 @@
 require 'state_machine/extensions'
+require 'state_machine/state'
 require 'state_machine/event'
 require 'state_machine/callback'
 require 'state_machine/assertions'
@@ -10,7 +11,7 @@ end
 
 module StateMachine
   # Represents a state machine for a particular attribute.  State machines
-  # consist of events and a set of transitions that define how the state
+  # consist of states, events and a set of transitions that define how the state
   # changes after a particular event is fired.
   # 
   # A state machine may not necessarily know all of the possible states for
@@ -95,7 +96,7 @@ module StateMachine
   #   
   #   vehicle = Vehicle.new
   #   vehicle.park        # => false
-  #   vehicle.park!       # => StateMachine::InvalidTransition: Cannot transition via :park from "idling"
+  #   vehicle.park!       # => StateMachine::InvalidTransition: Cannot transition state via :park from "idling"
   # 
   # == Observers
   # 
@@ -107,8 +108,8 @@ module StateMachine
   # 
   #   class Vehicle
   #     state_machine do
-  #       event :ignite do
-  #         transition :to => 'idling', :from => 'parked'
+  #       event :park do
+  #         transition :to => 'parked', :from => 'idling'
   #       end
   #       ...
   #     end
@@ -183,32 +184,6 @@ module StateMachine
   class Machine
     include Assertions
     
-    # The class that the machine is defined in
-    attr_reader :owner_class
-    
-    # The attribute for which the machine is being defined
-    attr_reader :attribute
-    
-    # The initial state that the machine will be in when an object is created
-    attr_reader :initial_state
-    
-    # The events that trigger transitions
-    attr_reader :events
-    
-    # A list of all of the states known to this state machine.  This will pull
-    # state names from the following sources:
-    # * Initial state
-    # * Event transitions (:to, :from, :except_to, and :except_from options)
-    # * Transition callbacks (:to, :from, :except_to, and :except_from options)
-    # * Unreferenced states (using +other_states+ helper)
-    attr_reader :states
-    
-    # The callbacks to invoke before/after a transition is performed
-    attr_reader :callbacks
-    
-    # The action to invoke when an object transitions
-    attr_reader :action
-    
     class << self
       # Attempts to find or create a state machine for the given class.  For
       # example,
@@ -263,24 +238,66 @@ module StateMachine
           end
           
           # Draw each of the class's state machines
-          klass.state_machines.values.each do |machine|
+          klass.state_machines.each do |name, machine|
             machine.draw(options)
           end
         end
       end
     end
     
+    # The class that the machine is defined in
+    attr_reader :owner_class
+    
+    # The attribute for which the machine is being defined
+    attr_reader :attribute
+    
+    # The initial state that the machine will be in when an object is created
+    attr_reader :initial_state
+    
+    # The events that trigger transitions
+    # 
+    # Maps "name" => StateMachine::Event
+    attr_reader :events
+    
+    # Tracks the order in which events were defined.  This is used to determine
+    # in what order events are drawn on GraphViz visualizations.
+    attr_reader :events_order
+    
+    # A list of all of the states known to this state machine.  This will pull
+    # state values from the following sources:
+    # * Initial state
+    # * State behaviors
+    # * Event transitions (:to, :from, :except_to, and :except_from options)
+    # * Transition callbacks (:to, :from, :except_to, and :except_from options)
+    # * Unreferenced states (using +other_states+ helper)
+    # 
+    # Maps value => StateMachine::State
+    attr_reader :states
+    
+    # The callbacks to invoke before/after a transition is performed
+    attr_reader :callbacks
+    
+    # The action to invoke when an object transitions
+    attr_reader :action
+    
+    # An identifier that forces all methods (including state predicates and
+    # event methods) to be generated with the value prefixed or suffixed,
+    # depending on the context.
+    attr_reader :namespace
+    
     # Creates a new state machine for the given attribute
     def initialize(owner_class, *args, &block)
       options = args.last.is_a?(Hash) ? args.pop : {}
-      assert_valid_keys(options, :initial, :action, :plural, :integration)
+      assert_valid_keys(options, :initial, :action, :plural, :namespace, :integration)
       
       # Set machine configuration
       @attribute = (args.first || 'state').to_s
       @events = {}
-      @states = []
+      @events_order = []
+      @states = {}
       @callbacks = {:before => [], :after => []}
       @action = options[:action]
+      @namespace = options[:namespace]
       
       # Add class-/instance-level methods to the owner class for state initialization
       owner_class.class_eval do
@@ -315,7 +332,14 @@ module StateMachine
         events[name] = event
         events
       end
-      @states = @states.dup
+      @events_order = @events_order.dup
+      @states = @states.inject({}) do |states, (value, state)|
+        state = state.dup
+        state.machine = self
+        states[value] = state
+        states
+      end
+      @initial_state = @states[@initial_state.value]
       @callbacks = {:before => @callbacks[:before].dup, :after => @callbacks[:after].dup}
     end
     
@@ -340,8 +364,8 @@ module StateMachine
       assert_valid_keys(options, :initial, :integration)
       
       @owner_class = owner_class
-      @initial_state = options[:initial] if options[:initial]
-      add_states([@initial_state])
+      @initial_state = add_states([options[:initial]]).first if options.include?(:initial) || !@initial_state
+      states.each {|name, state| state.initial = (state == @initial_state)}
       
       # Find an integration that can be used for implementing various parts
       # of the state machine that may behave differently in different libraries
@@ -391,7 +415,99 @@ module StateMachine
     #   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
+      @initial_state && @initial_state.value(object)
+    end
+    
+    # Defines a series of behaviors to mixin with objects when the current
+    # state matches the given one(s).  This allows instance methods to behave
+    # a specific way depending on what the value of the object's state is.
+    # 
+    # For example,
+    # 
+    #   class Vehicle
+    #     attr_accessor :driver
+    #     attr_accessor :passenger
+    #     
+    #     state_machine :initial => 'parked' do
+    #       event :ignite do
+    #         transition :to => 'idling', :from => 'parked'
+    #       end
+    #       
+    #       state 'parked' do
+    #         def speed
+    #           0
+    #         end
+    #         
+    #         def rotate_driver
+    #           driver = self.driver
+    #           self.driver = passenger
+    #           self.passenger = driver
+    #           true
+    #         end
+    #       end
+    #       
+    #       state 'idling', 'first_gear' do
+    #         def speed
+    #           20
+    #         end
+    #         
+    #         def rotate_driver
+    #           self.state = "parked"
+    #           rotate_driver
+    #         end
+    #       end
+    #     end
+    #   end
+    # 
+    # In the above example, there are two dynamic behaviors defined for the
+    # class:
+    # * +speed+
+    # * +rotate_driver+
+    # 
+    # Each of these behaviors are instance methods on the Vehicle class.  However,
+    # which method actually gets invoked is based on the current state of the
+    # object.  Using the above class as the example:
+    # 
+    #   vehicle = Vehicle.new
+    #   vehicle.driver = 'John'
+    #   vehicle.passenger = 'Jane'
+    #   
+    #   # Behaviors in the "parked" state
+    #   vehicle.state             # => "parked"
+    #   vehicle.speed             # => 0
+    #   vehicle.rotate_driver     # => true
+    #   vehicle.driver            # => "Jane"
+    #   vehicle.passenger         # => "John"
+    #   
+    #   vehicle.ignite            # => true
+    #   
+    #   # Behaviors in the "idling" state
+    #   vehicle.state             # => "idling"
+    #   vehicle.speed             # => 20
+    #   vehicle.rotate_driver     # => true
+    #   vehicle.driver            # => "John"
+    #   vehicle.passenger         # => "Jane"
+    #   vehicle.state             # => "parked"
+    # 
+    # As can be seen, both the +speed+ and +rotate_driver+ instance method
+    # implementations changed how they behave based on what the current state
+    # of the vehicle was.
+    # 
+    # == Invalid behaviors
+    # 
+    # If a specific behavior has not been defined for a state, then a
+    # NoMethodError exception will be raised, indicating that that method would
+    # not normally exist for an object with that state.
+    # 
+    # Using the example from before:
+    # 
+    #   vehicle = Vehicle.new
+    #   vehicle.state = "backing_up"
+    #   vehicle.speed               # => NoMethodError: undefined method 'speed' for #<Vehicle:0xb7d296ac> in state "backing_up"
+    def state(*values, &block)
+      states = add_states(values)
+      states.each {|state| state.context(&block)} if block_given?
+      states.length == 1 ? states.first : states
     end
     
     # Defines additional states that are possible in the state machine, but
@@ -429,7 +545,27 @@ module StateMachine
       add_states(args.flatten)
     end
     
-    # Defines an event for the machine.
+    # Gets the order in which states should be displayed based on where they
+    # were first referenced.  This will order states in the following priority:
+    # 
+    # 1. Initial state
+    # 2. Event transitions (:to, :from, :except_to, :except_from options)
+    # 3. States with behaviors
+    # 4. States referenced via +other_states+
+    # 5. States referenced in callbacks
+    # 
+    # This order will determine how the GraphViz visualizations are rendered.
+    def states_order
+      order = [initial_state(nil)]
+      
+      events.each {|name, event| order |= event.known_states}
+      order |= states.select {|value, state| state.methods.any?}.map {|state| state.first}
+      order |= states.keys - callbacks.values.flatten.map {|callback| callback.known_states}.flatten
+      order |= states.keys
+    end
+    
+    # Defines one or more events for the machine and the transitions that can
+    # be performed when those events are run.
     # 
     # == Instance methods
     # 
@@ -440,13 +576,19 @@ module StateMachine
     # * <tt>park(run_action = true)</tt> - Fires the "park" event, transitioning from the current state to the next valid state.
     # * <tt>park!(run_action = true)</tt> - Fires the "park" event, transitioning from the current state to the next valid state.  If the transition fails, then a StateMachine::InvalidTransition error will be raised.
     # 
+    # With a namespace of "car", the above names map to the following methods:
+    # * <tt>can_park_car?</tt>
+    # * <tt>next_park_car_transition</tt>
+    # * <tt>park_car</tt>
+    # * <tt>park_car!</tt>
+    # 
     # == Defining transitions
     # 
     # +event+ requires a block which allows you to define the possible
     # transitions that can happen as a result of that event.  For example,
     # 
-    #   event :park do
-    #     transition :to => 'parked', :from => 'idle'
+    #   event :park, :stop do
+    #     transition :to => 'parked', :from => 'idling'
     #   end
     #   
     #   event :first_gear do
@@ -476,19 +618,35 @@ module StateMachine
     # 
     #   class Vehicle
     #     state_machine do
-    #       event :park do
-    #         transition :to => 'parked', :from => %w(first_gear reverse)
+    #       # The park, stop, and halt events will all share the given transitions
+    #       event :park, :stop, :halt do
+    #         transition :to => 'parked', :from => %w(idling backing_up)
+    #       end
+    #       
+    #       event :stop do
+    #         transition :to => 'idling', :from => 'first_gear'
+    #       end
+    #       
+    #       event :ignite do
+    #         transition :to => 'idling', :from => 'parked'
     #       end
-    #       ...
     #     end
     #   end
-    def event(name, &block)
-      name = name.to_s
-      event = events[name] ||= Event.new(self, name)
-      event.instance_eval(&block)
-      add_states(event.known_states)
+    def event(*names, &block)
+      events = names.collect do |name|
+        name = name.to_s
+        event = self.events[name] ||= Event.new(self, name)
+        @events_order << name unless @events_order.include?(name)
+        
+        if block_given?
+          event.instance_eval(&block)
+          add_states(event.known_states)
+        end
+        
+        event
+      end
       
-      event
+      events.length == 1 ? events.first : events
     end
     
     # Creates a callback that will be invoked *before* a transition is
@@ -702,56 +860,21 @@ 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'
-          
-          # 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])
+        Array(state(*states_order)).each do |state|
+          node = state.draw(graph)
+          node.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 = 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|
-              # 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
+        Array(event(*events_order)).each do |event|
+          edges = event.draw(graph)
+          edges.each {|edge| edge.fontname = options[:font]}
         end
         
         # Generate the graph
         graph.output
-        
-        true
+        graph
       rescue LoadError
         $stderr.puts 'Cannot draw the machine. `gem install ruby-graphviz` and try again.'
         false
@@ -825,23 +948,7 @@ module StateMachine
       # Tracks the given set of states in the list of all known states for
       # this machine
       def add_states(states)
-        new_states = states - @states
-        @states += new_states
-        
-        # Add state predicates
-        attribute = self.attribute
-        new_states.each do |state|
-          if state && (state.is_a?(String) || state.is_a?(Symbol))
-            name = "#{state}?"
-            
-            owner_class.class_eval do
-              # Checks whether the current state is equal to the given value
-              define_method(name) do
-                self.send(attribute) == state
-              end unless method_defined?(name) || private_method_defined?(name)
-            end
-          end
-        end
+        states.collect {|state| @states[state] ||= State.new(self, state)}
       end
   end
 end