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.

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 RubyGems.org

% gem install aasm

Building your own gems

% rake build
% sudo gem install pkg/aasm-x.y.z.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

Callbacks around events

  class Relationship
    include AASM

    aasm_state :dating
    aasm_state :married

    aasm_event :get_married,
      :before => :make_vows,
      :after => :eat_wedding_cake do
      transitions :to => :married, :from => [:dating]
    end
  end

Other Stuff

Author:: Scott Barron 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.