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¶ ↑

1. Download dm-more.

2. 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”:

1. Defines a DataMapper property called ‘color’.

2. Makes the current state available by using ‘traffic_light.color’.

3. 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.

See also¶ ↑

Here are some other projects you might want to look at. Most of them are probably intended for ActiveRecord. They take different approaches, which is pretty interesting. If you find something you like in these other projects, let us know. Maybe we can incorporate some of your favorite parts. That said, I do not want to create a Frankenstein. :)

• github.com/pluginaweek/state_machine/tree/master

• github.com/davidlee/stateful/tree/master

• github.com/sbfaulkner/has_states/tree/master