verborghs-state_machine 0.9.4

data/lib/state_machine/transition_collection.rb

@@ -0,0 +1,244 @@
+module StateMachine
+  # Represents a collection of transitions in a state machine
+  class TransitionCollection < Array
+    include Assertions
+    
+    # Whether to skip running the action for each transition's machine
+    attr_reader :skip_actions
+    
+    # Whether to skip running the after callbacks
+    attr_reader :skip_after
+    
+    # Whether transitions should wrapped around a transaction block
+    attr_reader :use_transaction
+    
+    # Creates a new collection of transitions that can be run in parallel.  Each
+    # transition *must* be for a different attribute.
+    # 
+    # Configuration options:
+    # * <tt>:actions</tt> - Whether to run the action configured for each transition
+    # * <tt>:after</tt> - Whether to run after callbacks
+    # * <tt>:transaction</tt> - Whether to wrap transitions within a transaction
+    def initialize(transitions = [], options = {})
+      super(transitions)
+      
+      # Determine the validity of the transitions as a whole
+      @valid = all?
+      reject! {|transition| !transition}
+      
+      attributes = map {|transition| transition.attribute}.uniq
+      raise ArgumentError, 'Cannot perform multiple transitions in parallel for the same state machine attribute' if attributes.length != length
+      
+      assert_valid_keys(options, :actions, :after, :transaction)
+      options = {:actions => true, :after => true, :transaction => true}.merge(options)
+      @skip_actions = !options[:actions]
+      @skip_after = !options[:after]
+      @use_transaction = options[:transaction]
+    end
+    
+    # Runs each of the collection's transitions in parallel.
+    # 
+    # All transitions will run through the following steps:
+    # 1. Before callbacks
+    # 2. Persist state
+    # 3. Invoke action
+    # 4. After callbacks (if configured)
+    # 5. Rollback (if action is unsuccessful)
+    # 
+    # If a block is passed to this method, that block will be called instead
+    # of invoking each transition's action.
+    def perform(&block)
+      reset
+      
+      if valid?
+        if use_event_attributes? && !block_given?
+          each do |transition|
+            transition.transient = true
+            transition.machine.write(object, :event_transition, transition)
+          end
+          
+          run_actions
+        else
+          within_transaction do
+            catch(:halt) { run_callbacks(&block) }
+            rollback unless success?
+          end
+        end
+      end
+      
+      if actions.length == 1 && results.include?(actions.first)
+        results[actions.first]
+      else
+        success?
+      end
+    end
+    
+    private
+      attr_reader :results #:nodoc:
+      
+      # Is this a valid set of transitions?  If the collection was creating with
+      # any +false+ values for transitions, then the the collection will be
+      # marked as invalid.
+      def valid?
+        @valid
+      end
+      
+      # Did each transition perform successfully?  This will only be true if the
+      # following requirements are met:
+      # * No +before+ callbacks halt
+      # * All actions run successfully (always true if skipping actions)
+      def success?
+        @success
+      end
+      
+      # Gets the object being transitioned
+      def object
+        first.object
+      end
+      
+      # Gets the list of actions to run.  If configured to skip actions, then
+      # this will return an empty collection.
+      def actions
+        empty? ? [nil] : map {|transition| transition.action}.uniq
+      end
+      
+      # Determines whether an event attribute be used to trigger the transitions
+      # in this collection or whether the transitions be run directly *outside*
+      # of the action.
+      def use_event_attributes?
+        !skip_actions && !skip_after && actions.all? && actions.length == 1 && first.machine.action_helper_defined?
+      end
+      
+      # Resets any information tracked from previous attempts to perform the
+      # collection
+      def reset
+        @results = {}
+        @success = false
+      end
+      
+      # Runs each transition's callbacks recursively.  Once all before callbacks
+      # have been executed, the transitions will then be persisted and the
+      # configured actions will be run.
+      # 
+      # If any transition fails to run its callbacks, :halt will be thrown.
+      def run_callbacks(index = 0, &block)
+        if transition = self[index]
+          throw :halt unless transition.run_callbacks(:after => !skip_after) do
+            run_callbacks(index + 1, &block)
+            {:result => results[transition.action], :success => success?}
+          end
+        else
+          persist
+          run_actions(&block)
+        end
+      end
+      
+      # Transitions the current value of the object's states to those specified by
+      # each transition
+      def persist
+        each {|transition| transition.persist}
+      end
+      
+      # Runs the actions for each transition.  If a block is given method, then it
+      # will be called instead of invoking each transition's action.
+      # 
+      # The results of the actions will be used to determine #success?.
+      def run_actions
+        catch_exceptions do
+          @success = if block_given?
+            result = yield
+            actions.each {|action| results[action] = result}
+            !!result
+          else
+            actions.compact.each {|action| !skip_actions && results[action] = object.send(action)}
+            results.values.all?
+          end
+        end
+      end
+      
+      # Rolls back changes made to the object's states via each transition
+      def rollback
+        each {|transition| transition.rollback}
+      end
+      
+      # Wraps the given block with a rescue handler so that any exceptions that
+      # occur will automatically result in the transition rolling back any changes
+      # that were made to the object involved.
+      def catch_exceptions
+        begin
+          yield
+        rescue Exception
+          rollback
+          raise
+        end
+      end
+      
+      # Runs a block within a transaction for the object being transitioned.  If
+      # transactions are disabled, then this is a no-op.
+      def within_transaction
+        if use_transaction && !empty?
+          first.within_transaction do
+            yield
+            success?
+          end
+        else
+          yield
+        end
+      end
+  end
+  
+  # Represents a collection of transitions that were generated from attribute-
+  # based events
+  class AttributeTransitionCollection < TransitionCollection
+    def initialize(transitions = [], options = {}) #:nodoc:
+      super(transitions, {:transaction => false, :actions => false}.merge(options))
+    end
+    
+    private
+      # Hooks into running transition callbacks so that event / event transition
+      # attributes can be properly updated
+      def run_callbacks(index = 0)
+        if index == 0
+          # Clears any traces of the event attribute to prevent it from being
+          # evaluated multiple times if actions are nested
+          each do |transition|
+            transition.machine.write(object, :event, nil)
+            transition.machine.write(object, :event_transition, nil)
+          end
+          
+          # Rollback only if exceptions occur during before callbacks
+          begin
+            super
+          rescue Exception
+            rollback unless @before_run
+            raise
+          end
+          
+          # Persists transitions on the object if partial transition was successful.
+          # This allows us to reference them later to complete the transition with
+          # after callbacks.          
+          each {|transition| transition.machine.write(object, :event_transition, transition)} if skip_after && success?
+        else
+          super
+        end
+      end
+      
+      # Tracks that before callbacks have now completed
+      def persist
+        @before_run = true
+        super
+      end
+      
+      # Resets callback tracking
+      def reset
+        super
+        @before_run = false
+      end
+      
+      # Resets the event attribute so it can be re-evaluated if attempted again
+      def rollback
+        super
+        each {|transition| transition.machine.write(object, :event, transition.event) unless transition.transient?}
+      end
+  end
+end

data/lib/state_machine.rb

@@ -0,0 +1,421 @@
+require 'state_machine/machine'
+
+# A state machine is a model of behavior composed of states, events, and
+# transitions.  This helper adds support for defining this type of
+# functionality on any Ruby class.
+module StateMachine
+  module MacroMethods
+    # Creates a new state machine with the given name.  The default name, if not
+    # specified, is <tt>:state</tt>.
+    # 
+    # Configuration options:
+    # * <tt>:attribute</tt> - The name of the attribute to store the state value
+    #   in.  By default, this is the same as the name of the machine.
+    # * <tt>:initial</tt> - The initial state of the attribute. This can be a
+    #   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>:action</tt> - The instance method to invoke when an object
+    #   transitions. Default is nil unless otherwise specified by the
+    #   configured integration.
+    # * <tt>:namespace</tt> - The name to use for namespacing all generated
+    #   state / event instance methods (e.g. "heater" would generate
+    #   :turn_on_heater and :turn_off_heater for the :turn_on/:turn_off events).
+    #   Default is nil.
+    # * <tt>:integration</tt> - The name of the integration to use for adding
+    #   library-specific behavior to the machine.  Built-in integrations
+    #   include :active_model, :active_record, :data_mapper, :mongo_mapper, and
+    #   :sequel.  By default, this is determined automatically.
+    # 
+    # Configuration options relevant to ORM integrations:
+    # * <tt>:plural</tt> - The pluralized name of the attribute.  By default,
+    #   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>:messages</tt> - The error messages to use when invalidating
+    #   objects due to failed transitions.  Messages include:
+    #   * <tt>:invalid</tt>
+    #   * <tt>:invalid_event</tt>
+    #   * <tt>:invalid_transition</tt>
+    # * <tt>:use_transactions</tt> - Whether transactions should be used when
+    #   firing events.  Default is true unless otherwise specified by the
+    #   configured integration.
+    # 
+    # This also expects a block which will be used to actually configure the
+    # states, events and transitions for the state machine.  *Note* that this
+    # block will be executed within the context of the state machine.  As a
+    # result, you will not be able to access any class methods unless you refer
+    # to them directly (i.e. specifying the class name).
+    # 
+    # For examples on the types of state machine configurations and blocks, see
+    # the section below.
+    # 
+    # == Examples
+    # 
+    # With the default name/attribute and no configuration:
+    # 
+    #   class Vehicle
+    #     state_machine do
+    #       event :park do
+    #         ...
+    #       end
+    #     end
+    #   end
+    # 
+    # The above example will define a state machine named "state" that will
+    # store the value in the +state+ attribute.  Every vehicle will start
+    # without an initial state.
+    # 
+    # With a custom name / attribute:
+    # 
+    #   class Vehicle
+    #     state_machine :status, :attribute => :status_value do
+    #       ...
+    #     end
+    #   end
+    # 
+    # With a static initial state:
+    # 
+    #   class Vehicle
+    #     state_machine :status, :initial => :parked do
+    #       ...
+    #     end
+    #   end
+    # 
+    # With a dynamic initial state:
+    # 
+    #   class Vehicle
+    #     state_machine :status, :initial => lambda {|vehicle| vehicle.speed == 0 ? :parked : :idling} do
+    #       ...
+    #     end
+    #   end
+    # 
+    # == Class Methods
+    # 
+    # The following class methods will be automatically generated by the
+    # state machine based on the *name* of the machine.  Any existing methods
+    # will not be overwritten.
+    # * <tt>human_state_name(state)</tt> - Gets the humanized value for the
+    #   given state.  This may be generated by internationalization libraries if
+    #   supported by the integration.
+    # * <tt>human_state_event_name(event)</tt> - Gets the humanized value for
+    #   the given event.  This may be generated by internationalization
+    #   libraries if supported by the integration.
+    # 
+    # For example,
+    # 
+    #   class Vehicle
+    #     state_machine :state, :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #       
+    #       event :shift_up do
+    #         transition :idling => :first_gear
+    #       end
+    #     end
+    #   end
+    #   
+    #   Vehicle.human_state_name(:parked)         # => "parked"
+    #   Vehicle.human_state_name(:first_gear)     # => "first gear"
+    #   Vehicle.human_state_event_name(:park)     # => "park"
+    #   Vehicle.human_state_event_name(:shift_up) # => "shift up"
+    # 
+    # == Instance Methods
+    # 
+    # The following instance methods will be automatically generated by the
+    # state machine based on the *name* of the machine.  Any existing methods
+    # will not be overwritten.
+    # * <tt>state</tt> - Gets the current value for the attribute
+    # * <tt>state=(value)</tt> - Sets the current value for the attribute
+    # * <tt>state?(name)</tt> - Checks the given state name against the current
+    #   state.  If the name is not a known state, then an ArgumentError is raised.
+    # * <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.
+    # 
+    # For example,
+    # 
+    #   class Vehicle
+    #     state_machine :state, :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #       
+    #       event :park do
+    #         transition :idling => :parked
+    #       end
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.new
+    #   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
+    #   
+    #   # Getting current event / transition availability
+    #   vehicle.state_events              # => [:park]
+    #   vehicle.park                      # => true
+    #   vehicle.state_events              # => [:ignite]
+    #   
+    #   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>]
+    # 
+    # == Attribute initialization
+    # 
+    # For most classes, the initial values for state machine attributes are
+    # automatically assigned when a new object is created.  However, this
+    # behavior will *not* work if the class defines an +initialize+ method
+    # without properly calling +super+.
+    # 
+    # For example,
+    # 
+    #   class Vehicle
+    #     state_machine :state, :initial => :parked do
+    #       ...
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c8dbf8 @state="parked">
+    #   vehicle.state           # => "parked"
+    # 
+    # In the above example, no +initialize+ method is defined.  As a result,
+    # the default behavior of initializing the state machine attributes is used.
+    # 
+    # In the following example, a custom +initialize+ method is defined:
+    # 
+    #   class Vehicle
+    #     state_machine :state, :initial => :parked do
+    #       ...
+    #     end
+    #     
+    #     def initialize
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c77678>
+    #   vehicle.state           # => nil
+    # 
+    # Since the +initialize+ method is defined, the state machine attributes
+    # never get initialized.  In order to ensure that all initialization hooks
+    # are called, the custom method *must* call +super+ without any arguments
+    # like so:
+    # 
+    #   class Vehicle
+    #     state_machine :state, :initial => :parked do
+    #       ...
+    #     end
+    #     
+    #     def initialize(attributes = {})
+    #       ...
+    #       super()
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c8dbf8 @state="parked">
+    #   vehicle.state           # => "parked"
+    # 
+    # Because of the way the inclusion of modules works in Ruby, calling
+    # <tt>super()</tt> will not only call the superclass's +initialize+, but
+    # also +initialize+ on all included modules.  This allows the original state
+    # machine hook to get called properly.
+    # 
+    # If you want to avoid calling the superclass's constructor, but still want
+    # to initialize the state machine attributes:
+    # 
+    #   class Vehicle
+    #     state_machine :state, :initial => :parked do
+    #       ...
+    #     end
+    #     
+    #     def initialize(attributes = {})
+    #       ...
+    #       initialize_state_machines
+    #     end
+    #   end
+    #   
+    #   vehicle = Vehicle.new   # => #<Vehicle:0xb7c8dbf8 @state="parked">
+    #   vehicle.state           # => "parked"
+    # 
+    # == States
+    # 
+    # All of the valid states for the machine are automatically tracked based
+    # on the events, transitions, and callbacks defined for the machine.  If
+    # there are additional states that are never referenced, these should be
+    # explicitly added using the StateMachine::Machine#state or
+    # StateMachine::Machine#other_states helpers.
+    # 
+    # When a new state is defined, a predicate method for that state is
+    # generated on the class.  For example,
+    # 
+    #   class Vehicle
+    #     state_machine :initial => :parked do
+    #       event :ignite do
+    #         transition all => :idling
+    #       end
+    #     end
+    #   end
+    # 
+    # ...will generate the following instance methods (assuming they're not
+    # already defined in the class):
+    # * <tt>parked?</tt>
+    # * <tt>idling?</tt>
+    # 
+    # Each predicate method will return true if it matches the object's
+    # current state.  Otherwise, it will return false.
+    # 
+    # == Events and Transitions
+    # 
+    # Events defined on the machine are the interface to transitioning states
+    # for an object.  Events can be fired either directly (through the method
+    # generated for the event) or indirectly (through attributes defined on
+    # the machine).
+    # 
+    # For example,
+    # 
+    #   class Vehicle
+    #     include DataMapper::Resource
+    #     property :id, Serial
+    #     
+    #     state_machine :initial => :parked do
+    #       event :ignite do
+    #         transition :parked => :idling
+    #       end
+    #     end
+    #     
+    #     state_machine :alarm_state, :initial => :active do
+    #       event :disable do
+    #         transition all => :off
+    #       end
+    #     end
+    #   end
+    #   
+    #   # Fire +ignite+ event directly
+    #   vehicle = Vehicle.create    # => #<Vehicle id=1 state="parked" alarm_state="active">
+    #   vehicle.ignite              # => true
+    #   vehicle.state               # => "idling"
+    #   vehicle.alarm_state         # => "active"
+    #   
+    #   # Fire +disable+ event automatically
+    #   vehicle.alarm_state_event = 'disable'
+    #   vehicle.save                # => true
+    #   vehicle.alarm_state         # => "off"
+    # 
+    # In the above example, the +state+ attribute is transitioned using the
+    # +ignite+ action that's generated from the state machine.  On the other
+    # hand, the +alarm_state+ attribute is transitioned using the +alarm_state_event+
+    # attribute that automatically gets fired when the machine's action (+save+)
+    # is invoked.
+    # 
+    # For more information about how to configure an event and its associated
+    # transitions, see StateMachine::Machine#event.
+    # 
+    # == Defining callbacks
+    # 
+    # 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.
+    # 
+    # == Namespaces
+    # 
+    # When a namespace is configured for a state machine, the name provided
+    # will be used in generating the instance methods for interacting with
+    # states/events in the machine.  This is particularly useful when a class
+    # has multiple state machines and it would be difficult to differentiate
+    # between the various states / events.
+    # 
+    # For example,
+    # 
+    #   class Vehicle
+    #     state_machine :heater_state, :initial => :off, :namespace => 'heater' do
+    #       event :turn_on do
+    #         transition all => :on
+    #       end
+    #       
+    #       event :turn_off do
+    #         transition all => :off
+    #       end
+    #     end
+    #     
+    #     state_machine :alarm_state, :initial => :active, :namespace => 'alarm' do
+    #       event :turn_on do
+    #         transition all => :active
+    #       end
+    #       
+    #       event :turn_off do
+    #         transition all => :off
+    #       end
+    #     end
+    #   end
+    # 
+    # The above class defines two state machines: +heater_state+ and +alarm_state+.
+    # For the +heater_state+ machine, the following methods are generated since
+    # it's namespaced by "heater":
+    # * <tt>can_turn_on_heater?</tt>
+    # * <tt>turn_on_heater</tt>
+    # * ...
+    # * <tt>can_turn_off_heater?</tt>
+    # * <tt>turn_off_heater</tt>
+    # * ..
+    # * <tt>heater_off?</tt>
+    # * <tt>heater_on?</tt>
+    # 
+    # As shown, each method is unique to the state machine so that the states
+    # and events don't conflict.  The same goes for the +alarm_state+ machine:
+    # * <tt>can_turn_on_alarm?</tt>
+    # * <tt>turn_on_alarm</tt>
+    # * ...
+    # * <tt>can_turn_off_alarm?</tt>
+    # * <tt>turn_off_alarm</tt>
+    # * ..
+    # * <tt>alarm_active?</tt>
+    # * <tt>alarm_off?</tt>
+    # 
+    # == Scopes
+    # 
+    # For integrations that support it, a group of default scope filters will
+    # be automatically created for assisting in finding objects that have the
+    # attribute set to one of a given set of states.
+    # 
+    # For example,
+    # 
+    #   Vehicle.with_state(:parked)               # => All vehicles where the state is parked
+    #   Vehicle.with_states(:parked, :idling)     # => All vehicles where the state is either parked or idling
+    #   
+    #   Vehicle.without_state(:parked)            # => All vehicles where the state is *not* parked
+    #   Vehicle.without_states(:parked, :idling)  # => All vehicles where the state is *not* parked or idling
+    # 
+    # *Note* that if class methods already exist with those names (i.e.
+    # :with_state, :with_states, :without_state, or :without_states), then a
+    # scope will not be defined for that name.
+    # 
+    # See StateMachine::Machine for more information about using integrations
+    # and the individual integration docs for information about the actual
+    # scopes that are generated.
+    def state_machine(*args, &block)
+      StateMachine::Machine.find_or_create(self, *args, &block)
+    end
+  end
+end
+
+Class.class_eval do
+  include StateMachine::MacroMethods
+end
+
+require 'state_machine/initializers'

data/lib/tasks/state_machine.rake

@@ -0,0 +1 @@
+require File.join("#{File.dirname(__FILE__)}/state_machine")

data/lib/tasks/state_machine.rb

@@ -0,0 +1,27 @@
+namespace :state_machine do
+  desc 'Draws a set of state machines using GraphViz. Target files to load with FILE=x,y,z; Machine class with CLASS=x,y,z; Font name with FONT=x; Image format with FORMAT=x; Orientation with ORIENTATION=x'
+  task :draw do
+    if defined?(Rails)
+      Rake::Task['environment'].invoke
+    elsif defined?(Merb)
+      Rake::Task['merb_env'].invoke
+      
+      # Fix ruby-graphviz being incompatible with Merb's process title
+      $0 = 'rake'
+    else
+      # Load the library
+      $:.unshift(File.dirname(__FILE__) + '/..')
+      require 'state_machine'
+    end
+    
+    # Build drawing options
+    options = {}
+    options[:file] = ENV['FILE'] if ENV['FILE']
+    options[:path] = ENV['TARGET'] if ENV['TARGET']
+    options[:format] = ENV['FORMAT'] if ENV['FORMAT']
+    options[:font] = ENV['FONT'] if ENV['FONT']
+    options[:orientation] = ENV['ORIENTATION'] if ENV['ORIENTATION']
+    
+    StateMachine::Machine.draw(ENV['CLASS'], options)
+  end
+end