edge-state-machine 0.0.3 → 0.9.0

data/README.rdoc

@@ -1,10 +1,20 @@
 = Edge State Machine
 
-Edge state machine wants to be a complete state machine solution.
-It offers support for ActiveRecord and Mongoid
+Edge State Machine is a complete state machine solution.
+It offers support for ActiveRecord and Mongoid for persistence.
 
 {<img src="https://secure.travis-ci.org/danpersa/edge-state-machine.png"/>}[http://travis-ci.org/danpersa/edge-state-machine]
 
+== Supported Features
+
+* Multiple state machines per class each of them acting independently
+* Find errors in state machine definitions as early as possible
+* Transition guards
+* Multiple actions executed on transitions
+* Multiple actions executed on entering and exiting a state
+* No other dependencies for non-persistent state machines
+* Minimal dependencies for persistent ones
+
 == Installation
 
 If you're using Rails + ActiveRecord + Bundler
@@ -57,10 +67,124 @@ If you're using Rails + Mongoid + Bundler
     end
   end
 
-= Credits
+== State Machine Examples
+
+=== Microwave State Machine
+
+  class Microwave
+    state_machine :microwave do  # name should be optional, if the name is not present, it should have a default name
+                                 # we give state machines names, so we can pun many machines inside a class
+      initial_state :unplugged # initial state should be optional, if the initial state is not present, the initial state will be the first defined state
+
+      state :unplugged
+
+      state :plugged
+
+      state :door_opened do
+        enter :light_on            # enter should be executed on entering the state
+        exit  :light_off           # exit method should be executed on exiting the state
+      end
+
+      state :door_closed
+
+      state :started_in_grill_mode do
+        enter lambda { |t| p "Entering hate" }   # should have support for Procs
+        exit  :grill_off
+      end
+
+      state :started do
+        enter :microwaves_on
+        exit  :microwaves_off
+      end
+
+      event :plug_in do
+        transition :from => :unplugged, :to => :plugged
+      end
+
+      event :open_door do
+        transition :from => :plugged, :to => :door_opened
+      end
+
+      event :close_door do
+        transition :from => :door_opened, :to => :door_closed,
+                   :on_transition => :put_food_in_the_microwave # we can put many actions in an Array for the on_transition parameter
+      end
+
+      event :start do
+        transition :from => :door_closed, :to => [:started, :started_in_grill_mode],
+                   :on_transition => :start_spinning_the_food,
+                   :guard => :grill_button_pressed?    # the method grill_button_pressed? should choose the next state 
+      end
+
+      event :stop do
+          transition :from => [:started, :started_in_grill_mode], :to => :door_closed
+      end
+    end  
+  end 
+
+=== Dice State Machine
+
+  class Dice
+
+    state_machine do
+      state :one
+      state :two
+      state :three
+      state :four
+      state :five
+      state :six
+
+      event :roll do
+        transition :from => [:one, :two, :three, :four, :five, :six],
+                   :to => [:one, :two, :three, :four, :five, :six],
+                   :guard => :roll_result,
+                   :on_transition => :display_dice_rolling_animation
+      end
+    end
+
+    def roll_result
+      # return one of the states
+    end
+
+    def display_dice_rolling_animation
+      # draw the new position of the dice
+    end
+  end
+
+  class User
+    state_machine do
+      state :pending # first one is initial state
+      state :active
+      state :blocked # the user in this state can't sign in
+
+      event :activate do
+        transition :from => [:pending], :to => :active, :on_transition => :do_activate
+      end
+
+      event :block do
+        transition :from => [:pending, :active], :to => :blocked
+      end
+    end    
+  end
+
+=== Other Examples
+
+For other (more complex) examples, please check the following links:
+
+* {Examples without Persistence}[https://github.com/danpersa/edge-state-machine/tree/master/spec/non_persistent/samples]
+* {Examples with ActiveRecord}[https://github.com/danpersa/edge-state-machine/tree/master/spec/active_record/samples]
+* {Examples with Mongoid}[https://github.com/danpersa/edge-state-machine/tree/master/spec/mongoid/samples]
+
+== Notes
+
+For classes with multiple state machines, the state names, machine names must be unique per class.
+
+The same thing with the event names.
+
+== Credits
 
 The gem is based on Rick Olson's code of ActiveModel::StateMachine,
 axed from ActiveModel in {this
 commit}[http://github.com/rails/rails/commit/db49c706b62e7ea2ab93f05399dbfddf5087ee0c].
 
-And on Krzysiek Heród's gem, {Transitions}[https://github.com/netizer/transitions], which added Mongoid support.
+And on Krzysiek Heród's gem, {Transitions}[https://github.com/netizer/transitions], which added Mongoid support.

data/edge-state-machine.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   s.authors     = ["Dan Persa"]
   s.email       = ["dan.persa@gmail.com"]
   s.homepage    = "http://github.com/danpersa/edge-state-machine"
-  s.summary     = %q{State machine extracted from ActiveModel}
-  s.description = %q{Lightweight state machine extracted from ActiveModel}
+  s.summary     = %q{Edge State Machine}
+  s.description = %q{Edge State Machine is a complete state machine solution. It offers support for ActiveRecord and Mongoid for persistence.}
 
   s.rubyforge_project = "edge-state-machine"
 

data/lib/edge-state-machine/version.rb

@@ -1,3 +1,3 @@
 module EdgeStateMachine
-  VERSION = "0.0.3"
+  VERSION = "0.9.0"
 end

data/spec/active_record/active_record_helper.rb

@@ -3,8 +3,10 @@ require 'active_record'
 require 'active_support/core_ext/module/aliasing'
 require 'active_record/migrations/create_orders'
 require 'active_record/migrations/create_traffic_lights'
+require 'active_record/migrations/create_double_machine'
 require 'active_record/samples/traffic_light'
 require 'active_record/samples/order'
+require 'active_record/samples/double_machine'
 
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", 'lib'))
 $LOAD_PATH.unshift(File.dirname(__FILE__))

data/spec/active_record/active_record_spec.rb

@@ -1,127 +1,129 @@
 require 'active_record/active_record_helper'
 
-describe "active record state machine" do
+describe 'active record state machine' do
 
-  context "existing active record" do
+  context 'existing active record' do
     before do
-      ActiveRecord::Base.establish_connection(:adapter  => "sqlite3", :database => ":memory:")
+      ActiveRecord::Base.establish_connection(:adapter  => 'sqlite3', :database => ':memory:')
       ActiveRecord::Migration.verbose = false
       CreateTrafficLights.migrate(:up)
-      @light = TrafficLight.create!
     end
 
-    it "should have an initial state" do
-      @light.off?.should == true
-      @light.current_state.should == :off
+    let :light do
+      TrafficLight.create!
     end
 
-    it "should go to a valid state on transition" do
-      @light.reset
-      @light.red?.should == true
-      @light.current_state.should == :red
+    it 'should have an initial state' do
+      light.off?.should == true
+      light.current_state.should == :off
+    end
+
+    it 'should go to a valid state on transition' do
+      light.reset
+      light.red?.should == true
+      light.current_state.should == :red
 
-      @light.green_on
-      @light.green?.should == true
-      @light.current_state.should == :green
+      light.green_on
+      light.green?.should == true
+      light.current_state.should == :green
     end
 
-    it "should not persist state on transition" do
-      @light.reset
-      @light.current_state.should == :red
-      @light.reload
-      @light.state.should == "off"
+    it 'should not persist state on transition' do
+      light.reset
+      light.current_state.should == :red
+      light.reload
+      light.state.should == 'off'
     end
 
-    it "should persists state on transition" do
-      @light.reset!
-      @light.current_state.should == :red
-      @light.reload
-      @light.state.should == "red"
+    it 'should persists state on transition' do
+      light.reset!
+      light.current_state.should == :red
+      light.reload
+      light.state.should == 'red'
     end
 
-    it "should initialize the current state when loaded from database" do
-      @light.reset!
-      loaded_light = TrafficLight.find_by_id(@light.id)
+    it 'should initialize the current state when loaded from database' do
+      light.reset!
+      loaded_light = TrafficLight.find_by_id(light.id)
       loaded_light.current_state.should == :red
     end
 
-    it "should raise error on transition to an invalid state" do
-      expect { @light.yellow_on }.should raise_error EdgeStateMachine::NoTransitionFound
-      @light.current_state.should == :off
+    it 'should raise error on transition to an invalid state' do
+      expect { light.yellow_on }.should raise_error EdgeStateMachine::NoTransitionFound
+      light.current_state.should == :off
     end
 
-    it "should persist state when state is protected on transition" do
+    it 'should persist state when state is protected on transition' do
       protected_light = ProtectedTrafficLight.create!
       protected_light.reset!
       protected_light.current_state.should == :red
       protected_light.reload
-      protected_light.state.should == "red"
+      protected_light.state.should == 'red'
     end
 
-    it "should not validate when try transition with wrong state " do
-      for s in @light.class.state_machines[:default].states.keys
-        @light.state = s
-        @light.valid?.should == true
+    it 'should not validate when try transition with wrong state' do
+      for s in light.class.state_machines[:default].states.keys
+        light.state = s
+        light.valid?.should == true
       end
-      @light.state = "invalid_one"
-      @light.valid?.should_not == true
+      light.state = 'invalid_one'
+      light.valid?.should_not == true
     end
 
-    it "should raise exception when model validation fails on transition" do
+    it 'should raise exception when model validation fails on transition' do
       validating_light = ValidatingTrafficLight.create!
       expect {validating_light.reset!}.should raise_error ActiveRecord::RecordInvalid
       validating_light.red?.should == false
       validating_light.off?.should == true
     end
 
-    it "should state query method used in a validation condition" do
+    it 'should state query method used in a validation condition' do
       validating_light = ConditionalValidatingTrafficLight.create!
       #expect {validating_light.reset!}.should raise_error ActiveRecord::RecordInvalid
       validating_light.off?.should == true
       validating_light.red?.should == false
     end
 
-    it "should reload the model when current state resets" do
-      @light.reset
-      @light.red?.should == true
-      @light.update_attribute(:state, 'green')
-      @light.reload.green?.should == true # reloaded state should come from database
+    it 'should reload the model when current state resets' do
+      light.reset
+      light.red?.should == true
+      light.update_attribute(:state, 'green')
+      light.reload.green?.should == true # reloaded state should come from database
     end
 
-    describe "scopes" do
-      it "should be added for each state" do
+    describe 'scopes' do
+      it 'should be added for each state' do
         TrafficLight.should respond_to(:off)
         TrafficLight.should respond_to(:red)
       end
 
-      it "should not be added for each state" do
-        #TrafficLightNoScope.should_not respond_to(:off)
-        #TrafficLightNoScope.should_not respond_to(:red)
+      it 'should not be added for each state' do
+        TrafficLightNoScope.should_not respond_to(:off)
+        TrafficLightNoScope.should_not respond_to(:red)
       end
 
-      it "should behave like scopes" do
-        3.times { TrafficLight.create(:state => "off") }
-        3.times { TrafficLight.create(:state => "red") }
-        # one was created before
-        TrafficLight.off.count.should == 4
+      it 'should behave like scopes' do
+        3.times { TrafficLight.create(:state => 'off') }
+        3.times { TrafficLight.create(:state => 'red') }
+        TrafficLight.off.count.should == 3
         TrafficLight.red.count.should == 3
       end
     end
   end
 
-  context "new active record" do
-    before do
-      @light = TrafficLight.new
+  context 'new active record' do
+    let :light do
+      TrafficLight.new
     end
 
-    it "should have the initial state set" do
-      @light.current_state.should == :off
+    it 'should have the initial state set' do
+      light.current_state.should == :off
     end
   end
 
-  context "timestamp" do
+  context 'timestamp' do
     before do
-      ActiveRecord::Base.establish_connection(:adapter  => "sqlite3", :database => ":memory:")
+      ActiveRecord::Base.establish_connection(:adapter  => 'sqlite3', :database => ':memory:')
       ActiveRecord::Migration.verbose = false
       CreateOrders.migrate(:up)
     end
@@ -131,10 +133,10 @@ describe "active record state machine" do
     end
 
     # control case, no timestamp has been set so we should expect default behaviour
-    it "should not raise any exceptions when moving to placed" do
+    it 'should not raise any exceptions when moving to placed' do
       @order = create_order
       expect { @order.place! }.should_not raise_error
-      @order.state.should == "placed"
+      @order.state.should == 'placed'
     end
   end
 end

data/spec/active_record/double_machine_spec.rb

@@ -0,0 +1,75 @@
+require 'active_record/active_record_helper'
+
+describe DoubleMachineActiveRecord do
+
+  before do
+    ActiveRecord::Base.establish_connection(:adapter  => "sqlite3", :database => ":memory:")
+    ActiveRecord::Migration.verbose = false
+    CreateDoubleMachine.migrate(:up)
+  end
+
+  let :double_machine do
+    DoubleMachineActiveRecord.create!
+  end
+
+  it 'should have a current state equals with the initial state for each machine' do
+    double_machine.current_state.should == :first_state
+    double_machine.current_state(:second).should == :red
+  end
+
+  it 'should have the corresponding methods for verifying the states' do
+    double_machine.first_state?.should == true
+    double_machine.second_state?.should == false
+    double_machine.red?.should == true
+    double_machine.green?.should == false
+  end
+
+  it 'should trigger events from the state machines' do
+    double_machine.first_move
+    double_machine.current_state.should == :second_state
+    double_machine.second_state?.should == true
+
+    double_machine.go_green
+    double_machine.current_state(:second).should == :green
+    double_machine.green?.should == true
+
+    double_machine.second_move
+    double_machine.current_state.should == :third_state
+    double_machine.third_state?.should == true
+  end
+
+  it 'should execute the on_transition method' do
+    double_machine.should_receive :do_move
+    double_machine.first_move
+    double_machine.go_green
+
+    double_machine.should_receive :turn_off
+    double_machine.should_receive :color_in_red
+    double_machine.go_red
+  end
+
+  context 'persistence ' do
+    it 'should create scopes for each state machine' do
+      3.times { DoubleMachineActiveRecord.create(:state => 'second_state', :second_state => 'blue') }
+      3.times { DoubleMachineActiveRecord.create(:state => 'first_state', :second_state => 'blue') }
+      DoubleMachineActiveRecord.first_state.count.should == 3
+      DoubleMachineActiveRecord.second_state.count.should == 3
+      DoubleMachineActiveRecord.blue.count.should == 6
+    end
+
+    it 'should save the state machines in the database' do
+      machine = DoubleMachineActiveRecord.create(:state => 'second_state', :second_state => 'blue')
+      machine.go_red!
+      machine.current_state(:second).should == :red
+      machine.red?.should == true
+
+      machine.second_move!
+      machine.third_state?.should == true
+      machine.current_state.should == :third_state
+
+      loaded_machine = DoubleMachineActiveRecord.find_by_id(machine.id)
+      loaded_machine.third_state?.should == true
+      loaded_machine.current_state.should == :third_state
+    end
+  end
+end

data/spec/active_record/migrations/create_double_machine.rb

@@ -0,0 +1,8 @@
+class CreateDoubleMachine < ActiveRecord::Migration
+  def self.up
+    create_table(:double_machine_active_records, force: true) do |t|
+      t.string :state
+      t.string :second_state
+    end
+  end
+end

data/spec/active_record/samples/double_machine.rb

@@ -0,0 +1,59 @@
+require 'active_record'
+require 'active_record/edge-state-machine'
+
+ActiveRecord::Base.establish_connection(:adapter  => "sqlite3", :database => ":memory:")
+
+class DoubleMachineActiveRecord < ActiveRecord::Base
+  include ActiveRecord::EdgeStateMachine
+
+  state_machine do
+    # the machine is automatically named :default
+    # the scopes are not created by default
+    create_scopes true
+    # the persistence instance variable is the default one (:state)
+    state :first_state # first one is initial state
+    state :second_state
+    state :third_state # the user in this state can't sign in
+
+    event :first_move do
+      transition :from => :first_state, :to => :second_state, :on_transition => :do_move
+    end
+
+    event :second_move do
+      transition :from => :second_state, :to => :third_state
+    end
+  end
+
+  state_machine :second do
+    # the scopes are not created by default
+    create_scopes true
+    # for the second machine we must specify the name of the persistence instance variable
+    # so there are no conflicts between the state machines
+    persisted_to :second_state
+    initial_state :red
+    state :blue
+    state :green
+    state :red
+
+    event :go_blue do
+      transition :from => [:red, :green], :to => :blue
+    end
+
+    event :go_red do
+      transition :from => [:blue, :green], :to => :red, :on_transition => [:turn_off, :color_in_red]
+    end
+
+    event :go_green do
+      transition :from => [:blue, :red], :to => :green
+    end
+  end
+
+  def do_move
+  end
+
+  def turn_off
+  end
+
+  def color_in_red
+  end
+end

data/spec/active_record/samples/traffic_light.rb

@@ -43,4 +43,33 @@ end
 
 class ConditionalValidatingTrafficLight < TrafficLight
   validate :name, :presence => true, :length  => { :within => 20..40 }, :confirmation => true, :if => :red?
+end
+
+class TrafficLightNoScope < ActiveRecord::Base
+  include ActiveRecord::EdgeStateMachine
+
+  state_machine do
+    persisted_to :state
+    state :off
+
+    state :red
+    state :green
+    state :yellow
+
+    event :red_on do
+      transition :to => :red, :from => [:yellow]
+    end
+
+    event :green_on do
+      transition :to => :green, :from => [:red]
+    end
+
+    event :yellow_on do
+      transition :to => :yellow, :from => [:green]
+    end
+
+    event :reset do
+      transition :to => :red, :from => [:off]
+    end
+  end
 end

data/spec/event_spec.rb

@@ -34,17 +34,17 @@ describe EdgeStateMachine::Event do
     end
   end
 
-  it "should set the name" do
+  it 'should set the name' do
     @state_name.should == @event.name
   end
 
-  it "should create Transitions" do
+  it 'should create Transitions' do
     EdgeStateMachine::Transition.should_receive(:new).with(:to => :closed, :from => [:open, :received])
     new_event
   end
 
-  describe "event arguments" do
-    it "should pass arguments to transition method" do
+  describe 'event arguments' do
+    it 'should pass arguments to transition method' do
       subject = ArgumentsTestSubject.new
       subject.current_state.should == :initial
       subject.open!
@@ -52,13 +52,13 @@ describe EdgeStateMachine::Event do
     end
   end
 
-  describe "events being fired" do
+  describe 'events being fired' do
     before do
       @machine = mock
       @machine.stub!(:name).and_return(:default)
     end
 
-    it "should raise an EdgeStateMachine::NoTransitionFound error if the transitions are empty" do
+    it 'should raise an EdgeStateMachine::NoTransitionFound error if the transitions are empty' do
       event = EdgeStateMachine::Event.new(:event, @machine)
       obj = mock
       obj.stub!(:current_state).and_return(:open)

data/spec/machine_spec.rb

@@ -31,11 +31,11 @@ describe EdgeStateMachine::Machine do
     MachineTestSubject.state_machines.size.should == 2
   end
 
-  it "should set #initial_state_name from initial_state method" do
+  it 'should set #initial_state_name from initial_state method' do
     MachineTestSubject.state_machines[:extra].initial_state_name.should == :bar
   end
 
-  it "should access non-default state machine" do
+  it 'should access non-default state machine' do
     MachineTestSubject.state_machines[:extra].class.should == EdgeStateMachine::Machine
   end
 end