state_machine 0.8.1 → 0.9.0

data/CHANGELOG.rdoc

@@ -1,5 +1,22 @@
 == master
 
+== 0.9.0 / 2010-04-12
+
+* Use attribute-based event transitions whenever possible to ensure consistency
+* Fix action helpers being defined when the action is *only* defined in the machine's owner class
+* Disable attribute-based event transitions in DataMapper 0.9.4 - 0.9.6 when dm-validations is being used
+* Add support for DataMapper 0.10.3+
+* Add around_transition callbacks
+* Fix transition failures during save not being handled correctly in Sequel 2.12.0+
+* Fix attribute-based event transitions not hooking in properly in DataMapper 0.10.0+ and Sequel 2.12.0+
+* Fix dynamic initial states causing errors in Ruby 1.9+ if no arguments are defined in the block
+* Add MongoMapper 0.5.5+ support
+* Add ActiveModel 3.0+ support for use with integrations that implement its interface
+* Fix DataMapper integration failing when ActiveSupport is loaded in place of Extlib
+* Add version dependencies for ruby-graphviz
+* Remove app-specific rails / merb rake tasks in favor of always running state_machine:draw
+* Add Rails 3 railtie for automatically loading rake tasks when installed as a gem
+
 == 0.8.1 / 2010-03-14
 
 * Release gems via rake-gemcutter instead of rubyforge

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2009 Aaron Pfefier
+Copyright (c) 2006-2010 Aaron Pfefier
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -7,7 +7,7 @@ Ruby class.
 
 API
 
-* http://api.pluginaweek.org/state_machine
+* http://rdoc.info/projects/pluginaweek/state_machine
 
 Bugs
 
@@ -37,10 +37,8 @@ Some brief, high-level features include:
 * Defining state machines on any Ruby class
 * Multiple state machines on a single class
 * Namespaced state machines
-* before/after transition hooks with explicit transition requirements
-* ActiveRecord integration
-* DataMapper integration
-* Sequel integration
+* before/after/around transition hooks with explicit transition requirements
+* Integration with ActiveModel, ActiveRecord, DataMapper, MongoMapper, and Sequel
 * State predicates
 * State-driven instance / class behavior
 * State values of any data type
@@ -70,7 +68,7 @@ Below is an example of many of the features offered by this plugin, including:
 Class definition:
 
   class Vehicle
-    attr_accessor :seatbelt_on
+    attr_accessor :seatbelt_on, :time_used
     
     state_machine :state, :initial => :parked do
       before_transition :parked => any - :parked, :do => :put_on_seatbelt
@@ -81,6 +79,12 @@ Class definition:
         vehicle.seatbelt_on = false
       end
       
+      around_transition do |vehicle, transition, block|
+        start = Time.now
+        block.call
+        vehicle.time_used += Time.now - start
+      end
+      
       event :park do
         transition [:idling, :first_gear] => :parked
       end
@@ -107,6 +111,7 @@ Class definition:
       
       event :repair do
         transition :stalled => :parked, :if => :auto_shop_busy?
+        transition :stalled => same # Loopback if we have to
       end
       
       state :parked do
@@ -143,6 +148,7 @@ Class definition:
     
     def initialize
       @seatbelt_on = false
+      @time_used = 0
       super() # NOTE: This *must* be called, otherwise states won't get initialized
     end
     
@@ -229,12 +235,72 @@ libraries.  These integrations add library-specific behavior, allowing for state
 machines to work more tightly with the conventions defined by those libraries.
 
 The integrations currently available include:
+* ActiveModel classes
 * ActiveRecord models
 * DataMapper resources
+* MongoMapper models
 * Sequel models
 
 A brief overview of these integrations is described below.
 
+=== ActiveModel
+
+The ActiveModel integration is useful for both standalone usage and for providing
+the base implementation for ORMs which implement the ActiveModel API.  This
+integration adds support for validation errors, dirty attribute tracking, and
+observers.  For example,
+
+  class Vehicle
+    include ActiveModel::Dirty
+    include ActiveModel::Validations
+    include ActiveModel::Observing
+    
+    attr_accessor :state
+    define_attribute_methods [:state]
+    
+    state_machine :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      after_transition any => :parked do |vehicle, transition|
+        vehicle.seatbelt = 'off'
+      end
+      around_transition :benchmark
+      
+      event :ignite do
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_presence_of :seatbelt_on
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+    
+    def benchmark
+      ...
+      yield
+      ...
+    end
+  end
+  
+  class VehicleObserver < ActiveModel::Observer
+    # Callback for :ignite event *before* the transition is performed
+    def before_ignite(vehicle, transition)
+      # log message
+    end
+    
+    # Generic transition callback *after* the transition is performed
+    def after_transition(vehicle, transition)
+      Audit.log(vehicle, transition)
+    end
+  end
+
+For more information about the various behaviors added for ActiveModel state
+machines and how to build new integrations that use ActiveModel, see
+StateMachine::Integrations::ActiveModel.
+
 === ActiveRecord
 
 The ActiveRecord integration adds support for database transactions, automatically
@@ -246,6 +312,7 @@ saving the record, named scopes, validation errors, and observers.  For example,
       after_transition any => :parked do |vehicle, transition|
         vehicle.seatbelt = 'off'
       end
+      around_transition :benchmark
       
       event :ignite do
         transition :parked => :idling
@@ -259,6 +326,12 @@ saving the record, named scopes, validation errors, and observers.  For example,
     def put_on_seatbelt
       ...
     end
+    
+    def benchmark
+      ...
+      yield
+      ...
+    end
   end
   
   class VehicleObserver < ActiveRecord::Observer
@@ -293,19 +366,26 @@ callbacks, validation errors, and observers.  For example,
       after_transition any => :parked do |transition|
         self.seatbelt = 'off' # self is the record
       end
+      around_transition :benchmark
       
       event :ignite do
         transition :parked => :idling
       end
       
       state :first_gear, :second_gear do
-        validates_present :seatbelt_on
+        validates_presence_of :seatbelt_on
       end
     end
     
     def put_on_seatbelt
       ...
     end
+    
+    def benchmark
+      ...
+      yield
+      ...
+    end
   end
   
   class VehicleObserver
@@ -322,6 +402,12 @@ callbacks, validation errors, and observers.  For example,
     after_transition do |transition|
       Audit.log(self, transition) # self is the record
     end
+    
+    around_transition do |transition, block|
+      # mark start time
+      block.call
+      # mark stop time
+    end
   end
 
 *Note* that the DataMapper::Observer integration is optional and only available
@@ -330,6 +416,44 @@ when the dm-observer library is installed.
 For more information about the various behaviors added for DataMapper state
 machines, see StateMachine::Integrations::DataMapper.
 
+=== MongoMapper
+
+The MongoMapper integration adds support for automatically saving the record,
+basic scopes, validation errors and callbacks.  For example,
+
+  class Vehicle
+    include MongoMapper::Document
+    
+    state_machine :initial => :parked do
+      before_transition :parked => any - :parked, :do => :put_on_seatbelt
+      after_transition any => :parked do |vehicle, transition|
+        vehicle.seatbelt = 'off' # self is the record
+      end
+      around_transition :benchmark
+      
+      event :ignite do
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_presence_of :seatbelt_on
+      end
+    end
+    
+    def put_on_seatbelt
+      ...
+    end
+    
+    def benchmark
+      ...
+      yield
+      ...
+    end
+  end
+
+For more information about the various behaviors added for MongoMapper state
+machines, see StateMachine::Integrations::MongoMapper.
+
 === Sequel
 
 Like the ActiveRecord integration, the Sequel integration adds support for
@@ -342,6 +466,7 @@ errors and callbacks.  For example,
       after_transition any => :parked do |transition|
         self.seatbelt = 'off' # self is the record
       end
+      around_transition :benchmark
       
       event :ignite do
         transition :parked => :idling
@@ -355,6 +480,12 @@ errors and callbacks.  For example,
     def put_on_seatbelt
       ...
     end
+    
+    def benchmark
+      ...
+      yield
+      ...
+    end
   end
 
 For more information about the various behaviors added for Sequel state
@@ -425,10 +556,10 @@ environment, meaning that it's unnecessary to specify the actual file to load.
 
 For example,
 
-  rake state_machine:draw:rails CLASS=Vehicle
+  rake state_machine:draw CLASS=Vehicle
 
-If you are using this library as a gem, the following must be added to the end
-of your application's Rakefile in order for the above task to work:
+If you are using this library as a gem in Rails 2.x, the following must be added
+to the end of your application's Rakefile in order for the above task to work:
 
   require 'tasks/state_machine'
 
@@ -446,34 +577,36 @@ files to load.
 
 For example,
 
-  rake state_machine:draw:merb CLASS=Vehicle
+  rake state_machine:draw CLASS=Vehicle
 
 === Interactive graphs
 
-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.
+Jean Bovet's {Visual Automata Simulator}[http://www.cs.usfca.edu/~jbovet/vas.html]
+is a great tool for "simulating, visualizing and transforming finite state
+automata and Turing Machines".  It can help in the creation of states and events
+for your models.  It is cross-platform, written in Java.
 
 == Testing
 
-To run the entire test suite (will test ActiveRecord, DataMapper, and Sequel
-integrations if the proper dependencies are available):
+To run the core test suite (does *not* test any of the integrations):
 
   rake test
 
-Target specific versions of integrations like so:
+Test specific versions of integrations like so:
 
-  rake test AR_VERSION=2.0.0 DM_VERSION=0.9.4 SEQUEL_VERSION=2.8.0
+  rake test INTEGRATION=active_model VERSION=3.0.0
+  rake test INTEGRATION=active_record VERSION=2.0.0
+  rake test INTEGRATION=data_mapper VERSION=0.9.4
+  rake test INTEGRATION=mongo_mapper VERSION=0.5.5
+  rake test INTEGRATION=sequel VERSION=2.8.0
 
 == Caveats
 
 The following caveats should be noted when using state_machine:
 
-* DataMapper: dm-validations 0.9.4 - 0.9.6 causes +after+ callbacks for
-attribute-based event transitions to fail
-* Overridden event methods won't get invoked when using attribute-based event
-transitions
+* DataMapper: Attribute-based event transitions are disabled when dm-validations 0.9.4 - 0.9.6 is in use
+* Overridden event methods won't get invoked when using attribute-based event transitions
+* around_transition callbacks in ORM integrations won't work on JRuby since it doesn't support continuations
 
 == Dependencies
 
@@ -481,6 +614,12 @@ transitions
 
 If using specific integrations:
 
+* ActiveModel[http://rubyonrails.org] integration: 3.0.0 or later
 * ActiveRecord[http://rubyonrails.org] integration: 2.0.0 or later
 * DataMapper[http://datamapper.org] integration: 0.9.4 or later
+* MongoMapper[http://mongomapper.com] integration: 0.5.5 or later
 * Sequel[http://sequel.rubyforge.org] integration: 2.8.0 or later
+
+If graphing state machine:
+
+* ruby-graphviz[http://github.com/glejeune/Ruby-Graphviz]: 0.9.0 or later

data/Rakefile

@@ -6,7 +6,7 @@ require 'rake/gempackagetask'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'state_machine'
-  s.version           = '0.8.1'
+  s.version           = '0.9.0'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Adds support for creating state machines for attributes on any Ruby class'
   s.description       = s.summary
@@ -28,7 +28,7 @@ task :default => :test
 desc "Test the #{spec.name} plugin."
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
-  t.test_files = spec.test_files
+  t.test_files = ENV['INTEGRATION'] ? Dir["test/unit/integrations/#{ENV['INTEGRATION']}_test.rb"] : Dir['test/{functional,unit}/*_test.rb']
   t.verbose = true
 end
 
@@ -66,23 +66,8 @@ Rake::GemPackageTask.new(spec) do |p|
   p.gem_spec = spec
 end
 
-desc 'Publish the beta gem.'
-task :pgem => [:package] do
-  require 'rake/contrib/sshpublisher'
-  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.'
-task :pdoc => [:rdoc] do
-  require 'rake/contrib/sshpublisher'
-  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
-end
-
-desc 'Publish the API docs and gem'
-task :publish => [:pgem, :pdoc, :release]
-
 desc 'Publish the release files to RubyForge.'
-task :release => [:gem, :package] do
+task :release => :package do
   require 'rake/gemcutter'
   
   Rake::Gemcutter::Tasks.new(spec)

data/lib/state_machine.rb

@@ -24,8 +24,8 @@ module StateMachine
     #   Default is nil.
     # * <tt>:integration</tt> - The name of the integration to use for adding
     #   library-specific behavior to the machine.  Built-in integrations
-    #   include :data_mapper, :active_record, and :sequel.  By default, this
-    #   is determined automatically.
+    #   include :active_model, :active_record, :data_mapper, :mongo_mapper, and
+    #   :sequel.  By default, this is determined automatically.
     # 
     # Configuration options relevant to ORM integrations:
     # * <tt>:plural</tt> - The pluralized name of the attribute.  By default,
@@ -384,5 +384,4 @@ Class.class_eval do
   include StateMachine::MacroMethods
 end
 
-# Register rake tasks for supported libraries
-Merb::Plugins.add_rakefiles("#{File.dirname(__FILE__)}/tasks/state_machine") if defined?(Merb::Plugins)
+require 'state_machine/initializers'

data/lib/state_machine/callback.rb

@@ -3,7 +3,7 @@ require 'state_machine/eval_helpers'
 
 module StateMachine
   # Callbacks represent hooks into objects that allow logic to be triggered
-  # before or after a specific transition occurs.
+  # before, after, or around a specific set of transitions.
   class Callback
     include EvalHelpers
     
@@ -62,6 +62,13 @@ module StateMachine
       attr_accessor :terminator
     end
     
+    # The type of callback chain this callback is for.  This can be one of the
+    # following:
+    # * +before+
+    # * +after+
+    # * +around+
+    attr_accessor :type
+    
     # An optional block for determining whether to cancel the callback chain
     # based on the return value of the callback.  By default, the callback
     # chain never cancels based on the return value (i.e. there is no implicit
@@ -112,12 +119,14 @@ module StateMachine
     # 
     # More information about how those options affect the behavior of the
     # callback can be found in their attribute definitions.
-    def initialize(*args, &block)
+    def initialize(type, *args, &block)
+      @type = type
+      raise ArgumentError, 'Type must be :before, :after, or :around' unless [:before, :after, :around].include?(type)
+      
       options = args.last.is_a?(Hash) ? args.pop : {}
       @methods = args
       @methods.concat(Array(options.delete(:do)))
       @methods << block if block_given?
-      
       raise ArgumentError, 'Method(s) for callback must be specified' unless @methods.any?
       
       options = {:bind_to_object => self.class.bind_to_object, :terminator => self.class.terminator}.merge(options)
@@ -139,32 +148,68 @@ module StateMachine
     end
     
     # Runs the callback as long as the transition context matches the guard
-    # requirements configured for this callback.
+    # requirements configured for this callback.  If a block is provided, it
+    # will be called when the last method has run.
     # 
     # If a terminator has been configured and it matches the result from the
     # evaluated method, then the callback chain should be halted.
-    def call(object, context = {}, *args)
+    def call(object, context = {}, *args, &block)
       if @guard.matches?(object, context)
-        @methods.each do |method|
-          result = evaluate_method(object, method, *args)
-          throw :halt if @terminator && @terminator.call(result)
-        end
-        
+        run_methods(object, context, 0, *args, &block)
         true
       else
         false
       end
     end
     
+    # Verifies that the success requirement for this callback matches the given
+    # value
+    def matches_success?(success)
+      guard.success_requirement.matches?(success)
+    end
+    
     private
+      # Runs all of the methods configured for this callback.
+      # 
+      # When running +around+ callbacks, this will evaluate each method and
+      # yield when the last method has yielded.  The callback will only halt if
+      # one of the methods does not yield.
+      # 
+      # For all other types of callbacks, this will evaluate each method in
+      # order.  The callback will only halt if the resulting value from the
+      # method passes the terminator.
+      def run_methods(object, context = {}, index = 0, *args, &block)
+        if type == :around
+          if method = @methods[index]
+            yielded = false
+            evaluate_method(object, method, *args) do
+              yielded = true
+              run_methods(object, context, index + 1, *args, &block)
+            end
+            
+            throw :halt unless yielded
+          else
+            yield if block_given?
+          end
+        else
+          @methods.each do |method|
+            result = evaluate_method(object, method, *args)
+            throw :halt if @terminator && @terminator.call(result)
+          end
+        end
+      end
+      
       # Generates a method that can be bound to the object being transitioned
       # when the callback is invoked
       def bound_method(block)
+        type = self.type
         arity = block.arity
+        arity += 1 if arity >= 0
+        arity += 1 if arity == 1 && type == :around 
         
-        if RUBY_VERSION >= '1.9'
+        method = if RUBY_VERSION >= '1.9'
           lambda do |object, *args|
-            object.instance_exec(*(arity == 0 ? [] : args), &block)
+            object.instance_exec(*args, &block)
           end
         else
           # Generate a thread-safe unbound method that can be used on any object.
@@ -181,9 +226,16 @@ module StateMachine
           # Proxy calls to the method so that the method can be bound *and*
           # the arguments are adjusted
           lambda do |object, *args|
-            unbound_method.bind(object).call(*(arity == 0 ? [] : args))
+            unbound_method.bind(object).call(*args)
           end
         end
+        
+        # Proxy arity to the original block
+        (class << method; self; end).class_eval do
+          define_method(:arity) { arity }
+        end
+        
+        method
       end
   end
 end