Edge State Machine

Edge State Machine is a complete state machine solution. It offers support for ActiveRecord, Mongoid and MongoMapper for persistence.

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

# in your Gemfile
gem "edge-state-machine", :require => ["edge-state-machine", "active_record/edge-state-machine"]

# in your AR models that will use the state machine
include ::EdgeStateMachine
include ActiveRecord::EdgeStateMachine

state_machine do
state :available # first one is initial state
state :out_of_stock
state :discontinue

event :discontinue do
  transitions :to => :discontinue, :from => [:available, :out_of_stock], :on_transition => :do_discontinue
end
event :out_of_stock do
  transitions :to => :out_of_stock, :from => [:available, :discontinue]
end
event :available do
  transitions :to => :available, :from => [:out_of_stock], :on_transition => :send_alerts
end
end

If you're using Rails + Mongoid + Bundler

# in your Gemfile
gem "edge-state-machine", :require => ["edge-state-machine", "mongoid/edge-state-machine"]

# in your AR models that will use the state machine
include ::EdgeStateMachine
include Mongoid::EdgeStateMachine

state_machine do
state :available # first one is initial state
state :out_of_stock
state :discontinue

event :discontinue do
  transitions :to => :discontinue, :from => [:available, :out_of_stock], :on_transition => :do_discontinue
end
event :out_of_stock do
  transitions :to => :out_of_stock, :from => [:available, :discontinue]
end
event :available do
  transitions :to => :available, :from => [:out_of_stock], :on_transition => :send_alerts
end
end

If you're using Rails + MongoMapper + Bundler

# in your Gemfile
gem "edge-state-machine", :require => ["edge-state-machine", "mongo_mapper/edge-state-machine"]

# in your models that will use the state machine
include ::EdgeStateMachine
include MongoMapper::EdgeStateMachine

state_machine do
state :available # first one is initial state
state :out_of_stock
state :discontinue

event :discontinue do
  transitions :to => :discontinue, :from => [:available, :out_of_stock], :on_transition => :do_discontinue
end
event :out_of_stock do
  transitions :to => :out_of_stock, :from => [:available, :discontinue]
end
event :available do
  transitions :to => :available, :from => [:out_of_stock], :on_transition => :send_alerts
end
end

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
• Examples with ActiveRecord
• Examples with Mongoid
• Examples with Mongoid
• Examples with MongoMapper

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.

And on Krzysiek Heród's gem, Transitions, which added Mongoid support.