state_machine 0.6.3 → 0.7.0

data/examples/rails-rest/view_new.html.erb

@@ -0,0 +1,14 @@
+<h1>New User</h1>
+
+<% form_for @user do |f| %>
+  <%= f.error_messages %>
+  
+  <p>
+    <%= f.label :name %><br />
+    <%= f.text_field :name %>
+  </p>
+  
+  <p><%= f.submit 'Create' %></p>
+<% end %>
+
+<%= link_to 'Back', users_path %>

data/examples/rails-rest/view_show.html.erb

@@ -0,0 +1,17 @@
+<p>
+  <b>Name:</b>
+  <%=h @user.name %>
+</p>
+
+<p>
+  <b>State:</b>
+  <%=h @user.state %>
+</p>
+
+<p>
+  <b>Access State:</b>
+  <%=h @user.access_state %>
+</p>
+
+<%= link_to 'Edit', edit_user_path(@user) %> |
+<%= link_to 'Back', users_path %>

data/lib/state_machine/assertions.rb

@@ -1,6 +1,6 @@
 module StateMachine
-  # Provides a set of helper methods for making assertions about the content of
-  # various objects
+  # Provides a set of helper methods for making assertions about the content
+  # of various objects
   module Assertions
     # Validates that all keys in the given hash *only* includes the specified
     # valid keys.  If any invalid keys are found, an ArgumentError will be

data/lib/state_machine/callback.rb

@@ -2,14 +2,14 @@ require 'state_machine/guard'
 require 'state_machine/eval_helpers'
 
 module StateMachine
-  # Callbacks represent hooks into objects that allow you to trigger logic
+  # Callbacks represent hooks into objects that allow logic to be triggered
   # before or after a specific transition occurs.
   class Callback
     include EvalHelpers
     
     class << self
-      # Determines whether to automatically bind the callback to the object being
-      # transitioned.  This only applies to callbacks that are defined as
+      # Determines whether to automatically bind the callback to the object
+      # being transitioned.  This only applies to callbacks that are defined as
       # lambda blocks (or Procs).  Some integrations, such as DataMapper, handle
       # callbacks by executing them bound to the object involved, while other
       # integrations, such as ActiveRecord, pass the object as an argument to
@@ -53,6 +53,13 @@ module StateMachine
       #     end
       #   end
       attr_accessor :bind_to_object
+      
+      # The application-wide terminator to use for callbacks when not
+      # explicitly defined.  Terminators determine whether to cancel a
+      # callback chain based on the return value of the callback.
+      # 
+      # See StateMachine::Callback#terminator for more information.
+      attr_accessor :terminator
     end
     
     # An optional block for determining whether to cancel the callback chain
@@ -114,13 +121,12 @@ module StateMachine
         options = {}
       end
       
-      # The actual method to invoke must be defined
       raise ArgumentError, ':do callback must be specified' unless @method
       
-      # Proxy the method so that it's bound to the object.  Note that this only
-      # applies to lambda callbacks.  All other callbacks ignore this option.
-      bind_to_object = !options.include?(:bind_to_object) && self.class.bind_to_object || options.delete(:bind_to_object)
-      @method = bound_method(@method) if @method.is_a?(Proc) && bind_to_object
+      options = {:bind_to_object => self.class.bind_to_object, :terminator => self.class.terminator}.merge(options)
+      
+      # Proxy lambda blocks so that they're bound to the object
+      @method = bound_method(@method) if options.delete(:bind_to_object) && @method.is_a?(Proc)
       @terminator = options.delete(:terminator)
       
       @guard = Guard.new(options)

data/lib/state_machine/condition_proxy.rb

@@ -56,7 +56,7 @@ module StateMachine
       @condition = condition
     end
     
-    # Hooks in condition merging to methods that don't exist in this module
+    # 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)
@@ -77,8 +77,8 @@ module StateMachine
       # 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
+        # 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) &&

data/lib/state_machine/event.rb

@@ -4,6 +4,10 @@ require 'state_machine/assertions'
 require 'state_machine/matcher_helpers'
 
 module StateMachine
+  # An invalid event was specified
+  class InvalidEvent < StandardError
+  end
+  
   # An event defines an action that transitions an attribute from one state to
   # another.  The state that an attribute is transitioned to depends on the
   # guards configured for the event.
@@ -14,9 +18,12 @@ module StateMachine
     # The state machine for which this event is defined
     attr_accessor :machine
     
-    # The name of the action that fires the event
+    # The name of the event
     attr_reader :name
     
+    # The fully-qualified name of the event, scoped by the machine's namespace 
+    attr_reader :qualified_name
+    
     # The list of guards that determine what state this event transitions
     # objects to when fired
     attr_reader :guards
@@ -29,6 +36,7 @@ module StateMachine
     def initialize(machine, name) #:nodoc:
       @machine = machine
       @name = name
+      @qualified_name = machine.namespace ? :"#{name}_#{machine.namespace}" : name
       @guards = []
       @known_states = []
       
@@ -54,8 +62,8 @@ module StateMachine
     #   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+.
+    # 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:
@@ -149,13 +157,13 @@ module StateMachine
     # 
     # If the event can't be fired, then this will return false, otherwise true.
     def can_fire?(object)
-      !next_transition(object).nil?
+      !transition_for(object).nil?
     end
     
     # Finds and builds the next transition that can be performed on the given
     # object.  If no transitions can be made, then this will return nil.
-    def next_transition(object)
-      from = machine.state_for(object).name
+    def transition_for(object)
+      from = machine.states.match(object).name
       
       guards.each do |guard|
         if match = guard.match(object, :from => from)
@@ -179,21 +187,14 @@ module StateMachine
     def fire(object, *args)
       machine.reset(object)
       
-      if transition = next_transition(object)
+      if transition = transition_for(object)
         transition.perform(*args)
       else
-        machine.invalidate(object, self)
+        machine.invalidate(object, machine.attribute, :invalid_transition, [[:event, name]])
         false
       end
     end
     
-    # Attempts to perform the next available transition on the given object.
-    # If no transitions can be made, then a StateMachine::InvalidTransition
-    # exception will be raised, otherwise true will be returned.
-    def fire!(object, *args)
-      fire(object, *args) || raise(StateMachine::InvalidTransition, "Cannot transition #{machine.attribute} via :#{name} from #{machine.state_for(object).name.inspect}")
-    end
-    
     # Draws a representation of this event on the given graph.  This will
     # create 1 or more edges on the graph for each guard (i.e. transition)
     # configured.
@@ -225,9 +226,6 @@ module StateMachine
       # Add the various instance methods that can transition the object using
       # the current event
       def add_actions
-        qualified_name = name = self.name
-        qualified_name = "#{name}_#{machine.namespace}" if machine.namespace
-        
         # Checks whether the event can be fired on the current object
         machine.define_instance_method("can_#{qualified_name}?") do |machine, object|
           machine.event(name).can_fire?(object)
@@ -235,8 +233,8 @@ module StateMachine
         
         # Gets the next transition that would be performed if the event were
         # fired now
-        machine.define_instance_method("next_#{qualified_name}_transition") do |machine, object|
-          machine.event(name).next_transition(object)
+        machine.define_instance_method("#{qualified_name}_transition") do |machine, object|
+          machine.event(name).transition_for(object)
         end
         
         # Fires the event
@@ -246,7 +244,7 @@ module StateMachine
         
         # Fires the event, raising an exception if it fails
         machine.define_instance_method("#{qualified_name}!") do |machine, object, *args|
-          machine.event(name).fire!(object, *args)
+          object.send(qualified_name, *args) || raise(StateMachine::InvalidTransition, "Cannot transition #{machine.attribute} via :#{name} from #{machine.states.match(object).name.inspect}")
         end
       end
   end

data/lib/state_machine/event_collection.rb

@@ -0,0 +1,114 @@
+module StateMachine
+  # Represents a collection of events in a state machine
+  class EventCollection < NodeCollection
+    def initialize(machine) #:nodoc:
+      super(machine, :index => [:name, :qualified_name])
+    end
+    
+    # Gets the list of events that can be fired on the given object.
+    # 
+    # == Examples
+    # 
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #       
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #     end
+    #   end
+    #   
+    #   events = Vehicle.state_machine(:state).events
+    #   
+    #   vehicle = Vehicle.new               # => #<Vehicle:0xb7c464b0 @state="parked">
+    #   events.valid_for(vehicle)           # => [#<StateMachine::Event name=:ignite transitions=[:parked => :idling]>]
+    #   
+    #   vehicle.state = 'idling'
+    #   events.valid_for(vehicle)           # => [#<StateMachine::Event name=:park transitions=[:idling => :parked]>]
+    def valid_for(object)
+      select {|event| event.can_fire?(object)}
+    end
+    
+    # Gets the list of transitions that can be run on the given object.
+    # 
+    # == Examples
+    # 
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #       
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #     end
+    #   end
+    #   
+    #   events = Vehicle.state_machine.events
+    #   
+    #   vehicle = Vehicle.new                   # => #<Vehicle:0xb7c464b0 @state="parked">
+    #   events.transitions_for(vehicle)         # => [#<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>]
+    #   
+    #   vehicle.state = 'idling'
+    #   events.transitions_for(vehicle)         # => [#<StateMachine::Transition attribute=:state event=:park from="idling" from_name=:idling to="parked" to_name=:parked>]
+    def transitions_for(object)
+      map {|event| event.transition_for(object)}.compact
+    end
+    
+    # Gets the transition that should be performed for the event stored in the
+    # given object's event attribute.  This also takes an additional parameter
+    # for automatically invalidating the object if the event or transition
+    # are invalid.  By default, this is turned off.
+    # 
+    # *Note* that if a transition has already been generated for the event,
+    # then that transition will be used.
+    # 
+    # == Examples
+    # 
+    #   class Vehicle < ActiveRecord::Base
+    #     state_machine :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.new                       # => #<Vehicle id: nil, state: "parked">
+    #   events = Vehicle.state_machine.events
+    #   
+    #   vehicle.state_event = nil
+    #   events.attribute_transition_for(vehicle)    # => nil # Event isn't defined
+    #   
+    #   vehicle.state_event = 'invalid'
+    #   events.attribute_transition_for(vehicle)    # => false # Event is invalid
+    #   
+    #   vehicle.state_event = 'ignite'
+    #   events.attribute_transition_for(vehicle)    # => #<StateMachine::Transition attribute=:state event=:ignite from="parked" from_name=:parked to="idling" to_name=:idling>
+    def attribute_transition_for(object, invalidate = false)
+      return unless machine.action
+      
+      result = nil
+      attribute = machine.attribute
+      
+      if name = object.send("#{attribute}_event")
+        if event = self[name.to_sym, :qualified_name]
+          unless result = object.send("#{attribute}_event_transition") || event.transition_for(object)
+            # No valid transition: invalidate
+            machine.invalidate(object, "#{attribute}_event", :invalid_event, [[:state, machine.states.match(object).name]]) if invalidate
+            result = false
+          end
+        else
+          # Event is unknown: invalidate
+          machine.invalidate(object, "#{attribute}_event", :invalid) if invalidate
+          result = false
+        end
+      end
+      
+      result
+    end
+  end
+end

data/lib/state_machine/extensions.rb

@@ -1,19 +1,21 @@
+require 'state_machine/machine_collection'
+
 module StateMachine
   module ClassMethods
     def self.extended(base) #:nodoc:
       base.class_eval do
-        @state_machines = {}
+        @state_machines = MachineCollection.new
       end
     end
     
     # Gets the current list of state machines defined for this class.  This
     # class-level attribute acts like an inheritable attribute.  The attribute
-    # is available to each subclass, each subclass having a copy of its
-    # superclass's attribute.
+    # is available to each subclass, each having a copy of its superclass's
+    # attribute.
     # 
-    # The hash of state machines maps +attribute+ => +machine+, e.g.
+    # The hash of state machines maps <tt>:attribute</tt> => +machine+, e.g.
     # 
-    #   Vehicle.state_machines # => {:state => #<StateMachine::Machine:0xb6f6e4a4 ...>
+    #   Vehicle.state_machines # => {:state => #<StateMachine::Machine:0xb6f6e4a4 ...>}
     def state_machines
       @state_machines ||= superclass.state_machines.dup
     end
@@ -29,14 +31,128 @@ module StateMachine
       initialize_state_machines
     end
     
+    # Runs one or more events in parallel.  All events will run through the
+    # following steps:
+    # * Before callbacks
+    # * Persist state
+    # * Invoke action
+    # * After callbacks
+    # 
+    # For example, if two events (for state machines A and B) are run in
+    # parallel, the order in which steps are run is:
+    # * A - Before transition callbacks
+    # * B - Before transition callbacks
+    # * A - Persist new state
+    # * B - Persist new state
+    # * A - Invoke action
+    # * B - Invoke action (only if different than A's action)
+    # * A - After transition callbacks
+    # * B - After transition callbacks
+    # 
+    # *Note* that multiple events on the same state machine / attribute cannot
+    # be run in parallel.  If this is attempted, an ArgumentError will be
+    # raised.
+    # 
+    # == Halting callbacks
+    # 
+    # When running multiple events in parallel, special consideration should
+    # be taken with regard to how halting within callbacks affects the flow.
+    # 
+    # For *before* callbacks, any <tt>:halt</tt> error that's thrown will
+    # immediately cancel the perform for all transitions.  As a result, it's
+    # possible for one event's transition to affect the continuation of
+    # another.
+    # 
+    # On the other hand, any <tt>:halt</tt> error that's thrown within an
+    # *after* callback with only affect that event's transition.  Other
+    # transitions will continue to run their own callbacks.
+    # 
+    # == Example
+    # 
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #       
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #     end
+    #     
+    #     state_machine :alarm_state, :namespace => 'alarm', :initial => :on do
+    #       event :enable do
+    #         transition all => :active
+    #       end
+    #       
+    #       event :disable do
+    #         transition all => :off
+    #       end
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.new                         # => #<Vehicle:0xb7c02850 @state="parked", @alarm_state="active">
+    #   vehicle.state                                 # => "parked"
+    #   vehicle.alarm_state                           # => "active"
+    #   
+    #   vehicle.fire_events(:ignite, :disable_alarm)  # => true
+    #   vehicle.state                                 # => "idling"
+    #   vehicle.alarm_state                           # => "off"
+    #   
+    #   # If any event fails, the entire event chain fails
+    #   vehicle.fire_events(:ignite, :enable_alarm)   # => false
+    #   vehicle.state                                 # => "idling"
+    #   vehicle.alarm_state                           # => "off"
+    #   
+    #   # Exception raised on invalid event
+    #   vehicle.fire_events(:park, :invalid)          # => StateMachine::InvalidEvent: :invalid is an unknown event
+    #   vehicle.state                                 # => "idling"
+    #   vehicle.alarm_state                           # => "off"
+    def fire_events(*events)
+      self.class.state_machines.fire_events(self, *events)
+    end
+    
+    # Run one or more events in parallel.  If any event fails to run, then
+    # a StateMachine::InvalidTransition exception will be raised.
+    # 
+    # See StateMachine::InstanceMethods#fire_events for more information.
+    # 
+    # == Example
+    # 
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #       
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #     end
+    #     
+    #     state_machine :alarm_state, :namespace => 'alarm', :initial => :active do
+    #       event :enable do
+    #         transition all => :active
+    #       end
+    #       
+    #       event :disable do
+    #         transition all => :off
+    #       end
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.new                         # => #<Vehicle:0xb7c02850 @state="parked", @alarm_state="active">
+    #   vehicle.fire_events(:ignite, :disable_alarm)  # => true
+    #   
+    #   vehicle.fire_events!(:ignite, :disable_alarm) # => StateMachine::InvalidTranstion: Cannot run events in parallel: ignite, disable_alarm
+    def fire_events!(*events)
+      run_action = [true, false].include?(events.last) ? events.pop : true
+      fire_events(*(events + [run_action])) || raise(StateMachine::InvalidTransition, "Cannot run events in parallel: #{events * ', '}")
+    end
+    
     protected
       def initialize_state_machines #:nodoc:
-        self.class.state_machines.each do |attribute, machine|
-          # Set the initial value of the machine's attribute unless it already
-          # exists (which must mean the defaults are being skipped)
-          value = send(attribute)
-          send("#{attribute}=", machine.initial_state(self).value) if value.nil? || value.respond_to?(:empty?) && value.empty?
-        end
+        self.class.state_machines.initialize_states(self)
       end
   end
 end