dm-is-state_machine

DataMapper plugin that adds state machine functionality to your models.

Why is this plugin useful?

Your DataMapper resource might benefit from a state machine if it:

has different "modes" of operation
has discrete behaviors
especially if the behaviors are mutually exclusive

And you want a clean, high-level way of describing these modes / behaviors and how the resource moves between them. This plugin allows you to declaratively describe the states and transitions involved.

Installation

Download dm-more.
Install dm-is-state_machine using the supplied rake files.

Setting up with Merb ##

Add this line to your init.rb:

dependency "dm-is-state_machine"

Example DataMapper resource (i.e. model)

# /app/models/traffic_light.rb
class TrafficLight
include DataMapper::Resource

property :id, Serial

is :state_machine, :initial => :green, :column => :color do
  state :green
  state :yellow
  state :red,    :enter => :red_hook
  state :broken

  event :forward do
    transition :from => :green,  :to => :yellow
    transition :from => :yellow, :to => :red
    transition :from => :red,    :to => :green
  end
end

def red_hook
  # Do something
end
end

What this gives you

Explained in words

The above DSL (domain specific language) does these things "behind the scenes":

Defines a DataMapper property called 'color'.
Makes the current state available by using 'traffic_light.color'.
Defines the 'forward!' transition method. This method triggers the appropriate transition based on the current state and comparing it against the various :from states. It will raise an error if you attempt to call it with an invalid state (such as :broken, see above). After the method runs successfully, the state machine will be left in the :to state.

Explained with some code examples

# Somewhere in your controller, perhaps
light = TrafficLight.new

# Move to the next state
light.forward!

# Do something based on the current state
case light.color
when "green"
  # do something green-related
when "yellow"
  # do something yellow-related
when "red"
  # do something red-related
end

Specific examples

We would also like to hear how you are using state machines in your code.