File: README.rdoc [dm-is-state_machine-1.2.0 Documentation]

### Home Classes Methods

### Files

- LICENSE
- README.rdoc

### Class Index

Quicksearch

- DataMapper
- DataMapper::Is
- DataMapper::Is::StateMachine
- DataMapper::Is::StateMachine::Data
- DataMapper::Is::StateMachine::Data::Event
- DataMapper::Is::StateMachine::Data::Machine
- DataMapper::Is::StateMachine::Data::State
- DataMapper::Is::StateMachine::DuplicateStates
- DataMapper::Is::StateMachine::EventConfusion
- DataMapper::Is::StateMachine::EventDsl
- DataMapper::Is::StateMachine::InstanceMethods
- DataMapper::Is::StateMachine::InvalidContext
- DataMapper::Is::StateMachine::InvalidEvent
- DataMapper::Is::StateMachine::InvalidState
- DataMapper::Is::StateMachine::NoInitialState
- DataMapper::Is::StateMachine::StateDsl

No matching classes.

# 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

[Validate]

Generated with the Darkfish Rdoc Generator 2.