state_pattern 1.0.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Daniel Cadenas
+
+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/README.rdoc

@@ -0,0 +1,62 @@
+= state_pattern
+
+A Ruby state pattern implementation.
+
+  require 'rubygems'
+  require 'state_pattern'
+
+  class On < StatePattern::State
+    def press
+      transition_to(Off)
+      "#{stateable.button_name} is off"
+    end
+  end
+  
+  class Off < StatePattern::State
+    def press
+      transition_to(On)
+      "#{stateable.button_name} is on"
+    end
+  end
+  
+  class Button
+    include StatePattern
+    add_states On, Off
+    set_initial_state Off
+    valid_transitions [On, :press] => Off, [Off, :press] => On
+
+    #this method can be removed as it will be mapped automatically anyways
+    #but it is good to leave the option to do the delegation yourself in case you want more freedom
+    def press
+      delegate_to_event(:press)
+    end
+  
+    def button_name
+      "Light button"
+    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"
+
+== Validations
+
+One of the few drawbacks the state pattern has is that it can get difficult to see the global picture of your state machine when dealing with complex cases.
+To deal with this problem you have the option of using the valid_transitions statement to "draw" your state diagram in code. Whenever a state transition is performed, the valid_transitions hash is checked and if the transition is not valid a StatePattern::InvalidTransitionException is thrown.
+
+Examples:
+
+The most basic notation
+  valid_transitions On => Off, Off => On
+
+With more than one target state
+  valid_transitions Up => [Middle, Down], Down => Middle, Middle => Up 
+
+Using event names to gain more detail
+  valid_transitions [Up, :switch] => [Middle, Down], [Down, :switch] => Middle, [Middle, :switch] => Up 
+
+== Copyright
+
+Copyright (c) 2009 Daniel Cadenas. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,83 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "state_pattern"
+    gem.summary = %Q{A Ruby state pattern implementation}
+    gem.email = "dcadenas@gmail.com"
+    gem.homepage = "http://github.com/dcadenas/state_pattern"
+    gem.authors = ["Daniel Cadenas"]
+    gem.rubyforge_project = "statepattern"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "state_pattern #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'rake/contrib/sshpublisher'
+  namespace :rubyforge do
+
+    desc "Release gem and RDoc documentation to RubyForge"
+    task :release => ["rubyforge:release:gem", "rubyforge:release:docs"]
+
+    namespace :release do
+      desc "Publish RDoc to RubyForge."
+      task :docs => [:rdoc] do
+        config = YAML.load(
+            File.read(File.expand_path('~/.rubyforge/user-config.yml'))
+        )
+
+        host = "#{config['username']}@rubyforge.org"
+        remote_dir = "/var/www/gforge-projects/state_pattern/"
+        local_dir = 'rdoc'
+
+        Rake::SshDirPublisher.new(host, remote_dir, local_dir).upload
+      end
+    end
+  end
+rescue LoadError
+  puts "Rake SshDirPublisher is unavailable or your rubyforge environment is not configured."
+end
+

data/VERSION

@@ -0,0 +1 @@
+1.0.1

data/lib/state_pattern.rb

@@ -0,0 +1,92 @@
+require 'state_pattern/state'
+require 'state_pattern/invalid_transition_exception'
+
+module StatePattern
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    def state_classes
+      @state_classes ||= []
+    end
+
+    def initial_state_class
+      @initial_state_class
+    end
+
+    def set_initial_state(state_class)
+      @initial_state_class = state_class
+    end
+
+    def add_states(*state_classes)
+      state_classes.each do |state_class|
+        add_state_class(state_class)
+      end
+    end
+
+    def add_state_class(state_class)
+      state_classes << state_class
+    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
+      end
+    end
+
+    def transitions_hash
+      @transitions_hash
+    end
+
+    def delegate_all_state_events
+      state_methods.each do |state_method|
+        define_method state_method do |*args|
+          delegate_to_event(state_method)
+        end
+      end
+    end
+
+    def state_methods
+      state_classes.map{|state_class| state_class.public_instance_methods(false)}.flatten.uniq
+    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
+  end
+
+  def set_state(state_class)
+    self.current_state = state_class.new(self)
+  end
+
+  def delegate_to_event(method_name, *args)
+    self.current_event = method_name.to_sym
+    self.current_state.send(current_event, *args)
+  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)
+  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)
+  end
+
+  def state
+    self.current_state.state
+  end
+end
+
+

data/lib/state_pattern/invalid_transition_exception.rb

@@ -0,0 +1,14 @@
+module StatePattern
+  class InvalidTransitionException < RuntimeError
+    attr_reader :from_module, :to_module, :event
+    def initialize(from_module, to_module, event)
+      @from_module = from_module
+      @to_module = to_module
+      @event = event
+    end
+
+    def message
+      "Event #@event cannot transition from #@from_module to #@to_module"
+    end
+  end
+end

data/lib/state_pattern/state.rb

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

data/state_pattern.gemspec

@@ -0,0 +1,53 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{state_pattern}
+  s.version = "1.0.1"
+
+  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.email = %q{dcadenas@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/state_pattern.rb",
+     "lib/state_pattern/invalid_transition_exception.rb",
+     "lib/state_pattern/state.rb",
+     "state_pattern.gemspec",
+     "test/state_pattern_test.rb",
+     "test/test_class_creation_helper.rb",
+     "test/test_helper.rb",
+     "test/transition_validations_test.rb"
+  ]
+  s.homepage = %q{http://github.com/dcadenas/state_pattern}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{statepattern}
+  s.rubygems_version = %q{1.3.3}
+  s.summary = %q{A Ruby state pattern implementation}
+  s.test_files = [
+    "test/state_pattern_test.rb",
+     "test/test_class_creation_helper.rb",
+     "test/test_helper.rb",
+     "test/transition_validations_test.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/test/state_pattern_test.rb

@@ -0,0 +1,102 @@
+require 'test_helper'
+
+module Family
+  class James < StatePattern::State
+    def name
+      transition_to(Lynn)
+      "James #{stateable.last_name}"
+    end
+  end
+
+  class Lynn < StatePattern::State
+    def name
+      transition_to(James)
+      "Lynn #{stateable.last_name}"
+    end
+  end
+
+  class Member
+    include StatePattern
+    add_states James, Lynn
+    set_initial_state Lynn
+    valid_transitions [James, :name] => Lynn, [Lynn, :name] => James
+
+    #notice this method is optional, it will be delegated automatically if removed
+    def name
+      delegate_to_event :name
+    end
+
+    def last_name
+      "Holbrook"
+    end
+  end
+end
+
+Expectations do
+  expect "Lynn Holbrook" do
+    member = Family::Member.new
+    member.name 
+  end
+
+  expect "James Holbrook" do
+    member = Family::Member.new
+    member.name 
+    member.name 
+  end
+
+  expect "Lynn Holbrook" do
+    member = Family::Member.new
+    member.name 
+    member.name 
+    member.name 
+  end
+
+  expect "on" do
+    with_test_class("Button", :states => ["On", "Off"], :initial_state => "Off",
+                    :transitions => {["On", :press] => "Off", ["Off", :press] => "On"}) do
+      button = Button.new
+      button.press
+    end
+  end
+
+  expect "off" do
+    with_test_class("Button", :states => ["On", "Off"], :initial_state => "Off",
+                    :transitions => {["On", :press] => "Off", ["Off", :press] => "On"}) do
+      button = Button.new
+      button.press
+      button.press
+    end
+  end
+
+  expect "on" do
+    with_test_class("Button", :states => ["On", "Off"], :initial_state => "Off",
+                    :transitions => {["On", :press] => "Off", ["Off", :press] => "On"}) do
+      button = Button.new
+      button.press
+      button.press
+      button.press
+    end
+  end
+
+  expect "on" do
+    with_test_class("Button", :states => ["On", "Off"], :initial_state => "Off",
+                    :transitions => {["On", :press] => "Off", ["Off", :press] => "On"}) do
+      button1 = Button.new
+      button2 = Button.new
+      button1.press
+      button2.press
+    end
+  end
+
+  expect ["ping", "on", "pong", "off"] do
+    with_test_class("PingPong", :states => ["Ping", "Pong"], :initial_state => "Pong", :transitions => {["Ping", :do_it] => "Pong", ["Pong", :do_it] => "Ping"}) do
+      with_test_class("Button", :states => ["On", "Off"], :initial_state => "Off", :transitions => {["On", :press] => "Off", ["Off", :press] => "On"}) do
+        pingpong = PingPong.new
+        button = Button.new
+        [pingpong.do_it, button.press, pingpong.do_it, button.press]
+      end
+    end
+  end
+end
+
+

data/test/test_class_creation_helper.rb

@@ -0,0 +1,59 @@
+module TestClassCreationHelper
+  #TODO: ugly
+  def with_test_class(main_state_module_name, options = {})
+    created_consts = []
+    transitions = options[:transitions] || {}
+    state_methods = transitions.keys.map{|t| t.last}.uniq || []
+
+    if options.has_key?(:states)
+      options[:states].each do |state_name|
+        created_consts << create_class(state_name, StatePattern::State) do
+          state_methods.each do |method_name|
+            define_method method_name do
+              next_state_name = transitions[[state_name, method_name]]
+              next_state_module = next_state_name && Object.const_get(next_state_name)
+              transition_to next_state_module
+              next_state_name.downcase
+            end
+          end
+        end
+      end
+    end
+
+    created_consts << create_class(main_state_module_name) do
+      include StatePattern
+      add_states *options[:states].map{|s| Object.const_get(s)} if options.has_key?(:states)
+      set_initial_state Object.const_get(options[:initial_state]) if options.has_key?(:initial_state)
+      if options.has_key?(:valid_transitions)
+        valid_transitions_with_constants = {}
+        options[:valid_transitions].each do |from_module_string_or_array, to_module_string|
+          if from_module_string_or_array.respond_to?(:to_ary)
+            valid_transitions_with_constants[[Object.const_get(from_module_string_or_array.first), from_module_string_or_array.last]] = Object.const_get(to_module_string)
+          else
+            valid_transitions_with_constants[Object.const_get(from_module_string_or_array)] = Object.const_get(to_module_string)
+          end
+        end
+        valid_transitions valid_transitions_with_constants
+      end
+    end
+
+    begin
+      yield
+    ensure 
+      created_consts.each do |created_const|
+        Object.send(:remove_const, created_const.to_s.to_sym)
+      end
+    end
+  end
+
+private
+
+  def create_module(module_name, superklass = Object, module_or_class = Module, &block)
+    new_module = module_or_class.new(superklass, &block)
+    Object.const_set(module_name, new_module) unless Object.const_defined? module_name
+  end
+
+  def create_class(class_name, superklass = Object, &block)
+    create_module(class_name, superklass, Class, &block)
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,13 @@
+require 'rubygems'
+require 'expectations'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'state_pattern'
+require 'test_class_creation_helper'
+
+include TestClassCreationHelper
+
+class Test::Unit::TestCase
+end
+

data/test/transition_validations_test.rb

@@ -0,0 +1,55 @@
+require 'test_helper'
+
+Expectations do
+  expect "up" do
+    with_test_class("Switch", :states => ["Up", "Down", "Middle"], :initial_state => "Middle",
+                    :transitions => {["Up", :push_down] => "Middle",
+                      ["Down", :push_up] => "Middle",
+                      ["Middle", :push_up] => "Up",
+                      ["Middle", :push_down] => "Down"}) do
+      switch = Switch.new
+      switch.push_up
+    end
+  end
+
+  expect "up" do
+    with_test_class("Switch", :states => ["Up", "Down", "Middle"], :initial_state => "Middle",
+                    :transitions => {["Up", :push_down] => "Middle",
+                      ["Down", :push_up] => "Middle",
+                      ["Middle", :push_up] => "Up",
+                      ["Middle", :push_down] => "Down"},
+                    :valid_transitions => {["Up", :push_down] => "Middle",
+                      ["Down", :push_up] => "Middle",
+                      ["Middle", :push_up] => "Up",
+                      ["Middle", :push_down] => "Down"}) do
+      switch = Switch.new
+      switch.push_up
+    end
+  end
+
+  expect StatePattern::InvalidTransitionException do
+    with_test_class("Switch", :states => ["Up", "Down", "Middle"], :initial_state => "Middle",
+                    :transitions => {["Up", :push_down] => "Middle",
+                      ["Down", :push_up] => "Middle",
+                      ["Middle", :push_up] => "Up",
+                      ["Middle", :push_down] => "Down"},
+                    :valid_transitions => {["Up", :push_down] => "Middle",
+                      ["Down", :push_up] => "Middle",
+                      ["Middle", :push_down] => "Down"}) do
+      switch = Switch.new
+      switch.push_up
+    end
+  end
+
+  expect StatePattern::InvalidTransitionException do
+    with_test_class("Switch", :states => ["Up", "Down", "Middle"], :initial_state => "Middle",
+                    :transitions => {["Up", :push_down] => "Middle",
+                      ["Down", :push_up] => "Middle",
+                      ["Middle", :push_up] => "Up",
+                      ["Middle", :push_down] => "Down"},
+                    :valid_transitions => {"Up" => "Middle", "Down" => "Middle", "Middle" => "Down"}) do
+      switch = Switch.new
+      switch.push_up
+    end
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: state_pattern
+version: !ruby/object:Gem::Version 
+  version: 1.0.1
+platform: ruby
+authors: 
+- Daniel Cadenas
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-08 00:00:00 -03:00
+default_executable: 
+dependencies: []
+
+description: 
+email: dcadenas@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/state_pattern.rb
+- lib/state_pattern/invalid_transition_exception.rb
+- lib/state_pattern/state.rb
+- state_pattern.gemspec
+- test/state_pattern_test.rb
+- test/test_class_creation_helper.rb
+- test/test_helper.rb
+- test/transition_validations_test.rb
+has_rdoc: true
+homepage: http://github.com/dcadenas/state_pattern
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: statepattern
+rubygems_version: 1.3.3
+signing_key: 
+specification_version: 3
+summary: A Ruby state pattern implementation
+test_files: 
+- test/state_pattern_test.rb
+- test/test_class_creation_helper.rb
+- test/test_helper.rb
+- test/transition_validations_test.rb