state_machine 0.1.0

data/lib/state_machine/machine.rb

@@ -0,0 +1,141 @@
+require 'state_machine/event'
+
+module PluginAWeek #:nodoc:
+  module StateMachine
+    # Represents a state machine for a particular attribute
+    # 
+    # == State callbacks
+    # 
+    # These callbacks are invoked in the following order:
+    # 1. before_exit (old state)
+    # 2. before_enter (new state)
+    # 3. after_exit (old state)
+    # 4. after_enter (new state)
+    class Machine
+      # The events that trigger transitions
+      attr_reader :events
+      
+      # The attribute for which the state machine is being defined
+      attr_accessor :attribute
+      
+      # The initial state that the machine will be in
+      attr_reader :initial_state
+      
+      # The class that the attribute belongs to
+      attr_reader :owner_class
+      
+      # Creates a new state machine for the given attribute
+      # 
+      # Configuration options:
+      # * +initial+ - The initial value to set the attribute to
+      # 
+      # == Scopes
+      # 
+      # This will automatically created a named scope called with_#{attribute}
+      # that will find all records that have the attribute set to a given value.
+      # For example,
+      # 
+      #   Switch.with_state('on') # => Finds all switches where the state is on
+      #   Switch.with_states('on', 'off') # => Finds all switches where the state is either on or off
+      def initialize(owner_class, attribute, options = {})
+        options.assert_valid_keys(:initial)
+        
+        @owner_class = owner_class
+        @attribute = attribute.to_s
+        @initial_state = options[:initial]
+        @events = {}
+        
+        add_named_scopes
+      end
+      
+      # Gets the initial state of the machine for the given record. The record
+      # is only used if a dynamic initial state is being used
+      def initial_state(record)
+        @initial_state.is_a?(Proc) ? @initial_state.call(record) : @initial_state
+      end
+      
+      # Gets the initial state without processing it against a particular record
+      def initial_state_without_processing
+        @initial_state
+      end
+      
+      # Defines an event of the system.  This can take an optional hash that
+      # defines callbacks which will be invoked when the object enters/exits
+      # the event.
+      # 
+      # Configuration options:
+      # * +before+ - Invoked before the event has been executed
+      # * +after+ - Invoked after the event has been executed
+      # 
+      # == Callback order
+      # 
+      # These callbacks are invoked in the following order:
+      # 1. before
+      # 2. after
+      # 
+      # == Instance methods
+      # 
+      # The following instance methods are generated when a new event is defined
+      # (the "park" event is used as an example):
+      # * <tt>park!(*args)</tt> - Fires the "park" event, transitioning from the current state to the next valid state.  This takes an optional +args+ list which is passed to the event callbacks.
+      # 
+      # == Defining transitions
+      # 
+      # +event+ requires a block which allows you to define the possible
+      # transitions that can happen as a result of that event.  For example,
+      # 
+      #   event :park do
+      #     transition :to => 'parked', :from => 'idle'
+      #   end
+      #   
+      #   event :first_gear do
+      #     transition :to => 'first_gear', :from => 'parked', :if => :seatbelt_on?
+      #   end
+      # 
+      # See PluginAWeek::StateMachine::Event#transition for more information on
+      # the possible options that can be passed in.
+      # 
+      # == Example
+      # 
+      #   class Car < ActiveRecord::Base
+      #     state_machine(:state, :initial => 'parked') do
+      #       event :park, :after => :release_seatbelt do
+      #         transition :to => 'parked', :from => %w(first_gear reverse)
+      #       end
+      #       ...
+      #     end
+      #   end
+      def event(name, options = {}, &block)
+        name = name.to_s
+        event = events[name] = Event.new(self, name, options)
+        event.instance_eval(&block)
+        event
+      end
+      
+      # Define state callbacks
+      %w(before_exit before_enter after_exit after_enter).each do |callback|
+        module_eval <<-end_eval
+          def #{callback}(state, callback)
+            callback_name = "#{callback}_\#{attribute}_\#{state}"
+            owner_class.define_callbacks(callback_name)
+            owner_class.send(callback_name, callback)
+          end
+        end_eval
+      end
+      
+      private
+        def add_named_scopes
+          unless owner_class.respond_to?("with_#{attribute}")
+            # How do you alias named scopes? (doesn't work completely with a simple alias/alias_method)
+            %W(with_#{attribute} with_#{attribute.pluralize}).each do |scope_name|
+              owner_class.class_eval <<-end_eos
+                named_scope :#{scope_name}, Proc.new {|*values| {
+                  :conditions => {:#{attribute} => values.flatten}
+                }}
+              end_eos
+            end
+          end
+        end
+    end
+  end
+end

data/lib/state_machine/transition.rb

@@ -0,0 +1,75 @@
+module PluginAWeek #:nodoc:
+  module StateMachine
+    # A transition indicates a state change and is described by a condition
+    # that would need to be fulfilled to enable the transition.  Transitions
+    # consist of:
+    # * The starting state
+    # * The ending state
+    # * A guard to check if the transition is allowed
+    class Transition
+      # The state from which the transition is being made
+      attr_reader :from_state
+      
+      # The state to which the transition is being made
+      attr_reader :to_state
+      
+      # The event that caused the transition
+      attr_reader :event
+      
+      delegate  :machine,
+                  :to => :event
+      
+      def initialize(event, from_state, to_state) #:nodoc:
+        @event = event
+        @from_state = from_state
+        @to_state = to_state
+        @loopback = from_state == to_state
+      end
+      
+      # Whether or not this is a loopback transition (i.e. from and to state are the same)
+      def loopback?(state = from_state)
+        state == to_state
+      end
+      
+      # Determines whether or not this transition can be performed on the given
+      # states
+      def can_perform_on?(record)
+        !from_state || from_state == record.send(machine.attribute)
+      end
+      
+      # Runs the actual transition and any actions associated with entering
+      # and exiting the states
+      def perform(record, *args)
+        state = record.send(machine.attribute)
+        
+        invoke_before_callbacks(state, record) != false &&
+        update_state(state, record) &&
+        invoke_after_callbacks(state, record) != false
+      end
+      
+      private
+        def update_state(from_state, record)
+          loopback?(from_state) ? true : record.update_attribute(machine.attribute, to_state)
+        end
+        
+        def invoke_before_callbacks(from_state, record)
+          # Start leaving the last state and start entering the next state
+          loopback?(from_state) || invoke_callbacks(:before_exit, from_state, record) && invoke_callbacks(:before_enter, to_state, record)
+        end
+        
+        def invoke_after_callbacks(from_state, record)
+          # Start leaving the last state and start entering the next state
+          loopback?(from_state) || invoke_callbacks(:after_exit, from_state, record) && invoke_callbacks(:after_enter, to_state, record)
+        end
+        
+        def invoke_callbacks(type, state, record)
+          kind = "#{type}_#{machine.attribute}_#{state}"
+          if record.class.respond_to?("#{kind}_callback_chain")
+            record.run_callbacks(kind) {|result, record| result == false}
+          else
+            true
+          end
+        end
+    end
+  end
+end

data/test/app_root/app/models/auto_shop.rb

@@ -0,0 +1,34 @@
+class AutoShop < ActiveRecord::Base
+  state_machine :state, :initial => 'available' do
+    after_exit 'available', :increment_customers
+    after_exit 'busy', :decrement_customers
+    
+    event :tow_vehicle do
+      transition :to => 'busy', :from => 'available'
+    end
+    
+    event :fix_vehicle do
+      transition :to => 'available', :from => 'busy'
+    end
+  end
+  
+  # Is the Auto Shop available for new customers?
+  def available?
+    state == 'available'
+  end
+  
+  # Is the Auto Shop currently not taking new customers?
+  def busy?
+    state == 'busy'
+  end
+  
+  # Increments the number of customers in service
+  def increment_customers
+    update_attribute(:num_customers, num_customers + 1)
+  end
+  
+  # Decrements the number of customers in service
+  def decrement_customers
+    update_attribute(:num_customers, num_customers - 1)
+  end
+end

data/test/app_root/app/models/car.rb

@@ -0,0 +1,19 @@
+class Car < Vehicle
+  state_machine :state do
+    event :reverse do
+      transition :to => 'backing_up', :from => %w(parked idling first_gear)
+    end
+    
+    event :park do
+      transition :to => 'parked', :from => 'backing_up'
+    end
+    
+    event :idle do
+      transition :to => 'idling', :from => 'backing_up'
+    end
+    
+    event :shift_up do
+      transition :to => 'first_gear', :from => 'backing_up'
+    end
+  end
+end

data/test/app_root/app/models/highway.rb

@@ -0,0 +1,3 @@
+class Highway < ActiveRecord::Base
+  has_many :vehicles
+end

data/test/app_root/app/models/motorcycle.rb

@@ -0,0 +1,3 @@
+class Motorcycle < Vehicle
+  state_machine :state, :initial => 'idling'
+end

data/test/app_root/app/models/switch.rb

@@ -0,0 +1,12 @@
+class Switch < ActiveRecord::Base
+  # Tracks the callbacks that were invoked
+  attr_reader :callbacks
+  
+  # Dynamic sets the initial state
+  attr_accessor :initial_state
+  
+  def initialize(attributes = nil)
+    @callbacks = []
+    super
+  end
+end

data/test/app_root/app/models/toggle_switch.rb

@@ -0,0 +1,2 @@
+class ToggleSwitch < Switch
+end

data/test/app_root/app/models/vehicle.rb

@@ -0,0 +1,71 @@
+class Vehicle < ActiveRecord::Base
+  belongs_to :auto_shop
+  belongs_to :highway
+  
+  attr_accessor :force_idle
+  
+  # Defines the state machine for the state of the vehicle
+  state_machine :state, :initial => Proc.new {|vehicle| vehicle.force_idle ? 'idling' : 'parked'} do
+    before_exit   'parked', :put_on_seatbelt
+    after_enter   'parked', Proc.new {|vehicle| vehicle.update_attribute(:seatbelt_on, false)}
+    before_enter  'stalled', :increase_insurance_premium
+    
+    event :park do
+      transition :to => 'parked', :from => %w(idling first_gear)
+    end
+    
+    event :ignite do
+      transition :to => 'stalled', :from => 'stalled'
+      transition :to => 'idling', :from => 'parked'
+    end
+    
+    event :idle do
+      transition :to => 'idling', :from => 'first_gear'
+    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'
+    end
+    
+    event :shift_down do
+      transition :to => 'second_gear', :from => 'third_gear'
+      transition :to => 'first_gear', :from => 'second_gear'
+    end
+    
+    event :crash, :after => :tow! do
+      transition :to => 'stalled', :from => %w(first_gear second_gear third_gear), :if => Proc.new {|vehicle| vehicle.auto_shop.available?}
+    end
+    
+    event :repair, :after => :fix! do
+      transition :to => 'parked', :from => 'stalled', :if => :auto_shop_busy?
+    end
+  end
+  
+  # Tows the vehicle to the auto shop
+  def tow!
+    auto_shop.tow_vehicle!
+  end
+  
+  # Fixes the vehicle; it will no longer be in the auto shop
+  def fix!
+    auto_shop.fix_vehicle!
+  end
+  
+  private
+    # Safety first! Puts on our seatbelt
+    def put_on_seatbelt
+      self.seatbelt_on = true
+    end
+    
+    # We crashed! Increase the insurance premium on the vehicle
+    def increase_insurance_premium
+      update_attribute(:insurance_premium, self.insurance_premium + 100)
+    end
+    
+    # Is the auto shop currently servicing another customer?
+    def auto_shop_busy?
+      auto_shop.busy?
+    end
+end

data/test/app_root/db/migrate/001_create_switches.rb

@@ -0,0 +1,12 @@
+class CreateSwitches < ActiveRecord::Migration
+  def self.up
+    create_table :switches do |t|
+      t.string :state, :null => false
+      t.string :kind
+    end
+  end
+  
+  def self.down
+    drop_table :switches
+  end
+end

data/test/app_root/db/migrate/002_create_auto_shops.rb

@@ -0,0 +1,13 @@
+class CreateAutoShops < ActiveRecord::Migration
+  def self.up
+    create_table :auto_shops do |t|
+      t.string :name, :null => false
+      t.integer :num_customers, :null => false
+      t.string :state, :null => false
+    end
+  end
+  
+  def self.down
+    drop_table :auto_shops
+  end
+end

data/test/app_root/db/migrate/003_create_highways.rb

@@ -0,0 +1,11 @@
+class CreateHighways < ActiveRecord::Migration
+  def self.up
+    create_table :highways do |t|
+      t.string :name, :null => false
+    end
+  end
+  
+  def self.down
+    drop_table :highways
+  end
+end

data/test/app_root/db/migrate/004_create_vehicles.rb

@@ -0,0 +1,16 @@
+class CreateVehicles < ActiveRecord::Migration
+  def self.up
+    create_table :vehicles do |t|
+      t.references :highway, :null => false
+      t.references :auto_shop, :null => false
+      t.boolean :seatbelt_on, :null => false
+      t.integer :insurance_premium, :null => false
+      t.string :state, :null => false
+      t.string :type
+    end
+  end
+  
+  def self.down
+    drop_table :vehicles
+  end
+end

data/test/factory.rb

@@ -0,0 +1,61 @@
+module Factory
+  # Build actions for the class
+  def self.build(klass, &block)
+    name = klass.to_s.underscore
+    define_method("#{name}_attributes", block)
+    
+    module_eval <<-end_eval
+      def valid_#{name}_attributes(attributes = {})
+        #{name}_attributes(attributes)
+        attributes
+      end
+      
+      def new_#{name}(attributes = {})
+        #{klass}.new(valid_#{name}_attributes(attributes))
+      end
+      
+      def create_#{name}(*args)
+        record = new_#{name}(*args)
+        record.save!
+        record.reload
+        record
+      end
+    end_eval
+  end
+  
+  build AutoShop do |attributes|
+    attributes.reverse_merge!(
+      :name => "Joe's Auto Body",
+      :num_customers => 0
+    )
+  end
+  
+  build Car do |attributes|
+    attributes[:highway] = create_highway unless attributes.include?(:highway)
+    attributes[:auto_shop] = create_auto_shop unless attributes.include?(:auto_shop)
+    attributes.reverse_merge!(
+      :seatbelt_on => false,
+      :insurance_premium => 50
+    )
+  end
+  
+  build Highway do |attributes|
+    attributes.reverse_merge!(
+      :name => 'Route 66'
+    )
+  end
+  
+  build Motorcycle do |attributes|
+    valid_car_attributes(attributes)
+  end
+  
+  build Switch do |attributes|
+    attributes.reverse_merge!(
+      :state => 'off'
+    )
+  end
+  
+  build Vehicle do |attributes|
+    valid_car_attributes(attributes)
+  end
+end