gvaughn-aasm 2.0.3 → 2.0.4

data/lib/aasm.rb

@@ -0,0 +1,150 @@
+require File.join(File.dirname(__FILE__), 'event')
+require File.join(File.dirname(__FILE__), 'state')
+require File.join(File.dirname(__FILE__), 'state_machine')
+require File.join(File.dirname(__FILE__), 'persistence')
+
+module AASM
+  class InvalidTransition < RuntimeError
+  end
+  
+  def self.included(base) #:nodoc:
+    # TODO - need to ensure that a machine is being created because
+    # AASM was either included or arrived at via inheritance.  It
+    # cannot be both.
+    base.extend AASM::ClassMethods
+    AASM::Persistence.set_persistence(base)
+    AASM::StateMachine[base] = AASM::StateMachine.new('')
+
+    base.class_eval do
+      def base.inherited(klass)
+        AASM::StateMachine[klass] = AASM::StateMachine[self].dup
+        super
+      end
+    end
+  end
+
+  module ClassMethods
+    def aasm_initial_state(set_state=nil)
+      if set_state
+        aasm_state_machine.initial_state = set_state
+      else
+        aasm_state_machine.initial_state
+      end
+    end
+    
+    def aasm_initial_state=(state)
+      aasm_state_machine.initial_state = state
+    end
+    
+    def aasm_state(name, options={})
+      sm = aasm_state_machine
+      sm.create_state(name, options)
+      sm.initial_state = name unless sm.initial_state
+
+      define_method("#{name.to_s}?") do
+        aasm_current_state == name
+      end
+    end
+    
+    def aasm_event(name, options = {}, &block)
+      sm = aasm_state_machine
+      
+      unless sm.events.has_key?(name)
+        sm.events[name] = AASM::SupportingClasses::Event.new(name, options, &block)
+      end
+
+      define_method("#{name.to_s}!") do |*args|
+        aasm_fire_event(name, true, *args)
+      end
+
+      define_method("#{name.to_s}") do |*args|
+        aasm_fire_event(name, false, *args)
+      end
+    end
+
+    def aasm_states
+      aasm_state_machine.states
+    end
+
+    def aasm_events
+      aasm_state_machine.events
+    end
+    
+    def aasm_states_for_select
+      aasm_state_machine.states.map { |state| state.for_select }
+    end
+    
+    def aasm_state_machine
+      AASM::StateMachine[self]
+    end
+    
+  end
+
+  # Instance methods
+  def aasm_current_state
+    return @aasm_current_state if @aasm_current_state
+
+    if self.respond_to?(:aasm_read_state) || self.private_methods.include?('aasm_read_state')
+      @aasm_current_state = aasm_read_state
+    end
+    return @aasm_current_state if @aasm_current_state
+    self.class.aasm_initial_state
+  end
+
+  def aasm_events_for_current_state
+    aasm_events_for_state(aasm_current_state)
+  end
+
+  def aasm_events_for_state(state)
+    events = self.class.aasm_events.values.select {|event| event.transitions_from_state?(state) }
+    events.map {|event| event.name}
+  end
+
+  private
+  def aasm_current_state_with_persistence=(state)
+    if self.respond_to?(:aasm_write_state) || self.private_methods.include?('aasm_write_state')
+      aasm_write_state(state)
+    end
+    self.aasm_current_state = state
+  end
+
+  def aasm_current_state=(state)
+    if self.respond_to?(:aasm_write_state_without_persistence) || self.private_methods.include?('aasm_write_state_without_persistence')
+      aasm_write_state_without_persistence(state)
+    end
+    @aasm_current_state = state
+  end
+
+  def aasm_state_object_for_state(name)
+    self.class.aasm_states.find {|s| s == name}
+  end
+
+  def aasm_fire_event(name, persist, *args)
+    aasm_state_object_for_state(aasm_current_state).call_action(:exit, self)
+
+    new_state = self.class.aasm_events[name].fire(self, *args)
+    
+    unless new_state.nil?
+      aasm_state_object_for_state(new_state).call_action(:enter, self)
+      
+      if self.respond_to?(:aasm_event_fired)
+        self.aasm_event_fired(self.aasm_current_state, new_state)
+      end
+
+      if persist
+        self.aasm_current_state_with_persistence = new_state
+        self.send(self.class.aasm_events[name].success) if self.class.aasm_events[name].success
+      else
+        self.aasm_current_state = new_state
+      end
+
+      true
+    else
+      if self.respond_to?(:aasm_event_failed)
+        self.aasm_event_failed(name)
+      end
+      
+      false
+    end
+  end
+end

data/lib/event.rb

@@ -0,0 +1,45 @@
+require File.join(File.dirname(__FILE__), 'state_transition')
+
+module AASM
+  module SupportingClasses
+    class Event
+      attr_reader :name, :success
+      
+      def initialize(name, options = {}, &block)
+        @name = name
+        @success = options[:success]
+        @transitions = []
+        instance_eval(&block) if block
+      end
+
+      def fire(obj, *args)
+        transitions = @transitions.select { |t| t.from == obj.aasm_current_state }
+        raise AASM::InvalidTransition, "Event '#{name}' cannot transition from '#{obj.aasm_current_state}'" if transitions.size == 0
+        to_state = args.shift if args[0].nil? || #nil check is for backwards compatability
+          (args[0].is_a?(Symbol) && obj.class.aasm_state_machine.states.include?(args[0]))
+
+        next_state = nil
+        transitions.each do |transition|
+          next if to_state and !Array(transition.to).include?(to_state)
+          if transition.perform(obj)
+            next_state = to_state || Array(transition.to).first
+            transition.execute(obj, *args)
+            break
+          end
+        end
+        next_state
+      end
+
+      def transitions_from_state?(state)
+        @transitions.any? { |t| t.from == state }
+      end
+      
+      private
+      def transitions(trans_opts)
+        Array(trans_opts[:from]).each do |s|
+          @transitions << SupportingClasses::StateTransition.new(trans_opts.merge({:from => s.to_sym}))
+        end
+      end
+    end
+  end
+end

data/lib/persistence.rb

@@ -0,0 +1,16 @@
+module AASM
+  module Persistence
+    
+    # Checks to see this class or any of it's superclasses inherit from
+    # ActiveRecord::Base and if so includes ActiveRecordPersistence
+    def self.set_persistence(base)
+      # Use a fancier auto-loading thingy, perhaps.  When there are more persistence engines.
+      hierarchy = base.ancestors.map {|klass| klass.to_s}
+      
+      if hierarchy.include?("ActiveRecord::Base")
+        require File.join(File.dirname(__FILE__), 'persistence', 'active_record_persistence')
+        base.send(:include, AASM::Persistence::ActiveRecordPersistence)
+      end
+    end
+  end
+end

data/lib/persistence/active_record_persistence.rb

@@ -0,0 +1,238 @@
+module AASM
+  module Persistence
+    module ActiveRecordPersistence
+      # This method:
+      #
+      # * extends the model with ClassMethods
+      # * includes InstanceMethods
+      #
+      # Unless the corresponding methods are already defined, it includes
+      # * ReadState
+      # * WriteState
+      # * WriteStateWithoutPersistence
+      #
+      # Adds
+      #
+      #   before_validation_on_create :aasm_ensure_initial_state
+      #
+      # As a result, it doesn't matter when you define your methods - the following 2 are equivalent
+      #
+      #   class Foo < ActiveRecord::Base
+      #     def aasm_write_state(state)
+      #       "bar"
+      #     end
+      #     include AASM
+      #   end
+      #
+      #   class Foo < ActiveRecord::Base
+      #     include AASM
+      #     def aasm_write_state(state)
+      #       "bar"
+      #     end
+      #   end
+      #
+      def self.included(base)
+        base.extend AASM::Persistence::ActiveRecordPersistence::ClassMethods
+        base.send(:include, AASM::Persistence::ActiveRecordPersistence::InstanceMethods)
+        base.send(:include, AASM::Persistence::ActiveRecordPersistence::ReadState) unless base.method_defined?(:aasm_read_state)
+        base.send(:include, AASM::Persistence::ActiveRecordPersistence::WriteState) unless base.method_defined?(:aasm_write_state)
+        base.send(:include, AASM::Persistence::ActiveRecordPersistence::WriteStateWithoutPersistence) unless base.method_defined?(:aasm_write_state_without_persistence)
+        
+        if base.respond_to?(:named_scope)
+          base.extend(AASM::Persistence::ActiveRecordPersistence::NamedScopeMethods)
+          
+          base.class_eval do
+            class << self
+              alias_method :aasm_state_without_named_scope, :aasm_state
+              alias_method :aasm_state, :aasm_state_with_named_scope
+            end
+          end
+        end
+        
+        base.before_validation_on_create :aasm_ensure_initial_state
+      end
+
+      module ClassMethods
+        # Maps to the aasm_column in the database.  Deafults to "aasm_state".  You can write:
+        #
+        #   create_table :foos do |t|
+        #     t.string :name
+        #     t.string :aasm_state
+        #   end
+        #
+        #   class Foo < ActiveRecord::Base
+        #     include AASM
+        #   end
+        #
+        # OR:
+        #
+        #   create_table :foos do |t|
+        #     t.string :name
+        #     t.string :status
+        #   end
+        #
+        #   class Foo < ActiveRecord::Base
+        #     include AASM
+        #     aasm_column :status
+        #   end
+        #
+        # This method is both a getter and a setter
+        def aasm_column(column_name=nil)
+          if column_name
+            AASM::StateMachine[self].config.column = column_name.to_sym
+            # @aasm_column = column_name.to_sym
+          else
+            AASM::StateMachine[self].config.column ||= :aasm_state
+            # @aasm_column ||= :aasm_state
+          end
+          # @aasm_column
+          AASM::StateMachine[self].config.column
+        end
+
+        def find_in_state(number, state, *args)
+          with_state_scope state do
+            find(number, *args)
+          end
+        end
+
+        def count_in_state(state, *args)
+          with_state_scope state do
+            count(*args)
+          end
+        end
+
+        def calculate_in_state(state, *args)
+          with_state_scope state do
+            calculate(*args)
+          end
+        end
+
+        protected
+        def with_state_scope(state)
+          with_scope :find => {:conditions => ["#{table_name}.#{aasm_column} = ?", state.to_s]} do
+            yield if block_given?
+          end
+        end
+      end
+
+      module InstanceMethods
+
+        # Returns the current aasm_state of the object.  Respects reload and
+        # any changes made to the aasm_state field directly
+        # 
+        # Internally just calls <tt>aasm_read_state</tt>
+        #
+        #   foo = Foo.find(1)
+        #   foo.aasm_current_state # => :pending
+        #   foo.aasm_state = "opened"
+        #   foo.aasm_current_state # => :opened
+        #   foo.close # => calls aasm_write_state_without_persistence
+        #   foo.aasm_current_state # => :closed
+        #   foo.reload
+        #   foo.aasm_current_state # => :pending
+        #
+        def aasm_current_state
+          @current_state = aasm_read_state
+        end
+
+        private
+        
+        # Ensures that if the aasm_state column is nil and the record is new
+        # that the initial state gets populated before validation on create
+        #
+        #   foo = Foo.new
+        #   foo.aasm_state # => nil
+        #   foo.valid?
+        #   foo.aasm_state # => "open" (where :open is the initial state)
+        #
+        #
+        #   foo = Foo.find(:first)
+        #   foo.aasm_state # => 1
+        #   foo.aasm_state = nil
+        #   foo.valid?
+        #   foo.aasm_state # => nil
+        #
+        def aasm_ensure_initial_state
+          send("#{self.class.aasm_column}=", self.aasm_current_state.to_s)
+        end
+
+      end
+
+      module WriteStateWithoutPersistence
+        # Writes <tt>state</tt> to the state column, but does not persist it to the database
+        # 
+        #   foo = Foo.find(1)
+        #   foo.aasm_current_state # => :opened
+        #   foo.close
+        #   foo.aasm_current_state # => :closed
+        #   Foo.find(1).aasm_current_state # => :opened
+        #   foo.save
+        #   foo.aasm_current_state # => :closed
+        #   Foo.find(1).aasm_current_state # => :closed
+        #
+        # NOTE: intended to be called from an event
+        def aasm_write_state_without_persistence(state)
+          write_attribute(self.class.aasm_column, state.to_s)
+        end
+      end
+
+      module WriteState
+        # Writes <tt>state</tt> to the state column and persists it to the database
+        # using update_attribute (which bypasses validation)
+        # 
+        #   foo = Foo.find(1)
+        #   foo.aasm_current_state # => :opened
+        #   foo.close!
+        #   foo.aasm_current_state # => :closed
+        #   Foo.find(1).aasm_current_state # => :closed
+        #
+        # NOTE: intended to be called from an event
+        def aasm_write_state(state)
+          update_attribute(self.class.aasm_column, state.to_s)
+        end
+      end
+
+      module ReadState
+
+        # Returns the value of the aasm_column - called from <tt>aasm_current_state</tt>
+        #
+        # If it's a new record, and the aasm state column is blank it returns the initial state:
+        #
+        #   class Foo < ActiveRecord::Base
+        #     include AASM
+        #     aasm_column :status
+        #     aasm_state :opened
+        #     aasm_state :closed
+        #   end
+        # 
+        #   foo = Foo.new
+        #   foo.current_state # => :opened
+        #   foo.close
+        #   foo.current_state # => :closed
+        #   
+        #   foo = Foo.find(1)
+        #   foo.current_state # => :opened
+        #   foo.aasm_state = nil
+        #   foo.current_state # => nil
+        # 
+        # NOTE: intended to be called from an event
+        #
+        # This allows for nil aasm states - be sure to add validation to your model
+        def aasm_read_state
+          if new_record?
+            send(self.class.aasm_column).blank? ? self.class.aasm_initial_state : send(self.class.aasm_column).to_sym
+          else
+            send(self.class.aasm_column).nil? ? nil : send(self.class.aasm_column).to_sym
+          end
+        end
+      end
+
+      module NamedScopeMethods
+        def aasm_state_with_named_scope name, options = {}
+          aasm_state_without_named_scope name, options
+          self.named_scope name, :conditions => {self.aasm_column => name.to_s} unless self.scopes.include?(name)
+        end       
+      end
+    end
+  end
+end