= 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

== Download

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

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

A release and a gem are forthcoming.



== Installation

=== From GitHub hosted gems

  % 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 gem
  % sudo gem install pkg/aasm-2.0.2.gem


== Simple Example

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

  class Conversation
    include AASM

    aasm_initial_state :new

    aasm_state :new
    aasm_state :read, :enter => :mark_thread_as_read
    aasm_state :closed


    aasm_event :view do
      # Transitions can take an optional on_transition option to execute some logic when the event is happening.
      # It can take a single string or symbol (denoting a method), an array of string or symbols
      # (denoting several methods), or an inline lambda
      transitions :to => :read, :from => [:new], :on_transition => :set_last_read_at, :guard => :user_authorized
    end

    aasm_event :close do
      transitions :to => :closed, :from => [:read, :new]
    end
    
    # Update last_read_at timestamp when the conversation is viewed
    def set_last_read_at
      self.last_read_at = Time.now
    end
    
  end


== Explanation of transitions

The current state machine has the following process. If we were to call 
<tt>Conversation#view!</tt>, we would get:

     state:new
         |
         | <-- :exit called on state[new]
         |
         | <-- :guard called on state[read]
         |
         | <-- :on_transition called on state[read]
         |
         | <-- aasm_current_state set to "read"
         |
         | <-- :success called on state[read]
         |
         | <-- :enter called on state[read]
         |
     state:read


= Other Stuff

Author::  Scott Barron <scott at elitists dot net>
License:: Copyright 2006, 2007, 2008 by Scott Barron.
          Released under an MIT-style license.  See the LICENSE  file
          included in the distribution.
Bugs::    http://rubyist.lighthouseapp.com/projects/13207-aasm/
GitHub::  http://github.com/rubyist/aasm/tree/master

== 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.