state_machines 0.0.1

data/lib/state_machines/matcher.rb

@@ -0,0 +1,123 @@
+require 'singleton'
+
+module StateMachines
+  # 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 = StateMachines::AllMatcher.instance - [: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 = StateMachines::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 = StateMachines::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 = StateMachines::LoopbackMatcher.instance
+    #   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

data/lib/state_machines/matcher_helpers.rb

@@ -0,0 +1,54 @@
+module StateMachines
+  # Provides a set of helper methods for generating matchers
+  module MatcherHelpers
+    # Represents a state that matches all known states in a machine.
+    # 
+    # == Examples
+    # 
+    #   class Vehicle
+    #     state_machine do
+    #       before_transition any => :parked, :do => lambda {...}
+    #       before_transition all - :parked => all - :idling, :do => lambda {}
+    #       
+    #       event :park
+    #         transition all => :parked
+    #       end
+    #       
+    #       event :crash
+    #         transition all - :parked => :stalled
+    #       end
+    #     end
+    #   end
+    # 
+    # In the above example, +all+ will match the following states since they
+    # are known:
+    # * +parked+
+    # * +stalled+
+    # * +idling+
+    def all
+      AllMatcher.instance
+    end
+    alias_method :any, :all
+    
+    # Represents a state that matches the original +from+ state.  This is useful
+    # for defining transitions which are loopbacks.
+    # 
+    # == Examples
+    # 
+    #   class Vehicle
+    #     state_machine do
+    #       event :ignite
+    #         transition [:idling, :first_gear] => same
+    #       end
+    #     end
+    #   end
+    # 
+    # In the above example, +same+ will match whichever the from state is.  In
+    # the case of the +ignite+ event, it is essential the same as the following:
+    # 
+    #   transition :parked => :parked, :first_gear => :first_gear
+    def same
+      LoopbackMatcher.instance
+    end
+  end
+end

data/lib/state_machines/node_collection.rb

@@ -0,0 +1,221 @@
+require 'state_machines/assertions'
+
+module StateMachines
+  # Represents a collection of nodes in a state machine, be it events or states.
+  # Nodes will not differentiate between the String and Symbol versions of the
+  # values being indexed.
+  class NodeCollection
+    include Enumerable
+
+    # The machine associated with the nodes
+    attr_reader :machine
+
+    # 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(machine, options = {})
+      options.assert_valid_keys(:index)
+      options = { index: :name }.merge(options)
+
+      @machine = machine
+      @nodes = []
+      @index_names = Array(options[:index])
+      @indices = @index_names.reduce({}) do |indices, name|
+        indices[name] = {}
+        indices[:"#{name}_to_s"] = {}
+        indices[:"#{name}_to_sym"] = {}
+        indices
+      end
+      @default_index = Array(options[:index]).first
+      @contexts = []
+    end
+
+    # Creates a copy of this collection such that modifications don't affect
+    # the original collection
+    def initialize_copy(orig) #:nodoc:
+      super
+
+      nodes = @nodes
+      contexts = @contexts
+      @nodes = []
+      @contexts = []
+      @indices = @indices.reduce({}) { |indices, (name, *)| indices[name] = {}; indices }
+
+      # Add nodes *prior* to copying over the contexts so that they don't get
+      # evaluated multiple times
+      concat(nodes.map { |n| n.dup })
+      @contexts = contexts.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)
+      @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
+
+    # Tracks a context that should be evaluated for any nodes that get added
+    # which match the given set of nodes.  Matchers can be used so that the
+    # context can get added once and evaluated after multiple adds.
+    def context(nodes, &block)
+      nodes = nodes.first.is_a?(Matcher) ? nodes.first : WhitelistMatcher.new(nodes)
+      @contexts << context = { nodes: nodes, block: block }
+
+      # Evaluate the new context for existing nodes
+      each { |node| eval_context(context, node) }
+
+      context
+    end
+
+    # Adds a new node to the collection.  By doing so, this will also add it to
+    # the configured indices.  This will also evaluate any existings contexts
+    # that match the new node.
+    def <<(node)
+      @nodes << node
+      @index_names.each { |name| add_to_index(name, value(node, name), node) }
+      @contexts.each { |context| eval_context(context, node) }
+      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.
+    def update(node)
+      @index_names.each { |name| update_index(name, node) }
+    end
+
+    # Calls the block once for each element in self, passing that element as a
+    # parameter.
+    #
+    #   states = StateMachines::NodeCollection.new
+    #   states << StateMachines::State.new(machine, :parked)
+    #   states << StateMachines::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 = StateMachines::NodeCollection.new
+    #   states << StateMachines::State.new(machine, :parked)
+    #   states << StateMachines::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] ||
+      index(:"#{index_name}_to_s")[key.to_s] ||
+      to_sym?(key) && index(:"#{index_name}_to_sym")[:"#{key}"] ||
+      nil
+    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] || fail(IndexError, "#{key.inspect} is an invalid #{index_name}")
+    end
+
+    protected
+      # Gets the given index.  If the index does not exist, then an ArgumentError
+      # is raised.
+    def index(name)
+      fail ArgumentError, 'No indices configured' unless @indices.any?
+      @indices[name] || fail(ArgumentError, "Invalid index: #{name.inspect}")
+    end
+
+      # Gets the value for the given attribute on the node
+    def value(node, attribute)
+      node.send(attribute)
+    end
+
+      # Adds the given key / node combination to an index, including the string
+      # and symbol versions of the index
+    def add_to_index(name, key, node)
+      index(name)[key] = node
+      index(:"#{name}_to_s")[key.to_s] = node
+      index(:"#{name}_to_sym")[:"#{key}"] = node if to_sym?(key)
+    end
+
+      # Removes the given key from an index, including the string and symbol
+      # versions of the index
+    def remove_from_index(name, key)
+      index(name).delete(key)
+      index(:"#{name}_to_s").delete(key.to_s)
+      index(:"#{name}_to_sym").delete(:"#{key}") if to_sym?(key)
+    end
+
+      # Updates the node for the given index, including the string and symbol
+      # versions of the index
+    def update_index(name, node)
+      index = self.index(name)
+      old_key = index.key(node)
+      new_key = value(node, name)
+
+      # Only replace the key if it's changed
+      if old_key != new_key
+        remove_from_index(name, old_key)
+        add_to_index(name, new_key, node)
+      end
+    end
+
+      # Determines whether the given value can be converted to a symbol
+    def to_sym?(value)
+      "#{value}" != ''
+    end
+
+      # Evaluates the given context for a particular node.  This will only
+      # evaluate the context if the node matches.
+    def eval_context(context, node)
+      node.context(&context[:block]) if context[:nodes].matches?(node.name)
+    end
+  end
+end

data/lib/state_machines/path.rb

@@ -0,0 +1,120 @@
+module StateMachines
+  # 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
+
+    
+    # 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 = {})
+      options.assert_valid_keys(: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_machines/path_collection.rb

@@ -0,0 +1,90 @@
+require 'state_machines/path'
+
+module StateMachines
+  # 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
+
+    
+    # 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)
+      options.assert_valid_keys( :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