enum_state_machine 0.0.1 → 0.0.2

data/lib/enum_state_machine/matcher.rb

@@ -1,123 +0,0 @@
-require 'singleton'
-
-module EnumStateMachine
-  # 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 = EnumStateMachine::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 = EnumStateMachine::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 = EnumStateMachine::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 = EnumStateMachine::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/enum_state_machine/matcher_helpers.rb

@@ -1,54 +0,0 @@
-module EnumStateMachine
-  # 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/enum_state_machine/node_collection.rb

@@ -1,222 +0,0 @@
-require 'enum_state_machine/assertions'
-
-module EnumStateMachine
-  # 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
-    include Assertions
-    
-    # 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 = {})
-      assert_valid_keys(options, :index)
-      options = {:index => :name}.merge(options)
-      
-      @machine = machine
-      @nodes = []
-      @index_names = Array(options[:index])
-      @indices = @index_names.inject({}) 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.inject({}) {|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 = EnumStateMachine::NodeCollection.new
-    #   states << EnumStateMachine::State.new(machine, :parked)
-    #   states << EnumStateMachine::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 = EnumStateMachine::NodeCollection.new
-    #   states << EnumStateMachine::State.new(machine, :parked)
-    #   states << EnumStateMachine::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)
-      self.index(index_name)[key] ||
-      self.index(:"#{index_name}_to_s")[key.to_s] ||
-      to_sym?(key) && self.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] || raise(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)
-        raise ArgumentError, 'No indices configured' unless @indices.any?
-        @indices[name] || raise(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 = RUBY_VERSION < '1.9' ? index.index(node) : 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/enum_state_machine/path.rb

@@ -1,120 +0,0 @@
-module EnumStateMachine
-  # 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