yasm 0.0.1 → 0.0.2

data/README.markdown

@@ -93,7 +93,7 @@ invalid actions to the context, `Yasm` will raise an exception.
       #==> Waiting
 
     vending_machine.do! RetrieveSelection
-      #==> RuntimeError: We're sorry, but the action `RetrieveSelection` 
+      #==> InvalidActionException: We're sorry, but the action `RetrieveSelection` 
            is not possible given the current state `Waiting`.
 
     vending_machine.do! InputMoney
@@ -101,7 +101,8 @@ invalid actions to the context, `Yasm` will raise an exception.
     vending_machine.state.value 
       #==> Waiting
 
-## Side Effects
+
+### Side Effects
 
 How can we take our simulation farther? A real vending machine would verify that when you make a selection, 
 you actually have input enough money to pay for that selection. How can we model this? 
@@ -197,7 +198,7 @@ pay for our selection).
       #==> Waiting
 
 
-## End states
+### End states
 
 Sometimes, a state is final. Like, what if, out of frustration, you threw the vending machine off the top of a 10 story building? It's probably not going
 to work again after that. You can use the `final!` macro on a state to denote that this is the end.
@@ -219,8 +220,67 @@ to work again after that. You can use the `final!` macro on a state to denote th
     vending_machine.do! TossOffBuilding
 
     vending_machine.do! MakeSelection.new(SnickersBar)
-    #==> RuntimeError: We're sorry, but the current state `Obliterated` is final. It does not accept any actions 
+    #==> Yasm::FinalStateException: We're sorry, but the current state `Obliterated` is final. It does not accept any actions. 
+
+
+### State Timers
+
+When a vending machine vends an item, it takes about 10 seconds for the item to work it's way off the rack and fall to the bottom. We can simulate this
+by placing a `minimum` constraint on the `Vending` state. 
+
+    class Vending
+      include Yasm::State
+
+      minimum 10.seconds
+    end
+
+
+Now, when we go into the vending state, we won't be able to retrieve our selection until 10 seconds have passed. 
+
+    vending_machine.do! MakeSelection.new(SnickersBar)
+
+    vending_machine.state.value
+      #==> Vending
+
+    vending_machine.do! RetrieveSelection
+      #==> Yasm::TimeLimitNotYetReached: We're sorry, but the time limit on the state `Vending` has not yet been reached. 
+
+    sleep 10
+
+    vending_machine.do! RetrieveSelection
+
+    vending_machine.state.value
+      #==> Waiting
+
+You can also create maximum time limits. For example, suppose we want our vending machine to self destruct, out of frustration, if it goes
+an entire minute without any action.
+
+    class Waiting
+      include Yasm::State
+
+      maximum 1.minute, :action => :self_destruct
+    end
+
+    class SelfDestruct
+      include Yasm::Action
+
+      triggers :obliterated
 
+      def execute
+        puts "KABOOM!"
+      end
+    end
+
+Now, if we create a vending machine, then wait at least a minute, next time we try to do something to it, it will execute the `SelfDestruct` action.
+
+
+    v = VendingMachine.new
+    
+    sleep 60
+    
+    v.do! InputMoney.new(10)
+      #==> "KABOOM!"
+      #==> Yasm::FinalStateException: We're sorry, but the current state `Obliterated` is final. It does not accept any actions. 
 
 
 ## PUBLIC DOMAIN

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/lib/yasm.rb

@@ -1,4 +1,6 @@
 require 'active_support/core_ext/string'
+require 'active_support/time'
+require 'yasm/exceptions'
 require 'yasm/conversions'
 require 'yasm/manager'
 require 'yasm/version'

data/lib/yasm/context.rb

@@ -45,11 +45,8 @@ module Yasm
     
     def state_container(id)
       unless state_containers[id]
-        state_containers[id] = 
-          StateContainer.new(
-            :context => self, 
-            :state   => self.class.state_configurations[id].start_state.to_class.new
-          )
+        state_containers[id] = StateContainer.new :context => self 
+        Yasm::Manager.change_state :to => self.class.state_configurations[id].start_state, :on => state_containers[id]
       end
 
       state_containers[id]

data/lib/yasm/context/state_container.rb

@@ -20,6 +20,8 @@ module Yasm
       end
 
       def do!(*actions)
+        actions = [self.state.class.maximum_duration_action] + actions if self.state.passed_maximum_time_limit?
+
         Yasm::Manager.execute(
           :context => context, 
           :state_container => self,

data/lib/yasm/exceptions.rb

@@ -0,0 +1,3 @@
+require 'yasm/exceptions/time_limit_not_yet_reached'
+require 'yasm/exceptions/final_state_exception'
+require 'yasm/exceptions/invalid_action_exception'

data/lib/yasm/exceptions/final_state_exception.rb

@@ -0,0 +1,3 @@
+module Yasm
+  class FinalStateException < RuntimeError; end
+end

data/lib/yasm/exceptions/invalid_action_exception.rb

@@ -0,0 +1,3 @@
+module Yasm
+  class InvalidActionException < RuntimeError; end
+end

data/lib/yasm/exceptions/time_limit_not_yet_reached.rb

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

data/lib/yasm/manager.rb

@@ -5,9 +5,17 @@ module Yasm
     def change_state(options)
       new_state       = options[:to]
       state_container = options[:on]
+      
+      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
 
-      state_container.state = new_state.new
+      state_container.state = new_state
     end
     
     def execute(options)
@@ -23,9 +31,9 @@ module Yasm
 
         # Verify that the action is possible given the current state
         if state_container.state.class.final?
-          raise "We're sorry, but the current state `#{state_container.state}` is final. It does not accept any actions."
+          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 "We're sorry, but the action `#{action.class}` is not possible given the current state `#{state_container.state}`." 
+          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 

data/lib/yasm/state.rb

@@ -25,10 +25,49 @@ module Yasm
       def final?
         @allowed_actions == []
       end
+
+      def minimum(time)
+        raise(
+          ArgumentError,
+          "You must provide a Fixnum to the ##minimum method (represents number of seconds). For example: 2.minutes"
+        ) unless time.kind_of?(Fixnum)
+
+        @state_minimum_duration = time
+      end
+
+      def minimum_duration
+        @state_minimum_duration
+      end
+
+      def maximum(maximum_duration, action_hash)
+        @maximum_duration = maximum_duration
+        @maximum_duration_action = action_hash[:action]
+      end
+
+      def maximum_duration
+        @maximum_duration
+      end
+
+      def maximum_duration_action
+        return @maximum_duration_action.call if @maximum_duration_action.respond_to? :call
+        @maximum_duration_action.to_class
+      end
     end
+    
+    attr_accessor :instantiated_at
 
     def to_s
       self.class.to_s
     end
+
+    def reached_minimum_time_limit?
+      return true unless self.class.minimum_duration 
+      (Time.now - instantiated_at) >= self.class.minimum_duration 
+    end
+
+    def passed_maximum_time_limit?
+      return false unless self.class.maximum_duration
+      (Time.now - instantiated_at) >= self.class.maximum_duration
+    end
   end
 end

data/spec/yasm/manager_spec.rb

@@ -1,53 +1,82 @@
 require 'spec_helper'
 
 describe Yasm::Manager do
-  describe "##execute" do
-    before do
-      class VendingMachine
-        include Yasm::Context
-        
-        start :on
-      end
+  before do
+    class VendingMachine
+      include Yasm::Context
+      
+      start :on
+    end
 
-      class Unplug
-        include Yasm::Action
-        
-        triggers :off
-      end
+    class Unplug
+      include Yasm::Action
+      
+      triggers :off
+    end
 
-      class PlugIn
-        include Yasm::Action
-        
-        triggers :on
-      end
+    class PlugIn
+      include Yasm::Action
+      
+      triggers :on
+    end
 
-      class Destroy
-        include Yasm::Action
+    class Destroy
+      include Yasm::Action
 
-        triggers :destroyed
-      end
+      triggers :destroyed
+    end
 
-      class On
-        include Yasm::State
-        
-        actions :unplug, :destroy
-      end
+    class On
+      include Yasm::State
+      
+      actions :unplug, :destroy
+    end
 
-      class Off
-        include Yasm::State
-        
-        actions :plug_in, :destroy
-      end
+    class Off
+      include Yasm::State
+      
+      actions :plug_in, :destroy
+    end
+
+    class Destroyed
+      include Yasm::State
+
+      final!
+    end
+    
+    @vending_machine = VendingMachine.new
+  end
+    
 
-      class Destroyed
+  
+  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
 
-        final!
+        minimum 10.seconds
       end
-      
-      @vending_machine = VendingMachine.new
+
+      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
       
@@ -58,7 +87,7 @@ describe Yasm::Manager do
       @vending_machine.state.value.class.should == On
     end
 
-    it "should verify that the action is possible given the current state" do
+    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 { 
@@ -67,8 +96,20 @@ describe Yasm::Manager do
           :state_container => @vending_machine.state, 
           :actions => [PlugIn]
         )
-      }.should raise_exception("We're sorry, but the action `PlugIn` is not possible given the current state `On`.")
+      }.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, 
@@ -76,14 +117,6 @@ describe Yasm::Manager do
           :actions => [Unplug]
         )
       }.should_not raise_exception
-
-      proc {
-        Yasm::Manager.execute(
-          :context => @vending_machine,
-          :state_container => @vending_machine.state,
-          :actions => [Destroy, PlugIn]
-        )
-      }.should raise_exception("We're sorry, but the current state `Destroyed` is final. It does not accept any actions.") 
     end
   end
 end

data/spec/yasm/state_container_spec.rb

@@ -4,11 +4,39 @@ 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
@@ -21,5 +49,14 @@ describe Yasm::Context::StateContainer do
       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

@@ -30,4 +30,81 @@ describe Yasm::State do
       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

data/yasm.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{yasm}
-  s.version = "0.0.1"
+  s.version = "0.0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Matt Parker"]
-  s.date = %q{2011-02-12}
+  s.date = %q{2011-02-13}
   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 = [
@@ -26,6 +26,10 @@ Gem::Specification.new do |s|
     "lib/yasm/conversions.rb",
     "lib/yasm/conversions/class.rb",
     "lib/yasm/conversions/symbol.rb",
+    "lib/yasm/exceptions.rb",
+    "lib/yasm/exceptions/final_state_exception.rb",
+    "lib/yasm/exceptions/invalid_action_exception.rb",
+    "lib/yasm/exceptions/time_limit_not_yet_reached.rb",
     "lib/yasm/manager.rb",
     "lib/yasm/state.rb",
     "lib/yasm/version.rb",

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: yasm
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Matt Parker
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-12 00:00:00 -05:00
+date: 2011-02-13 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -68,6 +68,10 @@ files:
 - lib/yasm/conversions.rb
 - lib/yasm/conversions/class.rb
 - lib/yasm/conversions/symbol.rb
+- lib/yasm/exceptions.rb
+- lib/yasm/exceptions/final_state_exception.rb
+- lib/yasm/exceptions/invalid_action_exception.rb
+- lib/yasm/exceptions/time_limit_not_yet_reached.rb
 - lib/yasm/manager.rb
 - lib/yasm/state.rb
 - lib/yasm/version.rb