transitions 0.0.12 → 0.0.13

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    transitions (0.0.12)
+    transitions (0.0.13)
 
 GEM
   remote: http://rubygems.org/
@@ -16,15 +16,29 @@ GEM
       arel (~> 1.0.0)
       tzinfo (~> 0.3.23)
     activesupport (3.0.0)
+    archive-tar-minitar (0.5.2)
     arel (1.0.1)
       activesupport (~> 3.0.0)
     builder (2.1.2)
+    columnize (0.3.4)
     i18n (0.4.1)
+    linecache19 (0.5.12)
+      ruby_core_source (>= 0.1.4)
     mocha (0.9.8)
       rake
     rake (0.8.7)
+    ruby-debug-base19 (0.11.25)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.5)
+      archive-tar-minitar (>= 0.5.2)
     sqlite3-ruby (1.3.1)
-    test-unit (2.1.1)
+    test-unit (2.4.1)
     tzinfo (0.3.23)
 
 PLATFORMS
@@ -34,6 +48,7 @@ DEPENDENCIES
   activerecord (~> 3)
   bundler (~> 1)
   mocha
+  ruby-debug19
   sqlite3-ruby
-  test-unit (~> 2)
+  test-unit (~> 2.2)
   transitions!

data/README.rdoc

@@ -1,12 +1,28 @@
-== Travis Build Status {<img src="https://secure.travis-ci.org/troessner/transitions.png"/>}[http://travis-ci.org/troessner/transitions]
+= Travis Build Status 
 
-= What is transitions?
+{<img src="https://secure.travis-ci.org/troessner/transitions.png"/>}[http://travis-ci.org/troessner/transitions]
 
-transitions is a ruby state machine implementation based on Rick Olson’s
-ActiveModel::StateMachine. It was extracted from ActiveModel and turned
-into a gem when it got the axe in commit {db49c706b}[http://github.com/rails/rails/commit/db49c706b62e7ea2ab93f05399dbfddf5087ee0c].
+= Synopsis
 
-== Quick Example
+`transitions` is a ruby state machine implementation.
+
+= Installation
+
+== Rails
+
+This goes into your Gemfile:
+
+ gem "transitions", :require => ["transitions", "active_record/transitions"]
+
+… and this into your AR model:
+
+ include ActiveRecord::Transitions
+
+== Standalone
+
+ gem install transitions
+
+= Using transitions
 
  require 'transitions'
  
@@ -30,6 +46,15 @@ into a gem when it got the axe in commit {db49c706b}[http://github.com/rails/rai
    end
  end
 
+= Features
+
+== Events
+
+When you declare an event, say <tt>discontinue</tt>, two methods are declared for
+you: <tt>discontinue</tt> and <tt>discontinue!</tt>. Both events will call
+<tt>write_state_without_persistence</tt> on successful transition, but only the
+bang(!)-version will call <tt>write_state</tt>.
+
 == Automatic scope generation
 
 `transitions` will automatically generate scopes for you if you are using ActiveRecord and tell it to do so via the `auto_scopes` option:
@@ -70,6 +95,12 @@ In case you need to trigger a method call after a successful transition you can
     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
 
 == Timestamps
 
@@ -89,52 +120,24 @@ the name of the timestamp column.
     transiions :from => :exploded, :to => :rebuilt
   end
 
+== Listing all the available states
 
-== Using with Rails
-
-This goes into your Gemfile:
-
- gem "transitions", :require => ["transitions", "active_record/transitions"]
-
-… and this into your AR model:
-
- include ActiveRecord::Transitions
-
-=== A note about persistence
-The property used to persist the models’ state is named <tt>state</tt> (really!),
-which should be a string column wide enough to fit your longest state name.
-It should also be mentioned that <tt>#save!</tt> is called after every successful event.
-
-== Event execution flow
+You can easily get a listing of all available states:
 
-On an event, with our quick example product going from <tt>:available</tt> to
-<tt>:discontinued</tt> it looks like this:
+  Order.available_states # Uses the `default` state machine
+  # => [:pick_line_items, :picking_line_items]
 
-1. <tt>baby_ninja.discontinue!(:reason => :pirates)</tt>
-2. call <tt>:exit</tt> handler of <tt>:available</tt> state
-3. call <tt>:guard</tt> of <tt>:available to :discontinue</tt> transition within <tt>#discontinue</tt> event
-4. call <tt>#event_failed(:event)</tt> and abort unless <tt>3.</tt> returned <tt>true</tt>
-5. call <tt>:on_transition(:reason => :pirates)</tt> of <tt>:available to :discontinue</tt> transition within <tt>#discontinue</tt> event
-6. call <tt>:enter</tt> handler of <tt>:discontinue</tt>
-7. call <tt>#event_fired(:available, :discontinue)</tt>
-8. call <tt>#write_state(machine, :discontinue)</tt>
-9. call <tt>#write_state_without_persistence(machine, :discontinue)</tt>
-10. call <tt>baby_ninja#:success</tt> handler method of <tt>#discontinue</tt> event
+In case you have multiple state machines you can also pass the state machine name:
 
-=== A note about events
-
-When you declare an event <tt>discontinue</tt>, two methods are declared for
-you: <tt>discontinue</tt> and <tt>discontinue!</tt>. Both events will call
-<tt>write_state_without_persistence</tt> on successful transition, but only the
-bang(!)-version will call <tt>write_state</tt>.
+  Order.available_states(:your_machine)
 
-== Documentation, Guides & Examples
+= Documentation, Guides & Examples
 
 - {Online API Documentation}[http://rdoc.info/github/troessner/transitions/master/Transitions]
 - Krzysiek Heród (aka {Netizer}[http://github.com/netizer]) wrote a nice
   {blog post}[http://dev.netizer.pl/transitions-state-machine-for-rails-3.html]
   about using Transitions in ActiveRecord.
 
-== Copyright
+= Copyright
 
 Copyright (c) 2010 Jakub Kuźma, Timo Rößner. See LICENSE for details.

data/lib/transitions/event.rb

@@ -74,7 +74,7 @@ module Transitions
     end
 
     def update(options = {}, &block)
-      @success       = options[:success] if options.key?(:success)
+      @success       = build_sucess_callback(options[:success]) if options.key?(:success)
       self.timestamp = options[:timestamp] if options[:timestamp]
       instance_eval(&block) if block
       self
@@ -118,12 +118,20 @@ module Transitions
           Please define #{at_name} or #{on_name} in #{obj.class}"
       end
     end
-    
 
     def transitions(trans_opts)
       Array(trans_opts[:from]).each do |s|
         @transitions << StateTransition.new(trans_opts.merge({:from => s.to_sym}))
       end
     end
+
+    def build_sucess_callback(callback_symbol_or_proc)
+      case callback_symbol_or_proc
+      when Proc
+        callback_symbol_or_proc
+      when Symbol
+        lambda { |record| record.send(callback_symbol_or_proc) }
+      end
+    end
   end
 end

data/lib/transitions/machine.rb

@@ -45,22 +45,28 @@ module Transitions
 
     def fire_event(event, record, persist, *args)
       state_index[record.current_state(@name)].call_action(:exit, record)
-      if new_state = @events[event].fire(record, nil, *args)
-        state_index[new_state].call_action(:enter, record)
-
-        if record.respond_to?(event_fired_callback)
-          record.send(event_fired_callback, record.current_state, new_state, event)
+      begin
+        if new_state = @events[event].fire(record, nil, *args)
+          state_index[new_state].call_action(:enter, record)
+
+          if record.respond_to?(event_fired_callback)
+            record.send(event_fired_callback, record.current_state, new_state, event)
+          end
+
+          record.current_state(@name, new_state, persist)
+          @events[event].success.call(record) if @events[event].success
+          return true
+        else
+          record.send(event_fired_callback, event) if record.respond_to?(event_failed_callback)
+          return false
         end
-
-        record.current_state(@name, new_state, persist)
-        record.send(@events[event].success) if @events[event].success
-        true
-      else
+      rescue => e
         if record.respond_to?(event_failed_callback)
           record.send(event_failed_callback, event)
+          return false
+        else
+          raise e
         end
-
-        false
       end
     end
 

data/lib/transitions/version.rb

@@ -1,3 +1,3 @@
 module Transitions
-  VERSION = "0.0.12"
+  VERSION = "0.0.13"
 end

data/lib/transitions.rb

@@ -54,6 +54,10 @@ module Transitions
       block ? state_machines[name].update(options, &block) : state_machines[name]
     end
 
+    def available_states name = :default
+      state_machines[name].states.map(&:name).sort
+    end
+
     def define_state_query_method(state_name)
       name = "#{state_name}?"
       undef_method(name) if method_defined?(name)

data/test/helper.rb

@@ -4,6 +4,7 @@ require "active_support/all"
 require "active_record"
 require "mocha"
 require "db/create_db"
+require "ruby-debug"
 
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
 $LOAD_PATH.unshift(File.dirname(__FILE__))

data/test/test_active_record.rb

@@ -3,10 +3,39 @@ require 'active_support/core_ext/module/aliasing'
 
 ActiveRecord::Base.establish_connection(:adapter  => "sqlite3", :database => ":memory:")
 
+class CreateTrafficLights < ActiveRecord::Migration
+  def self.up
+    create_table(:traffic_lights) do |t|
+      t.string :state
+      t.string :name
+    end
+  end
+end
+
+class CreateLightBulbs < ActiveRecord::Migration
+  def self.up
+    create_table(:light_bulbs) do |t|
+      t.string :state
+    end
+  end
+end
+
+class CreateLights < ActiveRecord::Migration
+  def self.up
+    create_table(:lights) do |t|
+      t.string :state
+    end
+  end
+end
+
+CreateTrafficLights.migrate(:up)
+CreateLightBulbs.migrate(:up)
+CreateLights.migrate(:up)
+
 class TrafficLight < ActiveRecord::Base
   include ActiveRecord::Transitions
 
-  state_machine do
+  state_machine :auto_scopes => true do
     state :off
 
     state :red
@@ -43,6 +72,15 @@ class ConditionalValidatingTrafficLight < TrafficLight
   validates(:name, :presence => true, :if => :red?)
 end
 
+class LightBulb < ActiveRecord::Base
+  include ActiveRecord::Transitions
+
+  state_machine do
+    state :off
+    state :on
+  end
+end
+
 class TestActiveRecord < Test::Unit::TestCase
   def setup
     create_database
@@ -141,3 +179,37 @@ class TestNewActiveRecord < TestActiveRecord
   end
 
 end
+
+class TestScopes < Test::Unit::TestCase
+  test "scope returns correct object" do
+    @light = TrafficLight.create!
+    assert_respond_to TrafficLight, :off
+    assert_equal TrafficLight.off.first, @light
+    assert TrafficLight.red.empty?
+  end
+
+  test "scopes exist" do
+    assert_respond_to TrafficLight, :off
+    assert_respond_to TrafficLight, :red
+    assert_respond_to TrafficLight, :green
+    assert_respond_to TrafficLight, :yellow
+  end
+
+  test 'scopes are only generated if we explicitly say so' do
+    assert_not_respond_to LightBulb, :off
+    assert_not_respond_to LightBulb, :on
+  end
+
+  test 'scope generation raises an exception if we try to overwrite an existing method' do
+    assert_raise(Transitions::InvalidMethodOverride) {
+      class Light < ActiveRecord::Base
+        include ActiveRecord::Transitions
+
+        state_machine :auto_scopes => true do
+          state :new
+          state :broken
+        end
+      end
+    }
+  end
+end

data/test/test_available_states_listing.rb

@@ -0,0 +1,27 @@
+require "helper"
+
+class Bender
+  include Transitions
+
+  state_machine :default do
+    state :drinking
+    state :smoking
+    state :gambling
+  end
+
+  state_machine :maintenance do
+    state :wip
+    state :finished
+  end
+end
+
+class TestAvailableStatesListing < Test::Unit::TestCase
+  test 'available_states should return the states for the default state machine if no state machine is specified' do
+    assert_equal [:drinking, :gambling, :smoking], Bender.available_states
+  end
+
+  test 'available_states should return the states for a given state' do
+    assert_equal [:finished, :wip], Bender.available_states(:maintenance)
+    assert_equal [:drinking, :gambling, :smoking], Bender.available_states(:default)
+  end
+end

data/test/test_event.rb

@@ -3,11 +3,19 @@ require "helper"
 class TestEvent < Test::Unit::TestCase
   def setup
     @state_name = :close_order
-    @success = :success_callback
+    @success_as_symbol = :success_callback
+    @success_as_lambda = lambda { |record| record.success_callback }
   end
 
-  def new_event
-    @event = Transitions::Event.new(nil, @state_name, {:success => @success}) do
+  def event_with_symbol_success_callback
+    @event = Transitions::Event.new(nil, @state_name, {:success => @success_as_symbol}) do
+      transitions :to => :closed, :from => [:open, :received]
+    end
+  end
+  alias_method :new_event, :event_with_symbol_success_callback
+
+  def event_with_lambda_success_callback
+    @event = Transitions::Event.new(nil, @state_name, {:success => @success_as_lambda}) do
       transitions :to => :closed, :from => [:open, :received]
     end
   end
@@ -16,8 +24,19 @@ class TestEvent < Test::Unit::TestCase
     assert_equal @state_name, new_event.name
   end
 
-  test "should set the success option" do
-    assert_equal @success, new_event.success
+  test "should set the success callback with a symbol and return a block" do
+    assert_respond_to event_with_symbol_success_callback.success, :call
+  end
+
+  test "should build a block which calls the given success_callback symbol on the passed record instance" do
+    record = mock("SomeRecordToGetCalled")
+    record.expects(:success_callback)
+
+    event_with_symbol_success_callback.success.call(record)
+  end
+
+  test "should set the success callback with a lambda" do
+    assert_respond_to event_with_lambda_success_callback.success, :call
   end
 
   test "should create StateTransitions" do

data/test/test_state_transition_success_callback.rb

@@ -0,0 +1,60 @@
+require 'helper'
+
+class DrivingInstructor
+  def self.applause!
+  end
+end
+
+class DrivingSchoolCar
+  include Transitions
+
+  state_machine do
+    state :parked
+    state :running
+    state :driving
+    state :switched_off
+
+    event :start_driving, :success => lambda { |car| DrivingInstructor.applause! } do
+      transitions :from => :parked, :to => :driving, :on_transition => [:start_engine, :loosen_handbrake, :push_gas_pedal]
+    end
+
+    event :switch_off_engine do
+      transitions :from => :parked, :to => :switched_off
+    end
+  end
+
+  %w!start_engine loosen_handbrake push_gas_pedal!.each do |m|
+    define_method(m){}
+  end
+end
+
+class TestStateTransitionSuccessCallback < Test::Unit::TestCase
+  def setup
+    @car = DrivingSchoolCar.new
+  end
+
+  test "should execute the success callback after successfull event execution" do
+    DrivingInstructor.expects(:applause!)
+
+    @car.start_driving!
+  end
+
+  test "should not execute the success callback after event execution failed" do
+    DrivingInstructor.expects(:applause!).never
+
+    @car.stubs(:event_failed)
+    @car.expects(:loosen_handbrake).raises("Drive with handbrake fail!")
+    @car.start_driving!
+  end
+
+  test "should execute the event_failed_callback and don't raise error if callback is defined" do
+    @car.start_driving
+    @car.expects(:event_failed).with(:switch_off_engine)
+    @car.switch_off_engine
+  end
+
+  test "should just re-raise any error on transition if the event_failed_callback isn't defined" do
+    @car.start_driving
+    assert_raise(Transitions::InvalidTransition) { @car.switch_off_engine }
+  end
+end

data/transitions.gemspec

@@ -15,10 +15,11 @@ Gem::Specification.new do |s|
   s.rubyforge_project         = "transitions"
 
   s.add_development_dependency "bundler", "~> 1"
-  s.add_development_dependency "test-unit", "~> 2"
+  s.add_development_dependency "test-unit", "~> 2.2"
   s.add_development_dependency "mocha"
   s.add_development_dependency "sqlite3-ruby"
   s.add_development_dependency "activerecord", "~> 3"
+  s.add_development_dependency "ruby-debug19"
 
   s.files        = `git ls-files`.split("\n")
   s.executables  = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: transitions
 version: !ruby/object:Gem::Version
-  version: 0.0.12
+  version: 0.0.13
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-11-17 00:00:00.000000000Z
+date: 2011-12-20 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &74700350 !ruby/object:Gem::Requirement
+  requirement: &77702010 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,21 +22,21 @@ dependencies:
         version: '1'
   type: :development
   prerelease: false
-  version_requirements: *74700350
+  version_requirements: *77702010
 - !ruby/object:Gem::Dependency
   name: test-unit
-  requirement: &74700040 !ruby/object:Gem::Requirement
+  requirement: &77701310 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '2.2'
   type: :development
   prerelease: false
-  version_requirements: *74700040
+  version_requirements: *77701310
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &74699680 !ruby/object:Gem::Requirement
+  requirement: &77700870 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +44,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *74699680
+  version_requirements: *77700870
 - !ruby/object:Gem::Dependency
   name: sqlite3-ruby
-  requirement: &74699290 !ruby/object:Gem::Requirement
+  requirement: &77700370 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,10 +55,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *74699290
+  version_requirements: *77700370
 - !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &74698870 !ruby/object:Gem::Requirement
+  requirement: &77699800 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -66,7 +66,18 @@ dependencies:
         version: '3'
   type: :development
   prerelease: false
-  version_requirements: *74698870
+  version_requirements: *77699800
+- !ruby/object:Gem::Dependency
+  name: ruby-debug19
+  requirement: &77698980 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *77698980
 description: Lightweight state machine extracted from ActiveModel
 email: timo.roessner@googlemail.com
 executables: []
@@ -92,15 +103,16 @@ files:
 - test/helper.rb
 - test/test_active_record.rb
 - test/test_active_record_timestamps.rb
+- test/test_available_states_listing.rb
 - test/test_event.rb
 - test/test_event_arguments.rb
 - test/test_event_being_fired.rb
 - test/test_machine.rb
-- test/test_scopes.rb
 - test/test_state.rb
 - test/test_state_transition.rb
 - test/test_state_transition_callbacks.rb
 - test/test_state_transition_guard_check.rb
+- test/test_state_transition_success_callback.rb
 - transitions.gemspec
 homepage: http://github.com/troessner/transitions
 licenses: []
@@ -116,7 +128,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -171038385
+      hash: 819396333
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:

data/test/test_scopes.rb

@@ -1,104 +0,0 @@
-require "helper"
-require 'active_support/core_ext/module/aliasing'
-
-ActiveRecord::Base.establish_connection(:adapter  => "sqlite3", :database => ":memory:")
-
-class CreateTrafficLights < ActiveRecord::Migration
-  def self.up
-    create_table(:traffic_lights) do |t|
-      t.string :state
-      t.string :name
-    end
-  end
-end
-
-class CreateLightBulbs < ActiveRecord::Migration
-  def self.up
-    create_table(:light_bulbs) do |t|
-      t.string :state
-    end
-  end
-end
-
-class CreateLights < ActiveRecord::Migration
-  def self.up
-    create_table(:lights) do |t|
-      t.string :state
-    end
-  end
-end
-
-CreateTrafficLights.migrate(:up)
-CreateLightBulbs.migrate(:up)
-CreateLights.migrate(:up)
-
-class TrafficLight < ActiveRecord::Base
-  include ActiveRecord::Transitions
-
-  state_machine :auto_scopes => true do
-    state :off
-
-    state :red
-    state :green
-    state :yellow
-
-    event :red_on do
-      transitions :to => :red, :from => [:yellow]
-    end
-
-    event :green_on do
-      transitions :to => :green, :from => [:red]
-    end
-
-    event :yellow_on do
-      transitions :to => :yellow, :from => [:green]
-    end
-
-    event :reset do
-      transitions :to => :red, :from => [:off]
-    end
-  end
-end
-
-class LightBulb < ActiveRecord::Base
-  include ActiveRecord::Transitions
-
-  state_machine do
-    state :off
-    state :on
-  end
-end
-
-class TestScopes < Test::Unit::TestCase
-  test "scope returns correct object" do
-    @light = TrafficLight.create!
-    assert TrafficLight.respond_to? :off
-    assert_equal TrafficLight.off.first, @light
-    assert TrafficLight.red.empty?
-  end
-
-  test "scopes exist" do
-    assert TrafficLight.respond_to? :off
-    assert TrafficLight.respond_to? :red
-    assert TrafficLight.respond_to? :green
-    assert TrafficLight.respond_to? :yellow
-  end
-
-  test 'scopes are only generated if we explicitly say so' do
-    assert !LightBulb.respond_to?(:off)
-    assert !LightBulb.respond_to?(:on)
-  end
-
-  test 'scope generation raises an exception if we try to overwrite an existing method' do
-    assert_raise(Transitions::InvalidMethodOverride) {
-      class Light < ActiveRecord::Base
-        include ActiveRecord::Transitions
-
-        state_machine :auto_scopes => true do
-          state :new
-          state :broken
-        end
-      end
-    }
-  end
-end