alter-ego 1.0.0

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 2008-11-28
+
+* 1 major enhancement:
+  * Initial release

data/Manifest.txt

@@ -0,0 +1,19 @@
+History.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+State_Design_Pattern_UML_Class_Diagram.png
+Rakefile
+TODO
+lib/assertions.rb
+spec/assertions_spec.rb
+lib/alter_ego.rb
+script/console
+script/destroy
+script/generate
+spec/spec.opts
+spec/spec_helper.rb
+spec/alter_ego_spec.rb
+lib/alter_ego.rb
+spec/alter_ego_spec.rb
+tasks/rspec.rake

data/PostInstall.txt

@@ -0,0 +1,7 @@
+
+For more information on states, see http://alter-ego.rubyforge.org
+
+NOTE: Change this information in PostInstall.txt 
+You can also delete it if you don't want it.
+
+

data/README.rdoc

@@ -0,0 +1,149 @@
+= AlterEgo
+
+* http://alter-ego.rubyforge.org
+
+== DESCRIPTION:
+
+AlterEgo is a Ruby implementation of the State pattern as described by the Gang
+of Four.  It differs from other Ruby state machine libraries in that it focuses
+on providing polymorphic behavior based on object state.  In effect, it makes it
+easy to give an object different personalities depending on the state it is in.
+
+== SYNOPSIS:
+
+  class TrafficLight
+    include AlterEgo
+
+    state :proceed, :default => true do
+      handle :color do
+	"green"
+      end
+      transition :to => :caution, :on => :cycle!
+    end
+
+    state :caution do
+      handle :color do
+	"yellow"
+      end
+      transition :to => :stop, :on => :cycle!
+    end
+
+    state :stop do
+      handle :color do
+	"red"
+      end 
+      transition :to => :proceed, :on => :cycle!
+    end
+  end
+
+  light = TrafficLight.new
+  light.color                     # => "green"
+  light.cycle!
+  light.color                     # => "yellow"
+  light.cycle!
+  light.color                     # => "red"
+  light.cycle!
+  light.color                     # => "green"
+
+
+== FEATURES:
+
+* Implemented as a module which can be included in any Ruby class.
+* Fully tested with literate RSpec
+* Guard clauses may be defined for each transition.
+* Enter/exit actions may be defined for each state.
+* For more advanced scenarios, arbitrary "request filters" may be
+  defined with full control over which requests are filtered.
+* Uses dynamic module generation and delegation instead of method
+  rewriting.
+* Pervasive contract-checking catches mistakes in library usage
+  early.
+* Storing and reading current state is completely customizable,
+  making it easier to add AlterEgo to legacy classes.
+
+== DETAILS:
+
+AlterEgo differs from other Finite State Machine implementations in
+Ruby in that where other libraries focus on describing a set of
+valid state transitions, AlterEgo focuses on varying _behavior_ based
+on state.  In other words, it provides state-based polymorphism.
+
+AlterEgo draws heavily on the State Pattern as published in the book
+Design Patterns[1].  A summary of the pattern can be
+found on Wikipedia[http://en.wikipedia.org/wiki/State_pattern].
+Because AlterEgo uses the terminology set forth in the State Pattern,
+it is useful to have some familiarity with the pattern in order to
+understand the library.
+
+link://State_Design_Pattern_UML_Class_Diagram.png
+
+In the State Pattern, states of an object are represented as
+discrete objects.  At any given time an object with state-based
+behavior has-a state object.  The object with state-based behavior
+delegates certain method calls to its current state.  In this way,
+the implementation of those methods can vary with the state of the
+object.  Or in certain states some methods may not be supported at
+all.
+
+The AlterEgo library provides both an object model for manually
+setting up explicit state classes, and a concise DSL built on top
+of that model which simplifies building classes with state-based
+behavior.
+
+This file only scratches the surface of AlterEgo
+functionality.  For complete tutorial documentation, see the file
+spec/alter_ego_spec.rb.  It contains the annotated specification,
+written in the style of a step-by-step tutorial.
+
+=== Terminology:
+
+[Context] The *context* is the class which should have state-based
+          behavior.  In the example above, the +TrafficLight+ class
+          is the context.
+[State] Each *state* the *context* might exist in is represented by a
+        class,  In the example given above, the available states
+        are +caution+, +stop+, and +proceed+.
+[Request] A *request* refers to a message (method) sent to the
+          *context*.  In the example given above, the supported
+          requests are +color+ and +cycle+.
+[Handler] A *handler* is a method on a *state* which implements a
+          *request* for that state.  For instance, in the example
+          above, when the +TrafficLight+ is in the +caution+ state,
+          the handler for the request +color+ returns "yellow".
+
+=== Footnotes:
+
+1. Gamma, Erich; Richard Helm, Ralph Johnson, John M. Vlissides (1995). Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley, 395. ISBN 0201633612.
+
+== REQUIREMENTS:
+
+* ActiveSupport
+
+== INSTALL:
+
+* sudo gem install alter-ego
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Avdi Grimm
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,31 @@
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/alter_ego'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new('alter-ego', AlterEgo::VERSION) do |p|
+  p.developer('Avdi Grimm', 'avdi@avdi.org')
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.rubyforge_name       = p.name # TODO this is default value
+  p.extra_deps         = [
+    ['activesupport','>= 2.0.2'],
+  ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# task :default => [:spec, :features]
+
+task :docs do |task|
+  cp "State_Design_Pattern_UML_Class_Diagram.png", "doc"
+end

data/TODO

@@ -0,0 +1,10 @@
+* TODO Factor assertions out into separate library
+* TODO Remove ActiveSupport dependency
+* TODO Nested state support with history
+* TODO Verify full methods/respond_to? integration
+* TODO Composite state support
+  E.g. a Traffic Light could have both green/yellow/red state and "in
+  service"/out of service" state at the same time
+* TODO More natural/Rubyish DSL
+  It would be good to have plain-old "def" work as expected inside of "state"
+  blocks instead of requiring "handle".

data/lib/alter_ego.rb

@@ -0,0 +1,381 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require File.join(File.dirname(__FILE__), 'assertions')
+require 'forwardable'
+require 'singleton'
+require 'rubygems'
+require 'activesupport'
+
+module AlterEgo
+  VERSION = '1.0.0'
+
+  include Assertions
+
+  class StateError < RuntimeError
+  end
+  class InvalidDefinitionError < StateError
+  end
+  class InvalidTransitionError < StateError
+  end
+  class InvalidRequestError < StateError
+  end
+  class WrongStateError < StateError
+  end
+
+  RequestFilter = Struct.new("RequestFilter",
+                             :state,
+                             :request,
+                             :new_state,
+                             :action)
+  class RequestFilter
+    def ===(other)
+      result = (matches?(self.state, other.state) and
+                matches?(self.request, other.request) and
+                matches?(self.new_state, other.new_state))
+     result
+    end
+
+    def matches?(lhs, rhs)
+      if rhs.respond_to?(:include?)
+        rhs.include?(lhs)
+      else
+        rhs == lhs
+      end
+    end
+  end
+
+  class AnyMatcher
+    include Singleton
+
+    def ===(other)
+      self == other
+    end
+
+    def ==(other)
+      true
+    end
+  end
+
+  class NotNilMatcher
+    include Singleton
+
+    def ===(other)
+      self == other
+    end
+
+    def ==(other)
+      not other.nil?
+    end
+  end
+
+  class State
+    include Assertions
+    extend Assertions
+
+    def self.transition(options, &trans_action)
+      options.assert_valid_keys(:to, :on, :if)
+      assert_keys(options, :to)
+      guard    = options[:if]
+      to_state = options[:to]
+      request   = options[:on]
+      if request
+        handle(request) do
+          transition_to(to_state, request)
+        end
+      end
+      valid_transitions << to_state unless valid_transitions.include?(to_state)
+      if guard
+        method = guard.kind_of?(Symbol) ? guard : nil
+        block  = guard.kind_of?(Proc) ? guard : nil
+        predicate = AlterEgo.proc_from_symbol_or_block(method, &block)
+        guard_proc = proc do
+          result = instance_eval(&predicate)
+          throw :cancel unless result
+        end
+        add_request_filter(request, to_state, guard_proc)
+      end
+      if trans_action
+        add_request_filter(request, to_state, trans_action)
+      end
+    end
+
+    def self.identifier
+      self
+    end
+
+    def self.valid_transitions
+      (@valid_transitions ||= [])
+    end
+
+    def self.handled_requests
+      public_instance_methods(false)
+    end
+
+    def self.request_filters
+      (@request_filters ||= [])
+    end
+
+    def self.handle(request, method = nil, &block)
+      define_contextual_method_from_symbol_or_block(request, method, &block)
+    end
+
+    def self.on_enter(method = nil, &block)
+      assert(method.nil? ^ block.nil?)
+      define_contextual_method_from_symbol_or_block(:on_enter, method, &block)
+    end
+
+    def self.on_exit(method = nil, &block)
+      assert(method.nil? ^ block.nil?)
+      define_contextual_method_from_symbol_or_block(:on_exit, method, &block)
+    end
+
+    def valid_transitions
+      self.class.valid_transitions
+    end
+
+    def to_s
+      "<State:#{identifier}>"
+    end
+
+    def identifier
+      self.class.identifier
+    end
+
+    def ==(other)
+      (self.identifier == other) or super(other)
+    end
+
+    def can_handle_request?(request)
+      return true if respond_to?(request)
+      return false
+    end
+
+    def transition_to(context, request, new_state, *args)
+      return true if context.state == new_state
+      new_state_obj = context.state_for_identifier(new_state)
+      unless new_state_obj
+        raise(InvalidTransitionError,
+              "Context #{context.inspect} has no state '#{new_state}' defined")
+      end
+
+      continue = context.execute_request_filters(self.class.identifier,
+                                                 request,
+                                                 new_state)
+      return false unless continue
+
+      if (not valid_transitions.empty?) and (not valid_transitions.include?(new_state))
+        raise(InvalidTransitionError,
+              "Not allowed to transition from #{self.identifier} to #{new_state}")
+      end
+
+      on_exit(context)
+      new_state_obj.on_enter(context)
+      context.state=(new_state)
+      assert(new_state == context.state)
+      true
+    end
+
+    protected
+
+    def on_exit(context)
+    end
+
+    def on_enter(context)
+    end
+
+    private
+
+    def self.add_request_filter(request_pattern, new_state_pattern, action)
+      new_filter = RequestFilter.new(identifier,
+                                     request_pattern,
+                                     new_state_pattern,
+                                     action)
+      self.request_filters << new_filter
+    end
+
+    def self.define_contextual_method_from_symbol_or_block(name,
+                                                           symbol,
+                                                           &block)
+      if symbol
+        define_method(name) do |context, *args|
+           context.send(symbol, *args)
+         end
+      elsif block
+        define_method(name) do |context, *args|
+          context.send(:instance_eval, &block)
+        end
+      end
+    end
+end
+
+  module ClassMethods
+    def state(identifier, options={}, &block)
+      if states.has_key?(identifier)
+        raise InvalidDefinitionError, "State #{identifier.inspect} already defined"
+      end
+      new_state = Class.new(State)
+      new_state_eigenclass = class << new_state; self; end
+      new_state_eigenclass.send(:define_method, :identifier) { identifier }
+      new_state.instance_eval(&block) if block
+
+      add_state(new_state, identifier, options)
+    end
+
+    def request_filter(options, &block)
+      options.assert_valid_keys(:state, :request, :new_state, :action)
+      options = {
+        :state     => not_nil,
+        :request   => not_nil,
+        :new_state => nil
+      }.merge(options)
+      add_request_filter(options[:state],
+                         options[:request],
+                         options[:new_state],
+                         AlterEgo.proc_from_symbol_or_block(options[:method], &block))
+    end
+
+    def all_handled_requests
+      methods = @state_proxy.public_instance_methods(false)
+      methods -= ["identifier", "on_enter", "on_exit"]
+      methods.map{|m| m.to_sym}
+    end
+
+    def states
+      (@states ||= {})
+    end
+
+    def states=(value)
+      @states = value
+    end
+
+    def add_state(new_state, identifier=new_state.identifier, options = {})
+      options.assert_valid_keys(:default)
+
+      self.states[identifier] = new_state.new
+
+      if options[:default]
+        if @default_state
+          raise InvalidDefinitionError, "Cannot have more than one default state"
+        end
+        @default_state = identifier
+      end
+
+      new_requests = (new_state.handled_requests - all_handled_requests)
+      new_requests.each do |request|
+        @state_proxy.send(:define_method, request) do |*args|
+          args.unshift(self)
+          begin
+            continue = execute_request_filters(current_state.identifier,
+                                               request,
+                                               nil)
+            return false unless continue
+            current_state.send(request, *args)
+          rescue NoMethodError => error
+            if error.name.to_s == request.to_s
+              raise WrongStateError,
+                    "Request '#{request}' not supported by state #{current_state}"
+            else
+              raise
+            end
+          end
+        end
+      end
+
+      self.request_filters += new_state.request_filters
+    end
+
+    def add_request_filter(state_pattern, request_pattern, new_state_pattern, action)
+      @request_filters << RequestFilter.new(state_pattern,
+                                            request_pattern,
+                                            new_state_pattern,
+                                            action)
+    end
+
+    def default_state
+      @default_state
+    end
+
+    def request_filters
+      (@request_filters ||= [])
+    end
+
+    protected
+
+    def request_filters=(value)
+      @request_filters = value
+    end
+
+    def any
+      AlterEgo::AnyMatcher.instance
+    end
+
+    def not_nil
+      AlterEgo::NotNilMatcher.instance
+    end
+
+  end
+
+  def self.append_features(klass)
+    # Give the other module my instance methods at the class level
+    klass.extend(ClassMethods)
+    klass.extend(Forwardable)
+
+    state_proxy = Module.new
+    klass.instance_variable_set :@state_proxy, state_proxy
+    klass.send(:include, state_proxy)
+
+    super(klass)
+  end
+
+  def current_state
+    state_id = self.state
+    state_id ? self.class.states[state_id] : nil
+  end
+
+  def state
+    result = (@state || self.class.default_state)
+    assert(result.nil? || self.class.states.keys.include?(result))
+    result
+  end
+
+  def state=(identifier)
+    @state = identifier
+  end
+
+  def state_for_identifier(identifier)
+    self.class.states[identifier]
+  end
+
+  def transition_to(new_state, request=nil, *args)
+    current_state.transition_to(self, request, new_state, *args)
+  end
+
+  def all_handled_requests
+    self.class.all_handled_requests
+  end
+
+  def execute_request_filters(state, request, new_state)
+    pattern = RequestFilter.new(state, request, new_state)
+    self.class.request_filters.grep(pattern) do |filter|
+      result = catch(:cancel) do
+        self.instance_eval(&filter.action)
+        true
+      end
+      return false unless result
+    end
+    true
+  end
+
+  def self.proc_from_symbol_or_block(symbol = nil, &block)
+    if symbol then
+      proc do
+        self.send(symbol)
+      end
+    elsif block then
+      block
+    else raise "Should never get here"
+    end
+  end
+
+end