simple_machine 1.0.0

data/README.rdoc

@@ -0,0 +1,73 @@
+= SimpleMachine
+
+SimpleMachine is module for Ruby which injects simple state machine behavior in any class that includes it. It can be defined on multiple fields in the same class
+
+== Installation
+
+Install it with "gem install simple_machine" then require 'simple_machine' in your project, or if you use Bundler add this to your Gemfile:
+  gem "simple_machine"
+
+== Usage
+
+After requiring 'simple_machine' inject state machine in your class like this:
+
+  require 'simple_machine'
+
+  class Phone
+    include SimpleMachine  
+	  implement_state_machine_for :my_state do
+		initial_state :off
+		other_states :ready, :dialing, :busy
+		allow_transition :turn_on,  :from => :off,     :to => :ready
+		allow_transition :dial,     :from => :ready,   :to => :dialing
+		allow_transition :hangup,   :from => :dialing, :to => :ready 
+		allow_transition :hangup,   :from => :busy,    :to => :ready
+		allow_transition :turn_off, :from => :ready,   :to => :off
+	  end	
+	end
+  end
+
+This chunk of code produces following effects:
+
+  Phone.my_state_default_state #=> :off
+  phone = Phone.new
+  phone.my_state #=> :off
+  phone.my_state_machine.allowed_transitions #=> [:turn_on]
+  phone.my_state_machine.can_dial? #=> false
+  phone.my_state_machine.dial #=> raises exception: 'Invalid transition #dial from 'off' state'
+  phone.my_state_machine.can_turn_on? #=> true
+  phone.my_state_machine.turn_on #=> :ready
+  phone.my_state #=> :ready
+
+=== Transition Guards
+
+You can also implement transition guards in your class like this:
+
+  class Phone
+    def guard_for_dial_on_my_state; false; end
+  end
+
+In this case even if +dial+ is allowed transition from +ready+ state this is what will happen:
+
+  phone.my_state #=> :ready
+  phone.my_state_machine.allowed_transitions #=> [:hangup]
+  phone.my_state.machine.can_dial? #=> false
+  phone.my_state_machine.dial #=> raises exception: 'Unable to dial due to guard'
+
+=== Callback
+
+After each transition callback is invoked in parent class if it is defined:
+
+  class Phone
+    def after_my_state_changed
+      puts "New my state is '#{self.my_state}'"
+    end
+  end
+
+== Test
+
+If you want to run tests you will need 'rspec' and 'mocha' gems
+
+== Disclaimer
+
+This library was made without any pretend to be big-enterprise-sega-mega solution for State machine, but I still hope you will find this small library useful in some cases (I already do :). If you have any issues or ideas feel free to fork the project and send a pull request.

data/lib/simple_machine.rb

@@ -0,0 +1,113 @@
+module SimpleMachine
+  def self.included(klass)
+    klass.extend ClassMethods
+  end
+  
+  class SimpleMachinePrototype
+    def initialize(owner)
+      @owner = owner
+    end
+    
+    def all_states
+      self.class.all_states
+    end
+    def allowed_transitions
+      current_state = @owner.send self.class.parents_state_field_name
+      result = self.class.defined_transitions[current_state].collect { |hash| hash[:transition] }
+      result.collect do |transition|
+        guard_method = "guard_for_#{transition}_on_#{self.class.parents_state_field_name}".to_sym
+        transition if !@owner.respond_to?( guard_method ) or @owner.send(guard_method)
+      end.compact
+    end
+    
+    class << self
+      attr_accessor :parents_state_field_name
+      attr_reader :all_states, :defined_transitions
+      attr_writer :owner_class
+      
+      def initial_state(state)
+        @all_states = [] << state
+        variable = "@#{@parents_state_field_name}_default_state"
+        @owner_class.instance_eval { instance_variable_set(variable, state) }
+      end
+      def other_states(*other_states)
+        @all_states = @all_states | other_states
+      end
+      def defined_transition?(transition, from_state)
+        return false unless @defined_transitions.has_key? from_state
+        result = @defined_transitions[from_state].inject(false) { |sum, hash| sum || hash[:transition] == transition }
+        return result
+      end
+      def allow_transition(transition, options)
+        @defined_transitions ||= {}
+        raise "Unknown source state #{options[:from]}. Please define it first as initial_state or in other_states." unless all_states.include?(options[:from])
+        raise "Unknown target state #{options[:to]}. Please define it first as initial_state or in other_states." unless all_states.include?(options[:to])
+        raise "Already defined transition '#{transition}' from '#{options[:from]}' state" if defined_transition?(transition, options[:from])
+        
+        @defined_transitions[options[:from]] = [] unless @defined_transitions.has_key?(options[:from])
+        @defined_transitions[options[:from]] << { :transition => transition, :target_state => options[:to] }     
+        
+        class_eval do
+          define_method "can_#{transition}?" do
+            allowed_transitions.include? transition
+          end
+          define_method transition do
+            current_state = @owner.send self.class.parents_state_field_name
+            if self.class.defined_transitions[current_state].inject(false) { |memo, hash| memo or hash[:transition] == transition }
+              raise "Unable to #{transition.to_s.gsub '_', ' '} due to guard"
+            else
+              raise "Invalid transition ##{transition.to_s.gsub '_', ' '} from '#{current_state}' state"
+            end unless allowed_transitions.include? transition
+            variable = "@#{self.class.parents_state_field_name}"
+            result = @owner.instance_eval { instance_variable_set variable, options[:to] }
+            callback_method = "after_#{self.class.parents_state_field_name}_changed".to_sym
+            @owner.send callback_method if @owner.respond_to? callback_method
+            result
+          end
+        end   
+      end
+    end
+  end
+
+  module ClassMethods
+      
+    def implement_state_machine_for(state_field_name, &block)
+      machine_property_name = "#{state_field_name}_machine".to_sym
+      default_state_field_name = "#{state_field_name}_default_state".to_sym
+
+      define_method state_field_name do
+        result = instance_variable_get "@#{state_field_name}"
+        result = instance_variable_set "@#{state_field_name}", self.class.send(default_state_field_name) unless result
+        result
+      end
+      define_method machine_property_name do
+        result = instance_variable_get "@#{machine_property_name}"
+        result = instance_variable_set "@#{machine_property_name}", SimpleMachine::ClassMethods.get_state_machine_class_for(self.class, state_field_name).new(self) unless result
+        result
+      end
+      self.class.class_eval do
+        define_method default_state_field_name do
+          instance_variable_get "@#{default_state_field_name}"
+        end
+      end
+      
+      SimpleMachine::ClassMethods.get_state_machine_class_for(self, state_field_name).instance_eval &block
+      
+      raise "Initial state not defined." unless send default_state_field_name
+    end
+    
+    private
+    
+    @state_machine_classes = {}
+    
+    def self.get_state_machine_class_for(cls, state_field_name)
+      key = [cls.to_s.to_sym, state_field_name]
+      unless @state_machine_classes.has_key? key
+        @state_machine_classes[key] ||= SimpleMachine::SimpleMachinePrototype.clone
+        @state_machine_classes[key].owner_class = cls
+        @state_machine_classes[key].parents_state_field_name = state_field_name
+      end
+      @state_machine_classes[key]
+    end
+  end
+end

data/spec/spec_simple_machine.rb

@@ -0,0 +1,181 @@
+require 'rubygems'
+require 'rspec'
+require 'mocha'
+require File.expand_path(File.dirname(__FILE__) + '/../lib/simple_machine')
+
+RSpec.configure { |config| config.mock_with :mocha }
+
+describe SimpleMachine, "for :dispatch_state field on Job, when state machine is aready defined for :other_state on Job and for :dispatch_state on Driver" do
+  before :all do
+    class Driver
+      include SimpleMachine
+      implement_state_machine_for :dispatch_state do
+        initial_state :waiting
+        other_states :assigned, :circling, :going_to_pickup_location, :on_pickup_location, :driving_passenger, :changing_zone, :going_home
+        allow_transition :assign, :from => :waiting, :to => :assigned
+      end
+    end
+    class Job
+      include SimpleMachine  
+      implement_state_machine_for :other_state do
+        initial_state :created
+        other_states :deleted, :reviewed, :done, :closed
+        allow_transition :delete, :from => :created, :to => :deleted
+        allow_transition :delete, :from => :reviewed, :to => :deleted
+      end
+    end
+  end
+  context "without initial state" do
+    it "raises exception that initial state is undefined" do
+      lambda { Job.implement_state_machine_for :dispatch_state do; end }.should( raise_error do |e|
+        e.message.should match("Initial state not defined.")
+      end )
+    end
+  end
+
+  context "with only initial state :waiting" do
+    before :each do
+      Job.implement_state_machine_for :dispatch_state do
+        initial_state :waiting
+      end
+    end
+    it "defines :waiting as dispatch_state_default_state in Job" do
+      Job.dispatch_state_default_state.should be(:waiting)
+    end    
+    it "sets dispatch_status to :waiting on new job" do
+      Job.new.dispatch_state.should be(:waiting)
+    end
+
+    describe "#dispatch_state_machine on job " do
+      it "#all_states contains only :waiting" do
+        all_states = Job.new.dispatch_state_machine.all_states
+      
+        all_states.size.should == 1
+        all_states.should include(:waiting)
+      end    
+    end
+  end  
+
+  context "when initial :waiting and other :assigned, :accepted, :cancelled and :closed states are defined also" do
+    before :all do
+      Job.implement_state_machine_for :dispatch_state do
+        initial_state :waiting
+        other_states :assigned, :accepted, :cancelled, :closed
+      end
+    end
+    it "#dispatch_state_machine#all_states has 5 states" do
+      Job.new.dispatch_state_machine.all_states.should have(5).states
+    end
+
+    context "for defined :assign transition from :waiting to :assigned" do
+      before :all do
+        @inner_state_machine_class = Job.new.dispatch_state_machine.class
+        @inner_state_machine_class.allow_transition :assign, :from => :waiting, :to => :assigned
+      end
+      describe "#dispatch_state_machine#allowed_transitions" do
+        it "contains only :assign when in :waiting state" do
+          job = Job.new
+        
+          job.dispatch_state_machine.should have(1).allowed_transitions
+          job.dispatch_state_machine.allowed_transitions.should include(:assign)
+        end
+        it "doesn't contain :assign if job#guard_for_assign_on_dispatch_state returns false" do
+          Job.any_instance.stubs(:guard_for_assign_on_dispatch_state).returns false
+        
+          Job.new.dispatch_state_machine.should have(0).allowed_transitions
+        end
+        it "contains :assign if job#guard_for_assign_on_dispatch_state returns true" do
+          Job.any_instance.stubs(:guard_for_assign_on_dispatch_state).returns true
+        
+          Job.new.dispatch_state_machine.allowed_transitions.should include(:assign)
+        end
+        it "raises exception if there's attempt to define again :assign transition from :waiting state" do
+          @inner_state_machine_class = Job.new.dispatch_state_machine.class
+          lambda { @inner_state_machine_class.allow_transition :assign, :from => :waiting, :to => :closed }.should( raise_error do |e|
+            e.message.should match("Already defined transition 'assign' from 'waiting' state")
+          end )
+        end
+      end
+      describe "assign transition" do
+        context "when it is allowed" do
+          it "returns :assigned" do
+            job = Job.new
+            job.dispatch_state_machine.assign.should be(:assigned)
+          end
+          it "sets dispatch_state to :assigned" do
+            job = Job.new
+            job.dispatch_state_machine.assign
+          
+            job.dispatch_state.should be(:assigned)
+          end
+          it "calls job#after_dispatch_state_changed callback if defined" do
+            Job.any_instance.expects(:after_dispatch_state_changed)
+            Job.new.dispatch_state_machine.assign
+          end
+        end
+        context "when it is not valid transition from current state" do
+          it "raises an error" do
+            @inner_state_machine_class.allow_transition :reject, :from => :assigned, :to => :waiting
+          
+            job = Job.new
+            lambda { job.dispatch_state_machine.reject }.should( raise_error do |e|
+              e.message.should match("Invalid transition #reject from 'waiting' state")
+            end )
+          end
+        end
+        context "when it is not valid transition due to guard method" do
+          it "raises an error" do
+            Job.any_instance.stubs(:guard_for_assign_on_dispatch_state).returns false
+          
+            job = Job.new
+            lambda { job.dispatch_state_machine.assign }.should( raise_error do |e|
+              e.message.should match("Unable to assign due to guard")
+            end )
+          end
+        end
+      end
+      describe "transition guards" do
+        it "#can_assign? responds as true" do
+          job = Job.new
+          
+          job.dispatch_state_machine.allowed_transitions.should include(:assign)
+          job.dispatch_state_machine.can_assign?.should be_true
+        end
+        it "responds as false for #can_go_back? if :go_back is not allowed transition but is defined" do
+          @inner_state_machine_class.allow_transition :go_back, :from => :assigned, :to => :waiting
+          
+          job = Job.new
+          
+          job.dispatch_state_machine.allowed_transitions.should_not include(:go_back)
+          job.dispatch_state_machine.can_go_back?.should be_false
+        end
+        it "raises an error for #can_do_something_undefined? if :do_something_undefined is not defined transition" do
+          lambda { Job.new.dispatch_state_machine.can_do_something_undefined? }.should( raise_error do |e|
+            e.message.should include("undefined method `can_do_something_undefined?'")
+          end )
+        end
+      end
+    end
+  end
+  context "when there are more job instances" do
+    before :all do
+      Job.implement_state_machine_for :dispatch_state do
+        allow_transition :accept, :from => :assigned, :to => :accepted
+      end
+    end
+    
+    it "each instance tracks it's own flow" do
+      job1 = Job.new
+      job2 = Job.new
+      job3 = Job.new
+      
+      job1.dispatch_state_machine.assign
+      job2.dispatch_state_machine.assign
+      job2.dispatch_state_machine.accept
+      
+      job1.dispatch_state.should be(:assigned)
+      job2.dispatch_state.should be(:accepted)
+      job3.dispatch_state.should be(:waiting)
+    end
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: simple_machine
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Milan Burmaja
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-13 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: 
+email: burmajam@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.rdoc
+- lib/simple_machine.rb
+- spec/spec_simple_machine.rb
+has_rdoc: true
+homepage: http://github.com/burmajam/SimpleMachine
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: simple_machine
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: SimpleMachine is module for Ruby which injects simple state machine behavior in any class that includes it
+test_files: []
+