state_machine 0.9.4 → 0.10.0

data/CHANGELOG.rdoc

@@ -1,5 +1,25 @@
 == master
 
+== 0.10.0 / 2011-03-19
+
+* Support callback terminators in MongoMapper 0.9.0+
+* Fix pluralization integration on DataMapper 1.0.0 and 1.1.0
+* Allow transition guards to be bypassed for event / transition / path helpers
+* Allow state / condition requirements to be specified for all event / transition / path helpers
+* Add the ability to skip automatically initializing state machines on #initialize
+* Add #{name}_paths for walking the available paths in a state machine
+* Add Mongoid 2.0.0+ support
+* Use around hooks to improve compatibility with other libraries in ActiveModel / ActiveRecord / MongoMapper integrations
+* Add support for MassAssignmentSecurity feature in ActiveModel integrations
+* Add support for more observer hooks within MongoMapper integrations
+* Add i18n support for MongoMapper validation errors
+* Update support for MongoMapper integration based on rails3 branch
+* Fix objects not getting marked as dirty in all integrations when #{name}_event is set
+* Generate warnings when conflicting state / event names are detected
+* Allow fallback to generic state predicates when individual predicates are already defined in the owner class
+* Replace :include_failures after_transition option with new after_failure callback
+* Provide access to transition context when raising InvalidEvent / InvalidTransition exceptions
+
 == 0.9.4 / 2010-08-01
 
 * Fix validation / save hooks in Sequel 3.14.0+

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2010 Aaron Pfefier
+Copyright (c) 2006-2011 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://rdoc.info/projects/pluginaweek/state_machine
+* http://rdoc.info/github/pluginaweek/state_machine/master/frames
 
 Bugs
 
@@ -37,14 +37,15 @@ 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/around transition hooks with explicit transition requirements
-* Integration with ActiveModel, ActiveRecord, DataMapper, MongoMapper, and Sequel
+* before/after/around/failure transition hooks with explicit transition requirements
+* Integration with ActiveModel, ActiveRecord, DataMapper, Mongoid, MongoMapper, and Sequel
 * State predicates
 * State-driven instance / class behavior
 * State values of any data type
 * Dynamically-generated state values
 * Event parallelization
 * Attribute-based event transitions
+* Path analysis
 * Inheritance
 * Internationalization
 * GraphViz visualization creator
@@ -64,6 +65,7 @@ Below is an example of many of the features offered by this plugin, including:
 * State-driven instance behavior
 * Customized state values
 * Parallel events
+* Path analysis
 
 Class definition:
 
@@ -79,6 +81,8 @@ Class definition:
         vehicle.seatbelt_on = false
       end
       
+      after_failure :on => :ignite, :do => :log_start_failure
+      
       around_transition do |vehicle, transition, block|
         start = Time.now
         block.call
@@ -169,6 +173,10 @@ Class definition:
     def fix
       # get the vehicle fixed by a mechanic
     end
+    
+    def log_start_failure
+      # log a failed attempt to start the vehicle
+    end
   end
 
 *Note* the comment made on the +initialize+ method in the class.  In order for
@@ -235,7 +243,18 @@ like so:
   Vehicle.human_alarm_state_name(:active)             # => "active"
   
   Vehicle.human_state_event_name(:shift_down)         # => "shift down"
-  Vehicle.human_alarm_state_event_name(:enable_alarm) # => "enable alarm"
+  Vehicle.human_alarm_state_event_name(:enable)       # => "enable"
+  
+  # Available transition paths can be analyzed for an object
+  vehicle.state_paths                                       # => [[#<StateMachine::Transition ...], [#<StateMachine::Transition ...], ...]
+  vehicle.state_paths.to_states                             # => [:parked, :idling, :first_gear, :stalled, :second_gear, :third_gear]
+  vehicle.state_paths.events                                # => [:park, :ignite, :shift_up, :idle, :crash, :repair, :shift_down]
+  
+  # Find all paths that start and end on certain states
+  vehicle.state_paths(:from => :parked, :to => :first_gear) # => [[
+                                                            #       #<StateMachine::Transition attribute=:state event=:ignite from="parked" ...>,
+                                                            #       #<StateMachine::Transition attribute=:state event=:shift_up from="idling" ...>
+                                                            #    ]]
 
 == Integrations
 
@@ -248,6 +267,7 @@ The integrations currently available include:
 * ActiveModel classes
 * ActiveRecord models
 * DataMapper resources
+* Mongoid models
 * MongoMapper models
 * Sequel models
 
@@ -305,6 +325,11 @@ observers.  For example,
     def after_transition(vehicle, transition)
       Audit.log(vehicle, transition)
     end
+    
+    # Generic callback after the transition fails to perform
+    def after_failure_to_transition(vehicle, transition)
+      Audit.error(vehicle, transition)
+    end
   end
 
 For more information about the various behaviors added for ActiveModel state
@@ -418,6 +443,11 @@ callbacks, validation errors, and observers.  For example,
       block.call
       # mark stop time
     end
+    
+    # Generic callback after the transition fails to perform
+    after_transition_failure do |transition|
+      Audit.log(self, transition) # self is the record
+    end
   end
 
 *Note* that the DataMapper::Observer integration is optional and only available
@@ -426,6 +456,44 @@ when the dm-observer library is installed.
 For more information about the various behaviors added for DataMapper state
 machines, see StateMachine::Integrations::DataMapper.
 
+=== Mongoid
+
+The Mongoid integration adds support for automatically saving the record,
+basic scopes, validation errors and callbacks.  For example,
+
+  class Vehicle
+    include Mongoid::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 Mongoid state
+machines, see StateMachine::Integrations::Mongoid.
+
 === MongoMapper
 
 The MongoMapper integration adds support for automatically saving the record,
@@ -607,6 +675,7 @@ Test specific versions of integrations like so:
   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=mongoid VERSION=2.0.0
   rake test INTEGRATION=mongo_mapper VERSION=0.5.5
   rake test INTEGRATION=sequel VERSION=2.8.0
 
@@ -627,6 +696,7 @@ 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
+* Mongoid[http://mongoid.org] integration: 2.0.0 or later
 * MongoMapper[http://mongomapper.com] integration: 0.5.5 or later
 * Sequel[http://sequel.rubyforge.org] integration: 2.8.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.9.4'
+  s.version           = '0.10.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 = ENV['INTEGRATION'] ? Dir["test/unit/integrations/#{ENV['INTEGRATION']}_test.rb"] : Dir['test/{functional,unit}/*_test.rb']
+  t.test_files = ENV['INTEGRATION'] ? Dir["test/unit/integrations/#{ENV['INTEGRATION']}_test.rb"] : Dir['test/{functional,unit}/*_test.rb'] + ['test/unit/integrations/base_test.rb']
   t.verbose = true
 end
 
@@ -51,7 +51,7 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title    = spec.name
   rdoc.template = '../rdoc_template.rb'
-  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.options << '--line-numbers' << '--inline-source' << '--main=README.rdoc'
   rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb')
 end
 

data/lib/state_machine.rb

@@ -15,6 +15,8 @@ module StateMachine
     #   static state or a lambda block which will be evaluated at runtime
     #   (e.g. lambda {|vehicle| vehicle.speed == 0 ? :parked : :idling}).
     #   Default is nil.
+    # * <tt>:initialize</tt> - Whether to automatically initialize the attribute
+    #   by hooking into #initialize on the owner class.  Default is true.
     # * <tt>:action</tt> - The instance method to invoke when an object
     #   transitions. Default is nil unless otherwise specified by the
     #   configured integration.
@@ -28,10 +30,9 @@ module StateMachine
     #   :sequel.  By default, this is determined automatically.
     # 
     # Configuration options relevant to ORM integrations:
-    # * <tt>:plural</tt> - The pluralized name of the attribute.  By default,
-    #   this will attempt to call +pluralize+ on the attribute.  If this
-    #   method is not available, an "s" is appended.  This is used for
-    #   generating scopes.
+    # * <tt>:plural</tt> - The pluralized version of the name.  By default, this
+    #   will attempt to call +pluralize+ on the name.  If this method is not
+    #   available, an "s" is appended.  This is used for generating scopes.
     # * <tt>:messages</tt> - The error messages to use when invalidating
     #   objects due to failed transitions.  Messages include:
     #   * <tt>:invalid</tt>
@@ -133,13 +134,25 @@ module StateMachine
     # * <tt>state_name</tt> - Gets the name of the state for the current value
     # * <tt>human_state_name</tt> - Gets the human-readable name of the state
     #   for the current value
-    # * <tt>state_events</tt> - Gets the list of events that can be fired on
-    #   the current object's state (uses the *unqualified* event names)
-    # * <tt>state_transitions(requirements = {})</tt> - Gets the list of possible
-    #   transitions that can be made on the current object's state.  Additional
-    #   requirements, such as the :from / :to state and :on event can be specified
-    #   to restrict the transitions to select.  By default, the current state
-    #   will be used for the :from state.
+    # * <tt>state_events(requirements = {})</tt> - Gets the list of events that
+    #   can be fired on the current object's state (uses the *unqualified* event
+    #   names)
+    # * <tt>state_transitions(requirements = {})</tt> - Gets the list of
+    #   transitions that can be made on the current object's state
+    # * <tt>state_paths(requirements = {})</tt> - Gets the list of sequences of
+    #   transitions that can be run from the current object's state
+    # 
+    # The <tt>state_events</tt>, <tt>state_transitions</tt>, and <tt>state_paths</tt>
+    # helpers all take an optional set of requirements for determining what's
+    # available for the current object.  These requirements include:
+    # * <tt>:from</tt> - One or more states to transition from.  If none are
+    #   specified, then this will be the object's current state.
+    # * <tt>:to</tt> - One or more states to transition to.  If none are
+    #   specified, then this will match any to state.
+    # * <tt>:on</tt> - One or more events to transition on.  If none are
+    #   specified, then this will match any event.
+    # * <tt>:guard</tt> - Whether to guard transitions with the if/unless
+    #   conditionals defined for each one.  Default is true.
     # 
     # For example,
     # 
@@ -156,25 +169,39 @@ module StateMachine
     #   end
     #   
     #   vehicle = Vehicle.new
-    #   vehicle.state                     # => "parked"
-    #   vehicle.state_name                # => :parked
-    #   vehicle.human_state_name          # => "parked"
-    #   vehicle.state?(:parked)           # => true
+    #   vehicle.state                             # => "parked"
+    #   vehicle.state_name                        # => :parked
+    #   vehicle.human_state_name                  # => "parked"
+    #   vehicle.state?(:parked)                   # => true
     #   
     #   # Changing state
     #   vehicle.state = 'idling'
-    #   vehicle.state                     # => "idling"
-    #   vehicle.state_name                # => :idling
-    #   vehicle.state?(:parked)           # => false
+    #   vehicle.state                             # => "idling"
+    #   vehicle.state_name                        # => :idling
+    #   vehicle.state?(:parked)                   # => false
     #   
     #   # Getting current event / transition availability
-    #   vehicle.state_events              # => [:park]
-    #   vehicle.park                      # => true
-    #   vehicle.state_events              # => [:ignite]
+    #   vehicle.state_events                      # => [:park]
+    #   vehicle.park                              # => true
+    #   vehicle.state_events                      # => [:ignite]
+    #   vehicle.state_events(:from => :idling)    # => [:park]
+    #   vehicle.state_events(:to => :parked)      # => []
     #   
-    #   vehicle.state_transitions         # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+    #   vehicle.state_transitions                 # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
     #   vehicle.ignite
-    #   vehicle.state_transitions         # => [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>]
+    #   vehicle.state_transitions                 # => [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>]
+    #   
+    #   vehicle.state_transitions(:on => :ignite) # => []
+    #   
+    #   # Getting current path availability
+    #   vehicle.state_paths                       # => [
+    #                                             #     [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>,
+    #                                             #      #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+    #                                             #   ]
+    #   vehicle.state_paths(:guard => false)      # => 
+    #                                             #     [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>,
+    #                                             #      #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+    #                                             #   ]
     # 
     # == Attribute initialization
     # 
@@ -330,7 +357,7 @@ module StateMachine
     # Within the +state_machine+ block, you can also define callbacks for
     # transitions.  For more information about defining these callbacks,
     # see StateMachine::Machine#before_transition, StateMachine::Machine#after_transition,
-    # and StateMachine::Machine#around_transition.
+    # and StateMachine::Machine#around_transition, and StateMachine::Machine#after_failure.
     # 
     # == Namespaces
     # 

data/lib/state_machine/{guard.rb → branch.rb}

@@ -4,10 +4,10 @@ require 'state_machine/assertions'
 
 module StateMachine
   # Represents a set of requirements that must be met in order for a transition
-  # or callback to occur.  Guards verify that the event, from state, and to
+  # or callback to occur.  Branches verify that the event, from state, and to
   # state of the transition match, in addition to if/unless conditionals for
   # an object's state.
-  class Guard
+  class Branch
     include Assertions
     include EvalHelpers
     
@@ -17,23 +17,20 @@ module StateMachine
     # The condition that must *not* be met on an object
     attr_reader :unless_condition
     
-    # The requirement for verifying the event being guarded
+    # The requirement for verifying the event being matched
     attr_reader :event_requirement
     
-    # One or more requirements for verifying the states being guarded.  All
+    # One or more requirements for verifying the states being matched.  All
     # requirements contain a mapping of {:from => matcher, :to => matcher}.
     attr_reader :state_requirements
     
-    # The requirement for verifying the success of the event
-    attr_reader :success_requirement
-    
-    # A list of all of the states known to this guard.  This will pull states
+    # A list of all of the states known to this branch.  This will pull states
     # from the following options (in the same order):
     # * +from+ / +except_from+
     # * +to+ / +except_to+
     attr_reader :known_states
     
-    # Creates a new guard
+    # Creates a new branch
     def initialize(options = {}) #:nodoc:
       # Build conditionals
       @if_condition = options.delete(:if)
@@ -42,9 +39,6 @@ module StateMachine
       # Build event requirement
       @event_requirement = build_matcher(options, :on, :except_on)
       
-      # Build success requirement
-      @success_requirement = options.delete(:include_failures) ? AllMatcher.instance : WhitelistMatcher.new([true])
-      
       if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on]).empty?
         # Explicit from/to requirements specified
         @state_requirements = [{:from => build_matcher(options, :from, :except_from), :to => build_matcher(options, :to, :except_to)}]
@@ -70,34 +64,34 @@ module StateMachine
     end
     
     # Determines whether the given object / query matches the requirements
-    # configured for this guard.  In addition to matching the event, from state,
+    # configured for this branch.  In addition to matching the event, from state,
     # and to state, this will also check whether the configured :if/:unless
     # conditions pass on the given object.
     # 
     # == Examples
     # 
-    #   guard = StateMachine::Guard.new(:parked => :idling, :on => :ignite)
+    #   branch = StateMachine::Branch.new(:parked => :idling, :on => :ignite)
     #   
     #   # Successful
-    #   guard.matches?(object, :on => :ignite)                                    # => true
-    #   guard.matches?(object, :from => nil)                                      # => true
-    #   guard.matches?(object, :from => :parked)                                  # => true
-    #   guard.matches?(object, :to => :idling)                                    # => true
-    #   guard.matches?(object, :from => :parked, :to => :idling)                  # => true
-    #   guard.matches?(object, :on => :ignite, :from => :parked, :to => :idling)  # => true
+    #   branch.matches?(object, :on => :ignite)                                   # => true
+    #   branch.matches?(object, :from => nil)                                     # => true
+    #   branch.matches?(object, :from => :parked)                                 # => true
+    #   branch.matches?(object, :to => :idling)                                   # => true
+    #   branch.matches?(object, :from => :parked, :to => :idling)                 # => true
+    #   branch.matches?(object, :on => :ignite, :from => :parked, :to => :idling) # => true
     #   
     #   # Unsuccessful
-    #   guard.matches?(object, :on => :park)                                      # => false
-    #   guard.matches?(object, :from => :idling)                                  # => false
-    #   guard.matches?(object, :to => :first_gear)                                # => false
-    #   guard.matches?(object, :from => :parked, :to => :first_gear)              # => false
-    #   guard.matches?(object, :on => :park, :from => :parked, :to => :idling)    # => false
+    #   branch.matches?(object, :on => :park)                                     # => false
+    #   branch.matches?(object, :from => :idling)                                 # => false
+    #   branch.matches?(object, :to => :first_gear)                               # => false
+    #   branch.matches?(object, :from => :parked, :to => :first_gear)             # => false
+    #   branch.matches?(object, :on => :park, :from => :parked, :to => :idling)   # => false
     def matches?(object, query = {})
       !match(object, query).nil?
     end
     
     # Attempts to match the given object / query against the set of requirements
-    # configured for this guard.  In addition to matching the event, from state,
+    # configured for this branch.  In addition to matching the event, from state,
     # and to state, this will also check whether the configured :if/:unless
     # conditions pass on the given object.
     # 
@@ -112,21 +106,25 @@ module StateMachine
     #   specified, then this will always match.
     # * <tt>:on</tt> - One or more events that fired the transition.  If none
     #   are specified, then this will always match.
+    # * <tt>:guard</tt> - Whether to guard matches with the if/unless
+    #   conditionals defined for this branch.  Default is true.
     # 
     # == Examples
     # 
-    #   guard = StateMachine::Guard.new(:parked => :idling, :on => :ignite)
+    #   branch = StateMachine::Branch.new(:parked => :idling, :on => :ignite)
     #   
-    #   guard.match(object, :on => :ignite) # => {:to => ..., :from => ..., :on => ...}
-    #   guard.match(object, :on => :park)   # => nil
+    #   branch.match(object, :on => :ignite)  # => {:to => ..., :from => ..., :on => ...}
+    #   branch.match(object, :on => :park)    # => nil
     def match(object, query = {})
-      if (match = match_query(query)) && matches_conditions?(object)
+      assert_valid_keys(query, :from, :to, :on, :guard)
+      
+      if (match = match_query(query)) && matches_conditions?(object, query)
         match
       end
     end
     
-    # Draws a representation of this guard on the given graph.  This will draw
-    # an edge between every state this guard matches *from* to either the
+    # Draws a representation of this branch on the given graph.  This will draw
+    # an edge between every state this branch matches *from* to either the
     # configured to state or, if none specified, then a loopback to the from
     # state.
     # 
@@ -191,16 +189,11 @@ module StateMachine
       def match_query(query)
         query ||= {}
         
-        if match_success(query) && match_event(query) && (state_requirement = match_states(query))
+        if match_event(query) && (state_requirement = match_states(query))
           state_requirement.merge(:on => event_requirement)
         end
       end
       
-      # Verifies that the success requirement matches the given query
-      def match_success(query)
-        matches_requirement?(query, :success, success_requirement)
-      end
-      
       # Verifies that the event requirement matches the given query
       def match_event(query)
         matches_requirement?(query, :on, event_requirement)
@@ -220,9 +213,10 @@ module StateMachine
         !query.include?(option) || requirement.matches?(query[option], query)
       end
       
-      # Verifies that the conditionals for this guard evaluate to true for the
+      # Verifies that the conditionals for this branch evaluate to true for the
       # given object
-      def matches_conditions?(object)
+      def matches_conditions?(object, query)
+        query[:guard] == false ||
         Array(if_condition).all? {|condition| evaluate_method(object, condition)} &&
         !Array(unless_condition).any? {|condition| evaluate_method(object, condition)}
       end