aasm 2.1.1 → 5.2.0

data/lib/aasm/core/event.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module AASM::Core
+  class Event
+    include AASM::DslHelper
+
+    attr_reader :name, :state_machine, :options, :default_display_name
+
+    def initialize(name, state_machine, options = {}, &block)
+      @name = name
+      @state_machine = state_machine
+      @transitions = []
+      @valid_transitions = {}
+      @guards = Array(options[:guard] || options[:guards] || options[:if])
+      @unless = Array(options[:unless]) #TODO: This could use a better name
+      @default_display_name = name.to_s.gsub(/_/, ' ').capitalize
+
+      # from aasm4
+      @options = options # QUESTION: .dup ?
+      add_options_from_dsl(@options, [
+        :after,
+        :after_commit,
+        :after_transaction,
+        :before,
+        :before_transaction,
+        :ensure,
+        :error,
+        :before_success,
+        :success,
+      ], &block) if block
+    end
+
+    # called internally by Ruby 1.9 after clone()
+    def initialize_copy(orig)
+      super
+      @transitions = @transitions.collect { |transition| transition.clone }
+      @guards      = @guards.dup
+      @unless      = @unless.dup
+      @options     = {}
+      orig.options.each_pair { |name, setting| @options[name] = setting.is_a?(Hash) || setting.is_a?(Array) ? setting.dup : setting }
+    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=::AASM::NO_VALUE, *args)
+      _fire(obj, {:test_only => true}, to_state, *args) # true indicates test firing
+    end
+
+    def fire(obj, options={}, to_state=::AASM::NO_VALUE, *args)
+      _fire(obj, options, 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.nil? or 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
+
+    def fire_global_callbacks(callback_name, record, *args)
+      invoke_callbacks(state_machine.global_callbacks[callback_name], record, args)
+    end
+
+    def fire_callbacks(callback_name, record, *args)
+      # strip out the first element in args if it's a valid to_state
+      # #given where we're coming from, this condition implies args not empty
+      invoke_callbacks(@options[callback_name], record, args)
+    end
+
+    def fire_transition_callbacks(obj, *args)
+      from_state = obj.aasm(state_machine.name).current_state
+      transition = @valid_transitions[from_state]
+      @valid_transitions[from_state].invoke_success_callbacks(obj, *args) if transition
+    end
+
+    def ==(event)
+      if event.is_a? Symbol
+        name == event
+      else
+        name == event.name
+      end
+    end
+
+    ## DSL interface
+    def transitions(definitions=nil, &block)
+      if definitions # define new transitions
+        # Create a separate transition for each from-state to the given state
+        Array(definitions[:from]).each do |s|
+          @transitions << AASM::Core::Transition.new(self, attach_event_guards(definitions.merge(:from => s.to_sym)), &block)
+        end
+        # Create a transition if :to is specified without :from (transitions from ANY state)
+        if !definitions[:from] && definitions[:to]
+          @transitions << AASM::Core::Transition.new(self, attach_event_guards(definitions), &block)
+        end
+      end
+      @transitions
+    end
+
+    def failed_callbacks
+      transitions.flat_map(&:failures)
+    end
+
+    def to_s
+      name.to_s
+    end
+
+  private
+
+    def attach_event_guards(definitions)
+      unless @guards.empty?
+        given_guards = Array(definitions.delete(:guard) || definitions.delete(:guards) || definitions.delete(:if))
+        definitions[:guards] = @guards + given_guards # from aasm4
+      end
+      unless @unless.empty?
+        given_unless = Array(definitions.delete(:unless))
+        definitions[:unless] = given_unless + @unless
+      end
+      definitions
+    end
+
+    def _fire(obj, options={}, to_state=::AASM::NO_VALUE, *args)
+      result = options[:test_only] ? false : nil
+      clear_failed_callbacks
+      transitions = @transitions.select { |t| t.from == obj.aasm(state_machine.name).current_state || t.from == nil}
+      return result if transitions.size == 0
+
+      if to_state == ::AASM::NO_VALUE
+        to_state = nil
+      elsif !(to_state.respond_to?(:to_sym) && transitions.map(&:to).flatten.include?(to_state.to_sym))
+        # to_state is an argument
+        args.unshift(to_state)
+        to_state = nil
+      end
+      
+      # nop, to_state is a valid to-state
+
+      transitions.each do |transition|
+        next if to_state and !Array(transition.to).include?(to_state)
+        if (options.key?(:may_fire) && transition.eql?(options[:may_fire])) ||
+           (!options.key?(:may_fire) && transition.allowed?(obj, *args))
+
+          if options[:test_only]
+            result = transition
+          else
+            result = to_state || Array(transition.to).first
+            Array(transition.to).each {|to| @valid_transitions[to] = transition }
+            transition.execute(obj, *args)
+          end
+
+          break
+        end
+      end
+      result
+    end
+
+    def clear_failed_callbacks
+      # https://github.com/aasm/aasm/issues/383, https://github.com/aasm/aasm/issues/599
+      transitions.each { |transition| transition.failures.clear }
+    end
+
+    def invoke_callbacks(code, record, args)
+      Invoker.new(code, record, args)
+             .with_default_return_value(false)
+             .invoke
+    end
+  end
+end # AASM

data/lib/aasm/core/invoker.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module AASM
+  module Core
+    ##
+    # main invoker class which encapsulates the logic
+    # for invoking literal-based, proc-based, class-based
+    # and array-based callbacks for different entities.
+    class Invoker
+      DEFAULT_RETURN_VALUE = true
+
+      ##
+      # Initialize a new invoker instance.
+      # NOTE that invoker must be used per-subject/record
+      #      (one instance per subject/record)
+      #
+      # ==Options:
+      #
+      # +subject+ - invoking subject, may be Proc,
+      #             Class, String, Symbol or Array
+      # +record+  - invoking record
+      # +args+    - arguments which will be passed to the callback
+
+      def initialize(subject, record, args)
+        @subject = subject
+        @record = record
+        @args = args
+        @options = {}
+        @failures = []
+        @default_return_value = DEFAULT_RETURN_VALUE
+      end
+
+      ##
+      # Pass additional options to concrete invoker
+      #
+      # ==Options:
+      #
+      # +options+ - hash of options which will be passed to
+      #             concrete invokers
+      #
+      # ==Example:
+      #
+      # with_options(guard: proc {...})
+
+      def with_options(options)
+        @options = options
+        self
+      end
+
+      ##
+      # Collect failures to a specified buffer
+      #
+      # ==Options:
+      #
+      # +failures+ - failures buffer to collect failures
+
+      def with_failures(failures)
+        @failures = failures
+        self
+      end
+
+      ##
+      # Change default return value of #invoke method
+      # if none of invokers processed the request.
+      #
+      # The default return value is #DEFAULT_RETURN_VALUE
+      #
+      # ==Options:
+      #
+      # +value+ - default return value for #invoke method
+
+      def with_default_return_value(value)
+        @default_return_value = value
+        self
+      end
+
+      ##
+      # Find concrete invoker for specified subject and invoker it,
+      # or return default value set by #DEFAULT_RETURN_VALUE or
+      # overridden by #with_default_return_value
+
+      # rubocop:disable Metrics/AbcSize
+      def invoke
+        return invoke_array if subject.is_a?(Array)
+        return literal_invoker.invoke if literal_invoker.may_invoke?
+        return proc_invoker.invoke if proc_invoker.may_invoke?
+        return class_invoker.invoke if class_invoker.may_invoke?
+        default_return_value
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      private
+
+      attr_reader :subject, :record, :args, :options, :failures,
+                  :default_return_value
+
+      def invoke_array
+        return subject.all? { |item| sub_invoke(item) } if options[:guard]
+        return subject.all? { |item| !sub_invoke(item) } if options[:unless]
+        subject.map { |item| sub_invoke(item) }
+      end
+
+      def sub_invoke(new_subject)
+        self.class.new(new_subject, record, args)
+            .with_failures(failures)
+            .with_options(options)
+            .invoke
+      end
+
+      def proc_invoker
+        @proc_invoker ||= Invokers::ProcInvoker
+                          .new(subject, record, args)
+                          .with_failures(failures)
+      end
+
+      def class_invoker
+        @class_invoker ||= Invokers::ClassInvoker
+                           .new(subject, record, args)
+                           .with_failures(failures)
+      end
+
+      def literal_invoker
+        @literal_invoker ||= Invokers::LiteralInvoker
+                             .new(subject, record, args)
+                             .with_failures(failures)
+      end
+    end
+  end
+end

data/lib/aasm/core/invokers/base_invoker.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module AASM
+  module Core
+    module Invokers
+      ##
+      # Base concrete invoker class which contain basic
+      # invoking and logging definitions
+      class BaseInvoker
+        attr_reader :failures, :subject, :record, :args, :result
+
+        ##
+        # Initialize a new concrete invoker instance.
+        # NOTE that concrete invoker must be used per-subject/record
+        #      (one instance per subject/record)
+        #
+        # ==Options:
+        #
+        # +subject+ - invoking subject comparable with this invoker
+        # +record+  - invoking record
+        # +args+    - arguments which will be passed to the callback
+
+        def initialize(subject, record, args)
+          @subject = subject
+          @record = record
+          @args = args
+          @result = false
+          @failures = []
+        end
+
+        ##
+        # Collect failures to a specified buffer
+        #
+        # ==Options:
+        #
+        # +failures+ - failures buffer to collect failures
+
+        def with_failures(failures_buffer)
+          @failures = failures_buffer
+          self
+        end
+
+        ##
+        # Execute concrete invoker, log the error and return result
+
+        def invoke
+          return unless may_invoke?
+          log_failure unless invoke_subject
+          result
+        end
+
+        ##
+        # Check if concrete invoker may be invoked for a specified subject
+
+        def may_invoke?
+          raise NoMethodError, '"#may_invoke?" is not implemented'
+        end
+
+        ##
+        # Log failed invoking
+
+        def log_failure
+          raise NoMethodError, '"#log_failure" is not implemented'
+        end
+
+        ##
+        # Execute concrete invoker
+
+        def invoke_subject
+          raise NoMethodError, '"#invoke_subject" is not implemented'
+        end
+      end
+    end
+  end
+end

data/lib/aasm/core/invokers/class_invoker.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module AASM
+  module Core
+    module Invokers
+      ##
+      # Class invoker which allows to use classes which respond to #call
+      # to be used as state/event/transition callbacks.
+      class ClassInvoker < BaseInvoker
+        def may_invoke?
+          subject.is_a?(Class) && subject.instance_methods.include?(:call)
+        end
+
+        def log_failure
+          return log_source_location if Method.method_defined?(:source_location)
+          log_method_info
+        end
+
+        def invoke_subject
+          @result = retrieve_instance.call
+        end
+
+        private
+
+        def log_source_location
+          failures << instance.method(:call).source_location.join('#')
+        end
+
+        def log_method_info
+          failures << instance.method(:call)
+        end
+
+        def instance
+          @instance ||= retrieve_instance
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        def retrieve_instance
+          return subject.new if subject_arity.zero?
+          return subject.new(record) if subject_arity == 1
+          return subject.new(record, *args) if subject_arity < 0
+          subject.new(record, *args[0..(subject_arity - 2)])
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        def subject_arity
+          @arity ||= subject.instance_method(:initialize).arity
+        end
+      end
+    end
+  end
+end

data/lib/aasm/core/invokers/literal_invoker.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module AASM
+  module Core
+    module Invokers
+      ##
+      # Literal invoker which allows to use strings or symbols to call
+      # record methods as state/event/transition callbacks.
+      class LiteralInvoker < BaseInvoker
+        def may_invoke?
+          subject.is_a?(String) || subject.is_a?(Symbol)
+        end
+
+        def log_failure
+          failures << subject
+        end
+
+        def invoke_subject
+          @result = exec_subject
+        end
+
+        private
+
+        def subject_arity
+          @arity ||= record.__send__(:method, subject.to_sym).arity
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        def exec_subject
+          raise(*record_error) unless record.respond_to?(subject, true)
+          return record.__send__(subject) if subject_arity.zero?
+          return record.__send__(subject, *args) if subject_arity < 0
+          record.__send__(subject, *args[0..(subject_arity - 1)])
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        def record_error
+          [
+            NoMethodError,
+            'NoMethodError: undefined method ' \
+            "`#{subject}' for #{record.inspect}:#{record.class}"
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/aasm/core/invokers/proc_invoker.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module AASM
+  module Core
+    module Invokers
+      ##
+      # Proc invoker which allows to use Procs as
+      # state/event/transition callbacks.
+      class ProcInvoker < BaseInvoker
+        def may_invoke?
+          subject.is_a?(Proc)
+        end
+
+        def log_failure
+          return log_source_location if Method.method_defined?(:source_location)
+          log_proc_info
+        end
+
+        def invoke_subject
+          @result = if support_parameters?
+                      exec_proc(parameters_to_arity)
+                    else
+                      exec_proc(subject.arity)
+                    end
+        end
+
+        private
+
+        def support_parameters?
+          subject.respond_to?(:parameters)
+        end
+
+        # rubocop:disable Metrics/AbcSize
+        def exec_proc(parameters_size)
+          return record.instance_exec(&subject) if parameters_size.zero?
+          return record.instance_exec(*args, &subject) if parameters_size < 0
+          record.instance_exec(*args[0..(parameters_size - 1)], &subject)
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        def log_source_location
+          failures << subject.source_location.join('#')
+        end
+
+        def log_proc_info
+          failures << subject
+        end
+
+        def parameters_to_arity
+          subject.parameters.inject(0) do |memo, parameter|
+            memo += 1
+            memo *= -1 if parameter[0] == :rest && memo > 0
+            memo
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aasm/core/state.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module AASM::Core
+  class State
+    attr_reader :name, :state_machine, :options, :default_display_name
+
+    def initialize(name, klass, state_machine, options={})
+      @name = name
+      @klass = klass
+      @state_machine = state_machine
+      @default_display_name = name.to_s.gsub(/_/, ' ').capitalize
+      update(options)
+    end
+
+    # called internally by Ruby 1.9 after clone()
+    def initialize_copy(orig)
+      super
+      @options = {}
+      orig.options.each_pair do |name, setting|
+        @options[name] = if setting.is_a?(Hash) || setting.is_a?(Array)
+                           setting.dup
+                         else
+                           setting
+                         end
+      end
+    end
+
+    def ==(state)
+      if state.is_a? Symbol
+        name == state
+      else
+        name == state.name
+      end
+    end
+
+    def <=>(state)
+      if state.is_a? Symbol
+        name <=> state
+      else
+        name <=> state.name
+      end
+    end
+
+    def to_s
+      name.to_s
+    end
+
+    def fire_callbacks(action, record, *args)
+      action = @options[action]
+      catch :halt_aasm_chain do
+        action.is_a?(Array) ?
+                action.each {|a| _fire_callbacks(a, record, args)} :
+                _fire_callbacks(action, record, args)
+      end
+    end
+
+    def display_name
+      @display_name = begin
+        if Module.const_defined?(:I18n)
+          localized_name
+        else
+          @default_display_name
+        end
+      end
+    end
+
+    def localized_name
+      AASM::Localizer.new.human_state_name(@klass, self)
+    end
+    alias human_name localized_name
+
+    def for_select
+      [display_name, name.to_s]
+    end
+
+  private
+
+    def update(options = {})
+      if options.key?(:display)
+        @default_display_name = options.delete(:display)
+      end
+      @options = options
+      self
+    end
+
+    def _fire_callbacks(action, record, args)
+      Invoker.new(action, record, args).invoke
+    end
+
+  end
+end # AASM