= 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. :)

* http://github.com/pluginaweek/state_machine/tree/master
* http://github.com/davidlee/stateful/tree/master
* http://github.com/sbfaulkner/has_states/tree/master
