state_machine 0.5.2 → 0.6.0

data/CHANGELOG.rdoc

@@ -1,5 +1,14 @@
 == master
 
+== 0.6.0 / 2009-03-03
+
+* Allow multiple conditions for callbacks / class behaviors
+* Add support for state-driven class behavior with :if/:unless options
+* Alias Machine#event as Machine#on
+* Fix nil from/to states not being handled properly
+* Simplify hooking callbacks into loopbacks
+* Add simplified transition/callback requirement syntax
+
 == 0.5.2 / 2009-02-17
 
 * Improve pretty-print of events

data/README.rdoc

@@ -42,7 +42,7 @@ Some brief, high-level features include:
 * DataMapper integration
 * Sequel integration
 * State predicates
-* State-driven behavior
+* State-driven instance / class behavior
 * State values of any data type
 * Dynamically-generated state values
 * Inheritance
@@ -60,7 +60,7 @@ Below is an example of many of the features offered by this plugin, including:
 * Namespaced states
 * Transition callbacks
 * Conditional transitions
-* State-driven behavior
+* State-driven instance behavior
 * Customized state values
 
 Class definition:
@@ -69,43 +69,39 @@ Class definition:
     attr_accessor :seatbelt_on
     
     state_machine :state, :initial => :parked do
-      before_transition :from => [:parked, :idling], :do => :put_on_seatbelt
+      before_transition any => [:parked, :idling], :do => :put_on_seatbelt
       after_transition :on => :crash, :do => :tow
       after_transition :on => :repair, :do => :fix
-      after_transition :to => :parked do |vehicle, transition|
+      after_transition any => :parked do |vehicle, transition|
         vehicle.seatbelt_on = false
       end
       
       event :park do
-        transition :to => :parked, :from => [:idling, :first_gear]
+        transition [:idling, :first_gear] => :parked
       end
       
       event :ignite do
-        transition :to => :stalled, :from => :stalled
-        transition :to => :idling, :from => :parked
+        transition :stalled => :stalled, :parked => :idling
       end
       
       event :idle do
-        transition :to => :idling, :from => :first_gear
+        transition :first_gear => :idling
       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
+        transition :idling => :first_gear, :first_gear => :second_gear, :second_gear => :third_gear
       end
       
       event :shift_down do
-        transition :to => :second_gear, :from => :third_gear
-        transition :to => :first_gear, :from => :second_gear
+        transition :third_gear => :second_gear, :second_gear => :first_gear
       end
       
       event :crash do
-        transition :to => :stalled, :from => [:first_gear, :second_gear, :third_gear], :unless => :auto_shop_busy?
+        transition [:first_gear, :second_gear, :third_gear] => :stalled, :unless => :auto_shop_busy?
       end
       
       event :repair do
-        transition :to => :parked, :from => :stalled, :if => :auto_shop_busy?
+        transition :stalled => :parked, :if => :auto_shop_busy?
       end
       
       state :parked do
@@ -129,11 +125,11 @@ Class definition:
     
     state_machine :hood_state, :initial => :closed, :namespace => 'hood' do
       event :open do
-        transition :to => :opened
+        transition all => :opened
       end
       
       event :close do
-        transition :to => :closed
+        transition all => :closed
       end
       
       state :opened, :value => 1
@@ -232,13 +228,17 @@ saving the record, named scopes, and observers.  For example,
 
   class Vehicle < ActiveRecord::Base
     state_machine :initial => :parked do
-      before_transition :to => :idling, :do => :put_on_seatbelt
-      after_transition :to => :parked do |vehicle, transition|
+      before_transition any => :idling, :do => :put_on_seatbelt
+      after_transition any => :parked do |vehicle, transition|
         vehicle.seatbelt = 'off'
       end
       
       event :ignite do
-        transition :to => :idling, :from => :parked
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_presence_of :seatbelt_on
       end
     end
     
@@ -275,13 +275,17 @@ callbacks, and observers.  For example,
     property :state, String
     
     state_machine :initial => :parked do
-      before_transition :to => :idling, :do => :put_on_seatbelt
-      after_transition :to => :parked do |transition|
+      before_transition any => :idling, :do => :put_on_seatbelt
+      after_transition any => :parked do |transition|
         self.seatbelt = 'off' # self is the record
       end
       
       event :ignite do
-        transition :to => :idling, :from => :parked
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_present :seatbelt_on
       end
     end
     
@@ -320,13 +324,17 @@ callbacks.  For example,
 
   class Vehicle < Sequel::Model
     state_machine :initial => :parked do
-      before_transition :to => :idling, :do => :put_on_seatbelt
-      after_transition :to => :parked do |transition|
+      before_transition any => :idling, :do => :put_on_seatbelt
+      after_transition any => :parked do |transition|
         self.seatbelt = 'off' # self is the record
       end
       
       event :ignite do
-        transition :to => :idling, :from => :parked
+        transition :parked => :idling
+      end
+      
+      state :first_gear, :second_gear do
+        validates_presence_of :seatbelt_on
       end
     end
     

data/Rakefile

@@ -5,7 +5,7 @@ require 'rake/contrib/sshpublisher'
 
 spec = Gem::Specification.new do |s|
   s.name              = 'state_machine'
-  s.version           = '0.5.2'
+  s.version           = '0.6.0'
   s.platform          = Gem::Platform::RUBY
   s.summary           = 'Adds support for creating state machines for attributes on any Ruby class'
   

data/examples/auto_shop.rb

@@ -1,11 +1,11 @@
 class AutoShop
   state_machine :initial => :available do
     event :tow_vehicle do
-      transition :to => :busy, :from => :available
+      transition :available => :busy
     end
     
     event :fix_vehicle do
-      transition :to => :available, :from => :busy
+      transition :busy => :available 
     end
   end
 end

data/examples/car.rb

@@ -1,19 +1,19 @@
 class Car < Vehicle
   state_machine do
     event :reverse do
-      transition :to => :backing_up, :from => [:parked, :idling, :first_gear]
+      transition [:parked, :idling, :first_gear] => :backing_up
     end
     
     event :park do
-      transition :to => :parked, :from => :backing_up
+      transition :backing_up => :parked
     end
     
     event :idle do
-      transition :to => :idling, :from => :backing_up
+      transition :backing_up => :idling
     end
     
     event :shift_up do
-      transition :to => :first_gear, :from => :backing_up
+      transition :backing_up => :first_gear
     end
   end
 end

data/examples/traffic_light.rb

@@ -1,9 +1,7 @@
 class TrafficLight
   state_machine :initial => :stop do
     event :cycle do
-      transition :to => :proceed, :from => :stop
-      transition :to => :caution, :from => :proceed
-      transition :to => :stop, :from => :caution
+      transition :stop => :proceed, :proceed => :caution, :caution => :stop
     end
   end
 end

data/examples/vehicle.rb

@@ -1,35 +1,31 @@
 class Vehicle
   state_machine :initial => :parked do
     event :park do
-      transition :to => :parked, :from => [:idling, :first_gear]
+      transition [:idling, :first_gear] => :parked
     end
     
     event :ignite do
-      transition :to => :stalled, :from => :stalled
-      transition :to => :idling, :from => :parked
+      transition :stalled => same, :parked => :idling
     end
     
     event :idle do
-      transition :to => :idling, :from => :first_gear
+      transition :first_gear => :idling
     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
+      transition :idling => :first_gear, :first_gear => :second_gear, :second_gear => :third_gear
     end
     
     event :shift_down do
-      transition :to => :second_gear, :from => :third_gear
-      transition :to => :first_gear, :from => :second_gear
+      transition :third_gear => :second_gear, :second_gear => :first_gear
     end
     
     event :crash do
-      transition :to => :stalled, :from => [:first_gear, :second_gear, :third_gear]
+      transition [:first_gear, :second_gear, :third_gear] => :stalled
     end
     
     event :repair do
-      transition :to => :parked, :from => :stalled
+      transition :stalled => :parked
     end
   end
 end

data/lib/state_machine.rb

@@ -199,7 +199,7 @@ module StateMachine
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       event :ignite do
-    #         transition :to => :idling
+    #         transition all => :idling
     #       end
     #     end
     #   end
@@ -242,21 +242,21 @@ module StateMachine
     #   class Vehicle
     #     state_machine :heater_state, :initial => :off :namespace => 'heater' do
     #       event :turn_on do
-    #         transition :to => :on
+    #         transition all => :on
     #       end
     #       
     #       event :turn_off do
-    #         transition :to => :off
+    #         transition all => :off
     #       end
     #     end
     #     
     #     state_machine :hood_state, :initial => :closed, :namespace => 'hood' do
     #       event :open do
-    #         transition :to => :opened
+    #         transition all => :opened
     #       end
     #       
     #       event :close do
-    #         transition :to => :closed
+    #         transition all => :closed
     #       end
     #     end
     #   end

data/lib/state_machine/callback.rb

@@ -127,7 +127,7 @@ module StateMachine
     end
     
     # Gets a list of the states known to this callback by looking at the
-    # guard's requirements
+    # guard's known states
     def known_states
       guard.known_states
     end

data/lib/state_machine/condition_proxy.rb

@@ -0,0 +1,94 @@
+require 'state_machine/eval_helpers'
+
+module StateMachine
+  # Represents a type of module in which class-level methods are proxied to
+  # another class, injecting a custom :if condition along with method.
+  # 
+  # This is used for being able to automatically include conditionals which
+  # check the current state in class-level methods that have configuration
+  # options.
+  # 
+  # == Examples
+  # 
+  #   class Vehicle
+  #     class << self
+  #       attr_accessor :validations
+  #       
+  #       def validate(options, &block)
+  #         validations << options
+  #       end
+  #     end
+  #     
+  #     self.validations = []
+  #     attr_accessor :state, :simulate
+  #     
+  #     def moving?
+  #       self.class.validations.all? {|validation| validation[:if].call(self)}
+  #     end
+  #   end
+  # 
+  # In the above class, a simple set of validation behaviors have been defined.
+  # Each validation consists of a configuration like so:
+  # 
+  #   Vehicle.validate :unless => :simulate
+  #   Vehicle.validate :if => lambda {|vehicle| ...}
+  # 
+  # In order to scope conditions, a condition proxy can be created to the
+  # Vehicle class.  For example,
+  # 
+  #   proxy = StateMachine::ConditionProxy.new(Vehicle, lambda {|vehicle| vehicle.state == 'first_gear'})
+  #   proxy.validate(:unless => :simulate)
+  #   
+  #   vehicle = Vehicle.new     # => #<Vehicle:0xb7ce491c @simulate=nil, @state=nil>
+  #   vehicle.moving?           # => false
+  #   
+  #   vehicle.state = 'first_gear'
+  #   vehicle.moving?           # => true
+  #   
+  #   vehicle.simulate = true
+  #   vehicle.moving?           # => false
+  class ConditionProxy < Module
+    include EvalHelpers
+    
+    # Creates a new proxy to the given class, merging in the given condition
+    def initialize(klass, condition)
+      @klass = klass
+      @condition = condition
+    end
+    
+    # Hooks in condition merging to methods that don't exist in this module
+    def method_missing(*args, &block)
+      # Get the configuration
+      if args.last.is_a?(Hash)
+        options = args.last
+      else
+        args << options = {}
+      end
+      
+      # Get any existing condition that may need to be merged
+      if_condition = options.delete(:if)
+      unless_condition = options.delete(:unless)
+      
+      # Provide scope access to configuration in case the block is evaluated
+      # within the object instance
+      proxy = self
+      proxy_condition = @condition
+      
+      # Replace the configuration condition with the one configured for this
+      # proxy, merging together any existing conditions
+      options[:if] = lambda do |*args|
+        # Block may be executed within the context of the actual object, so it'll
+        # either be the first argument or the executing context
+        object = args.first || self
+        
+        proxy.evaluate_method(object, proxy_condition) &&
+        Array(if_condition).all? {|condition| proxy.evaluate_method(object, condition)} &&
+        !Array(unless_condition).any? {|condition| proxy.evaluate_method(object, condition)}
+      end
+      
+      # Evaluate the method on the original class with the condition proxied
+      # through
+      @klass.send(*args, &block)
+    end
+  end
+end

data/lib/state_machine/event.rb

@@ -1,6 +1,7 @@
 require 'state_machine/transition'
 require 'state_machine/guard'
 require 'state_machine/assertions'
+require 'state_machine/matcher_helpers'
 
 module StateMachine
   # An event defines an action that transitions an attribute from one state to
@@ -8,6 +9,7 @@ module StateMachine
   # guards configured for the event.
   class Event
     include Assertions
+    include MatcherHelpers
     
     # The state machine for which this event is defined
     attr_accessor :machine
@@ -41,15 +43,75 @@ module StateMachine
       @known_states = @known_states.dup
     end
     
-    # Creates a new transition that will be evaluated when the event is fired.
+    # Creates a new transition that determines what to change the current state
+    # to when this event fires.
     # 
-    # Configuration options:
+    # == Defining transitions
+    # 
+    # The options for a new transition uses the Hash syntax to map beginning
+    # states to ending states.  For example,
+    # 
+    #   transition :parked => :idling, :idling => :first_gear
+    # 
+    # In this case, when the event is fired, this transition will cause the
+    # state to be +idling+ if it's current state is +parked+ or +first_gear+ if
+    # it's current state is +idling+.
+    # 
+    # To help defining these implicit transitions, a set of helpers are available
+    # for defining slightly more complex matching:
+    # * <tt>all</tt> - Matches every state in the machine
+    # * <tt>all - [:parked, :idling, ...]</tt> - Matches every state except those specified
+    # * <tt>any</tt> - An alias for +all+ (matches every state in the machine)
+    # * <tt>same</tt> - Matches the same state being transitioned from
+    # 
+    # See StateMachine::MatcherHelpers for more information.
+    # 
+    # Examples:
+    # 
+    #   transition all => nil                               # Transitions to nil regardless of the current state
+    #   transition all => :idling                           # Transitions to :idling regardless of the current state
+    #   transition all - [:idling, :first_gear] => :idling  # Transitions every state but :idling and :first_gear to :idling
+    #   transition nil => :idling                           # Transitions to :idling from the nil state
+    #   transition :parked => :idling                       # Transitions to :idling if :parked
+    #   transition [:parked, :stalled] => :idling           # Transitions to :idling if :parked or :stalled
+    #   
+    #   transition :parked => same                          # Loops :parked back to :parked
+    #   transition [:parked, :stalled] => same              # Loops either :parked or :stalled back to the same state
+    #   transition all - :parked => same                    # Loops every state but :parked back to the same state
+    # 
+    # == Verbose transitions
+    # 
+    # Transitions can also be defined use an explicit set of deprecated
+    # configuration options:
     # * <tt>:from</tt> - A state or array of states that can be transitioned from.
     #   If not specified, then the transition can occur for *any* state.
     # * <tt>:to</tt> - The state that's being transitioned to.  If not specified,
     #   then the transition will simply loop back (i.e. the state will not change).
     # * <tt>:except_from</tt> - A state or array of states that *cannot* be
     #   transitioned from.
+    # 
+    # Examples:
+    # 
+    #   transition :to => nil
+    #   transition :to => :idling
+    #   transition :except_from => [:idling, :first_gear], :to => :idling
+    #   transition :from => nil, :to => :idling
+    #   transition :from => [:parked, :stalled], :to => :idling
+    #   
+    #   transition :from => :parked
+    #   transition :from => [:parked, :stalled]
+    #   transition :except_from => :parked
+    # 
+    # Notice that the above examples are the verbose equivalent of the examples
+    # described initially.
+    # 
+    # == Conditions
+    # 
+    # In addition to the state requirements for each transition, a condition
+    # can also be defined to help determine whether that transition is
+    # available.  These options will work on both the normal and verbose syntax.
+    # 
+    # Configuration options:
     # * <tt>:if</tt> - A method, proc or string to call to determine if the
     #   transition should occur (e.g. :if => :moving?, or :if => lambda {|vehicle| vehicle.speed > 60}).
     #   The condition should return or evaluate to true or false.
@@ -57,26 +119,25 @@ module StateMachine
     #   transition should not occur (e.g. :unless => :stopped?, or :unless => lambda {|vehicle| vehicle.speed <= 60}).
     #   The condition should return or evaluate to true or false.
     # 
+    # Examples:
+    # 
+    #   transition :parked => :idling, :if => :moving?
+    #   transition :parked => :idling, :unless => :stopped?
+    #   
+    #   transition :from => :parked, :to => :idling, :if => :moving?
+    #   transition :from => :parked, :to => :idling, :unless => :stopped?
+    # 
     # == Order of operations
     # 
     # Transitions are evaluated in the order in which they're defined.  As a
     # result, if more than one transition applies to a given object, then the
     # first transition that matches will be performed.
-    # 
-    # == Examples
-    # 
-    #   transition :from => nil, :to => :parked
-    #   transition :from => [:first_gear, :reverse]
-    #   transition :except_from => :parked
-    #   transition :to => nil
-    #   transition :to => :parked
-    #   transition :to => :parked, :from => :first_gear
-    #   transition :to => :parked, :from => [:first_gear, :reverse]
-    #   transition :to => :parked, :from => :first_gear, :if => :moving?
-    #   transition :to => :parked, :from => :first_gear, :unless => :stopped?
-    #   transition :to => :parked, :except_from => :parked
     def transition(options)
-      assert_valid_keys(options, :from, :to, :except_from, :if, :unless)
+      raise ArgumentError, 'Must specify as least one transition requirement' if options.empty?
+      
+      # Only a certain subset of explicit options are allowed for transition
+      # requirements
+      assert_valid_keys(options, :from, :to, :except_from, :if, :unless) if (options.keys - [:from, :to, :on, :except_from, :except_to, :except_on, :if, :unless]).empty?
       
       guards << guard = Guard.new(options)
       @known_states |= guard.known_states
@@ -96,11 +157,17 @@ module StateMachine
     def next_transition(object)
       from = machine.state_for(object).name
       
-      if guard = guards.find {|guard| guard.matches?(object, :from => from)}
-        # Guard allows for the transition to occur
-        to = guard.state_requirement[:to].values.any? ? guard.state_requirement[:to].values.first : from
-        Transition.new(object, machine, name, from, to)
+      guards.each do |guard|
+        if match = guard.match(object, :from => from)
+          # Guard allows for the transition to occur
+          to = match[:to].values.empty? ? from : match[:to].values.first
+          
+          return Transition.new(object, machine, name, from, to)
+        end
       end
+      
+      # No transition matched
+      nil
     end
     
     # Attempts to perform the next available transition on the given object.
@@ -139,11 +206,13 @@ module StateMachine
     # For example,
     # 
     #   event = StateMachine::Event.new(machine, :park)
-    #   event.transition :to => :parked, :from => :idling
-    #   event   # => #<StateMachine::Event name=:park transitions=[:idling => :parked]>
+    #   event.transition all - :idling => :parked, :idling => same
+    #   event   # => #<StateMachine::Event name=:park transitions=[all - :idling => :parked, :idling => same]>
     def inspect
       transitions = guards.map do |guard|
-        "#{guard.state_requirement[:from].description} => #{guard.state_requirement[:to].description}"
+        guard.state_requirements.map do |state_requirement|
+          "#{state_requirement[:from].description} => #{state_requirement[:to].description}"
+        end * ', '
       end
       
       "#<#{self.class} name=#{name.inspect} transitions=[#{transitions * ', '}]>"