state_machine 0.1.0

data/CHANGELOG

@@ -0,0 +1,101 @@
+*SVN*
+
+*0.1.0* (May 5th, 2008)
+
+* Completely rewritten from scratch
+
+* Renamed to state_machine
+
+* Removed database dependencies
+
+* Removed models in favor of an attribute-agnostic design
+
+* Use ActiveSupport::Callbacks instead of eval_call
+
+* Remove dry_transaction_rollbacks dependencies
+
+* Added functional tests
+
+* Updated documentation
+
+*0.0.1* (September 26th, 2007)
+
+* Add dependency on custom_callbacks
+
+* Move test fixtures out of the test application root directory
+
+* Improve documentation
+
+* Remove the StateExtension module in favor of adding singleton methods to the stateful class
+
+* Convert dos newlines to unix newlines
+
+* Fix error message when a given event can't be found in the database
+
+* Add before_#{action} and #{action} callbacks when an event is performed
+
+* All state and event callbacks can now explicitly return false in order to cancel the action
+
+* Refactor ActiveState callback creation
+
+* Refactor unit tests so that they use mock classes instead of themselves
+
+* Allow force_reload option to be set in the state association
+
+* Don't save the entire model when updating the state_id
+
+* Raise exception if a class tries to define a state more than once
+
+* Add tests for PluginAWeek::Has::States::ActiveState
+
+* Refactor active state/active event creation
+
+* Fix owner_type not being set correctly in active states/events of subclasses
+
+* Allow subclasses to override the initial state
+
+* Fix problem with migrations using default null when column cannot be null
+
+* Moved deadline support into a separate plugin (has_state_deadlines).
+
+* Added many more unit tests.
+
+* Simplified many of the interfaces for maintainability.
+
+* Added support for turning off recording state changes.
+
+* Removed the short_description and long_description columns, in favor of an optional human_name column.
+
+* Fixed not overriding the correct equality methods in the StateTransition class.
+
+* Added to_sym to State and Event.
+
+* State#name and Event#name now return the string version of the name instead of the symbol version.
+
+* Added State#human_name and Event#human_name to automatically figure out what the human name is if it isn't specified in the table.
+
+* Updated manual rollbacks to use the new Rails edge api (ActiveRecord::Rollback exception).
+
+* Moved StateExtension class into a separate file in order to help keep the has_state files clean.
+
+* Renamed InvalidState and InvalidEvent exceptions to StateNotFound and EventNotFound in order to follow the ActiveRecord convention (i.e. RecordNotFound).
+
+* Added StateNotActive and EventNotActive exceptions to help differentiate between states which don't exist and states which weren't defined in the class.
+
+* Added support for defining callbacks like so:
+
+  def before_exit_parked
+  end
+  
+  def after_enter_idling
+  end
+
+* Added support for defining callbacks using class methods:
+
+  before_exit_parked :fasten_seatbelt
+
+* Added event callbacks after the transition has occurred (e.g. after_park)
+
+* State callbacks no longer receive any of the arguments that were provided in the event action
+
+* Updated license to include our names.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006 Scott Barron, 2006-2008 Aaron Pfefier
+
+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.

data/README

@@ -0,0 +1,97 @@
+== state_machine
+
++state_machine+ support for creating state machines for attributes within a model.
+
+== Resources
+
+Wiki
+
+* http://wiki.pluginaweek.org/State_machine
+
+API
+
+* http://api.pluginaweek.org/state_machine
+
+Development
+
+* http://dev.pluginaweek.org/browser/trunk/state_machine
+
+Source
+
+* http://svn.pluginaweek.org/trunk/state_machine
+
+== Description
+
+State machines make it dead-simple to manage the behavior of a model.  Too often,
+the status of a record is kept by creating multiple boolean columns in the table
+and deciding how to behave based on the values in those columns.  This can become
+cumbersome and difficult to maintain when the complexity of your models starts to
+increase.
+
++state_machine+ simplifies this design by introducing the various parts of a state
+machine, including states, events, and transitions.  However, its api is designed
+to be similar to ActiveRecord in terms of validations and callbacks, making it
+so simple you don't even need to know what a state machine is :)
+
+== Usage
+
+=== Example
+
+  class Vehicle < ActiveRecord::Base
+    state_machine :state, :initial => 'idling' do
+      before_exit   'parked', :put_on_seatbelt
+      after_enter   'parked', Proc.new {|vehicle| vehicle.update_attribute(:seatbelt_on, false)}
+      
+      event :park do
+        transition :to => 'parked', :from => %w(idling first_gear)
+      end
+      
+      event :ignite do
+        transition :to => 'stalled', :from => 'stalled'
+        transition :to => 'idling', :from => 'parked'
+      end
+      
+      event :idle do
+        transition :to => 'idling', :from => 'first_gear'
+      end
+      
+      event :shift_up do
+        transition :to => 'first_gear', :from => 'idling'
+        transition :to => 'second_gear', :from => 'first_gear'
+        transition :to => 'third_gear', :from => 'second_gear'
+      end
+      
+      event :shift_down do
+        transition :to => 'second_gear', :from => 'third_gear'
+        transition :to => 'first_gear', :from => 'second_gear'
+      end
+      
+      event :crash, :after => :tow! do
+        transition :to => 'stalled', :from => %w(first_gear second_gear third_gear), :unless => :auto_shop_busy?
+      end
+      
+      event :repair, :after => :fix! do
+        transition :to => 'parked', :from => 'stalled', :if => :auto_shop_busy?
+      end
+    end
+  end
+
+== Tools
+
+Jean Bovet - {Visual Automata Simulator}[http://www.cs.usfca.edu/~jbovet/vas.html].
+This is a great tool for "simulating, visualizing and transforming finite state
+automata and Turing Machines".  This tool can help in the creation of states and
+events for your models.  It is cross-platform, written in Java.
+
+== Dependencies
+
+None.
+
+== Testing
+
+Before you can run any tests, the following gem must be installed:
+* plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]
+
+== References
+
+* Scott Barron - acts_as_state_machine[http://elitists.textdriven.com/svn/plugins/acts_as_state_machine]

data/Rakefile

@@ -0,0 +1,79 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+PKG_NAME           = 'state_machine'
+PKG_VERSION        = '0.1.0'
+PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
+RUBY_FORGE_PROJECT = 'pluginaweek'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the 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 state_machine plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'StateMachine'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s|
+  s.name            = PKG_NAME
+  s.version         = PKG_VERSION
+  s.platform        = Gem::Platform::RUBY
+  s.summary         = 'Adds support for creating state machines for attributes within a model'
+  
+  s.files           = FileList['{lib,test}/**/*'].to_a + %w(CHANGELOG init.rb MIT-LICENSE Rakefile README)
+  s.require_path    = 'lib'
+  s.autorequire     = 'state_machine'
+  s.has_rdoc        = true
+  s.test_files      = Dir['test/**/*_test.rb']
+  
+  s.author          = 'Aaron Pfeifer'
+  s.email           = 'aaron@pluginaweek.org'
+  s.homepage        = 'http://www.pluginaweek.org'
+end
+  
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+desc 'Publish the beta gem'
+task :pgem => [:package] do
+  Rake::SshFilePublisher.new('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{PKG_FILE_NAME}.gem").upload
+end
+
+desc 'Publish the API documentation'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{PKG_NAME}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new
+  ruby_forge.login
+  
+  %w( gem tgz zip ).each do |ext|
+    file = "pkg/#{PKG_FILE_NAME}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(RUBY_FORGE_PROJECT, PKG_NAME, PKG_VERSION, file)
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'state_machine'

data/lib/state_machine.rb

@@ -0,0 +1,92 @@
+require 'state_machine/machine'
+
+module PluginAWeek #:nodoc:
+  # A state machine is a model of behavior composed of states, transitions,
+  # and events.  This helper adds support for defining this type of
+  # functionality within your ActiveRecord models.
+  module StateMachine
+    def self.included(base) #:nodoc:
+      base.class_eval do
+        extend PluginAWeek::StateMachine::MacroMethods
+      end
+    end
+    
+    module MacroMethods
+      # Creates a state machine for the given attribute.
+      # 
+      # Configuration options:
+      # * +initial+ - The initial value of the attribute.  This can either be the actual value or a Proc for dynamic initial states.
+      # 
+      # == Example
+      # 
+      # With a static state:
+      # 
+      #   class Switch < ActiveRecord::Base
+      #     state_machine :state, :initial => 'off' do
+      #       ...
+      #     end
+      #   end
+      # 
+      # With a dynamic state:
+      # 
+      #   class Switch < ActiveRecord::Base
+      #     state_machine :state, :initial => Proc.new {|switch| (8..22).include?(Time.now.hour) ? 'on' : 'off'} do
+      #       ...
+      #     end
+      #   end
+      def state_machine(attribute, options = {}, &block)
+        unless included_modules.include?(PluginAWeek::StateMachine::InstanceMethods)
+          write_inheritable_attribute :state_machines, {}
+          class_inheritable_reader :state_machines
+          
+          after_create :run_initial_state_machine_actions
+          
+          include PluginAWeek::StateMachine::InstanceMethods
+        end
+        
+        # This will create a new machine for subclasses as well so that the owner_class and
+        # initial state can be overridden
+        attribute = attribute.to_s
+        options[:initial] = state_machines[attribute].initial_state_without_processing if !options.include?(:initial) && state_machines[attribute]
+        machine = state_machines[attribute] = PluginAWeek::StateMachine::Machine.new(self, attribute, options)
+        machine.instance_eval(&block) if block
+        machine
+      end
+    end
+    
+    module InstanceMethods
+      def self.included(base) #:nodoc:
+        base.class_eval do
+          alias_method_chain :initialize, :state_machine
+        end
+      end
+      
+      # Defines the initial values for state machine attributes
+      def initialize_with_state_machine(attributes = nil)
+        initialize_without_state_machine(attributes)
+        
+        attribute_keys = (attributes || {}).keys.map!(&:to_s)
+        
+        self.class.state_machines.each do |attribute, machine|
+          unless attribute_keys.include?(attribute)
+            send("#{attribute}=", machine.initial_state(self))
+          end
+        end
+        
+        yield self if block_given?
+      end
+      
+      # Records the transition for the record going into its initial state
+      def run_initial_state_machine_actions
+        self.class.state_machines.each do |attribute, machine|
+          callback = "after_enter_#{attribute}_#{self[attribute]}"
+          run_callbacks(callback) if self.class.respond_to?(callback)
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval do
+  include PluginAWeek::StateMachine
+end

data/lib/state_machine/event.rb

@@ -0,0 +1,127 @@
+require 'state_machine/transition'
+
+module PluginAWeek #:nodoc:
+  module StateMachine
+    # An event defines an action that transitions an attribute from one state to
+    # another
+    class Event
+      # The state machine for which this event is defined
+      attr_reader :machine
+      
+      # The name of the action that fires the event
+      attr_reader :name
+      
+      delegate  :owner_class,
+                  :to => :machine
+      
+      # Creates a new event with the given name
+      def initialize(machine, name, options = {})
+        options.assert_valid_keys(:before, :after)
+        
+        @machine = machine
+        @name = name
+        @options = options.stringify_keys
+        
+        add_transition_action
+        add_transition_callbacks
+        add_event_callbacks
+      end
+      
+      # Creates a new transition to the specified state.
+      # 
+      # Configuration options:
+      # * +to+ - The state that being transitioned to
+      # * +from+ - A state or array of states that can be transitioned from
+      # * +if+ - Specifies a method, proc or string to call to determine if the validation should occur (e.g. :if => :moving?, or :if => Proc.new {|car| car.speed > 60}). The method, proc or string should return or evaluate to a true or false value.
+      # * +unless+ - Specifies a method, proc or string to call to determine if the transition should not occur (e.g. :unless => :stopped?, or :unless => Proc.new {|car| car.speed <= 60}). The method, proc or string should return or evaluate to a true or false value.
+      # 
+      # == Examples
+      # 
+      #   transition :to => 'parked', :from => 'first_gear'
+      #   transition :to => 'parked', :from => %w(first_gear reverse)
+      #   transition :to => 'parked', :from => 'first_gear', :if => :moving?
+      #   transition :to => 'parked', :from => 'first_gear', :unless => :stopped?
+      def transition(options = {})
+        options.symbolize_keys!
+        options.assert_valid_keys(:to, :from, :if, :unless)
+        raise ArgumentError, ':to state must be specified' unless options.include?(:to)
+        
+        to_state = options.delete(:to)
+        from_states = Array(options.delete(:from))
+        from_states.collect do |from_state|
+          # Create the actual transition that will update records when run
+          transition = Transition.new(self, from_state, to_state)
+          
+          # The callback that will be invoked when the event is run. If the callback
+          # fails, then the next available callback for the event will run until
+          # one is successful.
+          callback = Proc.new do |record, *args|
+            transition.can_perform_on?(record) &&
+            invoke_event_callbacks(:before, record, *args) != false &&
+            transition.perform(record, *args) &&
+            invoke_event_callbacks(:after, record, *args) != false
+          end
+          
+          # Add the callback to the model
+          owner_class.send("transition_on_#{name}", callback, options)
+          
+          transition
+        end
+      end
+      
+      # Attempts to transition to one of the next possible states for the given record
+      def fire!(record, *args)
+        success = false
+        record.class.transaction {success = invoke_transition_callbacks(record, *args) == true || raise(ActiveRecord::Rollback)}
+        success
+      end
+      
+      private
+        # Add action for transitioning the record
+        def add_transition_action
+          owner_class.class_eval <<-end_eval
+            def #{name}!(*args)
+              #{owner_class}.state_machines['#{machine.attribute}'].events['#{name}'].fire!(self, *args)
+            end
+          end_eval
+        end
+        
+        # Defines callbacks for invoking transitions when this event is performed
+        def add_transition_callbacks
+          owner_class.define_callbacks("transition_on_#{name}")
+        end
+        
+        # Adds the before/after callbacks for when the event is performed
+        def add_event_callbacks
+          %w(before after).each do |type|
+            callback_name = "#{type}_#{name}"
+            owner_class.define_callbacks(callback_name)
+            
+            # Add each defined callback
+            Array(@options[type]).each {|callback| owner_class.send(callback_name, callback)}
+          end
+        end
+        
+        # Invokes a particulary type of callbacks for the event
+        def invoke_event_callbacks(type, record, *args)
+          args = [record] + args
+          
+          record.class.send("#{type}_#{name}_callback_chain").each do |callback|
+            result = callback.call(*args)
+            break result if result == false
+          end
+        end
+        
+        # Invokes the callbacks for each transition in order to find one that
+        # completes successfully
+        def invoke_transition_callbacks(record, *args)
+          args = [record] + args
+          
+          record.class.send("transition_on_#{name}_callback_chain").each do |callback|
+            result = callback.call(*args)
+            break result if result == true
+          end
+        end
+    end
+  end
+end