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.

• 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

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

Multiple transitions for an event are supported, in which case you want to specify a :guard option which is a symbol to a method or a proc that returns a boolean to decide whether that transition is allowed. aasm will process transitions in order and the first passing guard clause is the one in effect.

States also support :enter and :exit options allowing you further hooks into the lifecycle.

Advanced Features¶ ↑

Arguments to an event call will be passed to on_transition method.

aasm_event :view do transitions :to => :read, :from => [:initial], :on_transition => :view_happening end

def view_happening(a=nil, b=nil) end

Calling conversation.view(1, 2) will result in view_happening receiving a=1, b=2

UNLESS… You are using the advanced feature of multiple :to states in which case you can pass the state name symbol as the first argument to the event call to control your destination state.

aasm_event :view do transitions :to => [:read, :closed], :from => [:initial], :on_transition => :view_happening end

Now, you can call: conversation.view -> to transition to the first :to state (:read) or conversation.view :closed -> to force a transition to the :closed state or conversation.view(1, 2) -> to transition to :read and receive a=1, b=2 in view_happening or conversation.view(:closed, 1, 2) -> to transition to :closed and receive a=1, b=2 in view_happening

Other Stuff¶ ↑

Author

Scott Barron <scott at elitists dot net>

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.