transitions 0.0.10 → 0.0.11

data/.gitignore

@@ -1,3 +1,4 @@
 pkg
 *.gem
 .bundle
+.rvmrc

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    transitions (0.0.10)
+    transitions (0.0.11)
 
 GEM
   remote: http://rubygems.org/

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Jakub Kuźma
+Copyright (c) 2010 Jakub Kuźma, Timo Rößner
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -30,6 +30,29 @@ I really encourage you to try {state_machine}[https://github.com/pluginaweek/sta
    end
  end
 
+== Automatic scope generation
+
+`transitions` will automatically generate scopes for you if you are using AR:
+
+Given a model like this:
+
+  class Order < ActiveRecord::Base
+    include ActiveRecord::Transitions
+    state_machine 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 on_transition
 
 Each event definition takes an optional "on_transition" argument, which allows you to execute methods on transition.
@@ -39,6 +62,25 @@ You can pass in a Symbol, a String, a Proc or an Array containing method names a
     transitions :to => :discontinued, :from => [:available, :out_of_stock], :on_transition => [:do_discontinue, :notify_clerk]
   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
+    transiions :from => :exploded, :to => :rebuilt
+  end
+
+
 == Using with Rails
 
 This goes into your Gemfile:
@@ -86,4 +128,4 @@ bang(!)-version will call <tt>write_state</tt>.
 
 == Copyright
 
-Copyright (c) 2010 Jakub Kuźma. See LICENSE for details.
+Copyright (c) 2010 Jakub Kuźma, Timo Rößner. See LICENSE for details.

data/lib/active_record/transitions.rb

@@ -30,8 +30,11 @@ module ActiveRecord
       validates_presence_of :state
       validate :state_inclusion
     end
-
-    def reload
+    
+    # The optional options argument is passed to find when reloading so you may
+    # do e.g. record.reload(:lock => true) to reload the same record with an
+    # exclusive row lock. 
+    def reload(options = nil)
       super.tap do
         self.class.state_machines.values.each do |sm|
           remove_instance_variable(sm.current_state_variable) if instance_variable_defined?(sm.current_state_variable)

data/lib/transitions.rb

@@ -58,7 +58,7 @@ module Transitions
     def define_state_query_method(state_name)
       name = "#{state_name}?"
       undef_method(name) if method_defined?(name)
-      class_eval "def #{name}; current_state.to_s == %(#{state_name}) end"
+      define_method(name) { current_state.to_s == %(#{state_name}) }
     end
   end
 

data/lib/transitions/event.rb

@@ -22,7 +22,7 @@
 
 module Transitions
   class Event
-    attr_reader :name, :success
+    attr_reader :name, :success, :timestamp
 
     def initialize(machine, name, options = {}, &block)
       @machine, @name, @transitions = machine, name, []
@@ -51,6 +51,8 @@ module Transitions
           break
         end
       end
+      # Update timestamps on obj if a timestamp has been defined
+      update_event_timestamp(obj, next_state) if timestamp_defined?
       next_state
     end
 
@@ -65,14 +67,58 @@ module Transitions
         name == event.name
       end
     end
+    
+    # Has the timestamp option been specified for this event?
+    def timestamp_defined?
+      !@timestamp.nil?
+    end
 
     def update(options = {}, &block)
-      @success = options[:success] if options.key?(:success)
+      @success       = options[:success] if options.key?(:success)
+      self.timestamp = options[:timestamp] if options[:timestamp]
       instance_eval(&block) if block
       self
     end
+    
+    # update the timestamp attribute on obj
+    def update_event_timestamp(obj, next_state)
+      obj.send "#{timestamp_attribute_name(obj, next_state)}=", Time.now
+    end
+    
+    # Set the timestamp attribute.
+    # @raise [ArgumentError] timestamp should be either a String, Symbol or true
+    def timestamp=(value)
+      case value
+      when String, Symbol, TrueClass
+        @timestamp = value
+      else
+        raise ArgumentError, "timestamp must be either: true, a String or a Symbol"
+      end
+    end
+    
 
     private
+    
+    # Returns the name of the timestamp attribute for this event
+    # If the timestamp was simply true it returns the default_timestamp_name
+    # otherwise, returns the user-specified timestamp name
+    def timestamp_attribute_name(obj, next_state)
+      timestamp == true ? default_timestamp_name(obj, next_state) : @timestamp
+    end
+    
+    # If @timestamp is true, try a default timestamp name
+    def default_timestamp_name(obj, next_state)
+      at_name = "%s_at" % next_state
+      on_name = "%s_on" % next_state
+      case
+      when obj.respond_to?(at_name) then at_name
+      when obj.respond_to?(on_name) then on_name
+      else
+        raise NoMethodError, "Couldn't find a suitable timestamp field for event: #{@name}. 
+          Please define #{at_name} or #{on_name} in #{obj.class}"
+      end
+    end
+    
 
     def transitions(trans_opts)
       Array(trans_opts[:from]).each do |s|

data/lib/transitions/machine.rb

@@ -38,6 +38,7 @@ module Transitions
     def update(options = {}, &block)
       @initial_state = options[:initial] if options.key?(:initial)
       instance_eval(&block) if block
+      include_scopes if defined?(ActiveRecord::Base) && @klass < ActiveRecord::Base
       self
     end
 
@@ -92,6 +93,12 @@ module Transitions
     def event_failed_callback
       @event_failed_callback ||= (@name == :default ? '' : "#{@name}_") + 'event_failed'
     end
+
+    def include_scopes
+      @states.each do |state|
+        @klass.scope state.name.to_sym, @klass.where(:state => state.name.to_s)
+      end
+    end
   end
 end
 

data/lib/transitions/version.rb

@@ -1,3 +1,3 @@
 module Transitions
-  VERSION = "0.0.10"
+  VERSION = "0.0.11"
 end

data/test/db/create_db.rb

@@ -0,0 +1,19 @@
+# Use this schema to create all required tables
+class CreateDb < ActiveRecord::Migration
+  def self.up
+    create_table(:traffic_lights, force: true) do |t|
+      t.string :state
+      t.string :name
+    end
+    
+    create_table(:orders, force: true) do |t|
+      t.string :state
+      t.string :order_number
+      t.datetime :paid_at
+      t.datetime :prepared_on
+      t.datetime :dispatched_at 
+      t.date :cancellation_date
+    end
+    
+  end
+end

data/test/helper.rb

@@ -3,6 +3,7 @@ require "test/unit"
 require "active_support/all"
 require "active_record"
 require "mocha"
+require "db/create_db"
 
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
 $LOAD_PATH.unshift(File.dirname(__FILE__))
@@ -12,3 +13,9 @@ require "active_record/transitions"
 class Test::Unit::TestCase
 
 end
+
+def create_database
+  ActiveRecord::Base.establish_connection(:adapter  => "sqlite3", :database => ":memory:")
+  ActiveRecord::Migration.verbose = false
+  CreateDb.migrate(:up)
+end

data/test/test_active_record.rb

@@ -1,14 +1,7 @@
 require "helper"
 require 'active_support/core_ext/module/aliasing'
 
-class CreateTrafficLights < ActiveRecord::Migration
-  def self.up
-    create_table(:traffic_lights) do |t|
-      t.string :state
-      t.string :name
-    end
-  end
-end
+ActiveRecord::Base.establish_connection(:adapter  => "sqlite3", :database => ":memory:")
 
 class TrafficLight < ActiveRecord::Base
   include ActiveRecord::Transitions
@@ -52,10 +45,7 @@ end
 
 class TestActiveRecord < Test::Unit::TestCase
   def setup
-    ActiveRecord::Base.establish_connection(:adapter  => "sqlite3", :database => ":memory:")
-    ActiveRecord::Migration.verbose = false
-    CreateTrafficLights.migrate(:up)
-
+    create_database
     @light = TrafficLight.create!
   end
 
@@ -142,6 +132,7 @@ end
 class TestNewActiveRecord < TestActiveRecord
 
   def setup
+    create_database
     @light = TrafficLight.new
   end
 

data/test/test_active_record_timestamps.rb

@@ -0,0 +1,118 @@
+require "helper"
+require 'active_support/core_ext/module/aliasing'
+
+create_database
+
+class Order < ActiveRecord::Base
+  include ActiveRecord::Transitions
+
+  state_machine do
+    state :opened
+    state :placed
+    state :paid
+    state :prepared
+    state :delivered
+    state :cancelled
+    
+    # no timestamp col is being specified here - should be ignored
+    event :place do
+      transitions :from => :opened, :to => :placed
+    end
+
+    # should set paid_at timestamp
+    event :pay, :timestamp => true do
+      transitions :from => :placed, :to => :paid
+    end
+
+    # should set prepared_on
+    event :prepare, :timestamp => true do
+      transitions :from => :paid, :to => :prepared
+    end
+
+    # should set dispatched_at
+    event :deliver, :timestamp => "dispatched_at" do
+      transitions :from => :prepared, :to => :delivered
+    end
+    
+    # should set cancellation_date
+    event :cancel, :timestamp => :cancellation_date do
+      transitions :from => [:placed, :paid, :prepared], :to => :cancelled
+    end
+    
+    # should raise an exception as there is no timestamp col
+    event :reopen, :timestamp => true do
+      transitions :from => :cancelled, :to => :opened
+    end
+    
+  end
+end
+
+
+class TestActiveRecordTimestamps < Test::Unit::TestCase
+  
+  require "securerandom"
+  
+  def setup
+    create_database
+  end
+  
+  def create_order(state = nil)
+    Order.create! order_number: SecureRandom.hex(4), state: state
+  end
+
+  # control case, no timestamp has been set so we should expect default behaviour
+  test "moving to placed does not raise any exceptions" do
+    @order = create_order
+    assert_nothing_raised { @order.place! }
+    assert_equal @order.state, "placed"
+  end
+  
+  test "moving to paid should set paid_at" do
+    @order = create_order(:placed)    
+    @order.pay!
+    @order.reload
+    assert_not_nil @order.paid_at
+  end
+  
+  test "moving to prepared should set prepared_on" do
+    @order = create_order(:paid)    
+    @order.prepare!
+    @order.reload
+    assert_not_nil @order.prepared_on
+  end
+  
+  test "moving to delivered should set dispatched_at" do
+    @order = create_order(:prepared)    
+    @order.deliver!
+    @order.reload
+    assert_not_nil @order.dispatched_at
+  end
+  
+  test "moving to cancelled should set cancellation_date" do
+    @order = create_order(:placed)    
+    @order.cancel!
+    @order.reload
+    assert_not_nil @order.cancellation_date
+  end
+  
+  test "moving to reopened should raise an exception as there is no attribute" do
+    @order = create_order(:cancelled)    
+    assert_raise(NoMethodError) { @order.re_open! } 
+    @order.reload
+  end
+  
+  test "passing an invalid value to timestamp options should raise an exception" do
+    assert_raise(ArgumentError) do
+      class Order < ActiveRecord::Base
+        include ActiveRecord::Transitions
+        state_machine do
+          event :replace, timestamp: 1 do
+            transitions :from => :prepared, :to => :placed
+          end
+        end
+        
+      end      
+    end
+  end
+
+end

data/test/test_scopes.rb

@@ -0,0 +1,64 @@
+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 TrafficLight < ActiveRecord::Base
+  include ActiveRecord::Transitions
+
+  state_machine 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 TestScopes < Test::Unit::TestCase
+  def setup
+    ActiveRecord::Base.establish_connection(:adapter  => "sqlite3", :database => ":memory:")
+    ActiveRecord::Migration.verbose = false
+    CreateTrafficLights.migrate(:up)
+
+    @light = TrafficLight.create!
+  end
+
+  test "scope returns correct object" do
+    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
+end

data/transitions.gemspec

@@ -5,8 +5,8 @@ Gem::Specification.new do |s|
   s.name        = "transitions"
   s.version     = Transitions::VERSION
   s.platform    = Gem::Platform::RUBY
-  s.authors     = ["Jakub Kuźma"]
-  s.email       = "qoobaa@gmail.com"
+  s.authors     = ["Jakub Kuźma", "Timo Rößner"]
+  s.email       = "timo.roessner@googlemail.com"
   s.homepage    = "http://github.com/qoobaa/transitions"
   s.summary     = "State machine extracted from ActiveModel"
   s.description = "Lightweight state machine extracted from ActiveModel"

metadata

@@ -1,82 +1,78 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: transitions
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.0.11
   prerelease: 
-  version: 0.0.10
 platform: ruby
-authors: 
-- "Jakub Ku\xC5\xBAma"
+authors:
+- Jakub Kuźma
+- Timo Rößner
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-08-11 00:00:00 +02:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-10-12 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &69475640 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "1"
+      - !ruby/object:Gem::Version
+        version: '1'
   type: :development
   prerelease: false
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
+  version_requirements: *69475640
+- !ruby/object:Gem::Dependency
   name: test-unit
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: &69470060 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "2"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :development
   prerelease: false
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
+  version_requirements: *69470060
+- !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &69469200 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
   prerelease: false
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
+  version_requirements: *69469200
+- !ruby/object:Gem::Dependency
   name: sqlite3-ruby
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: &69468690 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
   prerelease: false
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
+  version_requirements: *69468690
+- !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: &69467660 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "3"
+      - !ruby/object:Gem::Version
+        version: '3'
   type: :development
   prerelease: false
-  version_requirements: *id005
+  version_requirements: *69467660
 description: Lightweight state machine extracted from ActiveModel
-email: qoobaa@gmail.com
+email: timo.roessner@googlemail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - Gemfile
 - Gemfile.lock
@@ -90,47 +86,45 @@ files:
 - lib/transitions/state.rb
 - lib/transitions/state_transition.rb
 - lib/transitions/version.rb
+- test/db/create_db.rb
 - test/helper.rb
 - test/test_active_record.rb
+- test/test_active_record_timestamps.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
 - transitions.gemspec
-has_rdoc: true
 homepage: http://github.com/qoobaa/transitions
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 347067155
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: 59531697
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
       version: 1.3.6
 requirements: []
-
 rubyforge_project: transitions
-rubygems_version: 1.6.2
+rubygems_version: 1.8.6
 signing_key: 
 specification_version: 3
 summary: State machine extracted from ActiveModel
 test_files: []
-