state_machine

state_machine adds support for creating state machines for attributes on any Ruby class.

Resources

API

• api.pluginaweek.org/state_machine

Bugs

• pluginaweek.lighthouseapp.com/projects/13288-state_machine

Development

• github.com/pluginaweek/state_machine

Source

• git://github.com/pluginaweek/state_machine.git

Description

State machines make it dead-simple to manage the behavior of a class. Too often, the status of an object is kept by creating multiple boolean attributes and deciding how to behave based on the values. This can become cumbersome and difficult to maintain when the complexity of your class starts to increase.

state_machine simplifies this design by introducing the various parts of a real state machine, including states, events, transitions, and callbacks. However, the api is designed to be so simple you don’t even need to know what a state machine is :)

Some brief, high-level features include:

• Defining state machines on any Ruby class
• Multiple state machines on a single class
• before/after transition hooks with explicit transition requirements
• ActiveRecord integration
• DataMapper integration
• Sequel integration
• States of any data type
• State predicates
• GraphViz visualization creator

Examples of the usage patterns for some of the above features are shown below. You can find more detailed documentation in the actual API.

Usage

Example

Below is an example of many of the features offered by this plugin, including

• Initial states
• Transition callbacks
• Conditional transitions

  class Vehicle

    attr_accessor :seatbelt_on
  
    state_machine :state, :initial => 'parked' do
      before_transition :from => %w(parked idling), :do => :put_on_seatbelt
      after_transition :on => 'crash', :do => :tow
      after_transition :on => 'repair', :do => :fix
      after_transition :to => 'parked' do |vehicle, transition|
        vehicle.seatbelt_on = false
      end
  
      event :park do
        transition :to => 'parked', :from => %w(idling first_gear)
      end
  
      event :ignite do
        transition :to => 'stalled', :from => 'stalled'
        transition :to => 'idling', :from => 'parked'
      end
  
      event :idle do
        transition :to => 'idling', :from => 'first_gear'
      end
  
      event :shift_up do
        transition :to => 'first_gear', :from => 'idling'
        transition :to => 'second_gear', :from => 'first_gear'
        transition :to => 'third_gear', :from => 'second_gear'
      end
  
      event :shift_down do
        transition :to => 'second_gear', :from => 'third_gear'
        transition :to => 'first_gear', :from => 'second_gear'
      end
  
      event :crash do
        transition :to => 'stalled', :from => %w(first_gear second_gear third_gear), :unless => :auto_shop_busy?
      end
  
      event :repair do
        transition :to => 'parked', :from => 'stalled', :if => :auto_shop_busy?
      end
    end
  
    def initialize
      @seatbelt_on = false
    end
  
    def put_on_seatbelt
      @seatbelt_on = true
    end
  
    def auto_shop_busy?
      false
    end
  
    def tow
      # tow the vehicle
    end
  
    def fix
      # get the vehicle fixed by a mechanic
    end
  

  end

Using the above class as an example, you can interact with the state machine like so:

  vehicle = Vehicle.new           # => #<Vehicle:0xb7cf4eac @state="parked", @seatbelt_on=false>
  vehicle.parked?                 # => true
  vehicle.can_ignite?             # => true
  vehicle.next_ignite_transition  # => #<StateMachine::Transition:0xb7c34cec ...>
  vehicle.ignite                  # => true
  vehicle.parked?                 # => false
  vehicle.idling?                 # => true
  vehicle                         # => #<Vehicle:0xb7cf4eac @state="idling", @seatbelt_on=true>
  vehicle.shift_up                # => true
  vehicle                         # => #<Vehicle:0xb7cf4eac @state="first_gear", @seatbelt_on=true>
  vehicle.shift_up                # => true
  vehicle                         # => #<Vehicle:0xb7cf4eac @state="second_gear", @seatbelt_on=true>

  # The bang (!) operator can raise exceptions if the event fails
  vehicle.park!                   # => StateMachine::InvalidTransition: Cannot transition via :park from "second_gear"

  # Generic state predicates can raise exceptions if the value does not exist
  vehicle.state?('parked')        # => true
  vehicle.state?('invalid')       # => ArgumentError: "parked" is not a known state value

Integrations

In addition to being able to define state machines on all Ruby classes, a set of out-of-the-box integrations are available for some of the more popular Ruby libraries. These integrations add library-specific behavior, allowing for state machines to work more tightly with the conventions defined by those libraries.

The integrations currently available include:

• ActiveRecord models
• DataMapper resources
• Sequel models

A brief overview of these integrations is described below.

ActiveRecord

The ActiveRecord integration adds support for database transactions, automatically saving the record, named scopes, and observers. For example,

  class Vehicle < ActiveRecord::Base
    state_machine :initial => 'parked' do
      before_transition :to => 'idling', :do => :put_on_seatbelt
      after_transition :to => 'parked' do |vehicle, transition|
        vehicle.seatbelt = 'off'
      end

      event :ignite do
        transition :to => 'idling', :from => 'parked'
      end
    end

    def put_on_seatbelt
      ...
    end
  end

  class VehicleObserver < ActiveRecord::Observer
    # Callback for :ignite event *before* the transition is performed
    def before_ignite(vehicle, transition)
      # log message
    end

    # Generic transition callback *before* the transition is performed
    def after_transition(vehicle, transition)
      Audit.log(vehicle, transition)
    end
  end

For more information about the various behaviors added for ActiveRecord state machines, see StateMachine::Integrations::ActiveRecord.

With enumerations

Using the acts_as_enumeration plugin with an ActiveRecord integration, states can be transparently stored using record ids in the database like so:

  class VehicleState < ActiveRecord::Base
    acts_as_enumeration

    create :id => 1, :name => 'parked'
    create :id => 2, :name => 'idling'
    ...
  end

  class Vehicle < ActiveRecord::Base
    belongs_to :state, :class_name => 'VehicleState'

    state_machine :state, :initial => 'parked' do
      ...

      event :park do
        transition :to => 'parked', :from => %w(idling first_gear)
      end
    end

    ...
  end

Notice that the state machine definition remains exactly the same. However, when interacting with the records, the actual state will be stored using the identifiers defined for the enumeration:

  vehicle = Vehicle.create  # => #<Vehicle id: 1, seatbelt_on: false, state_id: 1>
  vehicle.ignite            # => true
  vehicle                   # => #<Vehicle id: 1, seatbelt_on: true, state_id: 2>

This allows states to take on more complex functionality other than just being a string value.

DataMapper

Like the ActiveRecord integration, the DataMapper integration adds support for database transactions, automatically saving the record, named scopes, Extlib-like callbacks, and observers. For example,

  class Vehicle
    include DataMapper::Resource

    property :id, Serial
    property :state, String

    state_machine :initial => 'parked' do
      before_transition :to => 'idling', :do => :put_on_seatbelt
      after_transition :to => 'parked' do |transition|
        self.seatbelt = 'off' # self is the record
      end

      event :ignite do
        transition :to => 'idling', :from => 'parked'
      end
    end

    def put_on_seatbelt
      ...
    end
  end

  class VehicleObserver
    include DataMapper::Observer

    observe Vehicle

    # Callback for :ignite event *before* the transition is performed
    before_transition :on => :ignite do |transition|
      # log message (self is the record)
    end

    # Generic transition callback *before* the transition is performed
    after_transition do |transition, saved|
      Audit.log(self, transition) if saved # self is the record
    end
  end

For more information about the various behaviors added for DataMapper state machines, see StateMachine::Integrations::DataMapper.

Sequel

Like the ActiveRecord integration, the Sequel integration adds support for database transactions, automatically saving the record, named scopes, and callbacks. For example,

  class Vehicle < Sequel::Model
    state_machine :initial => 'parked' do
      before_transition :to => 'idling', :do => :put_on_seatbelt
      after_transition :to => 'parked' do |transition|
        self.seatbelt = 'off' # self is the record
      end

      event :ignite do
        transition :to => 'idling', :from => 'parked'
      end
    end

    def put_on_seatbelt
      ...
    end
  end

For more information about the various behaviors added for Sequel state machines, see StateMachine::Integrations::Sequel.

Tools

Generating graphs

This library comes with built-in support for generating di-graphs based on the events, states, and transitions defined for a state machine using GraphViz. This requires that both the ruby-graphviz gem and graphviz library be installed on the system.

Examples

To generate a graph for a specific file / class:

  rake state_machine:draw FILE=vehicle.rb CLASS=Vehicle

To save files to a specific path:

  rake state_machine:draw FILE=vehicle.rb CLASS=Vehicle TARGET=files

To customize the image format:

  rake state_machine:draw FILE=vehicle.rb CLASS=Vehicle FORMAT=jpg

To generate multiple state machine graphs:

  rake state_machine:draw FILE=vehicle.rb,car.rb CLASS=Vehicle,Car

Note that this will generate a different file for every state machine defined in the class. The generates files will an output filename of the format #{class_name}_#{attribute}.#{format}.

For examples of actual images generated using this task, see those under the test/examples folder.

Ruby on Rails Integration

There is a special integration Rake task for generating state machines for classes used in a Ruby on Rails application. This task will load the application environment, meaning that it’s unnecessary to specify the actual file to load.

For example,

  rake state_machine:draw:rails CLASS=Vehicle

Merb Integration

Like Ruby on Rails, there is a special integration Rake task for generating state machines for classes used in a Merb application. This task will load the application environment, meaning that it’s unnecessary to specify the actual files to load.

For example,

  rake state_machine:draw:merb CLASS=Vehicle

Interactive graphs

Jean Bovet - Visual Automata Simulator. This is a great tool for "simulating, visualizing and transforming finite state automata and Turing Machines". This tool can help in the creation of states and events for your models. It is cross-platform, written in Java.

Testing

To run the entire test suite (will test ActiveRecord, DataMapper, and Sequel integrations if available):

  rake test

Dependencies

By default, there are no dependencies. If using specific integrations, those dependencies are listed below.

• ActiveRecord integration: 2.1.0 or later
• DataMapper integration: 0.9.0 or later
• Sequel integration: 2.8.0 or later

References

• Scott Barron - acts_as_state_machine
• acts_as_enumeration