state_machine 0.5.2 → 0.6.0

data/lib/state_machine/guard.rb

@@ -17,58 +17,60 @@ module StateMachine
     # The condition that must *not* be met on an object
     attr_reader :unless_condition
     
-    # The requirement for verifying the event being guarded (includes :on and
-    # :except_on).
+    # The requirement for verifying the event being guarded
     attr_reader :event_requirement
     
-    # The requirement for verifying the states being guarded (includes :from,
-    # :to, :except_from, and :except_to).  All options map to
-    # either nil (if not specified) or an array of state names.
-    attr_reader :state_requirement
+    # One or more requrirements for verifying the states being guarded.  All
+    # requirements contain a mapping of {:from => matcher, :to => matcher}.
+    attr_reader :state_requirements
     
     # A list of all of the states known to this guard.  This will pull states
-    # from the following options in +state_requirements+ (in the same order):
+    # from the following options (in the same order):
     # * +from+ / +except_from+
     # * +to+ / +except_to+
     attr_reader :known_states
     
     # Creates a new guard
     def initialize(options = {}) #:nodoc:
-      assert_valid_keys(options, :from, :to, :on, :except_from, :except_to, :except_on, :if, :unless)
-      
       # Build conditionals
-      assert_exclusive_keys(options, :if, :unless)
       @if_condition = options.delete(:if)
       @unless_condition = options.delete(:unless)
       
-      # Build event/state requirements
+      # Build event requirement
       @event_requirement = build_matcher(options, :on, :except_on)
-      @state_requirement = {:from => build_matcher(options, :from, :except_from), :to => build_matcher(options, :to, :except_to)}
+      
+      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)}]
+      else
+        # Separate out the event requirement
+        options.delete(:on)
+        options.delete(:except_on)
+        
+        # Implicit from/to requirements specified
+        @state_requirements = options.collect do |from, to|
+          from = WhitelistMatcher.new(from) unless from.is_a?(Matcher)
+          to = WhitelistMatcher.new(to) unless to.is_a?(Matcher)
+          {:from => from, :to => to}
+        end
+      end
       
       # Track known states.  The order that requirements are iterated is based
       # on the priority in which tracked states should be added.
       @known_states = []
-      [:from, :to].each {|option| @known_states |= @state_requirement[option].values}
+      @state_requirements.each do |state_requirement|
+        [:from, :to].each {|option| @known_states |= state_requirement[option].values}
+      end
     end
     
-    # Attempts to match the given object / query against the set of requirements
+    # Determines whether the given object / query matches the requirements
     # configured for this guard.  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.
     # 
-    # This will return true or false depending on whether a match is found.
-    # 
-    # Query options:
-    # * <tt>:from</tt> - One or more states being transitioned from.  If none
-    #   are specified, then this will always match.
-    # * <tt>:to</tt> - One or more states being transitioned to.  If none are
-    #   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.
-    # 
     # == Examples
     # 
-    #   guard = StateMachine::Guard.new(:from => [nil, :parked], :to => :idling, :on => :ignite)
+    #   guard = StateMachine::Guard.new(:parked => :idling, :on => :ignite)
     #   
     #   # Successful
     #   guard.matches?(object, :on => :ignite)                                    # => true
@@ -85,7 +87,36 @@ module StateMachine
     #   guard.matches?(object, :from => :parked, :to => :first_gear)              # => false
     #   guard.matches?(object, :on => :park, :from => :parked, :to => :idling)    # => false
     def matches?(object, query = {})
-      matches_query?(query) && matches_conditions?(object)
+      !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,
+    # and to state, this will also check whether the configured :if/:unless
+    # conditions pass on the given object.
+    # 
+    # If a match is found, then the event/state requirements that the query
+    # passed successfully will be returned.  Otherwise, nil is returned if there
+    # was no match.
+    # 
+    # Query options:
+    # * <tt>:from</tt> - One or more states being transitioned from.  If none
+    #   are specified, then this will always match.
+    # * <tt>:to</tt> - One or more states being transitioned to.  If none are
+    #   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.
+    # 
+    # == Examples
+    # 
+    #   guard = StateMachine::Guard.new(:parked => :idling, :on => :ignite)
+    #   
+    #   guard.match(object, :on => :ignite) # => {:to => ..., :from => ..., :on => ...}
+    #   guard.match(object, :on => :park)   # => nil
+    def match(object, query = {})
+      if (match = match_query(query)) && matches_conditions?(object)
+        match
+      end
     end
     
     # Draws a representation of this guard on the given graph.  This will draw
@@ -108,26 +139,28 @@ module StateMachine
     # 
     # The collection of edges generated on the graph will be returned.
     def draw(graph, event, valid_states)
-      edges = []
-      
-      # From states determined based on the known valid states
-      from_states = state_requirement[:from].filter(valid_states)
-      
-      # If a to state is not specified, then it's a loopback and each from
-      # state maps back to itself
-      if state_requirement[:to].values.any?
-        to_state = state_requirement[:to].values.first
-        loopback = false
-      else
-        loopback = true
-      end
-      
-      # Generate an edge between each from and to state
-      from_states.each do |from_state|
-        edges << graph.add_edge(from_state.to_s, (loopback ? from_state : to_state).to_s, :label => event.to_s)
+      state_requirements.inject([]) do |edges, state_requirement|
+        # From states determined based on the known valid states
+        from_states = state_requirement[:from].filter(valid_states)
+        
+        # If a to state is not specified, then it's a loopback and each from
+        # state maps back to itself
+        if state_requirement[:to].values.empty?
+          loopback = true
+        else
+          to_state = state_requirement[:to].values.first
+          to_state = to_state ? to_state.to_s : 'nil'
+          loopback = false
+        end
+        
+        # Generate an edge between each from and to state
+        from_states.each do |from_state|
+          from_state = from_state ? from_state.to_s : 'nil'
+          edges << graph.add_edge(from_state, loopback ? from_state : to_state, :label => event.to_s)
+        end
+        
+        edges
       end
-      
-      edges
     end
     
     protected
@@ -149,20 +182,25 @@ module StateMachine
       # Verifies that all configured requirements (event and state) match the
       # given query.  If a match is return, then a hash containing the
       # event/state requirements that passed will be returned; otherwise, nil.
-      def matches_query?(query)
+      def match_query(query)
         query ||= {}
-        matches_event?(query) && matches_states?(query)
+        
+        if match_event(query) && (state_requirement = match_states(query))
+          state_requirement.merge(:on => event_requirement)
+        end
       end
       
       # Verifies that the event requirement matches the given query
-      def matches_event?(query)
+      def match_event(query)
         matches_requirement?(query, :on, event_requirement)
       end
       
       # Verifies that the state requirements match the given query.  If a
       # matching requirement is found, then it is returned.
-      def matches_states?(query)
-        [:from, :to].all? {|option| matches_requirement?(query, option, state_requirement[option])}
+      def match_states(query)
+        state_requirements.detect do |state_requirement|
+          [:from, :to].all? {|option| matches_requirement?(query, option, state_requirement[option])}
+        end
       end
       
       # Verifies that an option in the given query matches the values required
@@ -174,13 +212,8 @@ module StateMachine
       # Verifies that the conditionals for this guard evaluate to true for the
       # given object
       def matches_conditions?(object)
-        if if_condition
-          evaluate_method(object, if_condition)
-        elsif unless_condition
-          !evaluate_method(object, unless_condition)
-        else
-          true
-        end
+        Array(if_condition).all? {|condition| evaluate_method(object, condition)} &&
+        !Array(unless_condition).any? {|condition| evaluate_method(object, condition)}
       end
   end
 end

data/lib/state_machine/integrations/active_record.rb

@@ -10,7 +10,7 @@ module StateMachine
     #   class Vehicle < ActiveRecord::Base
     #     state_machine :initial => :parked do
     #       event :ignite do
-    #         transition :to => :idling, :from => :parked
+    #         transition :parked => :idling
     #       end
     #     end
     #   end
@@ -95,7 +95,7 @@ module StateMachine
     # 
     #   class Vehicle < ActiveRecord::Base
     #     state_machine :initial => :parked do
-    #       before_transition :to => :idling do |vehicle|
+    #       before_transition any => :idling do |vehicle|
     #         vehicle.put_on_seatbelt
     #       end
     #       
@@ -104,7 +104,7 @@ module StateMachine
     #       end
     #       
     #       event :ignite do
-    #         transition :to => :idling, :from => :parked
+    #         transition :parked => :idling
     #       end
     #     end
     #     

data/lib/state_machine/integrations/data_mapper.rb

@@ -16,7 +16,7 @@ module StateMachine
     #     
     #     state_machine :initial => :parked do
     #       event :ignite do
-    #         transition :to => :idling, :from => :parked
+    #         transition :parked => :idling
     #       end
     #     end
     #   end
@@ -122,7 +122,7 @@ module StateMachine
     #     property :state, String
     #     
     #     state_machine :initial => :parked do
-    #       before_transition :to => :idling do
+    #       before_transition any => :idling do
     #         put_on_seatbelt
     #       end
     #       
@@ -131,7 +131,7 @@ module StateMachine
     #       end
     #       
     #       event :ignite do
-    #         transition :to => :idling, :from => :parked
+    #         transition :parked => :idling
     #       end
     #     end
     #     

data/lib/state_machine/integrations/data_mapper/observer.rb

@@ -37,6 +37,8 @@ module StateMachine
       # If dm-observer is not available, then this feature will be skipped.
       # 
       module Observer
+        include MatcherHelpers
+        
         # Creates a callback that will be invoked *before* a transition is
         # performed, so long as the given configuration options match the
         # transition.  Each part of the transition (event, to state, from state)
@@ -55,7 +57,7 @@ module StateMachine
         #     
         #     state_machine :initial => :parked do
         #       event :ignite do
-        #         transition :to => :idling, :from => :parked
+        #         transition :parked => :idling
         #       end
         #     end
         #   end
@@ -70,12 +72,12 @@ module StateMachine
         #     end
         #     
         #     # Target all state machines
-        #     before_transition :to => :idling, :from => :parked, :on => :ignite do
+        #     before_transition :parked => :idling, :on => :ignite do
         #       # put on seatbelt
         #     end
         #     
         #     # Target a specific state machine
-        #     before_transition :state, :to => :idling do
+        #     before_transition :state, any => :idling do
         #       # put on seatbelt
         #     end
         #     
@@ -111,7 +113,7 @@ module StateMachine
         #     
         #     state_machine :initial => :parked do
         #       event :ignite do
-        #         transition :to => :idling, :from => :parked
+        #         transition :parked => :idling
         #       end
         #     end
         #   end
@@ -126,12 +128,12 @@ module StateMachine
         #     end
         #     
         #     # Target all state machines
-        #     after_transition :to => :idling, :from => :parked, :on => :ignite do
+        #     after_transition :parked => :idling, :on => :ignite do
         #       # put on seatbelt
         #     end
         #     
         #     # Target a specific state machine
-        #     after_transition :state, :to => :idling do
+        #     after_transition :state, any => :idling do
         #       # put on seatbelt
         #     end
         #     

data/lib/state_machine/integrations/sequel.rb

@@ -10,7 +10,7 @@ module StateMachine
     #   class Vehicle < Sequel::Model
     #     state_machine :initial => :parked do
     #       event :ignite do
-    #         transition :to => :idling, :from => :parked
+    #         transition :parked => :idling
     #       end
     #     end
     #   end
@@ -101,7 +101,7 @@ module StateMachine
     # 
     #   class Vehicle < Sequel::Model
     #     state_machine :initial => :parked do
-    #       before_transition :to => :idling do
+    #       before_transition any => :idling do
     #         put_on_seatbelt
     #       end
     #       
@@ -110,7 +110,7 @@ module StateMachine
     #       end
     #       
     #       event :ignite do
-    #         transition :to => :idling, :from => :parked
+    #         transition :parked => :idling
     #       end
     #     end
     #     

data/lib/state_machine/machine.rb

@@ -7,6 +7,7 @@ require 'state_machine/event'
 require 'state_machine/callback'
 require 'state_machine/node_collection'
 require 'state_machine/state_collection'
+require 'state_machine/matcher_helpers'
 
 module StateMachine
   # Represents a state machine for a particular attribute.  State machines
@@ -44,7 +45,7 @@ module StateMachine
   # 
   #   class Vehicle
   #     state_machine, :initial => :parked do
-  #       before_transition :to => :idling, :do => lambda {|vehicle| throw :halt}
+  #       before_transition any => :idling, :do => lambda {|vehicle| throw :halt}
   #       ...
   #     end
   #   end
@@ -64,7 +65,7 @@ module StateMachine
   #   class Vehicle
   #     state_machine do
   #       event :park do
-  #         transition :to => :parked, :from => :idling
+  #         transition :idling => :parked
   #       end
   #       ...
   #     end
@@ -115,8 +116,8 @@ module StateMachine
   #     end
   #   end
   # 
-  # Additional observer-like behavior may be exposed by the various
-  # integrations available.  See below for more information.
+  # Additional observer-like behavior may be exposed by the various integrations
+  # available.  See below for more information.
   # 
   # == Integrations
   # 
@@ -138,6 +139,7 @@ module StateMachine
   # constants defined under the StateMachine::Integrations namespace.
   class Machine
     include Assertions
+    include MatcherHelpers
     
     class << self
       # Attempts to find or create a state machine for the given class.  For
@@ -369,7 +371,7 @@ module StateMachine
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       event :ignite do
-    #         transition :to => :idling, :from => :parked
+    #         transition :parked => :idling
     #       end
     #     end
     #   end
@@ -387,7 +389,7 @@ module StateMachine
     #   class Vehicle
     #     state_machine :initial => :parked do
     #       event :ignite do
-    #         transition :to => :idling, :from => :parked
+    #         transition :parked => :idling
     #       end
     #       
     #       state :idling, :value => 'IDLING'
@@ -405,7 +407,7 @@ module StateMachine
     #   class Vehicle < ActiveRecord::Base
     #     state_machine :state_id, :initial => :parked do
     #       event :ignite do
-    #         transition :to => :idling, :from => :parked
+    #         transition :parked => :idling
     #       end
     #       
     #       states.each {|state| self.state(state.name, :value => VehicleState.find_by_name(state.name.to_s).id)}
@@ -424,11 +426,11 @@ module StateMachine
     #   class Vehicle
     #     state_machine :purchased_at, :initial => :available do
     #       event :purchase do
-    #         transition :to => :purchased
+    #         transition all => :purchased
     #       end
     #       
     #       event :restock do
-    #         transition :to => :available
+    #         transition all => :available
     #       end
     #       
     #       state :available, :value => nil
@@ -464,7 +466,7 @@ module StateMachine
     #     
     #     state_machine :initial => :parked do
     #       event :ignite do
-    #         transition :to => :idling, :from => :parked
+    #         transition :parked => :idling
     #       end
     #       
     #       state :parked do
@@ -540,6 +542,39 @@ module StateMachine
     #   vehicle = Vehicle.new
     #   vehicle.state = 'backing_up'
     #   vehicle.speed               # => NoMethodError: undefined method 'speed' for #<Vehicle:0xb7d296ac> in state "backing_up"
+    # 
+    # == State-aware class methods
+    # 
+    # In addition to defining scopes for instance methods that are state-aware,
+    # the same can be done for certain types of class methods.
+    # 
+    # Some libraries have support for class-level methods that only run certain
+    # behaviors based on a conditions hash passed in.  For example:
+    # 
+    #   class Vehicle < ActiveRecord::Base
+    #     state_machine do
+    #       ...
+    #       state :first_gear, :second_gear, :third_gear do
+    #         validates_presence_of   :speed
+    #         validates_inclusion_of  :speed, :in => 0..25, :if => :in_school_zone?
+    #       end
+    #     end
+    #   end
+    # 
+    # In the above ActiveRecord model, two validations have been defined which
+    # will *only* run when the Vehicle object is in one of the three states:
+    # +first_gear+, +second_gear+, or +third_gear.  Notice, also, that if/unless
+    # conditions can continue to be used.
+    # 
+    # This functionality is not library-specific and can work for any class-level
+    # method that is defined like so:
+    # 
+    #   def validates_presence_of(args, options = {})
+    #     ...
+    #   end
+    # 
+    # The minimum requirement is that the last argument in the method be an
+    # options hash which contains at least <tt>:if</tt> condition support.
     def state(*names, &block)
       options = names.last.is_a?(Hash) ? names.pop : {}
       assert_valid_keys(options, :value, :if)
@@ -616,6 +651,9 @@ module StateMachine
     # Defines one or more events for the machine and the transitions that can
     # be performed when those events are run.
     # 
+    # This method is also aliased as +on+ for improved compatibility with
+    # using a domain-specific language.
+    # 
     # == Instance methods
     # 
     # The following instance methods are generated when a new event is defined
@@ -643,11 +681,11 @@ module StateMachine
     # transitions that can happen as a result of that event.  For example,
     # 
     #   event :park, :stop do
-    #     transition :to => :parked, :from => :idling
+    #     transition :idling => :parked
     #   end
     #   
     #   event :first_gear do
-    #     transition :to => :first_gear, :from => :parked, :if => :seatbelt_on?
+    #     transition :parked => :first_gear, :if => :seatbelt_on?
     #   end
     # 
     # See StateMachine::Event#transition for more information on
@@ -664,7 +702,7 @@ module StateMachine
     #     
     #     state_machine do
     #       event :park do
-    #         transition :to => :parked, :from => Vehicle.safe_states
+    #         transition Vehicle.safe_states => :parked
     #       end
     #     end
     #   end 
@@ -675,15 +713,15 @@ module StateMachine
     #     state_machine do
     #       # The park, stop, and halt events will all share the given transitions
     #       event :park, :stop, :halt do
-    #         transition :to => :parked, :from => [:idling, :backing_up]
+    #         transition [:idling, :backing_up] => :parked
     #       end
     #       
     #       event :stop do
-    #         transition :to => :idling, :from => :first_gear
+    #         transition :first_gear => :idling
     #       end
     #       
     #       event :ignite do
-    #         transition :to => :idling, :from => :parked
+    #         transition :parked => :idling
     #       end
     #     end
     #   end
@@ -703,108 +741,71 @@ module StateMachine
       
       events.length == 1 ? events.first : events
     end
+    alias_method :on, :event
     
     # Creates a callback that will be invoked *before* a transition is
-    # performed so long as the given configuration options match the transition.
-    # Each part of the transition (event, to state, from state) must match in
-    # order for the callback to get invoked.
-    # 
-    # Configuration options:
-    # * <tt>:from</tt> - One or more states being transitioned from.  If none
-    #   are specified, then all states will match.
-    # * <tt>:to</tt> - One or more states being transitioned to.  If none are
-    #   specified, then all states will match.
-    # * <tt>:on</tt> - One or more events that fired the transition.  If none
-    #   are specified, then all events will match.
-    # * <tt>:except_from</tt> - One or more states *not* being transitioned from
-    # * <tt>:except_to</tt> - One more states *not* being transitioned to
-    # * <tt>:except_on</tt> - One or more events that *did not* fire the transition
-    # * <tt>:do</tt> - The callback to invoke when a transition matches. This
-    #   can be a method, proc or string.
-    # * <tt>:if</tt> - A method, proc or string to call to determine if the
-    #   callback should occur (e.g. :if => :allow_callbacks, or
-    #   :if => lambda {|user| user.signup_step > 2}). The method, proc or string
-    #   should return or evaluate to a true or false value. 
-    # * <tt>:unless</tt> - A method, proc or string to call to determine if the
-    #   callback should not occur (e.g. :unless => :skip_callbacks, or
-    #   :unless => lambda {|user| user.signup_step <= 2}). The method, proc or
-    #   string should return or evaluate to a true or false value. 
-    # 
-    # The +except+ group of options (+except_to+, +exception_from+, and
-    # +except_on+) acts as the +unless+ equivalent of their counterparts (+to+,
-    # +from+, and +on+, respectively)
+    # performed so long as the given requirements match the transition.
     # 
     # == The callback
     # 
-    # When defining additional configuration options, callbacks must be defined
-    # in either the :do option or as a block.  For example,
+    # Callbacks must be defined as either the only argument, in the :do option,
+    # or as a block.  For example,
     # 
     #   class Vehicle
     #     state_machine do
-    #       before_transition :to => :parked, :do => :set_alarm
-    #       before_transition :to => :parked do |vehicle, transition|
+    #       before_transition :set_alarm
+    #       before_transition all => :parked :do => :set_alarm
+    #       before_transition all => :parked do |vehicle, transition|
     #         vehicle.set_alarm
     #       end
     #       ...
     #     end
     #   end
     # 
-    # === Accessing the transition
+    # == State requirements
     # 
-    # In addition to passing the object being transitioned, the actual
-    # transition describing the context (e.g. event, from, to) can be accessed
-    # as well.  This additional argument is only passed if the callback allows
-    # for it.
+    # Callbacks can require that the machine be transitioning from and to
+    # specific states.  These requirements use a Hash syntax to map beginning
+    # states to ending states.  For example,
     # 
-    # For example,
+    #   before_transition :parked => :idling, :idling => :first_gear, :do => :set_alarm
     # 
-    #   class Vehicle
-    #     # Only specifies one parameter (the object being transitioned)
-    #     before_transition :to => :parked, :do => lambda {|vehicle| vehicle.set_alarm}
-    #     
-    #     # Specifies 2 parameters (object being transitioned and actual transition)
-    #     before_transition :to => :parked, :do => lambda {|vehicle, transition| vehicle.set_alarm(transition)}
-    #   end
+    # In this case, the +set_alarm+ callback will only be called if the machine
+    # is transitioning from +parked+ to +idling+ or from +idling+ to +parked+.
     # 
-    # *Note* that the object in the callback will only be passed in as an
-    # argument if callbacks are configured to *not* be bound to the object
-    # involved.  This is the default and may change on a per-integration basis.
+    # To help define state requirements, a set of helpers are available for
+    # slightly more complex matching:
+    # * <tt>all</tt> - Matches every state/event in the machine
+    # * <tt>all - [:parked, :idling, ...]</tt> - Matches every state/event except those specified
+    # * <tt>any</tt> - An alias for +all+ (matches every state/event in the machine)
+    # * <tt>same</tt> - Matches the same state being transitioned from
     # 
-    # See StateMachine::Transition for more information about the
-    # attributes available on the transition.
+    # See StateMachine::MatcherHelpers for more information.
     # 
-    # == Examples
+    # Examples:
     # 
-    # Below is an example of a class with one state machine and various types
-    # of +before+ transitions defined for it:
+    #   before_transition :parked => [:idling, :first_gear], :do => ...     # Matches from parked to idling or first_gear
+    #   before_transition all - [:parked, :idling] => :idling, :do => ...   # Matches from every state except parked and idling to idling
+    #   before_transition all => :parked, :do => ...                        # Matches all states to parked
+    #   before_transition any => same, :do => ...                           # Matches every loopback
     # 
-    #   class Vehicle
-    #     state_machine do
-    #       # Before all transitions
-    #       before_transition :update_dashboard
-    #       
-    #       # Before specific transition:
-    #       before_transition :to => :parked, :from => [:first_gear, :idling], :on => :park, :do => :take_off_seatbelt
-    #       
-    #       # With conditional callback:
-    #       before_transition :to => :parked, :do => :take_off_seatbelt, :if => :seatbelt_on?
-    #       
-    #       # Using :except counterparts:
-    #       before_transition :except_to => :stalled, :except_from => :stalled, :except_on => :crash, :do => :update_dashboard
-    #       ...
-    #     end
-    #   end
+    # == Event requirements
     # 
-    # As can be seen, any number of transitions can be created using various
-    # combinations of configuration options.
-    def before_transition(options = {}, &block)
-      add_callback(:before, options.is_a?(Hash) ? options : {:do => options}, &block)
-    end
-    
-    # Creates a callback that will be invoked *after* a transition is
-    # performed, so long as the given configuration options match the transition.
-    # Each part of the transition (event, to state, from state) must match
-    # in order for the callback to get invoked.
+    # In addition to state requirements, an event requirement can be defined so
+    # that the callback is only invoked on specific events using the +on+
+    # option.  This can also use the same matcher helpers as the state
+    # requirements.
+    # 
+    # Examples:
+    # 
+    #   before_transition :on => :ignite, :do => ...                        # Matches only on ignite
+    #   before_transition :on => all - :ignite, :do => ...                  # Matches on every event except ignite
+    #   before_transition :parked => :idling, :on => :ignite, :do => ...    # Matches from parked to idling on ignite
+    # 
+    # == Verbose Requirements
+    # 
+    # Requirements can also be defined using verbose options rather than the
+    # implicit Hash syntax and helper methods described above.
     # 
     # Configuration options:
     # * <tt>:from</tt> - One or more states being transitioned from.  If none
@@ -816,8 +817,18 @@ module StateMachine
     # * <tt>:except_from</tt> - One or more states *not* being transitioned from
     # * <tt>:except_to</tt> - One more states *not* being transitioned to
     # * <tt>:except_on</tt> - One or more events that *did not* fire the transition
-    # * <tt>:do</tt> - The callback to invoke when a transition matches. This
-    #   can be a method, proc or string.
+    # 
+    # Examples:
+    # 
+    #   before_transition :from => :ignite, :to => :idling, :on => :park, :do => ...
+    #   before_transition :except_from => :ignite, :except_to => :idling, :except_on => :park, :do => ...
+    # 
+    # == Conditions
+    # 
+    # In addition to the state/event requirements, a condition can also be
+    # defined to help determine whether the callback should be invoked.
+    # 
+    # Configuration options:
     # * <tt>:if</tt> - A method, proc or string to call to determine if the
     #   callback should occur (e.g. :if => :allow_callbacks, or
     #   :if => lambda {|user| user.signup_step > 2}). The method, proc or string
@@ -827,40 +838,26 @@ module StateMachine
     #   :unless => lambda {|user| user.signup_step <= 2}). The method, proc or
     #   string should return or evaluate to a true or false value. 
     # 
-    # The +except+ group of options (+except_to+, +exception_from+, and
-    # +except_on+) acts as the +unless+ equivalent of their counterparts (+to+,
-    # +from+, and +on+, respectively)
+    # Examples:
     # 
-    # == The callback
-    # 
-    # When defining additional configuration options, callbacks must be defined
-    # in either the :do option or as a block.  For example,
+    #   before_transition :parked => :idling, :if => :moving?
+    #   before_transition :on => :ignite, :unless => :seatbelt_on?
     # 
-    #   class Vehicle
-    #     state_machine do
-    #       after_transition :to => :parked, :do => :set_alarm
-    #       after_transition :to => :parked do |vehicle, transition, result|
-    #         vehicle.set_alarm
-    #       end
-    #       ...
-    #     end
-    #   end
-    # 
-    # === Accessing the transition / result
+    # === Accessing the transition
     # 
     # In addition to passing the object being transitioned, the actual
-    # transition describing the context (e.g. event, from, to) and the result
-    # from calling the object's action can be optionally passed as well.  These
-    # additional arguments are only passed if the callback allows for it.
+    # transition describing the context (e.g. event, from, to) can be accessed
+    # as well.  This additional argument is only passed if the callback allows
+    # for it.
     # 
     # For example,
     # 
     #   class Vehicle
     #     # Only specifies one parameter (the object being transitioned)
-    #     after_transition :to => :parked, :do => lambda {|vehicle| vehicle.set_alarm}
+    #     before_transition :to => :parked, :do => lambda {|vehicle| vehicle.set_alarm}
     #     
-    #     # Specifies 3 parameters (object being transitioned, transition, and action result)
-    #     after_transition :to => :parked, :do => lambda {|vehicle, transition, result| vehicle.set_alarm(transition) if result}
+    #     # Specifies 2 parameters (object being transitioned and actual transition)
+    #     before_transition :to => :parked, :do => lambda {|vehicle, transition| vehicle.set_alarm(transition)}
     #   end
     # 
     # *Note* that the object in the callback will only be passed in as an
@@ -872,28 +869,37 @@ module StateMachine
     # 
     # == Examples
     # 
-    # Below is an example of a model with one state machine and various types
-    # of +after+ transitions defined for it:
+    # Below is an example of a class with one state machine and various types
+    # of +before+ transitions defined for it:
     # 
     #   class Vehicle
     #     state_machine do
-    #       # After all transitions
-    #       after_transition :update_dashboard
+    #       # Before all transitions
+    #       before_transition :update_dashboard
     #       
-    #       # After specific transition:
-    #       after_transition :to => :parked, :from => [:first_gear, :idling], :on => :park, :do => :take_off_seatbelt
+    #       # Before specific transition:
+    #       before_transition [:first_gear, :idling] => :parked, :on => :park, :do => :take_off_seatbelt
     #       
     #       # With conditional callback:
-    #       after_transition :to => :parked, :do => :take_off_seatbelt, :if => :seatbelt_on?
+    #       before_transition :to => :parked, :do => :take_off_seatbelt, :if => :seatbelt_on?
     #       
-    #       # Using :except counterparts:
-    #       after_transition :except_to => :stalled, :except_from => :stalled, :except_on => :crash, :do => :update_dashboard
+    #       # Using helpers:
+    #       before_transition all - :stalled => same, :on => any - :crash, :do => :update_dashboard
     #       ...
     #     end
     #   end
     # 
     # As can be seen, any number of transitions can be created using various
     # combinations of configuration options.
+    def before_transition(options = {}, &block)
+      add_callback(:before, options.is_a?(Hash) ? options : {:do => options}, &block)
+    end
+    
+    # Creates a callback that will be invoked *after* a transition is
+    # performed so long as the given requirements match the transition.
+    # 
+    # See +before_transition+ for a description of the possible configurations
+    # for defining callbacks.
     def after_transition(options = {}, &block)
       add_callback(:after, options.is_a?(Hash) ? options : {:do => options}, &block)
     end