state_machine 0.9.4 → 0.10.0

data/lib/state_machine/machine_collection.rb

@@ -1,20 +1,28 @@
 module StateMachine
   # Represents a collection of state machines for a class
   class MachineCollection < Hash
-    # Initializes the state of each machine in the given object.  Initial
-    # values are only set if the machine's attribute doesn't already exist
-    # (which must mean the defaults are being skipped)
+    # Initializes the state of each machine in the given object.  This can allow
+    # states to be initialized in two groups: static and dynamic.  For example:
+    # 
+    #   machines.initialize_states(object) do
+    #     # After static state initialization, before dynamic state initialization
+    #   end
+    # 
+    # If no block is provided, then all states will still be initialized.
     def initialize_states(object, options = {})
-      if ignore = options[:ignore]
-        ignore = ignore.map {|attribute| attribute.to_sym}
-      end
+      options = {:static => true, :dynamic => true}.merge(options)
+      
+      each_value do |machine| 
+        machine.initialize_state(object, options) unless machine.dynamic_initial_state?
+      end if options[:static]
+      
+      result = yield if block_given?
       
       each_value do |machine|
-        if (!ignore || !ignore.include?(machine.attribute)) && (!options.include?(:dynamic) || machine.dynamic_initial_state? == options[:dynamic])
-          value = machine.read(object, :state)
-          machine.initialize_state(object) if ignore || value.nil? || value.respond_to?(:empty?) && value.empty?
-        end
-      end
+        machine.initialize_state(object, options) if machine.dynamic_initial_state?
+      end if options[:dynamic]
+      
+      result
     end
     
     # Runs one or more events in parallel on the given object.  See
@@ -28,12 +36,12 @@ module StateMachine
         event = nil
         detect {|name, machine| event = machine.events[event_name, :qualified_name]}
         
-        raise InvalidEvent, "#{event_name.inspect} is an unknown state machine event" unless event
+        raise(InvalidEvent.new(object, event_name)) unless event
         
         # Get the transition that will be performed for the event
         unless transition = event.transition_for(object)
           machine = event.machine
-          machine.invalidate(object, :state, :invalid_transition, [[:event, event.human_name]])
+          event.on_failure(object)
         end
         
         transition

data/lib/state_machine/node_collection.rb

@@ -34,7 +34,7 @@ module StateMachine
       nodes = @nodes
       @nodes = []
       @indices = @indices.inject({}) {|indices, (name, index)| indices[name] = {}; indices}
-      nodes.each {|node| self << node.dup}
+      concat(nodes.map {|n| n.dup})
     end
     
     # Changes the current machine associated with the collection.  In turn, this
@@ -62,6 +62,11 @@ module StateMachine
       self
     end
     
+    # Appends a group of nodes to the collection
+    def concat(nodes)
+      nodes.each {|node| self << node}
+    end
+    
     # Updates the indexed keys for the given node.  If the node's attribute
     # has changed since it was added to the collection, the old indexed keys
     # will be replaced with the updated ones.

data/lib/state_machine/path.rb

@@ -0,0 +1,120 @@
+module StateMachine
+  # A path represents a sequence of transitions that can be run for a particular
+  # object.  Paths can walk to new transitions, revealing all of the possible
+  # branches that can be encountered in the object's state machine.
+  class Path < Array
+    include Assertions
+    
+    # The object whose state machine is being walked
+    attr_reader :object
+    
+    # The state machine this path is walking
+    attr_reader :machine
+    
+    # Creates a new transition path for the given object.  Initially this is an
+    # empty path.  In order to start walking the path, it must be populated with
+    # an initial transition.
+    # 
+    # Configuration options:
+    # * <tt>:target</tt> - The target state to end the path on
+    # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
+    #   conditionals defined for each one
+    def initialize(object, machine, options = {})
+      assert_valid_keys(options, :target, :guard)
+      
+      @object = object
+      @machine = machine
+      @target = options[:target]
+      @guard = options[:guard]
+    end
+    
+    def initialize_copy(orig) #:nodoc:
+      super
+      @transitions = nil
+    end
+    
+    # The initial state name for this path
+    def from_name
+      first && first.from_name
+    end
+    
+    # Lists all of the from states that can be reached through this path.
+    # 
+    # For example,
+    # 
+    #   path.to_states  # => [:parked, :idling, :first_gear, ...]
+    def from_states
+      map {|transition| transition.from_name}.uniq
+    end
+    
+    # The end state name for this path.  If a target state was specified for
+    # the path, then that will be returned if the path is complete.
+    def to_name
+      last && last.to_name
+    end
+    
+    # Lists all of the to states that can be reached through this path.
+    # 
+    # For example,
+    # 
+    #   path.to_states  # => [:parked, :idling, :first_gear, ...]
+    def to_states
+      map {|transition| transition.to_name}.uniq
+    end
+    
+    # Lists all of the events that can be fired through this path.
+    # 
+    # For example,
+    # 
+    #   path.events # => [:park, :ignite, :shift_up, ...]
+    def events
+      map {|transition| transition.event}.uniq
+    end
+    
+    # Walks down the next transitions at the end of this path.  This will only
+    # walk down paths that are considered valid.
+    def walk
+      transitions.each {|transition| yield dup.push(transition)}
+    end
+    
+    # Determines whether or not this path has completed.  A path is considered
+    # complete when one of the following conditions is met:
+    # * The last transition in the path ends on the target state
+    # * There are no more transitions remaining to walk and there is no target
+    #   state
+    def complete?
+      !empty? && (@target ? to_name == @target : transitions.empty?)
+    end
+    
+    private
+      # Calculates the number of times the given state has been walked to
+      def times_walked_to(state)
+        select {|transition| transition.to_name == state}.length
+      end
+      
+      # Determines whether the given transition has been recently walked down in
+      # this path.  If a target is configured for this path, then this will only
+      # look at transitions walked down since the target was last reached.
+      def recently_walked?(transition)
+        transitions = self
+        if @target && @target != to_name && target_transition = detect {|t| t.to_name == @target}
+          transitions = transitions[index(target_transition) + 1..-1]
+        end
+        transitions.include?(transition)
+      end
+      
+      # Determines whether it's possible to walk to the given transition from
+      # the current path.  A transition can be walked to if:
+      # * It has not been recently walked and
+      # * If a target is specified, it has not been walked to twice yet
+      def can_walk_to?(transition)
+        !recently_walked?(transition) && (!@target || times_walked_to(@target) < 2)
+      end
+      
+      # Get the next set of transitions that can be walked to starting from the
+      # end of this path
+      def transitions
+        @transitions ||= empty? ? [] : machine.events.transitions_for(object, :from => to_name, :guard => @guard).select {|transition| can_walk_to?(transition)}
+      end
+  end
+end

data/lib/state_machine/path_collection.rb

@@ -0,0 +1,90 @@
+require 'state_machine/path'
+
+module StateMachine
+  # Represents a collection of paths that are generated based on a set of
+  # requirements regarding what states to start and end on
+  class PathCollection < Array
+    include Assertions
+    
+    # The object whose state machine is being walked
+    attr_reader :object
+    
+    # The state machine these path are walking
+    attr_reader :machine
+    
+    # The initial state to start each path from
+    attr_reader :from_name
+    
+    # The target state for each path
+    attr_reader :to_name
+    
+    # Creates a new collection of paths with the given requirements.
+    # 
+    # Configuration options:
+    # * <tt>:from</tt> - The initial state to start from
+    # * <tt>:to</tt> - The target end state
+    # * <tt>:deep</tt> - Whether to enable deep searches for the target state.
+    # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
+    #   conditionals defined for each one
+    def initialize(object, machine, options = {})
+      options = {:deep => false, :from => machine.states.match!(object).name}.merge(options)
+      assert_valid_keys(options, :from, :to, :deep, :guard)
+      
+      @object = object
+      @machine = machine
+      @from_name = machine.states.fetch(options[:from]).name
+      @to_name = options[:to] && machine.states.fetch(options[:to]).name
+      @guard = options[:guard]
+      @deep = options[:deep]
+      
+      initial_paths.each {|path| walk(path)}
+    end
+    
+    # Lists all of the states that can be transitioned from through the paths in
+    # this collection.
+    # 
+    # For example,
+    # 
+    #   paths.from_states # => [:parked, :idling, :first_gear, ...]
+    def from_states
+      map {|path| path.from_states}.flatten.uniq
+    end
+    
+    # Lists all of the states that can be transitioned to through the paths in
+    # this collection.
+    # 
+    # For example,
+    # 
+    #   paths.to_states # => [:idling, :first_gear, :second_gear, ...]
+    def to_states
+      map {|path| path.to_states}.flatten.uniq
+    end
+    
+    # Lists all of the events that can be fired through the paths in this
+    # collection.
+    # 
+    # For example,
+    # 
+    #   paths.events  # => [:park, :ignite, :shift_up, ...]
+    def events
+      map {|path| path.events}.flatten.uniq
+    end
+    
+    private
+      # Gets the initial set of paths to walk
+      def initial_paths
+        machine.events.transitions_for(object, :from => from_name, :guard => @guard).map do |transition|
+          path = Path.new(object, machine, :target => to_name, :guard => @guard)
+          path << transition
+          path
+        end
+      end
+      
+      # Walks down the given path.  Each new path that matches the configured
+      # requirements will be added to this collection.
+      def walk(path)
+        self << path if path.complete?
+        path.walk {|next_path| walk(next_path)} unless to_name && path.complete? && !@deep
+      end
+  end
+end

data/lib/state_machine/state.rb

@@ -73,7 +73,20 @@ module StateMachine
       @methods = {}
       @initial = options[:initial] == true
       
-      add_predicate
+      if name
+        conflicting_machines = machine.owner_class.state_machines.select {|name, other_machine| other_machine != machine && other_machine.states[qualified_name, :qualified_name]}
+        
+        # Output a warning if another machine has a conflicting qualified name
+        # for a different attribute
+        if conflict = conflicting_machines.detect {|name, other_machine| other_machine.attribute != machine.attribute}
+          name, other_machine = conflict
+          warn "State #{qualified_name.inspect} for #{machine.name.inspect} is already defined in #{other_machine.name.inspect}"
+        elsif conflicting_machines.empty?
+          # Only bother adding predicates when another machine for the same
+          # attribute hasn't already done so
+          add_predicate
+        end
+      end
     end
     
     # Creates a copy of this state in addition to the list of associated
@@ -89,8 +102,8 @@ module StateMachine
     # machine's definition.
     def final?
       !machine.events.any? do |event|
-        event.guards.any? do |guard|
-          guard.state_requirements.any? do |requirement|
+        event.branches.any? do |branch|
+          branch.state_requirements.any? do |requirement|
             requirement[:from].matches?(name) && !requirement[:to].matches?(name, :from => name)
           end
         end
@@ -247,13 +260,19 @@ module StateMachine
       end
       
       # Adds a predicate method to the owner class so long as a name has
-      # actually been configured for the state
+      # actually been configured for the state and the method isn't already
+      # defined in the owner class.
       def add_predicate
-        return unless name
-        
-        # Checks whether the current value matches this state
-        machine.define_instance_method("#{qualified_name}?") do |machine, object|
-          machine.states.matches?(object, name)
+        owner_class = machine.owner_class
+        predicate = "#{qualified_name}?"
+        if !owner_class.method_defined?(predicate) && !owner_class.private_method_defined?(predicate)
+          # Checks whether the current value matches this state
+          machine.define_helper(:instance, predicate) do |machine, object|
+            machine.states.matches?(object, name)
+          end
+        else
+          # Only output a warning since we can't defined the predicate
+          warn "#{owner_class.name}##{predicate} is already defined, use #{owner_class.name}##{machine.name}?(:#{name}) instead."
         end
       end
   end

data/lib/state_machine/state_collection.rb

@@ -4,7 +4,7 @@ module StateMachine
   # Represents a collection of states in a state machine
   class StateCollection < NodeCollection
     def initialize(machine) #:nodoc:
-      super(machine, :index => [:name, :value])
+      super(machine, :index => [:name, :qualified_name, :value])
     end
     
     # Determines whether the given object is in a specific state.  If the

data/lib/state_machine/transition.rb

@@ -1,8 +1,55 @@
 require 'state_machine/transition_collection'
+require 'state_machine/error'
 
 module StateMachine
   # An invalid transition was attempted
-  class InvalidTransition < StandardError
+  class InvalidTransition < Error
+    # The machine attempting to be transitioned
+    attr_reader :machine
+    
+    # The current state value for the machine
+    attr_reader :from
+    
+    def initialize(object, machine, event) #:nodoc:
+      @machine = machine
+      @from_state = machine.states.match!(object)
+      @from = machine.read(object, :state)
+      @event = machine.events.fetch(event)
+      
+      super(object, "Cannot transition #{machine.name} via :#{self.event} from #{from_name.inspect}")
+    end
+    
+    # The event that triggered the failed transition
+    def event
+      @event.name
+    end
+    
+    # The fully-qualified name of the event that triggered the failed transition
+    def qualified_event
+      @event.qualified_name
+    end
+    
+    # The name for the current state
+    def from_name
+      @from_state.name
+    end
+    
+    # The fully-qualified name for the current state
+    def qualified_from_name
+      @from_state.qualified_name
+    end
+  end
+  
+  # A set of transition failed to run in parallel
+  class InvalidParallelTransition < Error
+    # The set of events that failed the transition(s)
+    attr_reader :events
+    
+    def initialize(object, events) #:nodoc:
+      @events = events
+      
+      super(object, "Cannot run events in parallel: #{events * ', '}")
+    end
   end
   
   # A transition represents a state change for a specific attribute.
@@ -175,6 +222,7 @@ module StateMachine
     # provided, then it will be executed between the before and after callbacks.
     # 
     # Configuration options:
+    # * +before+ - Whether to run before callbacks.
     # * +after+ - Whether to run after callbacks.  If false, then any around
     #   callbacks will be paused until called again with +after+ enabled.
     #   Default is true.
@@ -182,10 +230,10 @@ module StateMachine
     # This will return true if all before callbacks gets executed.  After
     # callbacks will not have an effect on the result.
     def run_callbacks(options = {}, &block)
-      options = {:after => true}.merge(options)
+      options = {:before => true, :after => true}.merge(options)
       @success = false
       
-      halted = pausable { before(options[:after], &block) }
+      halted = pausable { before(options[:after], &block) } if options[:before]
       
       # After callbacks are only run if:
       # * An around callback didn't halt after yielding
@@ -257,6 +305,17 @@ module StateMachine
       @paused_block = nil
     end
     
+    # Determines equality of transitions by testing whether the object, states,
+    # and event involved in the transition are equal
+    def ==(other)
+      other.instance_of?(self.class) &&
+      other.object == object &&
+      other.machine == machine &&
+      other.from_name == from_name &&
+      other.to_name == to_name &&
+      other.event == event
+    end
+    
     # Generates a nicely formatted description of this transitions's contents.
     # 
     # For example,
@@ -341,7 +400,7 @@ module StateMachine
                   before(complete, index, &block)
                   
                   pause if @success && !complete
-                  throw :cancel, true unless callback.matches_success?(@success)
+                  throw :cancel, true unless @success
                 end
               end
             else
@@ -375,8 +434,8 @@ module StateMachine
           # First resume previously paused callbacks
           if resume
             catch(:halt) do
-              after_context = context.merge(:success => @success)
-              machine.callbacks[:after].each {|callback| callback.call(object, after_context, self)}
+              type = @success ? :after : :failure
+              machine.callbacks[type].each {|callback| callback.call(object, context, self)}
             end
           end