fmiopensource / aasm

AASM - State machines for Ruby classes

#AASM - Ruby state machines#

This package contains AASM, a library for adding finite state machines to Ruby classes.

AASM started as the acts_as_state_machine plugin but has evolved into a more generic library that no longer targets only ActiveRecord models.

AASM has the following features:

• States
• Machines
• Events
• Transitions

##New Callbacks##

The callback chain & order on a successful event looks like:

• oldstate:exit*
• event:before
• find transition, if possible
• transition:on_transition
• oldstate:before_exit
• newstate:before_enter
• newstate:enter*
• update state
• event:success
• oldstate:after_exit
• newstate:after_enter
• event:after
• obj:aasm_event_fired

(*) marks old callbacks

##Download##

The latest AASM can currently be pulled from the git repository on github.

• http://github.com/rubyist/aasm/tree/master

##Installation##

###From gemcutter###

sudo gem install gemcutter
sudo gem tumble
sudo gem install aasm

###From GitHub hosted gems (only older releases are available)###

sudo gem sources -a http://gems.github.com # (you only need to do this once)
sudo gem install rubyist-aasm

###Building your own gems###

rake gemspec
rake build
sudo gem install pkg/aasm-2.1.gem

##Examples##

###Simple Example###

Here's a quick example highlighting some of the features.

class Conversation
  include AASM

  aasm_column :current_state # defaults to aasm_state

  aasm_initial_state :unread

  aasm_state :unread
  aasm_state :read
  aasm_state :closed


  aasm_event :view do
    transitions :to => :read, :from => [:unread]
  end

  aasm_event :close do
    transitions :to => :closed, :from => [:read, :unread]
  end
end

###A Slightly More Complex Example###

This example uses a few of the more complex features available.

class Relationship include AASM

aasm_column :status

aasm_initial_state Proc.new { |relationship| relationship.strictly_for_fun? ? :intimate : :dating }

aasm_state :dating,   :enter => :make_happy,        :exit => :make_depressed
aasm_state :intimate, :enter => :make_very_happy,   :exit => :never_speak_again
aasm_state :married,  :enter => :give_up_intimacy,  :exit => :buy_exotic_car_and_wear_a_combover

aasm_event :get_intimate do
  transitions :to => :intimate, :from => [:dating], :guard => :drunk?
end

aasm_event :get_married do
  transitions :to => :married, :from => [:dating, :intimate], :guard => :willing_to_give_up_manhood?
end

def strictly_for_fun?; end
def drunk?; end
def willing_to_give_up_manhood?; end
def make_happy; end
def make_depressed; end
def make_very_happy; end
def never_speak_again; end
def give_up_intimacy; end
def buy_exotic_car_and_wear_a_combover; end

end

###Ohm Example###

This example shows how to use aasm with the Ohm object-hashing library

class Notification < Ohm::Model
  attribute :state
  attribute :attempts
  attribute :last_sent_at

  aasm_column :state

  aasm_state :created
  aasm_state :sending, :after_enter => :process_notification
  aasm_state :sent
  aasm_state :failed, :enter => :process_failure

  aasm_initial_state :created

  aasm_event :send_notification do
    transitions :to => :sending, :from => [:created, :failed], :guard => :max_attempts_not_reached?
  end

  aasm_event :complete do
    transitions :to => :sent, :from => [:sending]
  end

  aasm_event :fail do
    transitions :to => :failed, :from => [:created, :sending]
  end
end

##Other Stuff##

Author:: Scott Barron Ohm Persistence:: Bart Jedrocha < [email protected] > License:: Original code Copyright 2006, 2007, 2008 by Scott Barron. Released under an MIT-style license. See the LICENSE file included in the distribution.

##Warranty##

This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.