state_pattern 1.1.0 → 1.2.0

data/README.rdoc

@@ -2,40 +2,69 @@
 
 A Ruby state pattern implementation.
 
+== Example
+
+Let's use one nice example from the AASM documentation and translate it to state_pattern (but keep in mind state_pattern is a generic gem, AASM is a Rails plugin):
+
   require 'rubygems'
   require 'state_pattern'
 
-  class On < StatePattern::State
-    def press
-      transition_to(Off)
-      "#{stateable.button_name} is off"
+  class Dating < StatePattern::State
+    def get_intimate
+      transition_to(Intimate) if stateable.drunk?
+    end
+
+    def get_married
+      transition_to(Married) if stateable.willing_to_give_up_manhood?
+    end
+
+    def enter
+      stateable.make_happy
+    end
+
+    def exit
+      stateable.make_depressed
     end
   end
-  
-  class Off < StatePattern::State
-    def press
-      transition_to(On)
-      "#{stateable.button_name} is on"
+
+  class Intimate < StatePattern::State
+    def get_married
+      transition_to(Married) if stateable.willing_to_give_up_manhood?
+    end
+
+    def enter
+      stateable.make_very_happy
+    end
+
+    def exit
+      stateable.never_speak_again
     end
   end
-  
-  class Button
-    include StatePattern
-    set_initial_state Off
-    valid_transitions [On, :press] => Off, [Off, :press] => On
-  
-    def button_name
-      "Light button"
+
+  class Married < StatePattern::State
+    def enter
+      stateable.give_up_intimacy
+    end
+
+    def exit
+      stateable.buy_exotic_car_and_wear_a_combover
     end
   end
 
-  button = Button.new
-  puts button.press # => "Light button is on"
-  puts button.press # => "Light button is off"
-  puts button.press # => "Light button is on"
+  class Relationship
+    include StatePattern
+    set_initial_state Dating
+    valid_transitions [Dating, :get_intimate] => Intimate, [Dating, :get_married] => Married, [Intimate, :get_married] => Married
 
-== Installation
-  sudo gem install state_pattern
+    def drunk?; @drunk; end
+    def willing_to_give_up_manhood?; @give_up_manhood; end
+    def make_happy; end
+    def make_depressed; end
+    def make_very_happy; end
+    def never_speak_again; end
+    def give_up_intimacy; end
+    def buy_exotic_car_and_wear_a_combover; end
+  end
 
 == Validations
 
@@ -53,6 +82,21 @@ With more than one target state
 Using event names to gain more detail
   valid_transitions [Up, :switch] => [Middle, Down], [Down, :switch] => Middle, [Middle, :switch] => Up 
 
+== Enter and exit hooks
+
+Inside your state classes, any code that you put inside the enter method will be executed when the state is instantiated.
+You can also use the exit hook which is triggered when a successfull transition to another state takes place.
+
+== Querying
+
+The state pattern is a very dynamic way of representing a state machine, very few things are hard-coded and everything can change on runtime.
+This means that the only way (apart from parsing ruby code) to get a list of the state classes and events that are used, is inspecting the valid_transitions array.
+So assuming that you completely draw your state machine with valid_transitions (which is always recommended) you can use the class methods state_classes and state_events to get a list of states and events respectively.
+
+== Installation
+
+  sudo gem install state_pattern
+
 == Collaborate
 
 http://github.com/dcadenas/state_pattern

data/VERSION

@@ -1 +1 @@
-1.1.0
+1.2.0

data/lib/state_pattern.rb

@@ -7,87 +7,104 @@ module StatePattern
   end
 
   module ClassMethods
-    def state_classes
-      state_classes_in_transisions_hash = []
-
-      if transitions_hash
-        state_classes_in_transisions_hash = transitions_hash.map do |from, to|
-          from_class = from.respond_to?(:to_ary) ? from.first : from
-          to_classes = to.respond_to?(:to_ary) ? to : [to]
-          to_classes + [from_class]
-        end.flatten
-      end
-
-      state_classes_in_transisions_hash << initial_state_class
-      state_classes_in_transisions_hash.uniq
-    end
-
     def initial_state_class
       @initial_state_class
     end
 
     def set_initial_state(state_class)
       @initial_state_class = state_class
+      create_methods
+    end
+
+    def state_methods
+      state_classes_with_their_bases = state_classes.map{|c| c.ancestors.select{|a| a.ancestors.include?(StatePattern::State) && a != StatePattern::State}}.flatten.uniq
+      (state_classes_with_their_bases.map{|state_class| state_class.public_instance_methods(false)}.flatten.uniq - ["enter", "exit"]).map{|s| s.to_sym}
+    end
+
+    def state_events
+      transitions_hash.to_a.flatten.uniq.select{|t| t.respond_to?(:to_sym)}.map{|s| s.to_sym}
+    end
+
+    def state_classes
+      (transitions_hash.to_a << initial_state_class).flatten.uniq.select{|t| t.respond_to?(:ancestors) && t.ancestors.include?(StatePattern::State)}
     end
 
     def valid_transitions(transitions_hash)
       @transitions_hash = transitions_hash
       @transitions_hash.each do |key, value|
-        if !value.respond_to?(:to_ary)
-          @transitions_hash[key] = [value]
-        end
+        @transitions_hash[key] = [value] if !value.respond_to?(:to_ary)
       end
+      create_methods
     end
 
     def transitions_hash
       @transitions_hash
     end
 
-    def delegate_all_state_events
+  private
+    def create_methods
+      delegate_all_state_methods
+      create_query_methods
+    end
+
+    def delegate_all_state_methods
       state_methods.each do |state_method|
         define_method state_method do |*args|
-          delegate_to_event(state_method)
-        end
+          delegate_to_state(state_method, *args)
+        end unless respond_to?(state_method)
       end
     end
 
-    def state_methods
-      state_classes.map{|state_class| state_class.public_instance_methods(false)}.flatten.uniq
+    def create_query_methods
+      state_classes.each do |state_class|
+        method_name = "#{underscore(state_class.name.split("::").last)}?"
+        define_method method_name do
+          current_state_instance.class == state_class
+        end unless respond_to?(method_name)
+      end
     end
-  end
 
-  attr_accessor :current_state, :current_event
-  def initialize(*args)
-    super(*args)
-    set_state(self.class.initial_state_class)
-    self.class.delegate_all_state_events
+    def underscore(camel_cased_word)
+      camel_cased_word.to_s.gsub(/\W/, "_")
+      camel_cased_word.to_s.gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").
+      downcase
+    end
   end
 
-  def set_state(state_class)
-    self.current_state = state_class.new(self)
+  def set_state(state_class = nil)
+    state_class ||= self.class.initial_state_class
+    return @current_state_instance if @current_state_instance.class == state_class
+    @current_state_instance = state_class.new(self, @current_state_instance)
   end
-
-  def delegate_to_event(method_name, *args)
-    self.current_event = method_name.to_sym
-    self.current_state.send(current_event, *args)
+    
+  def current_state_instance
+    set_state if @current_state_instance.nil?
+    @current_state_instance
   end
 
-  def transition_to(state_class)
-    raise InvalidTransitionException.new(self.current_state.class, state_class, self.current_event) unless self.valid_transition?(self.current_state.class, state_class)
-    set_state(state_class)
+  def delegate_to_state(state_method_name, *args, &block)
+    @current_method = state_method_name.to_sym
+    self.current_state_instance.send(@current_method, *args, &block)
   end
 
-  def valid_transition?(from_module, to_module)
-    trans = self.class.transitions_hash
-    return true if trans.nil?
-
-    valid_transition_targets = trans[from_module] || trans[[from_module, current_event]]
-    valid_transition_targets && valid_transition_targets.include?(to_module)
+  def transition_to(next_state_class)
+    raise_invalid_transition_to(next_state_class) unless valid_transition?(current_state_instance.class, next_state_class)
+    current_state_instance.exit
+    set_state(next_state_class)
   end
 
-  def state
-    self.current_state.state
+  def raise_invalid_transition_to(state_class)
+    raise InvalidTransitionException.new(current_state_instance.class, state_class, @current_method)
   end
-end
 
+  def valid_transition?(from_state, to_state)
+    transitions = self.class.transitions_hash
+    return true if transitions.nil?
 
+    valid_transition_targets = transitions[from_state] || transitions[[from_state, @current_method]]
+    valid_transition_targets && valid_transition_targets.include?(to_state)
+  end
+end

data/lib/state_pattern/state.rb

@@ -1,16 +1,20 @@
 module StatePattern
   class State
-    attr_reader :stateable
-    def initialize(stateable)
+    attr_reader :stateable, :previous_state
+    def initialize(stateable, previous_state)
       @stateable = stateable
+      @previous_state = previous_state
+      enter
     end
 
     def transition_to(state_class)
       @stateable.transition_to(state_class)
     end
 
-    def state
-      self.class.to_s
+    def enter
+    end
+
+    def exit
     end
   end
 end

data/state_pattern.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{state_pattern}
-  s.version = "1.1.0"
+  s.version = "1.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Daniel Cadenas"]
-  s.date = %q{2009-06-08}
+  s.date = %q{2009-10-12}
   s.email = %q{dcadenas@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE",
@@ -23,6 +23,9 @@ Gem::Specification.new do |s|
      "lib/state_pattern/invalid_transition_exception.rb",
      "lib/state_pattern/state.rb",
      "state_pattern.gemspec",
+     "test/arguments_of_event_delegation_test.rb",
+     "test/hook_test.rb",
+     "test/querying_test.rb",
      "test/state_pattern_test.rb",
      "test/test_class_creation_helper.rb",
      "test/test_helper.rb",
@@ -35,7 +38,10 @@ Gem::Specification.new do |s|
   s.rubygems_version = %q{1.3.3}
   s.summary = %q{A Ruby state pattern implementation}
   s.test_files = [
-    "test/state_pattern_test.rb",
+    "test/arguments_of_event_delegation_test.rb",
+     "test/hook_test.rb",
+     "test/querying_test.rb",
+     "test/state_pattern_test.rb",
      "test/test_class_creation_helper.rb",
      "test/test_helper.rb",
      "test/transition_validations_test.rb"

data/test/arguments_of_event_delegation_test.rb

@@ -0,0 +1,44 @@
+require 'test_helper'
+
+class SampleClass
+  def event(arg1, arg2)
+    block_value = block_given? ? yield : nil
+    [arg1, arg2, block_value].compact.join(", ")
+  end
+end
+
+class SampleState < StatePattern::State
+  def event(arg1, arg2)
+    block_value = block_given? ? yield : nil
+    "state event args == " + [arg1, arg2, block_value].compact.join(", ")
+  end
+end
+
+class SampleClassWithStatePattern < SampleClass
+  include StatePattern
+  set_initial_state SampleState
+end
+
+Expectations do
+  expect "arg1, arg2" do
+    sample_class_instance = ::SampleClass.new
+    sample_class_instance.event("arg1", "arg2")
+  end
+
+  expect "state event args == arg1, arg2" do
+    sample_class_instance = ::SampleClassWithStatePattern.new
+    sample_class_instance.event("arg1", "arg2")
+  end
+
+=begin
+  PENDING
+  Currently using class_eval to define the delegation method (so we can pass a block)
+  is causing a segmention fault on 1.8.6 so we only use define_method to do the delegation
+  if you want to pass a block do so as a normal variable, do use yield
+
+  expect "state event args == arg1, arg2, arg3" do
+    sample_class_instance = ::SampleClassWithStatePattern.new
+    sample_class_instance.event("arg1", "arg2"){"arg3"}
+  end
+=end
+end

data/test/hook_test.rb

@@ -0,0 +1,83 @@
+require 'test_helper'
+
+module Hooks
+  class On < StatePattern::State
+    def press
+      transition_to(Off)
+      stateable.messages << "#{stateable.button_name} is off"
+    end
+
+    def enter
+      stateable.messages << "Entered the On state"
+    end
+
+    def exit
+      stateable.messages << "Exited the On state"
+    end
+
+  private 
+    def private_method
+    end
+  end
+
+  class Off < StatePattern::State
+    def press
+      transition_to(On)
+      stateable.messages << "#{stateable.button_name} is on"
+    end
+
+    def enter
+      stateable.messages << "Entered the Off state"
+    end
+
+    def exit
+      stateable.messages << "Exited the Off state"
+    end
+  end
+
+  class Button
+    include StatePattern
+    set_initial_state Off
+    valid_transitions [On, :press] => Off, [Off, :press] => On
+
+    def button_name
+      "Button"
+    end
+
+    def messages
+      @messages ||= []
+    end
+  end
+end
+
+Expectations do
+  expect ["Entered the Off state", "Exited the Off state", "Entered the On state", "Button is on"] do
+    button = Hooks::Button.new
+    button.press
+    button.messages
+  end
+
+  expect ["Entered the Off state", "Exited the Off state", "Entered the On state", "Button is on", "Exited the On state", "Entered the Off state", "Button is off"] do
+    button = Hooks::Button.new
+    button.press
+    button.press
+    button.messages
+  end
+
+  expect false do
+    Hooks::Button.new.respond_to?(:enter)
+  end
+
+  expect false do
+    Hooks::Button.new.respond_to?(:exit)
+  end
+
+  expect false do
+    Hooks::Button.new.respond_to?(:private_method)
+  end
+
+  expect true do
+    Hooks::Button.new.respond_to?(:press)
+  end
+end
+

data/test/querying_test.rb

@@ -0,0 +1,87 @@
+require 'test_helper'
+
+module Querying
+  class StateBaseBase < StatePattern::State
+    def common_event
+    end
+  end
+
+  class StateBase < StateBaseBase
+    def another_common_event
+    end
+  end
+
+  class On < StateBase
+    def press
+      transition_to(Off)
+    end
+
+    def one_event
+    end
+
+    def another_event
+    end
+
+    def enter
+    end
+
+    def exit
+    end
+  private
+    def not_an_event
+    end
+  end
+
+  class Off < StateBase
+    def press
+      transition_to(On)
+    end
+
+    def one_event
+    end
+
+    def another_event
+    end
+  end
+
+  class Button
+    include StatePattern
+    set_initial_state On
+    valid_transitions [On, :press] => Off, [Off, :press] => On
+  end
+end
+
+Expectations do
+  expect %w(Querying::Off Querying::On) do
+    Querying::Button.state_classes.map{|c| c.name}.sort
+  end
+
+  expect ["another_common_event", "another_event", "common_event", "one_event", "press"] do
+    Querying::Button.state_methods.map{|s| s.to_s}.sort
+  end
+
+  expect [:press] do
+    Querying::Button.state_events
+  end
+
+  expect true do
+    Querying::Button.new.on?
+  end
+
+  expect false do
+    Querying::Button.new.off?
+  end
+
+  expect false do
+    button = Querying::Button.new
+    button.press
+    button.on?
+  end
+
+  expect true do
+    button = Querying::Button.new
+    button.press
+    button.off?
+  end
+end
+

data/test/state_pattern_test.rb

@@ -6,6 +6,9 @@ module Family
       transition_to(Lynn)
       "James #{stateable.last_name}"
     end
+
+    def james_method
+    end
   end
 
   class Lynn < StatePattern::State
@@ -22,7 +25,7 @@ module Family
 
     #notice this method is optional, it will be delegated automatically if removed
     def name
-      delegate_to_event :name
+      delegate_to_state :name
     end
 
     def last_name
@@ -50,6 +53,10 @@ Expectations do
     member.name 
   end
 
+  expect true do
+    Family::Member.new.respond_to?(:james_method)
+  end
+
   expect "on" do
     with_test_class("Button", :states => ["On", "Off"], :initial_state => "Off",
                     :transitions => {["On", :press] => "Off", ["Off", :press] => "On"}) do

data/test/test_class_creation_helper.rb

@@ -39,7 +39,7 @@ module TestClassCreationHelper
     begin
       yield
     ensure 
-      created_consts.each do |created_const|
+      created_consts.compact.each do |created_const|
         Object.send(:remove_const, created_const.to_s.to_sym)
       end
     end

data/test/test_helper.rb

@@ -8,6 +8,3 @@ require 'test_class_creation_helper'
 
 include TestClassCreationHelper
 
-class Test::Unit::TestCase
-end
-

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: state_pattern
 version: !ruby/object:Gem::Version 
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors: 
 - Daniel Cadenas
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-08 00:00:00 -03:00
+date: 2009-10-12 00:00:00 -02:00
 default_executable: 
 dependencies: []
 
@@ -33,6 +33,9 @@ files:
 - lib/state_pattern/invalid_transition_exception.rb
 - lib/state_pattern/state.rb
 - state_pattern.gemspec
+- test/arguments_of_event_delegation_test.rb
+- test/hook_test.rb
+- test/querying_test.rb
 - test/state_pattern_test.rb
 - test/test_class_creation_helper.rb
 - test/test_helper.rb
@@ -66,6 +69,9 @@ signing_key:
 specification_version: 3
 summary: A Ruby state pattern implementation
 test_files: 
+- test/arguments_of_event_delegation_test.rb
+- test/hook_test.rb
+- test/querying_test.rb
 - test/state_pattern_test.rb
 - test/test_class_creation_helper.rb
 - test/test_helper.rb