state_machine 0.1.1 → 0.2.0

data/{CHANGELOG → CHANGELOG.rdoc}

@@ -1,93 +1,62 @@
-*SVN*
+== master
 
-*0.1.1* (June 22nd, 2008)
+== 0.2.0 / 2008-06-29
+
+* Add a non-bang version of events (e.g. park) that will return a boolean value for success
+* Raise an exception if the bang version of events are used (e.g. park!) and no transition is successful
+* Change callbacks to act a little more like ActiveRecord
+* Avoid using string evaluation for dynamic methods
+
+== 0.1.1 / 2008-06-22
 
 * Remove log files from gems
 
-*0.1.0* (May 5th, 2008)
+== 0.1.0 / 2008-05-05
 
 * 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)
+== 0.0.1 / 2007-09-26
 
 * 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
   
@@ -95,11 +64,9 @@
   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/{README → README.rdoc}

@@ -4,21 +4,21 @@
 
 == Resources
 
-Wiki
-
-* http://wiki.pluginaweek.org/State_machine
-
 API
 
 * http://api.pluginaweek.org/state_machine
 
+Bugs
+
+* http://pluginaweek.lighthouseapp.com/projects/13288-state_machine
+
 Development
 
-* http://dev.pluginaweek.org/browser/trunk/state_machine
+* http://github.com/pluginaweek/state_machine
 
 Source
 
-* http://svn.pluginaweek.org/trunk/state_machine
+* git://github.com/pluginaweek/state_machine.git
 
 == Description
 
@@ -86,7 +86,7 @@ events for your models.  It is cross-platform, written in Java.
 == Testing
 
 Before you can run any tests, the following gem must be installed:
-* plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]
+* plugin_test_helper[http://github.com/pluginaweek/plugin_test_helper]
 
 To run against a specific version of Rails:
 

data/Rakefile

@@ -3,46 +3,54 @@ require 'rake/rdoctask'
 require 'rake/gempackagetask'
 require 'rake/contrib/sshpublisher'
 
-PKG_NAME           = 'state_machine'
-PKG_VERSION        = '0.1.1'
-PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
-RUBY_FORGE_PROJECT = 'pluginaweek'
+spec = Gem::Specification.new do |s|
+  s.name              = 'state_machine'
+  s.version           = '0.2.0'
+  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 - FileList['test/app_root/log/*'].to_a + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc)
+  s.require_path      = 'lib'
+  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'
+  s.rubyforge_project = 'pluginaweek'
+end
 
-desc 'Default: run unit tests.'
+desc 'Default: run all tests.'
 task :default => :test
 
-desc 'Test the state_machine plugin.'
+desc "Test the #{spec.name} plugin."
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
-  t.pattern = 'test/**/*_test.rb'
+  t.test_files = spec.test_files
   t.verbose = true
 end
 
-desc 'Generate documentation for the state_machine plugin.'
+begin
+  require 'rcov/rcovtask'
+  namespace :test do
+    desc "Test the #{spec.name} plugin with Rcov."
+    Rcov::RcovTask.new(:rcov) do |t|
+      t.libs << 'lib'
+      t.test_files = spec.test_files
+      t.rcov_opts << '--exclude="^(?!lib/)"'
+      t.verbose = true
+    end
+  end
+rescue LoadError
+end
+
+desc "Generate documentation for the #{spec.name} plugin."
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'StateMachine'
+  rdoc.title    = spec.name
   rdoc.template = '../rdoc_template.rb'
   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 - FileList['test/app_root/log/*'].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'
+  rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb')
 end
   
 Rake::GemPackageTask.new(spec) do |p|
@@ -51,14 +59,14 @@ Rake::GemPackageTask.new(spec) do |p|
   p.need_zip = true
 end
 
-desc 'Publish the beta gem'
+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
+  Rake::SshFilePublisher.new('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{spec.name}-#{spec.version}.gem").upload
 end
 
-desc 'Publish the API documentation'
+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
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
 end
 
 desc 'Publish the API docs and gem'
@@ -71,10 +79,10 @@ task :release => [:gem, :package] do
   ruby_forge = RubyForge.new.configure
   ruby_forge.login
   
-  %w( gem tgz zip ).each do |ext|
-    file = "pkg/#{PKG_FILE_NAME}.#{ext}"
+  %w(gem tgz zip).each do |ext|
+    file = "pkg/#{spec.name}-#{spec.version}.#{ext}"
     puts "Releasing #{File.basename(file)}..."
     
-    ruby_forge.add_release(RUBY_FORGE_PROJECT, PKG_NAME, PKG_VERSION, file)
+    ruby_forge.add_release(spec.rubyforge_project, spec.name, spec.version, file)
   end
 end

data/lib/state_machine.rb

@@ -67,6 +67,8 @@ module PluginAWeek #:nodoc:
         
         attribute_keys = (attributes || {}).keys.map!(&:to_s)
         
+        # Set the initial value of each state machine as long as the value wasn't
+        # included in the attribute hash passed in
         self.class.state_machines.each do |attribute, machine|
           unless attribute_keys.include?(attribute)
             send("#{attribute}=", machine.initial_state(self))
@@ -80,7 +82,7 @@ module PluginAWeek #:nodoc:
       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)
+          run_callbacks(callback) if self[attribute] && self.class.respond_to?(callback)
         end
       end
     end

data/lib/state_machine/event.rb

@@ -22,7 +22,7 @@ module PluginAWeek #:nodoc:
         @name = name
         @options = options.stringify_keys
         
-        add_transition_action
+        add_transition_actions
         add_transition_callbacks
         add_event_callbacks
       end
@@ -46,49 +46,66 @@ module PluginAWeek #:nodoc:
         options.assert_valid_keys(:to, :from, :if, :unless)
         raise ArgumentError, ':to state must be specified' unless options.include?(:to)
         
+        # Get the states involved in the transition
         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
+          # Create the actual transition that will update records when performed
           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
+          # Add the callback to the model. If the callback fails, then the next
+          # available callback for the event will run until one is successful.
+          callback = Proc.new {|record, *args| try_transition(transition, false, record, *args)}
           owner_class.send("transition_on_#{name}", callback, options)
           
+          # Add the callback! to the model similar to above
+          callback = Proc.new {|record, *args| try_transition(transition, true, record, *args)}
+          owner_class.send("transition_bang_on_#{name}", callback, options)
+          
           transition
         end
       end
       
-      # Attempts to transition to one of the next possible states for the given record
+      # Attempts to perform one of the event's transitions for the given record
+      def fire(record, *args)
+        record.class.transaction {invoke_transition_callbacks(record, false, *args) || raise(ActiveRecord::Rollback)} || false
+      end
+      
+      # Attempts to perform one of the event's transitions for the given record.
+      # If the transition cannot be made, then a PluginAWeek::StateMachine::InvalidTransition
+      # error will be raised.
       def fire!(record, *args)
-        success = false
-        record.class.transaction {success = invoke_transition_callbacks(record, *args) == true || raise(ActiveRecord::Rollback)}
-        success
+        record.class.transaction {invoke_transition_callbacks(record, true, *args) || raise(ActiveRecord::Rollback)} || raise(PluginAWeek::StateMachine::InvalidTransition)
       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)
+        # Add the various instance methods that can transition the record using
+        # the current event
+        def add_transition_actions
+          name = self.name
+          owner_class = self.owner_class
+          machine = self.machine
+          
+          owner_class.class_eval do
+            # Fires the event, returning true/false
+            define_method(name) do |*args|
+              owner_class.state_machines[machine.attribute].events[name].fire(self, *args)
             end
-          end_eval
+            
+            # Fires the event, raising an exception if it fails
+            define_method("#{name}!") do |*args|
+              owner_class.state_machines[machine.attribute].events[name].fire!(self, *args)
+            end
+          end
         end
         
         # Defines callbacks for invoking transitions when this event is performed
         def add_transition_callbacks
-          owner_class.define_callbacks("transition_on_#{name}")
+          %W(transition transition_bang).each do |callback_name|
+            callback_name = "#{callback_name}_on_#{name}"
+            owner_class.define_callbacks(callback_name)
+          end
         end
         
         # Adds the before/after callbacks for when the event is performed
@@ -102,7 +119,25 @@ module PluginAWeek #:nodoc:
           end
         end
         
-        # Invokes a particulary type of callbacks for the event
+        # Attempts to perform the given transition. If it can't be performed based
+        # on the state of the given record, then the transition will be skipped
+        # and the next available one will be tried.
+        # 
+        # If +bang+ is specified, then perform! will be called on the transition.
+        # Otherwise, the default +perform+ will be invoked.
+        def try_transition(transition, bang, record, *args)
+          if transition.can_perform_on?(record)
+            return false if invoke_event_callbacks(:before, record, *args) == false
+            result = bang ? transition.perform!(record, *args) : transition.perform(record, *args)
+            invoke_event_callbacks(:after, record, *args)
+            result
+          else
+            # Indicate that the transition cannot be performed
+            :skip
+          end
+        end
+        
+        # Invokes a particulary type of callback for the event
         def invoke_event_callbacks(type, record, *args)
           args = [record] + args
           
@@ -113,14 +148,19 @@ module PluginAWeek #:nodoc:
         end
         
         # Invokes the callbacks for each transition in order to find one that
-        # completes successfully
-        def invoke_transition_callbacks(record, *args)
+        # completes successfully.
+        # 
+        # +bang+ indicates whether perform or perform! will be invoked on the
+        # transitions in the callback chain
+        def invoke_transition_callbacks(record, bang, *args)
           args = [record] + args
+          callback_chain = "transition#{'_bang' if bang}_on_#{name}_callback_chain"
           
-          record.class.send("transition_on_#{name}_callback_chain").each do |callback|
+          result = record.class.send(callback_chain).each do |callback|
             result = callback.call(*args)
-            break result if result == true
+            break result if [true, false].include?(result)
           end
+          result == true
         end
     end
   end

data/lib/state_machine/machine.rb

@@ -77,7 +77,8 @@ module PluginAWeek #:nodoc:
       # 
       # The following instance methods are generated when a new event is defined
       # (the "park" event is used as an example):
-      # * <tt>park!(*args)</tt> - Fires the "park" event, transitioning from the current state to the next valid state.  This takes an optional +args+ list which is passed to the event callbacks.
+      # * <tt>park(*args)</tt> - Fires the "park" event, transitioning from the current state to the next valid state.  This takes an optional +args+ list which is passed to the event callbacks.
+      # * <tt>park!(*args)</tt> - Fires the "park" event, transitioning from the current state to the next valid state.  This takes an optional +args+ list which is passed to the event callbacks.  If the transition cannot happen (for validation, database, etc. reasons), then an error will be raised
       # 
       # == Defining transitions
       # 
@@ -113,26 +114,25 @@ module PluginAWeek #:nodoc:
       end
       
       # Define state callbacks
-      %w(before_exit before_enter after_exit after_enter).each do |callback|
-        module_eval <<-end_eval
-          def #{callback}(state, callback)
-            callback_name = "#{callback}_\#{attribute}_\#{state}"
-            owner_class.define_callbacks(callback_name)
-            owner_class.send(callback_name, callback)
-          end
-        end_eval
+      %w(before_exit before_enter after_exit after_enter).each do |callback_type|
+        define_method(callback_type) {|state, callback| add_callback(callback_type, state, callback)}
       end
       
       private
+        # Adds the given callback to the callback chain during a state transition
+        def add_callback(type, state, callback)
+          callback_name = "#{type}_#{attribute}_#{state}"
+          owner_class.define_callbacks(callback_name)
+          owner_class.send(callback_name, callback)
+        end
+        
+        # Add named scopes for finding records with a particular value or values
+        # for the attribute
         def add_named_scopes
-          unless owner_class.respond_to?("with_#{attribute}")
-            # How do you alias named scopes? (doesn't work completely with a simple alias/alias_method)
-            %W(with_#{attribute} with_#{attribute.pluralize}).each do |scope_name|
-              owner_class.class_eval <<-end_eos
-                named_scope :#{scope_name}, Proc.new {|*values| {
-                  :conditions => {:#{attribute} => values.flatten}
-                }}
-              end_eos
+          [attribute, attribute.pluralize].each do |name|
+            unless owner_class.respond_to?("with_#{name}")
+              name = "with_#{name}"
+              owner_class.named_scope name, Proc.new {|*values| {:conditions => {attribute => values.flatten}}}
             end
           end
         end