yasm 0.0.2 → 0.0.3

data/README.markdown

@@ -283,6 +283,82 @@ Now, if we create a vending machine, then wait at least a minute, next time we t
       #==> Yasm::FinalStateException: We're sorry, but the current state `Obliterated` is final. It does not accept any actions. 
 
 
+## The Lazy Domino Effect
+
+The maximum time limit on a state can cause a domino effect. For example, suppose the start state for your context has a max time limit. And the action that
+runs when that time limit is reached transitions to a state with another max time limit. And so on. Now suppose you instantiate your context, and wait a reeeeealy 
+long time. Like, long enough to cause a state transition domino effect. Let's model this with a traffic light system: 
+
+    class TrafficLight
+      include Yasm::Context
+
+      start :green
+    end
+
+    class Green
+      include Yasm::State
+
+      maximum 10.seconds, :action => :transition_to_yellow
+    end
+
+    class TransitionToYellow
+      include Yasm::Action
+      
+      triggers :yellow
+
+      def execute
+        puts "transitioning to yellow."
+      end
+    end
+
+    class Yellow
+      include Yasm::State
+
+      maximum 3.seconds, :action => :transition_to_red
+    end
+
+    class TransitionToRed
+      include Yasm::Action
+
+      triggers :red
+      
+      def execute
+        puts "transitioning to red."
+      end
+    end
+
+    class Red
+      include Yasm::State
+
+      maximum 13.seconds, :action => :transition_to_green
+    end
+
+    class TransitionToGreen
+      include Yasm::Action
+
+      triggers :green
+      
+      def execute
+        puts "transitioning to green."
+      end
+    end
+
+    t = TrafficLight.new
+
+    puts t.state.value
+      #==> Green
+
+    sleep 30
+
+    t.state.value
+      #==> "transitioning to yellow."
+      #==> "transitioning to red."
+      #==> "transitioning to green."
+      #==> Green 
+
+Notice that this domino effect happened lazily when you call the `do!` method, or the `context.state.value` methods. Quite nice for systems where
+you persist your state to a db. 
+
 ## PUBLIC DOMAIN
 
 This software is committed to the public domain. No license. No copyright. DO ANYTHING! 

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

data/lib/yasm/context/state_container.rb

@@ -9,8 +9,13 @@ module Yasm
         @state   = options[:state]
       end
 
-      def value; @state; end
-      
+      def value; state; end
+
+      def state
+        check_maximum
+        @state
+      end
+
       def state=(s)
         if s.class == Class
           @state = s.new
@@ -20,13 +25,51 @@ module Yasm
       end
 
       def do!(*actions)
-        actions = [self.state.class.maximum_duration_action] + actions if self.state.passed_maximum_time_limit?
+        actions.each do |action|
+          fire! action
+        end
+      end
+
+      private
+      def fire!(action)
+        check_maximum
 
-        Yasm::Manager.execute(
-          :context => context, 
-          :state_container => self,
-          :actions => actions
-        )
+        # Verify that the action is possible given the current state
+        if !@state.reached_minimum_time_limit?
+          raise Yasm::TimeLimitNotYetReached, "We're sorry, but the time limit on the state `#{@state}` has not yet been reached."
+        elsif @state.class.final?
+          raise Yasm::FinalStateException,    "We're sorry, but the current state `#{@state}` is final. It does not accept any actions."
+        elsif !@state.class.is_allowed?(action.class)
+          raise Yasm::InvalidActionException, "We're sorry, but the action `#{action.class}` is not possible given the current state `#{@state}`." 
+        end
+
+        action = Yasm::Manager.setup_action :action => action, :context => context, :state_container => self
+        Yasm::Manager.change_state(
+          :to => action.class.trigger_state,
+          :on => self
+        ) if action.class.trigger_state
+        Yasm::Manager.execute_action action
+      end
+
+      def check_maximum
+        while @state.passed_maximum_time_limit?
+          # setup the action that should be performed when a state has lasted too long
+          action = Yasm::Manager.setup_action(
+            :action => @state.class.maximum_duration_action,
+            :context => context,
+            :state_container => self
+          )
+          
+          # update the state
+          Yasm::Manager.change_state(
+            :to => action.class.trigger_state || @state.class,
+            :on => self,
+            :at => @state.instantiated_at + @state.class.maximum_duration
+          )
+
+          # execute the action
+          Yasm::Manager.execute_action action
+        end
       end
     end
   end

data/lib/yasm/exceptions/time_limit_not_yet_reached.rb

@@ -1,4 +1,3 @@
 module Yasm
-  class TimeLimitNotYetReached < RuntimeError
-  end
+  class TimeLimitNotYetReached < RuntimeError; end
 end

data/lib/yasm/manager.rb

@@ -5,40 +5,32 @@ module Yasm
     def change_state(options)
       new_state       = options[:to]
       state_container = options[:on]
+      state_time      = options[:at] || Time.now
       
-      raise(
-        Yasm::TimeLimitNotYetReached,
-        "We're sorry, but the time limit on the state `#{state_container.state}` has not yet been reached."
-      ) if state_container.state and !state_container.state.reached_minimum_time_limit?
-      
-      new_state = new_state.to_class if new_state.respond_to? :to_class
-      new_state = new_state.new
-      new_state.instantiated_at = Time.now
-
+      new_state = get_instance new_state
+      new_state.instantiated_at = state_time
       state_container.state = new_state
     end
     
-    def execute(options)
+    def setup_action(options)
+      action = options[:action]
       context = options[:context]
-      actions = options[:actions]
       state_container = options[:state_container]
+      
+      action = get_instance action
+      action.context = context
+      action.state_container = state_container
+      action
+    end
+    
+    def execute_action(action)
+      action.execute
+    end
 
-      actions.each do |action|
-        action                  = action.new if action.class == Class
-        action.context          = context
-        action.state_container  = state_container
-        
-
-        # Verify that the action is possible given the current state
-        if state_container.state.class.final?
-          raise Yasm::FinalStateException, "We're sorry, but the current state `#{state_container.state}` is final. It does not accept any actions."
-        elsif !state_container.state.class.is_allowed?(action.class)
-          raise Yasm::InvalidActionException, "We're sorry, but the action `#{action.class}` is not possible given the current state `#{state_container.state}`." 
-        end
-
-        change_state :to => action.triggers.to_class, :on => state_container if action.triggers 
-        action.execute 
-      end
+    def get_instance(obj)
+      obj = obj.to_class if obj.respond_to? :to_class
+      obj = obj.new if obj.class == Class
+      obj
     end
   end
 end

data/yasm.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{yasm}
-  s.version = "0.0.2"
+  s.version = "0.0.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Matt Parker"]
-  s.date = %q{2011-02-13}
+  s.date = %q{2011-02-17}
   s.description = %q{Breaks up states, actions, and contexts into seperate classes.moonmaster9000@gmail.com}
   s.email = %q{moonmaster9000@gmail.com}
   s.extra_rdoc_files = [
@@ -39,14 +39,6 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.5.0}
   s.summary = %q{Yet Another State Machine. Pronounced "yaz-um."}
-  s.test_files = [
-    "spec/spec_helper.rb",
-    "spec/yasm/context_spec.rb",
-    "spec/yasm/conversions_spec.rb",
-    "spec/yasm/manager_spec.rb",
-    "spec/yasm/state_container_spec.rb",
-    "spec/yasm/state_spec.rb"
-  ]
 
   if s.respond_to? :specification_version then
     s.specification_version = 3

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: yasm
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: 
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Matt Parker
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-13 00:00:00 -05:00
+date: 2011-02-17 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -77,12 +77,6 @@ files:
 - lib/yasm/version.rb
 - yasm.gemspec
 - README.markdown
-- spec/spec_helper.rb
-- spec/yasm/context_spec.rb
-- spec/yasm/conversions_spec.rb
-- spec/yasm/manager_spec.rb
-- spec/yasm/state_container_spec.rb
-- spec/yasm/state_spec.rb
 has_rdoc: true
 homepage: http://github.com/moonmaster9000/yasm
 licenses: []
@@ -117,10 +111,5 @@ rubygems_version: 1.5.0
 signing_key: 
 specification_version: 3
 summary: Yet Another State Machine. Pronounced "yaz-um."
-test_files: 
-- spec/spec_helper.rb
-- spec/yasm/context_spec.rb
-- spec/yasm/conversions_spec.rb
-- spec/yasm/manager_spec.rb
-- spec/yasm/state_container_spec.rb
-- spec/yasm/state_spec.rb
+test_files: []
+

data/spec/spec_helper.rb

@@ -1,100 +0,0 @@
-$LOAD_PATH.unshift './lib'
-require 'yasm'
-
-# class VendingMachine
-#   include Yasm::Context
-# 
-#   start Waiting
-# end
-# 
-# class Waiting
-#   include Yasm::State
-# end
-# 
-# class Vending
-# end
-# 
-# class InputMoney
-#   include Yasm::Action
-#   
-#   triggers Vending
-# end
-# 
-# 
-# class VendingMachine
-#   include Yasm::Context
-#   
-#   # start Waiting
-#   # 
-#   # state :status do
-#   #   start Waiting
-#   # end
-#   # 
-#   attr_accessor :money
-#   def initialize
-#     @money = 0
-#   end
-# end
-# 
-# class Waiting
-#   include Yasm::State
-# 
-#   actions InputMoney
-# end
-# 
-# class Vending
-#   include Yasm::State
-# end
-# 
-# class NotAState
-# end
-# 
-# class InputMoney
-#   include Yasm::Action
-# end
-# 
-# class Vend
-#   include Yasm::Action
-#   triggers Vending
-# 
-#   def initialize(item)
-#     @item = item
-#   end
-#   
-#   def execute
-#     puts "Vending #{@item}"
-#     context.do! Refund if context.money > 0
-#   end
-# end
-# 
-# class Refund
-#   include Yasm::Action
-# 
-#   triggers Waiting
-# 
-#   def execute
-#     puts "Refunding #{context.money}"
-#     context.money = 0
-#   end
-# end
-# 
-# class MakeSelection
-#   include Yasm::Action
-#   
-#   def initialize(selection)
-#     @selection = selection
-#   end
-# 
-#   def execute
-#     if context.money >= selection.price
-#       trigger Vending
-#       context.money -= selection.price
-#       context.do! Vend.new(selection)
-#     else
-#       puts "You must enter more money."
-#     end
-#   end
-# end
-# 
-# class NotAnAction
-# end

data/spec/yasm/context_spec.rb

@@ -1,65 +0,0 @@
-require 'spec_helper'
-
-describe Yasm::Context do
-  context "when included in a class" do
-    before do
-      class VendingMachine
-        include Yasm::Context
-      end
-
-      class Waiting
-        include Yasm::State
-      end
-
-      class InputMoney
-        include Yasm::Action
-      end
-    end
-    
-    describe "##state" do
-      it "should require something that can be converted to a symbol" do
-        proc { VendingMachine.state(nil) }.should raise_exception(ArgumentError, "The state name must respond to `to_sym`")
-      end
-
-      it "should create a new state configuration" do
-        VendingMachine.state_configurations[:electricity].should be_nil
-        class On; include Yasm::State; end
-        VendingMachine.state(:electricity) { start :on }
-        VendingMachine.state_configurations[:electricity].should_not be_nil
-        VendingMachine.state_configurations[:electricity].start_state.should == :on
-      end
-
-      it "should instance_eval the block on the new state configuration" do
-        VendingMachine.state_configurations[:power].should be_nil
-        class On; include Yasm::State; end
-        VendingMachine.state(:power) { start :on }
-        VendingMachine.state_configurations[:power].should_not be_nil
-        VendingMachine.state_configurations[:power].start_state.should == :on
-      end
-
-      it "should create an instance method that returns the state" do
-        class On; include Yasm::State; end
-        VendingMachine.state(:light) { start :on }
-        VendingMachine.new.light.state.class.should == On
-      end
-    end
-    
-    describe "##start" do
-      context "when called directly on the context" do
-        it "should store the state as the start state of the anonymous state configuration" do
-          VendingMachine.state_configurations[Yasm::Context::ANONYMOUS_STATE].should be_nil
-          VendingMachine.start :waiting 
-          VendingMachine.state_configurations[Yasm::Context::ANONYMOUS_STATE].start_state.should == :waiting
-        end
-      end
-    end
-
-    describe "#do!" do
-      it "should pass all actions passed to it off to the anonymous state_container #do! method" do
-        v = VendingMachine.new
-        v.state.should_receive(:do!).with(InputMoney, InputMoney)
-        v.do! InputMoney, InputMoney
-      end
-    end
-  end
-end

data/spec/yasm/conversions_spec.rb

@@ -1,43 +0,0 @@
-require 'spec_helper'
-
-describe Yasm::Conversions::Symbol do
-  it "should create a :to_class instance method on Symbols" do
-    :sym.respond_to?(:to_class).should be_true
-  end
-end
-
-describe Symbol do
-  describe "#to_class" do
-    it "should convert the symbol to a class" do
-      class SymbolTest; end
-      :symbol_test.to_class.should == SymbolTest
-    end
-
-    it "should be the inverse of the Class #to_sym class method" do
-      class SymbolTest; end
-      :symbol_test.to_class.to_sym.should == :symbol_test
-    end
-  end
-end
-
-
-describe Yasm::Conversions::Class do
-  it "should create a :to_sym class method on classes" do
-    class SymbolTest; end
-    SymbolTest.respond_to?(:to_sym).should be_true
-  end
-end
-
-describe Symbol do
-  describe "#to_sym" do
-    it "should convert the class to a symbol" do
-      class SymbolTest; end
-      SymbolTest.to_sym.should == :symbol_test
-    end
-
-    it "should be the inverse of the Symbol #to_class instance method" do
-      class SymbolTest; end
-      SymbolTest.to_sym.to_class.should == SymbolTest
-    end
-  end
-end

data/spec/yasm/manager_spec.rb

@@ -1,122 +0,0 @@
-require 'spec_helper'
-
-describe Yasm::Manager do
-  before do
-    class VendingMachine
-      include Yasm::Context
-      
-      start :on
-    end
-
-    class Unplug
-      include Yasm::Action
-      
-      triggers :off
-    end
-
-    class PlugIn
-      include Yasm::Action
-      
-      triggers :on
-    end
-
-    class Destroy
-      include Yasm::Action
-
-      triggers :destroyed
-    end
-
-    class On
-      include Yasm::State
-      
-      actions :unplug, :destroy
-    end
-
-    class Off
-      include Yasm::State
-      
-      actions :plug_in, :destroy
-    end
-
-    class Destroyed
-      include Yasm::State
-
-      final!
-    end
-    
-    @vending_machine = VendingMachine.new
-  end
-    
-
-  
-  describe "##change_state" do
-    it "should convert the state to a class if we pass an object that respond to :to_class" do
-      Destroyed.should_receive(:to_class).and_return Destroyed
-      Yasm::Manager.change_state :to => Destroyed, :on => @vending_machine.state
-    end
-
-    it "should set the instantiated_at property on the state to the current time" do
-      seconds_since_the_epoch = Time.now
-      Time.should_receive(:now).twice.and_return seconds_since_the_epoch 
-      Yasm::Manager.change_state :to => On, :on => @vending_machine.state
-      @vending_machine.state.value.instantiated_at.should == seconds_since_the_epoch
-    end
-
-    it "should raise an exception if the current state has not yet reached it's time limit" do
-      class TenSeconds
-        include Yasm::State
-
-        minimum 10.seconds
-      end
-
-      proc {
-        Yasm::Manager.change_state :to => TenSeconds, :on => @vending_machine.state
-        Yasm::Manager.change_state :to => On, :on => @vending_machine.state
-      }.should raise_exception(Yasm::TimeLimitNotYetReached, "We're sorry, but the time limit on the state `TenSeconds` has not yet been reached.")
-    end
-  end
-  
-  describe "##execute" do
-    it "should apply each action, sequentially, to the appropriate state_container within the context" do
-      @vending_machine.state.value.class.should == On
-      
-      Yasm::Manager.execute :context => @vending_machine, :state_container => @vending_machine.state, :actions => [Unplug]
-      @vending_machine.state.value.class.should == Off
-
-      Yasm::Manager.execute :context => @vending_machine, :state_container => @vending_machine.state, :actions => [PlugIn]
-      @vending_machine.state.value.class.should == On
-    end
-
-    it "should raise an exception if you attempt to execute an action that isn't allowed by a state" do
-      @vending_machine.state.value.class.should == On
-      
-      proc { 
-        Yasm::Manager.execute(
-          :context => @vending_machine, 
-          :state_container => @vending_machine.state, 
-          :actions => [PlugIn]
-        )
-      }.should raise_exception(Yasm::InvalidActionException, "We're sorry, but the action `PlugIn` is not possible given the current state `On`.")
-    end
-
-    it "should raise an exception if you attempt to execute an action on a final state." do
-      proc {
-        Yasm::Manager.execute(
-          :context => @vending_machine,
-          :state_container => @vending_machine.state,
-          :actions => [Destroy, PlugIn]
-        )
-      }.should raise_exception(Yasm::FinalStateException, "We're sorry, but the current state `Destroyed` is final. It does not accept any actions.") 
-    end
-    
-    it "should not raise an exception if the action is allowed by the state" do
-      proc { 
-        Yasm::Manager.execute(
-          :context => @vending_machine, 
-          :state_container => @vending_machine.state, 
-          :actions => [Unplug]
-        )
-      }.should_not raise_exception
-    end
-  end
-end

data/spec/yasm/state_container_spec.rb

@@ -1,62 +0,0 @@
-require 'spec_helper'
-
-describe Yasm::Context::StateContainer do
-  before do
-    class VendingMachine
-      include Yasm::Context
-
-      start :waiting
-    end
-
-    class Waiting
-      include Yasm::State
-    end
-    
-    class Hit
-      include Yasm::Action
-
-      triggers :jammed
-    end
-
-    class Jammed
-      include Yasm::State
-      
-      maximum 10.seconds, :action => :explode
-    end
-
-    class Exploded
-      include Yasm::State
-
-      actions :clean_up
-    end
-
-    class CleanUp
-      include Yasm::Action
-    end
-
-    class Explode
-      include Yasm::Action
-    end
-
-    class InputMoney
-      include Yasm::Action
-    end
-  end
-
-  describe "#do!" do
-    it "should pass the actions off to the Yasm::Manager.execute method" do
-      v = VendingMachine.new
-      Yasm::Manager.should_receive(:execute).with(:context => v, :state_container => v.state, :actions => [InputMoney, InputMoney])
-      v.state.do! InputMoney, InputMoney
-    end
-
-    it "should add the maximum action to the front of the action list if the maximum time limit has been reached" do
-      v = VendingMachine.new
-      v.do! Hit
-      Yasm::Manager.should_receive(:execute).with(:context => v, :state_container => v.state, :actions => [Explode, CleanUp]) 
-      time = 10.seconds.from_now
-      Time.stub!(:now).and_return time
-      v.do! CleanUp
-    end
-  end
-end

data/spec/yasm/state_spec.rb

@@ -1,110 +0,0 @@
-require 'spec_helper'
-
-describe Yasm::State do
-  before do
-    class TestState
-      include Yasm::State
-    end
-
-    class Action1; include Yasm::Action; end
-    class Action2; include Yasm::Action; end
-  end
-
-  describe "##actions" do 
-    it "should set the @allowed_actions to the input to this method" do
-      TestState.actions Action1, Action2 
-      TestState.allowed_actions.should == [Action1, Action2]
-    end
-  end
-
-  describe "##final!" do
-    it "should set the @allowed_actions to an empty array" do
-      TestState.final!
-      TestState.allowed_actions.should == []
-    end
-  end
-
-  describe "##final?" do
-    it "should return true if there are no allowed actions" do
-      TestState.final!
-      TestState.final?.should be_true
-    end
-  end
-
-  describe "##minimum" do
-    it "should require an integer" do
-      proc { TestState.minimum "10 minutes" }.should raise_exception("You must provide a Fixnum to the ##minimum method (represents number of seconds). For example: 2.minutes")
-    end
-    
-    it "should set the @state_minimum_duration to the number input" do
-      TestState.minimum 1.minute
-      TestState.minimum_duration.should == 60
-    end
-  end
-
-  describe "#reached_minimum_time_limit?" do
-    before do
-      class MinState
-        include Yasm::State
-      end
-    end
-
-    it "should return true if there is no minimum time limit for the state" do
-      MinState.new.reached_minimum_time_limit?.should be_true 
-    end
-
-    it "should return false if there is a time limit that hasn't been reached yet" do
-      MinState.minimum 10.seconds
-      state = MinState.new
-      state.instantiated_at = Time.now
-      state.reached_minimum_time_limit?.should be_false
-    end
-
-    it "should return true if the state has reached it's time limit" do
-      MinState.minimum 10.seconds
-      state = MinState.new
-      state.instantiated_at = Time.now
-      ten_seconds_from_now = 10.seconds.from_now
-      Time.should_receive(:now).and_return ten_seconds_from_now
-      state.reached_minimum_time_limit?
-    end
-  end
-
-  describe "##maximum" do
-    it "should require both a time limit and an action" do
-      proc { TestState.maximum }.should raise_exception(ArgumentError)
-      proc { TestState.maximum 10.seconds }.should raise_exception(ArgumentError)
-      proc { TestState.maximum 10.seconds, :action => :action1 }.should_not raise_exception
-    end
-
-    it "should store the time limit and action" do
-      TestState.maximum 20.seconds, :action => :action2
-      TestState.maximum_duration.should == 20.seconds
-      TestState.maximum_duration_action.should == Action2
-    end
-  end
-
-  describe "##passed_maximum_time_limit?" do
-    it "should return false if no time limit has been set" do
-      class UnlimitedState
-        include Yasm::State
-      end
-
-      UnlimitedState.new.passed_maximum_time_limit?.should be_false
-    end
-
-    it "should return true if a time limit was set, and that limit has been passed" do
-      class LimitedState
-        include Yasm::State
-
-        maximum 10.seconds, :action => :action2
-      end
-
-      s = LimitedState.new
-      s.instantiated_at = Time.now
-      ten_seconds_from_now = 10.seconds.from_now
-      Time.stub!(:now).and_return ten_seconds_from_now
-      s.passed_maximum_time_limit?.should be_true
-    end
-  end
-end