=== Travis Build Status 

{<img src="https://secure.travis-ci.org/troessner/transitions.png?branch=master"/>}[http://travis-ci.org/troessner/transitions]

=== Synopsis

<tt>transitions</tt> is a ruby state machine implementation.

=== Installation

==== Rails

This goes into your Gemfile:

 gem "transitions", :require => ["transitions", "active_model/transitions"]

… and this into your ORM model:

 include ActiveModel::Transitions

==== Standalone

 gem install transitions

=== Using transitions

 class Product
   include ActiveModel::Transitions
 
   state_machine do
     state :available # first one is initial state
     state :out_of_stock, :exit => :exit_out_of_stock
     state :discontinued, :enter => lambda { |product| product.cancel_orders }
   
     event :discontinued do
       transitions :to => :discontinued, :from => [:available, :out_of_stock], :on_transition => :do_discontinue
     end
     event :out_of_stock do
       transitions :to => :out_of_stock, :from => [:available, :discontinued]
     end
     event :available do
       transitions :to => :available, :from => [:out_of_stock], :guard => lambda { |product| product.in_stock > 0 }
     end
   end
 end

In this example we assume that you are in a rails project using Bundler, which would automatically require `transitions`.
If this is not the case for you you have to add

 require 'transitions'

whereever you load your dependencies in your application.

<b>Known limitations:</b> 

* You can only use one state machine per model. While in theory you can define two or more, this won't work as you would expect. Not supporting this was intentional, if you're interested in the ratione look up version 1.0.0 in the CHANGELOG.

* Use symbols, not strings for declaring the state machine. Using strings is *not* supported as is using whitespace in names (because `transitions` possibly generates methods out of this).

=== Features

==== Getting and setting the current state

Use the (surprise ahead) `current_state` method - in case you didn't set a state explicitly you'll get back the state that you defined as initial state.

  >> Product.new.current_state
  => :available

You can also set a new state explicitly via `update_current_state(new_state, persist = true / false)` but you should never do this unless you really know what you're doing and why - rather use events / state transitions (see below).

==== Events

When you declare an event, say <tt>discontinue</tt>, three methods are declared for
you: <tt>discontinue</tt>, <tt>discontinue!</tt> and <tt>can_discontinue?</tt>. The first two events will modify the <tt>state</tt> attribute on successful transition,
but only the bang(!)-version will call <tt>save!</tt>.  The <tt>can_discontinue?</tt> method will
not modify state but instead returns a boolean letting you know if a given transition is possible.

==== Automatic scope generation

<tt>transitions</tt> will automatically generate scopes for you if you are using ActiveRecord and tell it to do so via the <tt>auto_scopes</tt> option:

Given a model like this:

  class Order < ActiveRecord::Base
    include ActiveModel::Transitions
    state_machine :auto_scopes => true do
      state :pick_line_items
      state :picking_line_items
    end
  end

you can use this feature a la:

  >> Order.pick_line_items
  => []
  >> Order.create!
  => #<Order id: 3, state: "pick_line_items", description: nil, created_at: "2011-08-23 15:48:46", updated_at: "2011-08-23 15:48:46">
  >> Order.pick_line_items
  => [#<Order id: 3, state: "pick_line_items", description: nil, created_at: "2011-08-23 15:48:46", updated_at: "2011-08-23 15:48:46">]

==== Using <tt>guard</tt>

Each event definition takes an optional "guard" argument, which acts as a predicate for the transition.
You can pass in a Symbol, a String, or a Proc like this:

  event :discontinue do
    transitions :to => :discontinued, :from => [:available, :out_of_stock], :guard => :can_discontinue
  end

Any arguments passed to the event method will be passed on to the <tt>guard</tt> predicate.

==== Using <tt>on_transition</tt>

Each event definition takes an optional "on_transition" argument, which allows you to execute methods on transition.
You can pass in a Symbol, a String, a Proc or an Array containing method names as Symbol or String like this:

  event :discontinue do
    transitions :to => :discontinued, :from => [:available, :out_of_stock], :on_transition => [:do_discontinue, :notify_clerk]
  end

Any arguments passed to the event method will be passed on to the <tt>on_transition</tt> callback.

==== Using <tt>success</tt>

In case you need to trigger a method call after a successful transition you can use <tt>success</tt>:

  event :discontinue, :success => :notfiy_admin do
    transitions :to => :discontinued, :from => [:available, :out_of_stock]
  end

In addition to just specify the method name on the record as a symbol you can pass a lambda to
perfom some more complex success callbacks:

  event :discontinue, :success => lambda { |order| AdminNotifier.notify_about_discontinued_order(order) } do
    transitions :to => :discontinued, :from => [:available, :out_of_stock]
  end

If you need it, you can even call multiple methods or lambdas just passing an array:

  event :discontinue, :success => [:notify_admin, lambda { |order| AdminNotifier.notify_about_discontinued_order(order) }] do
    transitions :to => :discontinued, :from => [:available, :out_of_stock]
  end

==== Timestamps

If you'd like to note the time of a state change, Transitions comes with timestamps free!
To activate them, simply pass the :timestamp option to the event definition with a value of either true or
the name of the timestamp column.
*NOTE - This should be either true, a String or a Symbol*

  # This will look for an attribute called exploded_at or exploded_on (in that order)
  # If present, it will be updated
  event :explode, :timestamp => true do
    transitions :from => :complete, :to => :exploded
  end

  # This will look for an attribute named repaired_on to update upon save
  event :rebuild, :timestamp => :repaired_on do
    transitions :from => :exploded, :to => :rebuilt
  end

====  Using <tt>event_fired</tt> and <tt>event_failed</tt>

In case you define `event_fired` and / or `event_failed`, `transitions` will use those callbacks correspondingly.
You can use those callbacks like this:

  def event_fired(current_state, new_state, event)
    MyLogger.info "Event fired #{event.inspect}"
  end

  def event_failed(event)
    MyLogger.warn "Event failed #{event.inspect}"
  end

==== Listing all the available states

You can easily get a listing of all available states:

  Order.available_states # Uses the <tt>default</tt> state machine
  # => [:pick_line_items, :picking_line_items]

==== Explicitly setting the initial state with the <tt>initial</tt> option

  state_machine :initial => :closed do
    state :open
    state :closed
  end

=== Configuring a different column name with ActiveRecord

To use a different column than <tt>state</tt> to track it's value simply do this:

  class Product < ActiveRecord::Base
    include Transitions
    
    state_machine :attribute_name => :different_column do
    
      ...
    
    end
  end

=== Known bugs / limitations

- Right now it seems like `transitions` does not play well with `mongoid`. A possible fix had to be rolled back due to other side effects: https://github.com/troessner/transitions/issues/76. Since I know virtually zero about mongoid, a pull request would be highly appreciated.
- Multiple state machines are and will not be supported. For the rationale behind this see the Changelog.

=== Documentation, Guides & Examples

- {Online API Documentation}[http://rdoc.info/github/troessner/transitions/master/Transitions]

=== Copyright

Copyright (c) 2010 Jakub Kuźma, Timo Rößner. See LICENSE for details.