verborghs-state_machine 0.9.4

data/lib/state_machine/machine_collection.rb

@@ -0,0 +1,64 @@
+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)
+    def initialize_states(object, options = {})
+      if ignore = options[:ignore]
+        ignore = ignore.map {|attribute| attribute.to_sym}
+      end
+      
+      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
+    end
+    
+    # Runs one or more events in parallel on the given object.  See
+    # StateMachine::InstanceMethods#fire_events for more information.
+    def fire_events(object, *events)
+      run_action = [true, false].include?(events.last) ? events.pop : true
+      
+      # Generate the transitions to run for each event
+      transitions = events.collect do |event_name|
+        # Find the actual event being run
+        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
+        
+        # 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]])
+        end
+        
+        transition
+      end.compact
+      
+      # Run the events in parallel only if valid transitions were found for
+      # all of them
+      if events.length == transitions.length
+        TransitionCollection.new(transitions, :actions => run_action).perform
+      else
+        false
+      end
+    end
+    
+    # Builds the collection of transitions for all event attributes defined on
+    # the given object.  This will only include events whose machine actions
+    # match the one specified.
+    # 
+    # These should only be fired as a result of the action being run.
+    def transitions(object, action, options = {})
+      transitions = map do |name, machine|
+        machine.events.attribute_transition_for(object, true) if machine.action == action
+      end
+      
+      AttributeTransitionCollection.new(transitions.compact, options)
+    end
+  end
+end

data/lib/state_machine/matcher.rb

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

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

@@ -0,0 +1,152 @@
+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
+    
+    # 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 = []
+      @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)
+      @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[value(node, 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 = RUBY_VERSION < '1.9' ? index.index(node) : index.key(node)
+        new_key = value(node, 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
+    # parameter.
+    # 
+    #   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(IndexError, "#{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
+      
+      # Gets the value for the given attribute on the node
+      def value(node, attribute)
+        node.send(attribute)
+      end
+  end
+end

data/lib/state_machine/state.rb

@@ -0,0 +1,260 @@
+require 'state_machine/assertions'
+require 'state_machine/condition_proxy'
+
+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 (and default) type is String.
+  # 
+  # 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
+    
+    # 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 fully-qualified identifier for the state, scoped by the machine's
+    # namespace
+    attr_reader :qualified_name
+    
+    # The human-readable name for the state
+    attr_writer :human_name
+    
+    # The value that is written to a machine's attribute when an object
+    # transitions into this state
+    attr_writer :value
+    
+    # Whether this state's value should be cached after being evaluated
+    attr_accessor :cache
+    
+    # Whether or not this state is the initial state to use for new objects
+    attr_accessor :initial
+    alias_method :initial?, :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
+    attr_reader :methods
+    
+    # Creates a new state within the context of the given machine.
+    # 
+    # Configuration options:
+    # * <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>:cache</tt> - If a dynamic value (via a lambda block) is being used,
+    #   then setting this to true will cache the evaluated result
+    # * <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.
+    # * <tt>:human_name</tt> - The human-readable version of this state's name
+    def initialize(machine, name, options = {}) #:nodoc:
+      assert_valid_keys(options, :initial, :value, :cache, :if, :human_name)
+      
+      @machine = machine
+      @name = name
+      @qualified_name = name && machine.namespace ? :"#{machine.namespace}_#{name}" : name
+      @human_name = options[:human_name] || (@name ? @name.to_s.tr('_', ' ') : 'nil')
+      @value = options.include?(:value) ? options[:value] : name && name.to_s
+      @cache = options[:cache]
+      @matcher = options[:if]
+      @methods = {}
+      @initial = options[:initial] == true
+      
+      add_predicate
+    end
+    
+    # Creates a copy of this state in addition to the list of associated
+    # methods to prevent conflicts across different states.
+    def initialize_copy(orig) #:nodoc:
+      super
+      @methods = methods.dup
+    end
+    
+    # Determines whether there are any states that can be transitioned to from
+    # this state.  If there are none, then this state is considered *final*.
+    # Any objects in a final state will remain so forever given the current
+    # machine's definition.
+    def final?
+      !machine.events.any? do |event|
+        event.guards.any? do |guard|
+          guard.state_requirements.any? do |requirement|
+            requirement[:from].matches?(name) && !requirement[:to].matches?(name, :from => name)
+          end
+        end
+      end
+    end
+    
+    # Transforms the state name into a more human-readable format, such as
+    # "first gear" instead of "first_gear"
+    def human_name(klass = @machine.owner_class)
+      @human_name.is_a?(Proc) ? @human_name.call(self, klass) : @human_name
+    end
+    
+    # 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.  This will optionally evaluate the
+    # original block if it's a lambda block.  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
+    #   State.new(machine, :parked, :value => lambda {Time.now}).value(false) # => <Proc:0xb6ea7ca0@...>
+    def value(eval = true)
+      if @value.is_a?(Proc) && eval
+        if cache_value?
+          @value = @value.call
+          machine.states.update(self)
+          @value
+        else
+          @value.call
+        end
+      else
+        @value
+      end
+    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 owner class when the machine is in this state.
+    # 
+    # 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)
+      owner_class = machine.owner_class
+      machine_name = machine.name
+      name = self.name
+      
+      # Evaluate the method definitions
+      context = ConditionProxy.new(owner_class, lambda {|object| object.class.state_machine(machine_name).states.matches?(object, name)})
+      context.class_eval(&block)
+      context.instance_methods.each do |method|
+        methods[method.to_sym] = context.instance_method(method)
+        
+        # Calls the method defined by the current state of the machine
+        context.class_eval <<-end_eval, __FILE__, __LINE__
+          def #{method}(*args, &block)
+            self.class.state_machine(#{machine_name.inspect}).states.match!(self).call(self, #{method.inspect}, lambda {super}, *args, &block)
+          end
+        end_eval
+      end
+      
+      # Include the context so that it can be bound to the owner class (the
+      # context is considered an ancestor, so it's allowed to be bound)
+      owner_class.class_eval { include context }
+      
+      context
+    end
+    
+    # Calls a method defined in this state's context on the given object.  All
+    # arguments and any block will be passed into the method defined.
+    # 
+    # If the method has never been defined for this state, then a NoMethodError
+    # will be raised.
+    def call(object, method, method_missing = nil, *args, &block)
+      if context_method = methods[method.to_sym]
+        # Method is defined by the state: proxy it through
+        context_method.bind(object).call(*args, &block)
+      else
+        # Dispatch to the superclass since this state doesn't handle the method
+        method_missing.call if method_missing
+      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+ - The human-friendly description of the state.
+    # * +width+ - The width of the node.  Always 1.
+    # * +height+ - The height of the node.  Always 1.
+    # * +shape+ - The actual shape of the node.  If the state is a final
+    #   state, then "doublecircle", otherwise "ellipse".
+    # 
+    # The actual node generated on the graph will be returned.
+    def draw(graph)
+      node = graph.add_node(name ? name.to_s : 'nil',
+        :label => description,
+        :width => '1',
+        :height => '1',
+        :shape => final? ? 'doublecircle' : 'ellipse'
+      )
+      
+      # Add open arrow for initial state
+      graph.add_edge(graph.add_node('starting_state', :shape => 'point'), node) if initial?
+      
+      node
+    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 context=[]>
+    def inspect
+      attributes = [[:name, name], [:value, @value], [:initial, initial?], [:context, methods.keys]]
+      "#<#{self.class} #{attributes.map {|attr, value| "#{attr}=#{value.inspect}"} * ' '}>"
+    end
+    
+    private
+      # Should the value be cached after it's evaluated for the first time?
+      def cache_value?
+        @cache
+      end
+      
+      # Adds a predicate method to the owner class so long as a name has
+      # actually been configured for the state
+      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)
+        end
+      end
+  end
+end