aasm 2.1.1 → 5.2.0

data/lib/aasm/aasm.rb

@@ -1,185 +1,208 @@
-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
-  def self.Version
-    '2.1.1'
-  end
-
-  class InvalidTransition < RuntimeError
-  end
-
-  class UndefinedState < RuntimeError
-  end
+  # this is used internally as an argument default value to represent no value
+  NO_VALUE = :_aasm_no_value
 
+  # provide a state machine for the including class
+  # make sure to load class methods as well
+  # initialize persistence for the state machine
   def self.included(base) #:nodoc:
     base.extend AASM::ClassMethods
-    AASM::Persistence.set_persistence(base)
-    unless AASM::StateMachine[base]
-      AASM::StateMachine[base] = AASM::StateMachine.new('')
-    end
+
+    # do not overwrite existing state machines, which could have been created by
+    # inheritance, see class method inherited
+    AASM::StateMachineStore.register(base)
+
+    AASM::Persistence.load_persistence(base)
+    super
   end
 
   module ClassMethods
-    def inherited(klass)
-      AASM::StateMachine[klass] = AASM::StateMachine[self].clone
+    # make sure inheritance (aka subclassing) works with AASM
+    def inherited(base)
+      AASM::StateMachineStore.register(base, self)
+
       super
     end
 
-    def aasm_initial_state(set_state=nil)
-      if set_state
-        AASM::StateMachine[self].initial_state = set_state
+    # this is the entry point for all state and event definitions
+    def aasm(*args, &block)
+      if args[0].is_a?(Symbol) || args[0].is_a?(String)
+        # using custom name
+        state_machine_name = args[0].to_sym
+        options = args[1] || {}
       else
-        AASM::StateMachine[self].initial_state
+        # using the default state_machine_name
+        state_machine_name = :default
+        options = args[0] || {}
       end
-    end
 
-    def aasm_initial_state=(state)
-      AASM::StateMachine[self].initial_state = state
-    end
+      AASM::StateMachineStore.fetch(self, true).register(state_machine_name, AASM::StateMachine.new(state_machine_name))
 
-    def aasm_state(name, options={})
-      sm = AASM::StateMachine[self]
-      sm.create_state(name, options)
-      sm.initial_state = name unless sm.initial_state
+      # use a default despite the DSL configuration default.
+      # this is because configuration hasn't been setup for the AASM class but we are accessing a DSL option already for the class.
+      aasm_klass = options[:with_klass] || AASM::Base
 
-      define_method("#{name.to_s}?") do
-        aasm_current_state == name
-      end
-    end
+      raise ArgumentError, "The class #{aasm_klass} must inherit from AASM::Base!" unless aasm_klass.ancestors.include?(AASM::Base)
 
-    def aasm_event(name, options = {}, &block)
-      sm = AASM::StateMachine[self]
-
-      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)
+      @aasm ||= Concurrent::Map.new
+      if @aasm[state_machine_name]
+        # make sure to use provided options
+        options.each do |key, value|
+          @aasm[state_machine_name].state_machine.config.send("#{key}=", value)
+        end
+      else
+        # create a new base
+        @aasm[state_machine_name] = aasm_klass.new(
+          self,
+          state_machine_name,
+          AASM::StateMachineStore.fetch(self, true).machine(state_machine_name),
+          options
+        )
       end
+      @aasm[state_machine_name].instance_eval(&block) if block # new DSL
+      @aasm[state_machine_name]
     end
+  end # ClassMethods
 
-    def aasm_states
-      AASM::StateMachine[self].states
+  # this is the entry point for all instance-level access to AASM
+  def aasm(name=:default)
+    unless AASM::StateMachineStore.fetch(self.class, true).machine(name)
+      raise AASM::UnknownStateMachineError.new("There is no state machine with the name '#{name}' defined in #{self.class.name}!")
     end
-
-    def aasm_events
-      AASM::StateMachine[self].events
-    end
-
-    def aasm_states_for_select
-      AASM::StateMachine[self].states.map { |state| state.for_select }
-    end
-
+    @aasm ||= Concurrent::Map.new
+    @aasm[name.to_sym] ||= AASM::InstanceBase.new(self, name.to_sym)
   end
 
-  # Instance methods
-  def aasm_current_state
-    return @aasm_current_state if @aasm_current_state
+  def initialize_dup(other)
+    @aasm = Concurrent::Map.new
+    super
+  end
 
-    if self.respond_to?(:aasm_read_state) || self.private_methods.include?('aasm_read_state')
-      @aasm_current_state = aasm_read_state
+private
+
+  # Takes args and a from state and removes the first
+  # element from args if it is a valid to_state for
+  # the event given the from_state
+  def process_args(event, from_state, *args)
+    # If the first arg doesn't respond to to_sym then
+    # it isn't a symbol or string so it can't be a state
+    # name anyway
+    return args unless args.first.respond_to?(:to_sym)
+    if event.transitions_from_state(from_state).map(&:to).flatten.include?(args.first)
+      return args[1..-1]
     end
-    return @aasm_current_state if @aasm_current_state
-    aasm_determine_state_name(self.class.aasm_initial_state)
+    return args
   end
 
-  def aasm_events_for_current_state
-    aasm_events_for_state(aasm_current_state)
-  end
+  def aasm_fire_event(state_machine_name, event_name, options, *args, &block)
+    event = self.class.aasm(state_machine_name).state_machine.events[event_name]
+    begin
+      old_state = aasm(state_machine_name).state_object_for_name(aasm(state_machine_name).current_state)
 
-  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
+      fire_default_callbacks(event, *process_args(event, aasm(state_machine_name).current_state, *args))
 
-  private
-  def set_aasm_current_state_with_persistence(state)
-    save_success = true
-    if self.respond_to?(:aasm_write_state) || self.private_methods.include?('aasm_write_state')
-      save_success = aasm_write_state(state)
+      if may_fire_to = event.may_fire?(self, *args)
+        fire_exit_callbacks(old_state, *process_args(event, aasm(state_machine_name).current_state, *args))
+        if new_state_name = event.fire(self, {:may_fire => may_fire_to}, *args)
+          aasm_fired(state_machine_name, event, old_state, new_state_name, options, *args, &block)
+        else
+          aasm_failed(state_machine_name, event_name, old_state, event.failed_callbacks)
+        end
+      else
+        aasm_failed(state_machine_name, event_name, old_state, event.failed_callbacks)
+      end
+    rescue StandardError => e
+      event.fire_callbacks(:error, self, e, *process_args(event, aasm(state_machine_name).current_state, *args)) ||
+      event.fire_global_callbacks(:error_on_all_events, self, e, *process_args(event, aasm(state_machine_name).current_state, *args)) ||
+      raise(e)
+      false
+    ensure
+      event.fire_callbacks(:ensure, self, *process_args(event, aasm(state_machine_name).current_state, *args))
+      event.fire_global_callbacks(:ensure_on_all_events, self, *process_args(event, aasm(state_machine_name).current_state, *args))
     end
-    self.aasm_current_state = state if save_success
-
-    save_success
   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 fire_default_callbacks(event, *processed_args)
+    event.fire_global_callbacks(
+      :before_all_events,
+      self,
+      *processed_args
+    )
 
-  def aasm_determine_state_name(state)
-    case state
-    when Symbol, String
-      state
-    when Proc
-      state.call(self)
-    else
-      raise NotImplementedError, "Unrecognized state-type given.  Expected Symbol, String, or Proc."
-    end
+    # new event before callback
+    event.fire_callbacks(
+      :before,
+      self,
+      *processed_args
+    )
   end
 
-  def aasm_state_object_for_state(name)
-    obj = self.class.aasm_states.find {|s| s == name}
-    raise AASM::UndefinedState, "State :#{name} doesn't exist" if obj.nil?
-    obj
+  def fire_exit_callbacks(old_state, *processed_args)
+    old_state.fire_callbacks(:before_exit, self, *processed_args)
+    old_state.fire_callbacks(:exit, self, *processed_args)
   end
 
-  def aasm_fire_event(name, persist, *args)
-    old_state = aasm_state_object_for_state(aasm_current_state)
-    event = self.class.aasm_events[name]
+  def aasm_fired(state_machine_name, event, old_state, new_state_name, options, *args)
+    persist = options[:persist]
 
-    old_state.call_action(:exit, self)
+    new_state = aasm(state_machine_name).state_object_for_name(new_state_name)
+    callback_args = process_args(event, aasm(state_machine_name).current_state, *args)
 
-    # new event before callback
-    event.call_action(:before, self)
-
-    new_state_name = event.fire(self, *args)
-
-    unless new_state_name.nil?
-      new_state = aasm_state_object_for_state(new_state_name)
-    
-      # new before_ callbacks
-      old_state.call_action(:before_exit, self)
-      new_state.call_action(:before_enter, self)
-      
-      new_state.call_action(:enter, self)
-      
-      persist_successful = true
-      if persist
-        persist_successful = set_aasm_current_state_with_persistence(new_state_name)
-        event.execute_success_callback(self) if persist_successful
-      else
-        self.aasm_current_state = new_state_name
-      end
+    new_state.fire_callbacks(:before_enter, self, *callback_args)
 
-      if persist_successful 
-        old_state.call_action(:after_exit, self)
-        new_state.call_action(:after_enter, self)
-        event.call_action(:after, self)
+    new_state.fire_callbacks(:enter, self, *callback_args) # TODO: remove for AASM 4?
 
-        self.aasm_event_fired(name, old_state.name, self.aasm_current_state) if self.respond_to?(:aasm_event_fired)
-      else
-        self.aasm_event_failed(name, old_state.name) if self.respond_to?(:aasm_event_failed)
+    persist_successful = true
+    if persist
+      persist_successful = aasm(state_machine_name).set_current_state_with_persistence(new_state_name)
+      if persist_successful
+        yield if block_given?
+        event.fire_callbacks(:before_success, self, *callback_args)
+        event.fire_transition_callbacks(self, *process_args(event, old_state.name, *args))
+        event.fire_callbacks(:success, self, *callback_args)
       end
+    else
+      aasm(state_machine_name).current_state = new_state_name
+      yield if block_given?
+    end
 
-      persist_successful
+    binding_event = event.options[:binding_event]
+    if binding_event
+      __send__("#{binding_event}#{'!' if persist}")
+    end
+
+    if persist_successful
+      old_state.fire_callbacks(:after_exit, self, *callback_args)
+      new_state.fire_callbacks(:after_enter, self, *callback_args)
+      event.fire_callbacks(
+        :after,
+        self,
+        *process_args(event, old_state.name, *args)
+      )
+      event.fire_global_callbacks(
+        :after_all_events,
+        self,
+        *process_args(event, old_state.name, *args)
+      )
+
+      self.aasm_event_fired(event.name, old_state.name, aasm(state_machine_name).current_state) if self.respond_to?(:aasm_event_fired)
     else
-      if self.respond_to?(:aasm_event_failed)
-        self.aasm_event_failed(name, old_state.name)
-      end
+      self.aasm_event_failed(event.name, old_state.name) if self.respond_to?(:aasm_event_failed)
+    end
 
+    persist_successful
+  end
+
+  def aasm_failed(state_machine_name, event_name, old_state, failures = [])
+    if self.respond_to?(:aasm_event_failed)
+      self.aasm_event_failed(event_name, old_state.name)
+    end
+
+    if AASM::StateMachineStore.fetch(self.class, true).machine(state_machine_name).config.whiny_transitions
+      raise AASM::InvalidTransition.new(self, event_name, state_machine_name, failures)
+    else
       false
     end
   end
+
 end

data/lib/aasm/base.rb

@@ -0,0 +1,290 @@
+require 'logger'
+
+module AASM
+  class Base
+
+    attr_reader :klass, :state_machine
+
+    def initialize(klass, name, state_machine, options={}, &block)
+      @klass = klass
+      @name = name
+      # @state_machine = klass.aasm(@name).state_machine
+      @state_machine = state_machine
+      @state_machine.config.column ||= (options[:column] || default_column).to_sym
+      # @state_machine.config.column = options[:column].to_sym if options[:column] # master
+      @options = options
+
+      # let's cry if the transition is invalid
+      configure :whiny_transitions, true
+
+      # create named scopes for each state
+      configure :create_scopes, true
+
+      # don't store any new state if the model is invalid (in ActiveRecord)
+      configure :skip_validation_on_save, false
+
+      # raise if the model is invalid (in ActiveRecord)
+      configure :whiny_persistence, false
+
+      # Use transactions (in ActiveRecord)
+      configure :use_transactions, true
+
+      # use requires_new for nested transactions (in ActiveRecord)
+      configure :requires_new_transaction, true
+
+      # use pessimistic locking (in ActiveRecord)
+      # true for FOR UPDATE lock
+      # string for a specific lock type i.e. FOR UPDATE NOWAIT
+      configure :requires_lock, false
+
+      # automatically set `"#{state_name}_at" = ::Time.now` on state changes
+      configure :timestamps, false
+
+      # set to true to forbid direct assignment of aasm_state column (in ActiveRecord)
+      configure :no_direct_assignment, false
+
+      # allow a AASM::Base sub-class to be used for state machine
+      configure :with_klass, AASM::Base
+
+      configure :enum, nil
+
+      # Set to true to namespace reader methods and constants
+      configure :namespace, false
+
+      # Configure a logger, with default being a Logger to STDERR
+      configure :logger, Logger.new(STDERR)
+
+      # setup timestamp-setting callback if enabled
+      setup_timestamps(@name)
+
+      # make sure to raise an error if no_direct_assignment is enabled
+      # and attribute is directly assigned though
+      setup_no_direct_assignment(@name)
+    end
+
+    # This method is both a getter and a setter
+    def attribute_name(column_name=nil)
+      if column_name
+        @state_machine.config.column = column_name.to_sym
+      else
+        @state_machine.config.column ||= :aasm_state
+      end
+      @state_machine.config.column
+    end
+
+    def initial_state(new_initial_state=nil)
+      if new_initial_state
+        @state_machine.initial_state = new_initial_state
+      else
+        @state_machine.initial_state
+      end
+    end
+
+    # define a state
+    # args
+    # [0] state
+    # [1] options (or nil)
+    # or
+    # [0] state
+    # [1..] state
+    def state(*args)
+      names, options = interpret_state_args(args)
+      names.each do |name|
+        @state_machine.add_state(name, klass, options)
+
+        aasm_name = @name.to_sym
+        state = name.to_sym
+
+        method_name = namespace? ? "#{namespace}_#{name}" : name
+        safely_define_method klass, "#{method_name}?", -> do
+          aasm(aasm_name).current_state == state
+        end
+
+        const_name = namespace? ? "STATE_#{namespace.upcase}_#{name.upcase}" : "STATE_#{name.upcase}"
+        unless klass.const_defined?(const_name)
+          klass.const_set(const_name, name)
+        end
+      end
+    end
+
+    # define an event
+    def event(name, options={}, &block)
+      @state_machine.add_event(name, options, &block)
+
+      aasm_name = @name.to_sym
+      event = name.to_sym
+
+      # an addition over standard aasm so that, before firing an event, you can ask
+      # may_event? and get back a boolean that tells you whether the guard method
+      # on the transition will let this happen.
+      safely_define_method klass, "may_#{name}?", ->(*args) do
+        aasm(aasm_name).may_fire_event?(event, *args)
+      end
+
+      safely_define_method klass, "#{name}!", ->(*args, &block) do
+        aasm(aasm_name).current_event = :"#{name}!"
+        aasm_fire_event(aasm_name, event, {:persist => true}, *args, &block)
+      end
+
+      safely_define_method klass, name, ->(*args, &block) do
+        aasm(aasm_name).current_event = event
+        aasm_fire_event(aasm_name, event, {:persist => false}, *args, &block)
+      end
+
+      skip_instance_level_validation(event, name, aasm_name, klass)
+
+      # Create aliases for the event methods. Keep the old names to maintain backwards compatibility.
+      if namespace?
+        klass.send(:alias_method, "may_#{name}_#{namespace}?", "may_#{name}?")
+        klass.send(:alias_method, "#{name}_#{namespace}!", "#{name}!")
+        klass.send(:alias_method, "#{name}_#{namespace}", name)
+      end
+
+    end
+
+    def after_all_transitions(*callbacks, &block)
+      @state_machine.add_global_callbacks(:after_all_transitions, *callbacks, &block)
+    end
+
+    def after_all_transactions(*callbacks, &block)
+      @state_machine.add_global_callbacks(:after_all_transactions, *callbacks, &block)
+    end
+
+    def before_all_transactions(*callbacks, &block)
+      @state_machine.add_global_callbacks(:before_all_transactions, *callbacks, &block)
+    end
+
+    def before_all_events(*callbacks, &block)
+      @state_machine.add_global_callbacks(:before_all_events, *callbacks, &block)
+    end
+
+    def after_all_events(*callbacks, &block)
+      @state_machine.add_global_callbacks(:after_all_events, *callbacks, &block)
+    end
+
+    def error_on_all_events(*callbacks, &block)
+      @state_machine.add_global_callbacks(:error_on_all_events, *callbacks, &block)
+    end
+
+    def ensure_on_all_events(*callbacks, &block)
+      @state_machine.add_global_callbacks(:ensure_on_all_events, *callbacks, &block)
+    end
+
+    def states
+      @state_machine.states
+    end
+
+    def events
+      @state_machine.events.values
+    end
+
+    # aasm.event(:event_name).human?
+    def human_event_name(event) # event_name?
+      AASM::Localizer.new.human_event_name(klass, event)
+    end
+
+    def states_for_select
+      states.map { |state| state.for_select }
+    end
+
+    def from_states_for_state(state, options={})
+      if options[:transition]
+        @state_machine.events[options[:transition]].transitions_to_state(state).flatten.map(&:from).flatten
+      else
+
+        events.map {|e| e.transitions_to_state(state)}.flatten.map(&:from).flatten
+      end
+    end
+
+    private
+
+    def default_column
+      @name.to_sym == :default ? :aasm_state : @name.to_sym
+    end
+
+    def configure(key, default_value)
+      if @options.key?(key)
+        @state_machine.config.send("#{key}=", @options[key])
+      elsif @state_machine.config.send(key).nil?
+        @state_machine.config.send("#{key}=", default_value)
+      end
+    end
+
+    def safely_define_method(klass, method_name, method_definition)
+      # Warn if method exists and it did not originate from an enum
+      if klass.method_defined?(method_name) &&
+         ! ( @state_machine.config.enum &&
+             klass.respond_to?(:defined_enums) &&
+             klass.defined_enums.values.any?{ |methods|
+                 methods.keys{| enum | enum + '?' == method_name }
+             })
+        unless AASM::Configuration.hide_warnings
+          @state_machine.config.logger.warn "#{klass.name}: overriding method '#{method_name}'!"
+        end
+      end
+
+      klass.send(:define_method, method_name, method_definition)
+    end
+
+    def namespace?
+      !!@state_machine.config.namespace
+    end
+
+    def namespace
+      if @state_machine.config.namespace == true
+        @name
+      else
+        @state_machine.config.namespace
+      end
+    end
+
+    def interpret_state_args(args)
+      if args.last.is_a?(Hash) && args.size == 2
+        [[args.first], args.last]
+      elsif args.size > 0
+        [args, {}]
+      else
+        raise "count not parse states: #{args}"
+      end
+    end
+
+    def skip_instance_level_validation(event, name, aasm_name, klass)
+      # Overrides the skip_validation config for an instance (If skip validation is set to false in original config) and
+      # restores it back to the original value after the event is fired.
+      safely_define_method klass, "#{name}_without_validation!", ->(*args, &block) do
+        original_config = AASM::StateMachineStore.fetch(self.class, true).machine(aasm_name).config.skip_validation_on_save
+        begin
+          AASM::StateMachineStore.fetch(self.class, true).machine(aasm_name).config.skip_validation_on_save = true unless original_config
+          aasm(aasm_name).current_event = :"#{name}!"
+          aasm_fire_event(aasm_name, event, {:persist => true}, *args, &block)
+        ensure
+          AASM::StateMachineStore.fetch(self.class, true).machine(aasm_name).config.skip_validation_on_save = original_config
+        end
+      end
+    end
+
+    def setup_timestamps(aasm_name)
+      return unless @state_machine.config.timestamps
+
+      after_all_transitions do
+        if self.class.aasm(:"#{aasm_name}").state_machine.config.timestamps
+          ts_setter = "#{aasm(aasm_name).to_state}_at="
+          respond_to?(ts_setter) && send(ts_setter, ::Time.now)
+        end
+      end
+    end
+
+    def setup_no_direct_assignment(aasm_name)
+      return unless @state_machine.config.no_direct_assignment
+
+      @klass.send(:define_method, "#{@state_machine.config.column}=") do |state_name|
+        if self.class.aasm(:"#{aasm_name}").state_machine.config.no_direct_assignment
+          raise AASM::NoDirectAssignmentError.new('direct assignment of AASM column has been disabled (see AASM configuration for this class)')
+        else
+          super(state_name)
+        end
+      end
+    end
+
+  end
+end

data/lib/aasm/configuration.rb

@@ -0,0 +1,48 @@
+module AASM
+  class Configuration
+    # for all persistence layers: which database column to use?
+    attr_accessor :column
+
+    # let's cry if the transition is invalid
+    attr_accessor :whiny_transitions
+
+    # for all persistence layers: create named scopes for each state
+    attr_accessor :create_scopes
+
+    # for ActiveRecord: when the model is invalid, true -> raise, false -> return false
+    attr_accessor :whiny_persistence
+
+    # for ActiveRecord: store the new state even if the model is invalid and return true
+    attr_accessor :skip_validation_on_save
+
+    # for ActiveRecord: use transactions
+    attr_accessor :use_transactions
+
+    # for ActiveRecord: use requires_new for nested transactions?
+    attr_accessor :requires_new_transaction
+
+    # for ActiveRecord: use pessimistic locking
+    attr_accessor :requires_lock
+
+    # automatically set `"#{state_name}_at" = ::Time.now` on state changes
+    attr_accessor :timestamps
+
+    # forbid direct assignment in aasm_state column (in ActiveRecord)
+    attr_accessor :no_direct_assignment
+
+    # allow a AASM::Base sub-class to be used for state machine
+    attr_accessor :with_klass
+
+    attr_accessor :enum
+
+    # namespace reader methods and constants
+    attr_accessor :namespace
+
+    # Configure a logger, with default being a Logger to STDERR
+    attr_accessor :logger
+
+    class << self
+      attr_accessor :hide_warnings
+    end
+  end
+end