transitions 0.0.18 → 0.1.0

data/CHANGELOG.md

@@ -1,3 +1,29 @@
+# 1.0.0
+
+(troessner) Remove suppport for multipe state machines
+
+Here is the reasoning:
+
+1.) If you really need multiple state machines for one model, you probably need multiple models.
+    So far, I have not seen a valid use case for multiple state machines, which was not better expressed
+    by using multiple models.
+
+2.) The current transitions semantics and  API is not suited for multiple state machines:
+    Right now events are just plain methods defined on the models itself.
+    Consider you had multiple state machines, on named `day` and one named `night`, both with differing events.
+    What to do when you switch to state machine `day` but trigger an event defined on `night`?
+    You can either allow it, but this would make multiple state machines pointless if there is no enforced
+    separation of concerns. Or you disallow it, in which case `events` would either have to be bound
+    to state machines, not to the object itself, which would be tedious and ugly, or the `events` themselves
+    would need to check if they are allowed to be called. The last solution seems like a clean solution
+    but it would require a decent amount of rewriting existing code - and I just do not see the benefit for this.
+
+3.) Kind of a weak point, but right now the functionality is broken anyway throughout the gem. This functionality
+    is not even documented, so the side effects on existing projects should be minimal.
+
+On the plus side, removing the possibility of having multiple state machines will streamline and improve existing
+code a lot.
+
 # 0.0.18 (2012-05-18)
 
 * (troessner) Remove `define_state_query_method` from public API

data/README.rdoc

@@ -1,6 +1,6 @@
 = Travis Build Status 
 
-{<img src="https://secure.travis-ci.org/troessner/transitions.png"/>}[http://travis-ci.org/troessner/transitions]
+{<img src="https://secure.travis-ci.org/troessner/transitions.png?branch=master"/>}[http://travis-ci.org/troessner/transitions]
 
 = Synopsis
 
@@ -24,10 +24,8 @@ This goes into your Gemfile:
 
 = Using transitions
 
- require 'transitions'
- 
  class Product
-   include Transitions
+   include ActiveModel::Transitions
  
    state_machine do
      state :available # first one is initial state
@@ -46,6 +44,13 @@ This goes into your Gemfile:
    end
  end
 
+In this example we assume that you are in a rails project using Bundler, which would automitcally require `transitions`.
+If this is not the case for you you have to add
+
+ require 'transitions'
+
+whereever you load your dependencies in your application.
+
 = Features
 
 == Events
@@ -119,6 +124,19 @@ the name of the timestamp column.
     transitions :from => :exploded, :to => :rebuilt
   end
 
+== `event_fired` and `event_failed`
+
+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:
@@ -133,9 +151,6 @@ In case you have multiple state machines you can also pass the state machine nam
 = 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
 

data/lib/active_model/transitions.rb

@@ -36,39 +36,38 @@ module ActiveModel
     # 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)
-        end
+        sm = self.class.get_state_machine
+        remove_instance_variable(sm.current_state_variable) if instance_variable_defined?(sm.current_state_variable)
       end
     end
 
     protected
 
-    def write_state(state_machine, state)
-      prev_state = current_state(state_machine.name)
-      write_state_without_persistence(state_machine, state)
+    def write_state(state)
+      prev_state = current_state
+      write_state_without_persistence(state)
       save!
     rescue ActiveRecord::RecordInvalid
-      write_state_without_persistence(state_machine, prev_state)
+      write_state_without_persistence(prev_state)
       raise
     end
     
-    def write_state_without_persistence(state_machine, state)
-      ivar = state_machine.current_state_variable
+    def write_state_without_persistence(state)
+      ivar = self.class.get_state_machine.current_state_variable
       instance_variable_set(ivar, state)
       self.state = state.to_s
     end
 
-    def read_state(state_machine)
+    def read_state
       self.state && self.state.to_sym
     end
 
     def set_initial_state
-      self.state ||= self.class.state_machine.initial_state.to_s if self.has_attribute?(:state)
+      self.state ||= self.class.get_state_machine.initial_state.to_s if self.has_attribute?(:state)
     end
 
     def state_inclusion
-      unless self.class.state_machine.states.map{|s| s.name.to_s }.include?(self.state.to_s)
+      unless self.class.get_state_machine.states.map{|s| s.name.to_s }.include?(self.state.to_s)
         self.errors.add(:state, :inclusion, :value => self.state)
       end
     end

data/lib/transitions.rb

@@ -33,30 +33,23 @@ module Transitions
   module ClassMethods
     def inherited(klass)
       super # Make sure we call other callbacks possibly defined upstream the ancestor chain.
-      klass.state_machines = state_machines
-    end
-
-    def state_machines
-      @state_machines ||= {}
+      klass.state_machine = state_machine
     end
 
     # The only reason we need this method is for the inherited callback.
-    def state_machines=(value)
-      @state_machines = value ? value.dup : nil
+    def state_machine=(value)
+      @state_machine = value.dup
     end
 
-    def state_machine(name = nil, options = {}, &block)
-      if name.is_a?(Hash)
-        options = name
-        name    = nil
-      end
-      name ||= :default
-      state_machines[name] ||= Machine.new(self, name)
-      block ? state_machines[name].update(options, &block) : state_machines[name]
+    def state_machine(options = {}, &block)
+      @state_machine ||= Machine.new self
+      block ? @state_machine.update(options, &block) : @state_machine
     end
 
-    def available_states(name = :default)
-      state_machines[name].states.map(&:name).sort_by {|x| x.to_s}
+    def get_state_machine; @state_machine; end
+
+    def available_states
+      @state_machine.states.map(&:name).sort_by {|x| x.to_s}
     end
   end
 
@@ -65,16 +58,16 @@ module Transitions
   end
 
   # TODO Do we need this method really? Also, it's not a beauty, refactor at least.
-  def current_state(name = nil, new_state = nil, persist = false)
-    sm   = self.class.state_machine(name)
+  def current_state(new_state = nil, persist = false)
+    sm   = self.class.get_state_machine
     ivar = sm.current_state_variable
-    if name && new_state
+    if new_state
       if persist && respond_to?(:write_state)
-        write_state(sm, new_state)
+        write_state(new_state)
       end
 
       if respond_to?(:write_state_without_persistence)
-        write_state_without_persistence(sm, new_state)
+        write_state_without_persistence(new_state)
       end
 
       instance_variable_set(ivar, new_state)
@@ -84,7 +77,7 @@ module Transitions
       return value if value
 
       if respond_to?(:read_state)
-        value = instance_variable_set(ivar, read_state(sm))
+        value = instance_variable_set(ivar, read_state)
       end
 
       value || sm.initial_state

data/lib/transitions/event.rb

@@ -39,7 +39,7 @@ module Transitions
     end
 
     def fire(obj, to_state = nil, *args)
-      transitions = @transitions.select { |t| t.from == obj.current_state(@machine ? @machine.name : nil) }
+      transitions = @transitions.select { |t| t.from == obj.current_state }
       raise InvalidTransition, error_message_for_invalid_transitions(obj, to_state) if transitions.size == 0
 
       next_state = nil

data/lib/transitions/machine.rb

@@ -24,10 +24,10 @@ module Transitions
   class Machine
     attr_writer :initial_state
     attr_accessor :states, :events, :state_index
-    attr_reader :klass, :name, :auto_scopes
+    attr_reader :klass, :auto_scopes
 
-    def initialize(klass, name, options = {}, &block)
-      @klass, @name, @states, @state_index, @events = klass, name, [], {}, {}
+    def initialize(klass, options = {}, &block)
+      @klass, @states, @state_index, @events = klass, [], {}, {}
       update(options, &block)
     end
 
@@ -44,25 +44,25 @@ module Transitions
     end
 
     def fire_event(event, record, persist, *args)
-      state_index[record.current_state(@name)].call_action(:exit, record)
+      state_index[record.current_state].call_action(:exit, record)
       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)
+          if record.respond_to?(:event_fired)
+            record.send(:event_fired, record.current_state, new_state, event)
           end
 
-          record.current_state(@name, new_state, persist)
+          record.current_state(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)
+          record.send(:event_failed, event) if record.respond_to?(:event_failed)
           return false
         end
       rescue => e
-        if record.respond_to?(event_failed_callback)
-          record.send(event_failed_callback, event)
+        if record.respond_to?(:event_failed)
+          record.send(:event_failed, event)
           return false
         else
           raise e
@@ -80,27 +80,24 @@ module Transitions
     end
 
     def current_state_variable
-      "@#{@name}_current_state"
+      "@current_state"
     end
 
     private
 
     def state(name, options = {})
-      @states << (state_index[name] ||= State.new(name, :machine => self)).update(options)
+      unless @state_index.key? name # Just ignore duplicates
+        state = State.new(name, :machine => self)
+        state.update options
+        @state_index[name] = state
+        @states << state
+      end
     end
 
     def event(name, options = {}, &block)
       (@events[name] ||= Event.new(self, name)).update(options, &block)
     end
 
-    def event_fired_callback
-      @event_fired_callback ||= (@name == :default ? '' : "#{@name}_") + 'event_fired'
-    end
-
-    def event_failed_callback
-      @event_failed_callback ||= (@name == :default ? '' : "#{@name}_") + 'event_failed'
-    end
-
     def include_scopes
       @states.each do |state|
         state_name = state.name.to_s

data/lib/transitions/version.rb

@@ -1,3 +1,3 @@
 module Transitions
-  VERSION = "0.0.18"
+  VERSION = "0.1.0"
 end

data/test/test_active_record.rb

@@ -137,7 +137,7 @@ class TestActiveRecord < Test::Unit::TestCase
   end
 
   test "transition with wrong state will not validate" do
-    for s in @light.class.state_machine.states
+    for s in @light.class.get_state_machine.states
       @light.state = s.name
       assert @light.valid?
     end

data/test/test_available_states_listing.rb

@@ -3,25 +3,15 @@ require "helper"
 class Bender
   include Transitions
 
-  state_machine :default do
+  state_machine 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_machine.rb

@@ -3,12 +3,10 @@ require "helper"
 class MachineTestSubject
   include Transitions
 
-  state_machine do
+  state_machine :initial => :closed do
     state :open
     state :closed
-  end
 
-  state_machine :initial => :foo do
     event :shutdown do
       transitions :from => :open, :to => :closed
     end
@@ -17,26 +15,19 @@ class MachineTestSubject
       transitions :from => :open, :to => :closed
     end
   end
-
-  state_machine :extra, :initial => :bar do
-  end
 end
 
 class TransitionsMachineTest < Test::Unit::TestCase
-  test "allows reuse of existing machines" do
-    assert_equal 2, MachineTestSubject.state_machines.size
-  end
-
   test "sets #initial_state from :initial option" do
-    assert_equal :bar, MachineTestSubject.state_machine(:extra).initial_state
+    assert_equal :closed, MachineTestSubject.get_state_machine.initial_state
   end
 
-  test "accesses non-default state machine" do
-    assert_kind_of Transitions::Machine, MachineTestSubject.state_machine(:extra)
+  test "`get_state_machine` returns Transitions::Machine" do
+    assert_kind_of Transitions::Machine, MachineTestSubject.get_state_machine
   end
 
   test "finds events for given state" do
-    events = MachineTestSubject.state_machine.events_for(:open)
+    events = MachineTestSubject.get_state_machine.events_for(:open)
     assert events.include?(:shutdown)
     assert events.include?(:timeout)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: transitions
 version: !ruby/object:Gem::Version
-  version: 0.0.18
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-18 00:00:00.000000000Z
+date: 2012-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &76418870 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,10 +22,15 @@ dependencies:
         version: '1'
   type: :development
   prerelease: false
-  version_requirements: *76418870
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: test-unit
-  requirement: &76418470 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -33,10 +38,15 @@ dependencies:
         version: '2.2'
   type: :development
   prerelease: false
-  version_requirements: *76418470
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &76418120 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -44,10 +54,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *76418120
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &76417650 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -55,10 +70,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *76417650
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: random_data
-  requirement: &76417170 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -66,10 +86,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *76417170
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &76416820 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -77,10 +102,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *76416820
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &76416030 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -88,7 +118,12 @@ dependencies:
         version: '3'
   type: :development
   prerelease: false
-  version_requirements: *76416030
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3'
 description: Lightweight state machine extracted from ActiveModel
 email: timo.roessner@googlemail.com
 executables: []
@@ -140,7 +175,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1015670387
+      hash: -659970477
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -149,7 +184,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubyforge_project: transitions
-rubygems_version: 1.8.10
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: State machine extracted from ActiveModel