updated to r66 of acts_as_state_machine plugin. This eliminates some rails deprecation warnings

git-svn-id: http://www.rousette.org.uk/svn/tracks-repos/trunk@420 a4c988fc-2ded-0310-b66e-134b36920a42

tracks/vendor/plugins/acts_as_state_machine/CHANGELOG

@@ -0,0 +1,13 @@
+* trunk *
+  break with true value [Kaspar Schiess]
+
+* 2.1 *
+  After actions [Saimon Moore]
+
+* 2.0 * (2006-01-20 15:26:28 -0500)
+  Enter / Exit actions
+  Transition guards
+  Guards and actions can be a symbol pointing to a method or a Proc
+
+* 1.0 * (2006-01-15 12:16:55 -0500)
+	Initial Release

tracks/vendor/plugins/acts_as_state_machine/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006 Scott Barron
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

tracks/vendor/plugins/acts_as_state_machine/README

@@ -0,0 +1,33 @@
+= Acts As State Machine
+
+This act gives an Active Record model the ability to act as a finite state
+machine (FSM).
+
+Acquire via subversion at:
+
+http://elitists.textdriven.com/svn/plugins/acts_as_state_machine/trunk
+
+If prompted, use the user/pass anonymous/anonymous.
+
+== Example
+
+ class Order < ActiveRecord::Base
+   acts_as_state_machine :initial => :opened
+
+   state :opened
+   state :closed, :enter => Proc.new {|o| Mailer.send_notice(o)}
+   state :returned
+
+   event :close do
+     transitions :to => :closed, :from => :opened
+   end
+
+   event :return do
+     transitions :to => :returned, :from => :closed
+   end
+ end
+
+ o = Order.create
+ o.close! # notice is sent by mailer
+ o.return!
+

tracks/vendor/plugins/acts_as_state_machine/Rakefile

@@ -0,0 +1,28 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => [:clean_db, :test]
+
+desc 'Remove the stale db file'
+task :clean_db do
+  `rm -f #{File.dirname(__FILE__)}/test/state_machine.sqlite.db`
+end
+
+desc 'Test the acts as state machine plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the acts as state machine plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Acts As State Machine'
+  rdoc.options << '--line-numbers --inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('TODO')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

tracks/vendor/plugins/acts_as_state_machine/TODO

@@ -0,0 +1,11 @@
+* Currently invalid events are ignored, create an option so that they can be
+  ignored or raise an exception.
+
+* Query for a list of possible next states.
+
+* Make listing states optional since they can be inferred from the events.
+  Only required to list a state if you want to define a transition block for it.
+
+* Real transition actions
+
+* Default states

tracks/vendor/plugins/acts_as_state_machine/init.rb

@@ -0,0 +1,5 @@
+require 'acts_as_state_machine'
+
+ActiveRecord::Base.class_eval do
+  include ScottBarron::Acts::StateMachine
+end

tracks/vendor/plugins/acts_as_state_machine/lib/acts_as_state_machine.rb

@@ -0,0 +1,268 @@
+module ScottBarron                   #:nodoc:
+  module Acts                        #:nodoc:
+    module StateMachine              #:nodoc:
+      class InvalidState < Exception #:nodoc:
+      end
+      class NoInitialState < Exception #:nodoc:
+      end
+      
+      def self.included(base)        #:nodoc:
+        base.extend ActMacro
+      end
+      
+      module SupportingClasses
+        class State
+          attr_reader :name
+        
+          def initialize(name, opts)
+            @name, @opts = name, opts
+          end
+        
+          def entering(record)
+            enteract = @opts[:enter]
+            record.send(:run_transition_action, enteract) if enteract
+          end
+        
+          def entered(record)
+            afteractions = @opts[:after]
+            return unless afteractions
+            Array(afteractions).each do |afteract|
+              record.send(:run_transition_action, afteract)
+            end
+          end
+        
+          def exited(record)
+            exitact  = @opts[:exit]
+            record.send(:run_transition_action, exitact) if exitact
+          end
+        end
+
+        class StateTransition
+          attr_reader :from, :to, :opts
+          
+          def initialize(opts)
+            @from, @to, @guard = opts[:from], opts[:to], opts[:guard]
+            @opts = opts
+          end
+          
+          def guard(obj)
+            @guard ? obj.send(:run_transition_action, @guard) : true
+          end
+
+          def perform(record)
+            return false unless guard(record)
+            loopback = record.current_state == to
+            states = record.class.read_inheritable_attribute(:states)
+            next_state = states[to]
+            old_state = states[record.current_state]
+          
+            next_state.entering(record) unless loopback
+          
+            record.update_attribute(record.class.state_column, to.to_s)
+          
+            next_state.entered(record) unless loopback
+            old_state.exited(record) unless loopback
+            true
+          end
+          
+          def ==(obj)
+            @from == obj.from && @to == obj.to
+          end
+        end
+        
+        class Event
+          attr_reader :name
+          attr_reader :transitions
+          attr_reader :opts
+
+          def initialize(name, opts, transition_table, &block)
+            @name = name.to_sym
+            @transitions = transition_table[@name] = []
+            instance_eval(&block) if block
+            @opts = opts
+            @opts.freeze
+            @transitions.freeze
+            freeze
+          end
+          
+          def next_states(record)
+            @transitions.select { |t| t.from == record.current_state }
+          end
+          
+          def fire(record)
+            next_states(record).each do |transition|
+              break true if transition.perform(record)
+            end
+          end
+          
+          def transitions(trans_opts)
+            Array(trans_opts[:from]).each do |s|
+              @transitions << SupportingClasses::StateTransition.new(trans_opts.merge({:from => s.to_sym}))
+            end
+          end
+        end
+      end
+      
+      module ActMacro
+        # Configuration options are
+        #
+        # * +column+ - specifies the column name to use for keeping the state (default: state)
+        # * +initial+ - specifies an initial state for newly created objects (required)
+        def acts_as_state_machine(opts)
+          self.extend(ClassMethods)
+          raise NoInitialState unless opts[:initial]
+          
+          write_inheritable_attribute :states, {}
+          write_inheritable_attribute :initial_state, opts[:initial]
+          write_inheritable_attribute :transition_table, {}
+          write_inheritable_attribute :event_table, {}
+          write_inheritable_attribute :state_column, opts[:column] || 'state'
+          
+          class_inheritable_reader    :initial_state
+          class_inheritable_reader    :state_column
+          class_inheritable_reader    :transition_table
+          class_inheritable_reader    :event_table
+          
+          self.send(:include, ScottBarron::Acts::StateMachine::InstanceMethods)
+
+          before_create               :set_initial_state
+          after_create                :run_initial_state_actions
+        end
+      end
+      
+      module InstanceMethods
+        def set_initial_state #:nodoc:
+          write_attribute self.class.state_column, self.class.initial_state.to_s
+        end
+
+        def run_initial_state_actions
+          initial = self.class.read_inheritable_attribute(:states)[self.class.initial_state.to_sym]
+          initial.entering(self)
+          initial.entered(self)
+        end
+      
+        # Returns the current state the object is in, as a Ruby symbol.
+        def current_state
+          self.send(self.class.state_column).to_sym
+        end
+      
+        # Returns what the next state for a given event would be, as a Ruby symbol.
+        def next_state_for_event(event)
+          ns = next_states_for_event(event)
+          ns.empty? ? nil : ns.first.to
+        end
+
+        def next_states_for_event(event)
+          self.class.read_inheritable_attribute(:transition_table)[event.to_sym].select do |s|
+            s.from == current_state
+          end
+        end
+
+        def run_transition_action(action)
+          Symbol === action ? self.method(action).call : action.call(self)
+        end
+        private :run_transition_action
+      end
+
+      module ClassMethods
+        # Returns an array of all known states.
+        def states
+          read_inheritable_attribute(:states).keys
+        end
+        
+        # Define an event.  This takes a block which describes all valid transitions
+        # for this event.
+        #
+        # Example:
+        #
+        # class Order < ActiveRecord::Base
+        #   acts_as_state_machine :initial => :open
+        #
+        #   state :open
+        #   state :closed
+        #
+        #   event :close_order do
+        #     transitions :to => :closed, :from => :open
+        #   end
+        # end
+        #
+        # +transitions+ takes a hash where <tt>:to</tt> is the state to transition
+        # to and <tt>:from</tt> is a state (or Array of states) from which this
+        # event can be fired.
+        #
+        # This creates an instance method used for firing the event.  The method
+        # created is the name of the event followed by an exclamation point (!).
+        # Example: <tt>order.close_order!</tt>.
+        def event(event, opts={}, &block)
+          tt = read_inheritable_attribute(:transition_table)
+          
+          et = read_inheritable_attribute(:event_table)
+          e = et[event.to_sym] = SupportingClasses::Event.new(event, opts, tt, &block)
+          define_method("#{event.to_s}!") { e.fire(self) }
+        end
+        
+        # Define a state of the system. +state+ can take an optional Proc object
+        # which will be executed every time the system transitions into that
+        # state.  The proc will be passed the current object.
+        #
+        # Example:
+        #
+        # class Order < ActiveRecord::Base
+        #   acts_as_state_machine :initial => :open
+        #
+        #   state :open
+        #   state :closed, Proc.new { |o| Mailer.send_notice(o) }
+        # end
+        def state(name, opts={})
+          state = SupportingClasses::State.new(name.to_sym, opts)
+          read_inheritable_attribute(:states)[name.to_sym] = state
+        
+          define_method("#{state.name}?") { current_state == state.name }
+        end
+        
+        # Wraps ActiveRecord::Base.find to conveniently find all records in
+        # a given state.  Options:
+        #
+        # * +number+ - This is just :first or :all from ActiveRecord +find+
+        # * +state+ - The state to find
+        # * +args+ - The rest of the args are passed down to ActiveRecord +find+
+        def find_in_state(number, state, *args)
+          with_state_scope state do
+            find(number, *args)
+          end
+        end
+        
+        # Wraps ActiveRecord::Base.count to conveniently count all records in
+        # a given state.  Options:
+        #
+        # * +state+ - The state to find
+        # * +args+ - The rest of the args are passed down to ActiveRecord +find+
+        def count_in_state(state, *args)
+          with_state_scope state do
+            count(*args)
+          end
+        end
+        
+        # Wraps ActiveRecord::Base.calculate to conveniently calculate all records in
+        # a given state.  Options:
+        #
+        # * +state+ - The state to find
+        # * +args+ - The rest of the args are passed down to ActiveRecord +calculate+
+        def calculate_in_state(state, *args)
+          with_state_scope state do
+            calculate(*args)
+          end
+        end
+        
+        protected
+        def with_state_scope(state)
+          raise InvalidState unless states.include?(state)
+          
+          with_scope :find => {:conditions => ["#{table_name}.#{state_column} = ?", state.to_s]} do
+            yield if block_given?
+          end
+        end
+      end
+    end
+  end
+end

tracks/vendor/plugins/acts_as_state_machine/test/acts_as_state_machine_test.rb

@@ -0,0 +1,224 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+include ScottBarron::Acts::StateMachine
+
+class ActsAsStateMachineTest < Test::Unit::TestCase
+  fixtures :conversations
+  
+  def test_no_initial_value_raises_exception
+    assert_raise(NoInitialState) {
+      Person.acts_as_state_machine({})
+    }
+  end
+  
+  def test_initial_state_value
+    assert_equal :needs_attention, Conversation.initial_state
+  end
+  
+  def test_column_was_set
+    assert_equal 'state_machine', Conversation.state_column
+  end
+  
+  def test_initial_state
+    c = Conversation.create
+    assert_equal :needs_attention, c.current_state
+    assert c.needs_attention?
+  end
+  
+  def test_states_were_set
+    [:needs_attention, :read, :closed, :awaiting_response, :junk].each do |s|
+      assert Conversation.states.include?(s)
+    end
+  end
+  
+  def test_event_methods_created
+    c = Conversation.create
+    %w(new_message! view! reply! close! junk! unjunk!).each do |event|
+      assert c.respond_to?(event)
+    end
+  end
+
+  def test_query_methods_created
+    c = Conversation.create
+    %w(needs_attention? read? closed? awaiting_response? junk?).each do |event|
+      assert c.respond_to?(event)
+    end
+  end
+  
+  def test_transition_table
+    tt = Conversation.transition_table
+    
+    assert tt[:new_message].include?(SupportingClasses::StateTransition.new(:from => :read, :to => :needs_attention))
+    assert tt[:new_message].include?(SupportingClasses::StateTransition.new(:from => :closed, :to => :needs_attention))
+    assert tt[:new_message].include?(SupportingClasses::StateTransition.new(:from => :awaiting_response, :to => :needs_attention))
+  end
+
+  def test_next_state_for_event
+    c = Conversation.create
+    assert_equal :read, c.next_state_for_event(:view)
+  end
+  
+  def test_change_state
+    c = Conversation.create
+    c.view!
+    assert c.read?
+  end
+  
+  def test_can_go_from_read_to_closed_because_guard_passes
+    c = Conversation.create
+    c.can_close = true
+    c.view!
+    c.reply!
+    c.close!
+    assert_equal :closed, c.current_state
+  end
+  
+  def test_cannot_go_from_read_to_closed_because_of_guard
+    c = Conversation.create
+    c.can_close = false
+    c.view!
+    c.reply!
+    c.close!
+    assert_equal :read, c.current_state
+  end
+
+  def test_ignore_invalid_events
+    c = Conversation.create
+    c.view!
+    c.junk!
+
+    # This is the invalid event
+    c.new_message!
+    assert_equal :junk, c.current_state
+  end
+
+  def test_entry_action_executed
+    c = Conversation.create
+    c.read_enter = false
+    c.view!
+    assert c.read_enter
+  end
+
+  def test_after_actions_executed
+    c = Conversation.create
+
+    c.read_after_first = false
+    c.read_after_second = false
+    c.closed_after = false
+
+    c.view!
+    assert c.read_after_first
+    assert c.read_after_second
+
+    c.can_close = true
+    c.close!
+
+    assert c.closed_after
+    assert_equal :closed, c.current_state
+  end
+
+  def test_after_actions_not_run_on_loopback_transition
+    c = Conversation.create
+
+    c.view!
+    c.read_after_first = false
+    c.read_after_second = false
+    c.view!
+
+    assert !c.read_after_first
+    assert !c.read_after_second
+
+    c.can_close = true
+
+    c.close!
+    c.closed_after = false
+    c.close!
+
+    assert !c.closed_after
+  end
+
+  def test_exit_action_executed
+    c = Conversation.create
+    c.read_exit = false
+    c.view!
+    c.junk!
+    assert c.read_exit
+  end
+  
+  def test_entry_and_exit_not_run_on_loopback_transition
+    c = Conversation.create
+    c.view!
+    c.read_enter = false
+    c.read_exit  = false
+    c.view!
+    assert !c.read_enter
+    assert !c.read_exit
+  end
+
+  def test_entry_and_after_actions_called_for_initial_state
+    c = Conversation.create
+    assert c.needs_attention_enter
+    assert c.needs_attention_after
+  end
+  
+  def test_run_transition_action_is_private
+    c = Conversation.create
+    assert_raise(NoMethodError) { c.run_transition_action :foo }
+  end
+  
+  def test_find_all_in_state
+    cs = Conversation.find_in_state(:all, :read)
+    
+    assert_equal 2, cs.size
+  end
+  
+  def test_find_first_in_state
+    c = Conversation.find_in_state(:first, :read)
+    
+    assert_equal conversations(:first).id, c.id
+  end
+  
+  def test_find_all_in_state_with_conditions
+    cs = Conversation.find_in_state(:all, :read, :conditions => ['subject = ?', conversations(:second).subject])
+    
+    assert_equal 1, cs.size
+    assert_equal conversations(:second).id, cs.first.id
+  end
+  
+  def test_find_first_in_state_with_conditions
+    c = Conversation.find_in_state(:first, :read, :conditions => ['subject = ?', conversations(:second).subject])
+    assert_equal conversations(:second).id, c.id
+  end
+  
+  def test_count_in_state
+    cnt0 = Conversation.count(['state_machine = ?', 'read'])
+    cnt  = Conversation.count_in_state(:read)
+    
+    assert_equal cnt0, cnt
+  end
+  
+  def test_count_in_state_with_conditions
+    cnt0 = Conversation.count(['state_machine = ? AND subject = ?', 'read', 'Foo'])
+    cnt  = Conversation.count_in_state(:read, ['subject = ?', 'Foo'])
+    
+    assert_equal cnt0, cnt
+  end
+  
+  def test_find_in_invalid_state_raises_exception
+    assert_raise(InvalidState) {
+      Conversation.find_in_state(:all, :dead)
+    }
+  end
+  
+  def test_count_in_invalid_state_raises_exception
+    assert_raise(InvalidState) {
+      Conversation.count_in_state(:dead)
+    }
+  end
+
+  def test_can_access_events_via_event_table
+    event = Conversation.event_table[:junk]
+    assert_equal :junk, event.name
+    assert_equal "finished", event.opts[:note]
+  end
+end

tracks/vendor/plugins/acts_as_state_machine/test/database.yml

@@ -0,0 +1,18 @@
+sqlite:
+  :adapter: sqlite
+  :dbfile: state_machine.sqlite.db
+sqlite3:
+  :adapter: sqlite3
+  :dbfile: state_machine.sqlite3.db
+postgresql:
+  :adapter: postgresql
+  :username: postgres
+  :password: postgres
+  :database: state_machine_test
+  :min_messages: ERROR
+mysql:
+  :adapter: mysql
+  :host: localhost
+  :username: rails
+  :password:
+  :database: state_machine_test

tracks/vendor/plugins/acts_as_state_machine/test/fixtures/conversation.rb

@@ -0,0 +1,67 @@
+class Conversation < ActiveRecord::Base
+  attr_writer :can_close
+  attr_accessor :read_enter, :read_exit, :read_after_first, :read_after_second,
+                :closed_after, :needs_attention_enter, :needs_attention_after
+
+  acts_as_state_machine :initial => :needs_attention, :column => 'state_machine'
+
+  state :needs_attention, :enter => Proc.new { |o| o.needs_attention_enter = true },
+                          :after => Proc.new { |o| o.needs_attention_after = true }
+                          
+  state :read, :enter => :read_enter_action,
+               :exit  => Proc.new { |o| o.read_exit  = true },
+               :after => [:read_after_first_action, :read_after_second_action]
+
+  state :closed, :after => :closed_after_action
+  state :awaiting_response
+  state :junk
+
+  event :new_message do
+    transitions :to => :needs_attention,   :from => [:read, :closed, :awaiting_response]
+  end
+
+  event :view do
+    transitions :to => :read,              :from => [:needs_attention, :read]
+  end
+  
+  event :reply do
+    transitions :to => :awaiting_response, :from => [:read, :closed]
+  end
+
+  event :close do
+    transitions :to => :closed,            :from => [:read, :awaiting_response], :guard => Proc.new {|o| o.can_close?}
+    transitions :to => :read,              :from => [:read, :awaiting_response], :guard => :always_true
+  end
+
+  event :junk, :note => "finished" do
+    transitions :to => :junk,              :from => [:read, :closed, :awaiting_response]
+  end
+
+  event :unjunk do
+    transitions :to => :closed,            :from => :junk
+  end
+
+  def can_close?
+    @can_close
+  end
+
+  def read_enter_action
+    self.read_enter = true
+  end
+
+  def always_true
+    true
+  end
+
+  def read_after_first_action
+    self.read_after_first = true
+  end
+
+  def read_after_second_action
+    self.read_after_second = true
+  end
+
+  def closed_after_action
+    self.closed_after = true
+  end
+end

tracks/vendor/plugins/acts_as_state_machine/test/fixtures/conversations.yml

@@ -0,0 +1,11 @@
+first:
+  id: 1
+  state_machine: read
+  subject: This is a test
+  closed: false
+  
+second:
+  id: 2
+  state_machine: read
+  subject: Foo
+  closed: false

tracks/vendor/plugins/acts_as_state_machine/test/fixtures/person.rb

@@ -0,0 +1,2 @@
+class Person < ActiveRecord::Base
+end

tracks/vendor/plugins/acts_as_state_machine/test/schema.rb

@@ -0,0 +1,11 @@
+ActiveRecord::Schema.define(:version => 1) do
+  create_table :conversations, :force => true do |t|
+    t.column :state_machine, :string
+    t.column :subject,       :string
+    t.column :closed,        :boolean
+  end
+  
+  create_table :people, :force => true do |t|
+    t.column :name, :string
+  end
+end

tracks/vendor/plugins/acts_as_state_machine/test/test_helper.rb

@@ -0,0 +1,38 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+RAILS_ROOT = File.dirname(__FILE__)
+
+require 'rubygems'
+require 'test/unit'
+require 'active_record'
+require 'active_record/fixtures'
+require 'active_support/binding_of_caller'
+require 'active_support/breakpoint'
+require "#{File.dirname(__FILE__)}/../init"
+
+
+config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
+ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
+ActiveRecord::Base.establish_connection(config[ENV['DB'] || 'sqlite'])
+
+load(File.dirname(__FILE__) + "/schema.rb") if File.exist?(File.dirname(__FILE__) + "/schema.rb")
+
+Test::Unit::TestCase.fixture_path = File.dirname(__FILE__) + "/fixtures/"
+$LOAD_PATH.unshift(Test::Unit::TestCase.fixture_path)
+
+class Test::Unit::TestCase #:nodoc:
+  def create_fixtures(*table_names)
+    if block_given?
+      Fixtures.create_fixtures(Test::Unit::TestCase.fixture_path, table_names) { yield }
+    else
+      Fixtures.create_fixtures(Test::Unit::TestCase.fixture_path, table_names)
+    end
+  end
+
+  # Turn off transactional fixtures if you're working with MyISAM tables in MySQL
+  self.use_transactional_fixtures = true
+  
+  # Instantiated fixtures are slow, but give you @david where you otherwise would need people(:david)
+  self.use_instantiated_fixtures  = false
+
+  # Add more helper methods to be used by all tests here...
+end