SSM - Simple State Machine mixin

SSM is a mixin that adds finite-state machine behavior to a class.

Installation

gem sources -a http://gems.github.com
sudo gem install spoonsix-ssm

Simple example usage

class Door
  include SSM

  ssm_initial_state :closed # required
  ssm_state :opened

  ssm_event :open, :from => [:closed], :to => :opened do
    puts "Just opened door"
  end

  ssm_event :close, :from => [:opened], :to => :closed do
    puts "Closed door"
  end

end

door = Door.new
door.open
door.is?(:opened) #=> true
door.close
door.is_not?(:opened) #=> true
door.is?(:closed) #=> true

Persistence

SSM does not worry about persistence. It does allow the user to specify an instance property to store the State in, either as a string (default) or as an integer. This can then be persisted. SSM will recover state based on this property.

Integrating with Rails and ActiveRecord

In your config/environment.rb file:

config.gem 'spoonsix-ssm', :lib => 'ssm', :version => '>= 0.1.8', :source => 'http://gems.github.com'

Then run:

rake gems:install
rake gems:unpack # Optional, if you want to vendor the gem

Add a migration to include the state column, either as a string or integer, for instance:

create_table :doors do |t|
  t.integer :state # Needed to store the current state as an integer
end

Setup your ActiveRecord object to use SSM, as

class Door < ActiveRecord:Base
  include SSM

  ssm_inject_state_into :state, :as_integer => true, :strategy => :active_record

  ssm_initial_state :closed # required
  ssm_state :opened
  ...
end

door = Door.new
door.open
door.is?(:opened) #=> true
door.state #=> 1
door.save

persisted_door = Door.find(door.id)
persisted_door.is?(:opened) #=> true

Integrating with DataMapper

Comming soon...

Writing custom strategies

Comming soon...

Inspiration and resources

• http://en.wikipedia.org/wiki/Finite-state_machine
• http://github.com/rubyist/aasm
• http://www.ibm.com/developerworks/java/library/j-cb03137/index.html

License

SSM - Simple State Machine mixin Copyright (C) 2009 spoonsix - Luis Corrêa d'Almeida

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.