state_machine 0.4.3 → 0.5.0

data/lib/state_machine/node_collection.rb

@@ -0,0 +1,142 @@
+require 'state_machine/assertions'
+
+module StateMachine
+  # Represents a collection of nodes in a state machine, be it events or states.
+  class NodeCollection
+    include Enumerable
+    include Assertions
+    
+    # Creates a new collection of nodes for the given state machine.  By default,
+    # the collection is empty.
+    # 
+    # Configuration options:
+    # * <tt>:index</tt> - One or more attributes to automatically generate
+    #   hashed indices for in order to perform quick lookups.  Default is to
+    #   index by the :name attribute
+    def initialize(options = {})
+      assert_valid_keys(options, :index)
+      options = {:index => :name}.merge(options)
+      
+      @nodes = []
+      @indices = Array(options[:index]).inject({}) {|indices, attribute| indices[attribute] = {}; indices}
+      @default_index = Array(options[:index]).first
+    end
+    
+    # Creates a copy of this collection such that modifications don't affect
+    # the original collection
+    def initialize_copy(orig) #:nodoc:
+      super
+      
+      nodes = @nodes
+      @nodes = []
+      @indices = @indices.inject({}) {|indices, (name, index)| indices[name] = {}; indices}
+      nodes.each {|node| self << node.dup}
+    end
+    
+    # Changes the current machine associated with the collection.  In turn, this
+    # will change the state machine associated with each node in the collection.
+    def machine=(new_machine)
+      each {|node| node.machine = new_machine}
+    end
+    
+    # Gets the number of nodes in this collection
+    def length
+      @nodes.length
+    end
+    
+    # Gets the set of unique keys for the given index
+    def keys(index_name = @default_index)
+      index(index_name).keys
+    end
+    
+    # Adds a new node to the collection.  By doing so, this will also add it to
+    # the configured indices.
+    def <<(node)
+      @nodes << node
+      @indices.each {|attribute, index| index[node.send(attribute)] = node}
+      self
+    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.
+    def update(node)
+      @indices.each do |attribute, index|
+        old_key = index.respond_to?(:key) ? index.key(node) : index.index(node)
+        new_key = node.send(attribute)
+        
+        # Only replace the key if it's changed
+        if old_key != new_key
+          index.delete(old_key)
+          index[new_key] = node
+        end
+      end
+    end
+    
+    # Calls the block once for each element in self, passing that element as a
+    # parameters.
+    # 
+    #   states = StateMachine::NodeCollection.new
+    #   states << StateMachine::State.new(machine, :parked)
+    #   states << StateMachine::State.new(machine, :idling)
+    #   states.each {|state| puts state.name, ' -- '}
+    # 
+    # ...produces:
+    # 
+    #   parked -- idling --
+    def each
+      @nodes.each {|node| yield node}
+      self
+    end
+    
+    # Gets the node at the given index.
+    # 
+    #   states = StateMachine::NodeCollection.new
+    #   states << StateMachine::State.new(machine, :parked)
+    #   states << StateMachine::State.new(machine, :idling)
+    #   
+    #   states.at(0).name    # => :parked
+    #   states.at(1).name    # => :idling
+    def at(index)
+      @nodes[index]
+    end
+    
+    # Gets the node indexed by the given key.  By default, this will look up the
+    # key in the first index configured for the collection.  A custom index can
+    # be specified like so:
+    # 
+    #   collection['parked', :value]
+    # 
+    # The above will look up the "parked" key in a hash indexed by each node's
+    # +value+ attribute.
+    # 
+    # If the key cannot be found, then nil will be returned.
+    def [](key, index_name = @default_index)
+      index(index_name)[key]
+    end
+    
+    # Gets the node indexed by the given key.  By default, this will look up the
+    # key in the first index configured for the collection.  A custom index can
+    # be specified like so:
+    # 
+    #   collection['parked', :value]
+    # 
+    # The above will look up the "parked" key in a hash indexed by each node's
+    # +value+ attribute.
+    # 
+    # If the key cannot be found, then an IndexError exception will be raised:
+    # 
+    #   collection['invalid', :value]   # => IndexError: "invalid" is an invalid value
+    def fetch(key, index_name = @default_index)
+      self[key, index_name] || raise(ArgumentError, "#{key.inspect} is an invalid #{index_name}")
+    end
+    
+    private
+      # Gets the given index.  If the index does not exist, then an ArgumentError
+      # is raised.
+      def index(name)
+        raise ArgumentError, 'No indices configured' unless @indices.any?
+        @indices[name] || raise(ArgumentError, "Invalid index: #{name.inspect}")
+      end
+  end
+end

data/lib/state_machine/state.rb

@@ -3,54 +3,55 @@ require 'state_machine/assertions'
 module StateMachine
   # A state defines a value that an attribute can be in after being transitioned
   # 0 or more times.  States can represent a value of any type in Ruby, though
-  # the most common type is String.
+  # the most common (and default) type is String.
   # 
-  # In addition to defining the machine's value, states can also define a
+  # In addition to defining the machine's value, a state can also define a
   # behavioral context for an object when that object is in the state.  See
   # StateMachine::Machine#state for more information about how state-driven
   # behavior can be utilized.
   class State
     include Assertions
     
-    class << self
-      # Generates a unique identifier for the given state value.  Ids are based
-      # on the object type:
-      # * Proc - "lambda#{object_id}"
-      # * NilClass - "nil"
-      # * Everything else - Stringified version of the object
-      def id_for(value)
-        case value
-        when Proc
-          "lambda#{value.object_id.abs}"
-        when nil
-          'nil'
-        else
-          value.to_s
-        end
-      end
-    end
-    
     # The state machine for which this state is defined
     attr_accessor :machine
     
+    # The unique identifier for the state used in event and callback definitions
+    attr_reader :name
+    
+    # The value that is written to a machine's attribute when an object
+    # transitions into this state
+    attr_writer :value
+    
+    # Whether or not this state is the initial state to use for new objects
+    attr_accessor :initial
+    
+    # A custom lambda block for determining whether a given value matches this
+    # state
+    attr_accessor :matcher
+    
     # Tracks all of the methods that have been defined for the machine's owner
     # class when objects are in this state.
     # 
-    # Maps "method name" => UnboundMethod
+    # Maps :method_name => UnboundMethod
     attr_reader :methods
     
-    # Whether or not this state in the initial state to use for new objects
-    attr_accessor :initial
-    
-    # Creates a new state within the context of the given machine
+    # Creates a new state within the context of the given machine.
     # 
     # Configuration options:
-    # * +initial+ - Whether this state is the beginning state for the machine.  Default is false.
-    def initialize(machine, value, options = {}) #:nodoc:
-      assert_valid_keys(options, :initial)
+    # * <tt>:initial</tt> - Whether this state is the beginning state for the
+    #   machine. Default is false.
+    # * <tt>:value</tt> - The value to store when an object transitions to this
+    #   state.  Default is the name (stringified).
+    # * <tt>:if</tt> - Determines whether a value matches this state
+    #   (e.g. :value => lambda {Time.now}, :if => lambda {|state| !state.nil?}).
+    #   By default, the configured value is matched.
+    def initialize(machine, name, options = {}) #:nodoc:
+      assert_valid_keys(options, :initial, :value, :if)
       
       @machine = machine
-      @value = value
+      @name = name
+      @value = options.include?(:value) ? options[:value] : name && name.to_s
+      @matcher = options[:if]
       @methods = {}
       @initial = options.include?(:initial) && options[:initial]
       
@@ -61,14 +62,53 @@ module StateMachine
     # methods to prevent conflicts across different states.
     def initialize_copy(orig) #:nodoc:
       super
-      @methods = @methods.dup
+      @methods = methods.dup
     end
     
-    # The value (of any type) that represents this state.  If an object is
-    # passed in and the state's value is a lambda block, then the object will be
-    # passed into the block to generate the actual value of the state.
-    def value(object = nil)
-      @value.is_a?(Proc) && object ? @value.call(object) : @value
+    # Generates a human-readable description of this state's name / value:
+    # 
+    # For example,
+    # 
+    #   State.new(machine, :parked).description                               # => "parked"
+    #   State.new(machine, :parked, :value => :parked).description            # => "parked"
+    #   State.new(machine, :parked, :value => nil).description                # => "parked (nil)"
+    #   State.new(machine, :parked, :value => 1).description                  # => "parked (1)"
+    #   State.new(machine, :parked, :value => lambda {Time.now}).description  # => "parked (*)
+    def description
+      description = name ? name.to_s : name.inspect
+      description << " (#{@value.is_a?(Proc) ? '*' : @value.inspect})" unless name.to_s == @value.to_s
+      description
+    end
+    
+    # The value that represents this state.  If the value is a lambda block,
+    # then it will be evaluated at this time.  Otherwise, the static value is
+    # returned.
+    # 
+    # For example,
+    # 
+    #   State.new(machine, :parked, :value => 1).value                  # => 1
+    #   State.new(machine, :parked, :value => lambda {Time.now}).value  # => Tue Jan 01 00:00:00 UTC 2008
+    def value
+      @value.is_a?(Proc) ? @value.call : @value
+    end
+    
+    # Determines whether this state matches the given value.  If no matcher is
+    # configured, then this will check whether the values are equivalent.
+    # Otherwise, the matcher will determine the result.
+    # 
+    # For example,
+    # 
+    #   # Without a matcher
+    #   state = State.new(machine, :parked, :value => 1)
+    #   state.matches?(1)           # => true
+    #   state.matches?(2)           # => false
+    #   
+    #   # With a matcher
+    #   state = State.new(machine, :parked, :value => lambda {Time.now}, :if => lambda {|value| !value.nil?})
+    #   state.matches?(nil)         # => false
+    #   state.matches?(Time.now)    # => true
+    def matches?(other_value)
+      matcher ? matcher.call(other_value) : other_value == value
     end
     
     # Defines a context for the state which will be enabled on instances of the
@@ -77,7 +117,6 @@ module StateMachine
     # This can be called multiple times.  Each time a new context is created, a
     # new module will be included in the owner class.
     def context(&block)
-      value = self.value
       owner_class = machine.owner_class
       attribute = machine.attribute
       
@@ -95,15 +134,14 @@ module StateMachine
           # not possible with lambdas in Ruby 1.8.6.
           owner_class.class_eval <<-end_eval, __FILE__, __LINE__
             def #{method}(*args, &block)
-              attribute = #{attribute.dump}
-              self.class.state_machines[attribute].state(send(attribute)).call(self, #{method.dump}, *args, &block)
+              self.class.state_machines[#{attribute.inspect}].state_for(self).call(self, #{method.inspect}, *args, &block)
             end
           end_eval
         end
         
         # Track the method defined for the context so that it can be invoked
         # at a later point in time
-        methods[method] = context.instance_method(method)
+        methods[method.to_sym] = context.instance_method(method)
       end
       
       # Include the context so that it can be bound to the owner class (the
@@ -112,7 +150,7 @@ module StateMachine
         include context
       end
       
-      methods
+      context
     end
     
     # Calls a method defined in this state's context on the given object.  All
@@ -121,53 +159,60 @@ module StateMachine
     # If the method has never been defined for this state, then a NoMethodError
     # will be raised.
     def call(object, method, *args, &block)
-      if context_method = methods[method.to_s]
+      if context_method = methods[method.to_sym]
         # Method is defined by the state: proxy it through
         context_method.bind(object).call(*args, &block)
       else
         # Raise exception as if the method never existed on the original object
-        raise NoMethodError, "undefined method '#{method}' for #{object} in state #{object.send(machine.attribute).inspect}"
+        raise NoMethodError, "undefined method '#{method}' for #{object} in state #{machine.state_for(object).name.inspect}"
       end
     end
     
     # Draws a representation of this state on the given machine.  This will
     # create a new node on the graph with the following properties:
-    # * +label+ - A human-friendly version of the value.  For lambda blocks / procs, "*", otherwise the stringified version of the value is used.
+    # * +label+ - The human-friendly description of the state.
     # * +width+ - The width of the node.  Always 1.
     # * +height+ - The height of the node.  Always 1.
-    # * +fixedsize+ - Whether the size of the node stays the same regardless of its contents.  Always true.
-    # * +shape+ - The actual shape of the node.  If the state is the beginning state, then "doublecircle", otherwise "circle".
+    # * +fixedsize+ - Whether the size of the node stays the same regardless of
+    #   its contents.  Always true.
+    # * +shape+ - The actual shape of the node.  If the state is the initial
+    #   state, then "doublecircle", otherwise "circle".
     # 
     # The actual node generated on the graph will be returned.
     def draw(graph)
-      shape = initial ? 'doublecircle' : 'circle'
-      
-      # Use GraphViz-friendly name/label for dynamic/nil states
-      name = self.class.id_for(value)
-      if value.is_a?(Proc)
-        label = '*'
-      else
-        label = value.nil? ? 'nil' : value.to_s
-      end
-      
-      graph.add_node(name, :label => label, :width => '1', :height => '1', :fixedsize => 'true', :shape => shape)
+      graph.add_node(name ? name.to_s : 'nil',
+        :label => description,
+        :width => '1',
+        :height => '1',
+        :fixedsize => 'true',
+        :shape => initial ? 'doublecircle' : 'circle'
+      )
+    end
+    
+    # Generates a nicely formatted description of this state's contents.
+    # 
+    # For example,
+    # 
+    #   state = StateMachine::State.new(machine, :parked, :value => 1, :initial => true)
+    #   state   # => #<StateMachine::State name=:parked value=1 initial=true>
+    def inspect
+      "#<#{self.class} #{%w(name value initial).map {|attr| "#{attr}=#{instance_variable_get("@#{attr}").inspect}"} * ' '}>"
     end
     
     private
-      # Adds a predicate method to the owner class as long as this state's value
-      # is a string/symbol
+      # Adds a predicate method to the owner class so long as a name has
+      # actually been configured for the state
       def add_predicate
-        if value && (value.is_a?(String) || value.is_a?(Symbol))
-          attribute = machine.attribute
-          value = self.value
-          name = "#{value}?"
-          name = "#{machine.namespace}_#{name}" if machine.namespace
-          
-          machine.owner_class.class_eval do
-            # Checks whether the current state is equal to the given value
-            define_method(name) do
-              self.send(attribute) == value
-            end unless method_defined?(name) || private_method_defined?(name)
+        return unless name
+        
+        attribute = machine.attribute
+        qualified_name = name = self.name
+        qualified_name = "#{machine.namespace}_#{name}" if machine.namespace
+        
+        machine.owner_class.class_eval do
+          # Checks whether the current value matches this state
+          define_method("#{qualified_name}?") do
+            self.class.state_machines[attribute].state(name).matches?(send(attribute))
           end
         end
       end

data/lib/state_machine/state_collection.rb

@@ -0,0 +1,38 @@
+require 'state_machine/node_collection'
+
+module StateMachine
+  # Represents a collection of states in a state machine
+  class StateCollection < NodeCollection
+    def initialize #:nodoc:
+      super(:index => [:name, :value])
+    end
+    
+    # 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 (:from, :except_from, :to, :except_to options)
+    # 3. States with behaviors
+    # 4. States referenced via +state+ or +other_states+
+    # 5. States referenced in callbacks
+    # 
+    # This order will determine how the GraphViz visualizations are rendered.
+    def by_priority
+      if first = @nodes.first
+        machine = first.machine
+        order = select {|state| state.initial}.map {|state| state.name}
+        
+        machine.events.each {|event| order += event.known_states}
+        order += select {|state| state.methods.any?}.map {|state| state.name}
+        order += keys(:name) - machine.callbacks.values.flatten.map {|callback| callback.known_states}.flatten
+        order += keys(:name)
+        
+        order.uniq!
+        order.map! {|name| self[name]}
+        order
+      else
+        []
+      end
+    end
+  end
+end

data/lib/state_machine/transition.rb

@@ -4,6 +4,7 @@ module StateMachine
   end
   
   # A transition represents a state change for a specific attribute.
+  # 
   # Transitions consist of:
   # * An event
   # * A starting state
@@ -18,19 +19,27 @@ module StateMachine
     # The event that caused the transition
     attr_reader :event
     
-    # The original state *before* the transition
+    # The original state value *before* the transition
     attr_reader :from
     
-    # The new state *after* the transition
+    # The original state name *before* the transition
+    attr_reader :from_name
+    
+    # The new state value *after* the transition
     attr_reader :to
     
+    # The new state name *after* the transition
+    attr_reader :to_name
+    
     # Creates a new, specific transition
-    def initialize(object, machine, event, from, to) #:nodoc:
+    def initialize(object, machine, event, from_name, to_name) #:nodoc:
       @object = object
       @machine = machine
       @event = event
-      @from = from
-      @to = to
+      @from = object.send(machine.attribute)
+      @from_name = from_name
+      @to = machine.states[to_name].value
+      @to_name = to_name
     end
     
     # Gets the attribute which this transition's machine is defined for
@@ -38,14 +47,14 @@ module StateMachine
       machine.attribute
     end
     
-    # Gets a hash of all the attributes defined for this transition with their
-    # names as keys and values of the attributes as values.
+    # Gets a hash of all the core attributes defined for this transition with
+    # their names as keys and values of the attributes as values.
     # 
     # == Example
     # 
-    #   machine = StateMachine.new(Object, 'state')
-    #   transition = StateMachine::Transition.new(Object.new, machine, 'enable, 'disabled', 'enabled')
-    #   transition.attributes   # => {:object => #<Object:0xb7d60ea4>, :attribute => 'state', :event => 'enable', :from => 'disabled', :to => 'enabled'}
+    #   machine = StateMachine.new(Vehicle)
+    #   transition = StateMachine::Transition.new(Vehicle.new, machine, :ignite, :parked, :idling)
+    #   transition.attributes   # => {:object => #<Vehicle:0xb7d60ea4>, :attribute => :state, :event => :ignite, :from => 'parked', :to => 'idling'}
     def attributes
       @attributes ||= {:object => object, :attribute => attribute, :event => event, :from => from, :to => to}
     end
@@ -63,9 +72,9 @@ module StateMachine
     #   end
     #   
     #   vehicle = Vehicle.new
-    #   transition = StateMachine::Transition.new(vehicle, machine, :turn_on, 'off', 'on')
-    #   transition.perform          # => Runs the +save+ action after updating the state attribute
-    #   transition.perform(false)   # => Only updates the state attribute
+    #   transition = StateMachine::Transition.new(vehicle, machine, :ignite, :parked, :idling)
+    #   transition.perform          # => Runs the +save+ action after setting the state attribute
+    #   transition.perform(false)   # => Only sets the state attribute
     def perform(run_action = true)
       result = false
       
@@ -91,17 +100,27 @@ module StateMachine
       result
     end
     
+    # Generates a nicely formatted description of this transitions's contents.
+    # 
+    # For example,
+    # 
+    #   transition = StateMachine::Transition.new(object, machine, :ignite, :parked, :idling)
+    #   transition   # => #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
+    def inspect
+      "#<#{self.class} #{%w(attribute event from from_name to to_name).map {|attr| "#{attr}=#{send(attr).inspect}"} * ' '}>"
+    end
+    
     protected
       # Gets a hash of the context defining this unique transition (including
       # event, from state, and to state).
       # 
       # == Example
       # 
-      #   machine = StateMachine.new(Object, 'state')
-      #   transition = StateMachine::Transition.new(Object.new, machine, 'enable', 'disabled', 'enabled')
-      #   transition.context    # => {:on => "enable", :from => "disabled", :to => "enabled"}
+      #   machine = StateMachine.new(Vehicle)
+      #   transition = StateMachine::Transition.new(Vehicle.new, machine, :ignite, :parked, :idling)
+      #   transition.context    # => {:on => :ignite, :from => :parked, :to => :idling}
       def context
-        @context ||= {:on => event, :from => from, :to => to}
+        @context ||= {:on => event, :from => from_name, :to => to_name}
       end
       
       # Runs the callbacks of the given type for this transition.  This will