aasm 3.0.16 → 3.0.17

data/lib/aasm/event.rb

@@ -0,0 +1,130 @@
+module AASM
+  class Event
+
+    attr_reader :name, :options
+
+    def initialize(name, options = {}, &block)
+      @name = name
+      @transitions = []
+      update(options, &block)
+    end
+
+    # a neutered version of fire - it doesn't actually fire the event, it just
+    # executes the transition guards to determine if a transition is even
+    # an option given current conditions.
+    def may_fire?(obj, to_state=nil, *args)
+      _fire(obj, true, to_state, *args) # true indicates test firing
+    end
+
+    def fire(obj, to_state=nil, *args)
+      _fire(obj, false, to_state, *args) # false indicates this is not a test (fire!)
+    end
+
+    def transitions_from_state?(state)
+      transitions_from_state(state).any?
+    end
+
+    def transitions_from_state(state)
+      @transitions.select { |t| t.from == state }
+    end
+
+    def transitions_to_state?(state)
+      transitions_to_state(state).any?
+    end
+
+    def transitions_to_state(state)
+      @transitions.select { |t| t.to == state }
+    end
+
+    # deprecated
+    def all_transitions
+      # warn "Event#all_transitions is deprecated and will be removed in version 3.2.0; please use Event#transitions instead!"
+      transitions
+    end
+
+    def fire_callbacks(callback_name, record, *args)
+      invoke_callbacks(@options[callback_name], record, args)
+    end
+
+    def ==(event)
+      if event.is_a? Symbol
+        name == event
+      else
+        name == event.name
+      end
+    end
+
+  private
+
+    def update(options = {}, &block)
+      @options = options
+      if block then
+        instance_eval(&block)
+      end
+      self
+    end
+
+    # Execute if test? == false, otherwise return true/false depending on whether it would fire
+    def _fire(obj, test, to_state=nil, *args)
+      if @transitions.map(&:from).any?
+        transitions = @transitions.select { |t| t.from == obj.aasm_current_state }
+        return nil if transitions.size == 0
+      else
+        transitions = @transitions
+      end
+
+      result = test ? false : nil
+      transitions.each do |transition|
+        next if to_state and !Array(transition.to).include?(to_state)
+        if transition.perform(obj, *args)
+          if test
+            result = true
+          else
+            result = to_state || Array(transition.to).first
+            transition.execute(obj, *args)
+          end
+
+          break
+        end
+      end
+      result
+    end
+
+    def invoke_callbacks(code, record, args)
+      case code
+        when Symbol, String
+          record.send(code, *args)
+          true
+        when Proc
+          record.instance_exec(*args, &code)
+          true
+        when Array
+          code.each {|a| invoke_callbacks(a, record, args)}
+          true
+        else
+          false
+      end
+    end
+
+    ## DSL interface
+    def transitions(trans_opts=nil)
+      if trans_opts # define new transitions
+        # Create a separate transition for each from state to the given state
+        Array(trans_opts[:from]).each do |s|
+          @transitions << AASM::Transition.new(trans_opts.merge({:from => s.to_sym}))
+        end
+        # Create a transition if to is specified without from (transitions from ANY state)
+        @transitions << AASM::Transition.new(trans_opts) if @transitions.empty? && trans_opts[:to]
+      end
+      @transitions
+    end
+
+    [:after, :before, :error, :success].each do |callback_name|
+      define_method callback_name do |*args, &block|
+        options[callback_name] = Array(options[callback_name])
+        options[callback_name] << block if block
+        options[callback_name] += Array(args)
+      end
+    end
+  end
+end # AASM

data/lib/aasm/instance_base.rb

@@ -0,0 +1,87 @@
+module AASM
+  class InstanceBase
+
+    def initialize(instance)
+      @instance = instance
+    end
+
+    def current_state
+      @current_state ||= @instance.aasm_read_state
+    end
+
+    def current_state=(state)
+      @instance.aasm_write_state_without_persistence(state)
+      @current_state = state
+    end
+
+    def enter_initial_state
+      state_name = determine_state_name(@instance.class.aasm_initial_state)
+      state_object = state_object_for_name(state_name)
+
+      state_object.fire_callbacks(:before_enter, @instance)
+      state_object.fire_callbacks(:enter, @instance)
+      self.current_state = state_name
+      state_object.fire_callbacks(:after_enter, @instance)
+
+      state_name
+    end
+
+    def human_state
+      AASM::Localizer.new.human_state_name(@instance.class, current_state)
+    end
+
+    def states(options={})
+      if options[:permissible]
+        # ugliness level 1000
+        transitions = @instance.class.aasm.events.values.map {|e| e.transitions_from_state(current_state) }
+        tos = transitions.map {|t| t[0] ? t[0].to : nil}.flatten.compact.map(&:to_sym).uniq
+        @instance.class.aasm.states.select {|s| tos.include?(s.name.to_sym)}
+      else
+        @instance.class.aasm.states
+      end
+    end
+
+    # QUESTION: shouldn't events and permissible_events be the same thing?
+    # QUESTION: shouldn't events return objects instead of strings?
+    def events(state=current_state)
+      events = @instance.class.aasm.events.values.select {|e| e.transitions_from_state?(state) }
+      events.map {|e| e.name}
+    end
+
+    # filters the results of events_for_current_state so that only those that
+    # are really currently possible (given transition guards) are shown.
+    # QUESTION: what about events.permissible ?
+    def permissible_events
+      events.select{ |e| @instance.send(("may_" + e.to_s + "?").to_sym) }
+    end
+
+    def state_object_for_name(name)
+      obj = @instance.class.aasm.states.find {|s| s == name}
+      raise AASM::UndefinedState, "State :#{name} doesn't exist" if obj.nil?
+      obj
+    end
+
+    def determine_state_name(state)
+      case state
+        when Symbol, String
+          state
+        when Proc
+          state.call(@instance)
+        else
+          raise NotImplementedError, "Unrecognized state-type given.  Expected Symbol, String, or Proc."
+      end
+    end
+
+    def may_fire_event?(name, *args)
+      event = @instance.class.aasm.events[name]
+      event.may_fire?(@instance, *args)
+    end
+
+    def set_current_state_with_persistence(state)
+      save_success = @instance.aasm_write_state(state)
+      self.current_state = state if save_success
+      save_success
+    end
+
+  end
+end

data/lib/aasm/localizer.rb

@@ -0,0 +1,54 @@
+module AASM
+  class Localizer
+    def human_event_name(klass, event)
+      checklist = ancestors_list(klass).inject([]) do |list, ancestor|
+        list << :"#{i18n_scope(klass)}.events.#{i18n_klass(ancestor)}.#{event}"
+        list
+      end
+      translate_queue(checklist) || I18n.translate(checklist.shift, :default => event.to_s.humanize)
+    end
+
+    def human_state_name(klass, state)
+      checklist = ancestors_list(klass).inject([]) do |list, ancestor|
+        list << item_for(klass, state, ancestor)
+        list << item_for(klass, state, ancestor, :old_style => true)
+        list
+      end
+      translate_queue(checklist) || I18n.translate(checklist.shift, :default => state.to_s.humanize)
+    end
+
+  private
+
+    def item_for(klass, state, ancestor, options={})
+      separator = options[:old_style] ? '.' : '/'
+      :"#{i18n_scope(klass)}.attributes.#{i18n_klass(ancestor)}.#{klass.aasm_column}#{separator}#{state}"
+    end
+
+    def translate_queue(checklist)
+      (0...(checklist.size-1)).each do |i|
+        begin
+          return I18n.translate(checklist.shift, :raise => true)
+        rescue I18n::MissingTranslationData
+          # that's okay
+        end
+      end
+      nil
+    end
+
+    # added for rails 2.x compatibility
+    def i18n_scope(klass)
+      klass.respond_to?(:i18n_scope) ? klass.i18n_scope : :activerecord
+    end
+
+    # added for rails < 3.0.3 compatibility
+    def i18n_klass(klass)
+      klass.model_name.respond_to?(:i18n_key) ? klass.model_name.i18n_key : klass.name.underscore
+    end
+
+    def ancestors_list(klass)
+      klass.ancestors.select do |ancestor|
+        ancestor.respond_to?(:model_name) unless ancestor == ActiveRecord::Base
+      end
+    end
+  end
+end # AASM

data/lib/aasm/persistence.rb

@@ -1,20 +1,28 @@
 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}
+    class << self
 
-      require File.join(File.dirname(__FILE__), 'persistence', 'base')
-      require File.join(File.dirname(__FILE__), 'persistence', 'read_state')
-      if hierarchy.include?("ActiveRecord::Base")
-        require File.join(File.dirname(__FILE__), 'persistence', 'active_record_persistence')
-        base.send(:include, AASM::Persistence::ActiveRecordPersistence)
-      elsif hierarchy.include?("Mongoid::Document")
-        require File.join(File.dirname(__FILE__), 'persistence', 'mongoid_persistence')
-        base.send(:include, AASM::Persistence::MongoidPersistence)
+      def load_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_files_for(:active_record)
+          base.send(:include, AASM::Persistence::ActiveRecordPersistence)
+        elsif hierarchy.include?("Mongoid::Document")
+          require_files_for(:mongoid)
+          base.send(:include, AASM::Persistence::MongoidPersistence)
+        end
       end
-    end
+
+    private
+
+      def require_files_for(persistence)
+        ['base', "#{persistence}_persistence"].each do |file_name|
+          require File.join(File.dirname(__FILE__), 'persistence', file_name)
+        end
+      end
+
+    end # class << self
   end
 end # AASM

data/lib/aasm/persistence/active_record_persistence.rb

@@ -6,11 +6,6 @@ module AASM
       # * extends the model with ClassMethods
       # * includes InstanceMethods
       #
-      # Unless the corresponding methods are already defined, it includes
-      # * ReadState
-      # * WriteState
-      # * WriteStateWithoutPersistence
-      #
       # Adds
       #
       #   before_validation :aasm_ensure_initial_state, :on => :create
@@ -32,12 +27,9 @@ module AASM
       #   end
       #
       def self.included(base)
-        base.extend AASM::Persistence::Base::ClassMethods
+        base.send(:include, AASM::Persistence::Base)
         base.extend AASM::Persistence::ActiveRecordPersistence::ClassMethods
         base.send(:include, AASM::Persistence::ActiveRecordPersistence::InstanceMethods)
-        base.send(:include, AASM::Persistence::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 ActiveRecord::VERSION::MAJOR >= 3
           base.before_validation(:aasm_ensure_initial_state, :on => :create)
@@ -76,25 +68,49 @@ module AASM
 
       module InstanceMethods
 
-        # Returns the current aasm_state of the object.  Respects reload and
-        # any changes made to the aasm_state field directly
+        # Writes <tt>state</tt> to the state column and persists it to the database
         #
-        # Internally just calls <tt>aasm_read_state</tt>
+        #   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)
+          old_value = read_attribute(self.class.aasm_column)
+          write_attribute(self.class.aasm_column, state.to_s)
+
+          success = if AASM::StateMachine[self.class].config.skip_validation_on_save
+            self.class.update_all({ self.class.aasm_column => state.to_s }, self.class.primary_key => self.id) == 1
+          else
+            self.save
+          end
+          unless success
+            write_attribute(self.class.aasm_column, old_value)
+            return false
+          end
+
+          true
+        end
+
+        # Writes <tt>state</tt> to the state column, but does not persist it to the database
         #
         #   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.close
+        #   foo.aasm_current_state # => :closed
+        #   Foo.find(1).aasm_current_state # => :opened
+        #   foo.save
         #   foo.aasm_current_state # => :closed
-        #   foo.reload
-        #   foo.aasm_current_state # => :pending
+        #   Foo.find(1).aasm_current_state # => :closed
         #
-        def aasm_current_state
-          @current_state = aasm_read_state
+        # 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
 
-        private
+      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
@@ -112,7 +128,7 @@ module AASM
         #   foo.aasm_state # => nil
         #
         def aasm_ensure_initial_state
-          aasm_enter_initial_state if send(self.class.aasm_column).blank?
+          aasm.enter_initial_state if send(self.class.aasm_column).blank?
         end
 
         def aasm_fire_event(name, options, *args)
@@ -120,54 +136,7 @@ module AASM
             super
           end
         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
-        #
-        #   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)
-          old_value = read_attribute(self.class.aasm_column)
-          write_attribute(self.class.aasm_column, state.to_s)
-
-          success = if AASM::StateMachine[self.class].config.skip_validation_on_save
-            self.class.update_all({ self.class.aasm_column => state.to_s }, self.class.primary_key => self.id) == 1
-          else
-            self.save
-          end
-          unless success
-            write_attribute(self.class.aasm_column, old_value)
-            return false
-          end
-
-          true
-        end
-      end
+      end # InstanceMethods
 
     end
   end