aasm 4.2.0 → 4.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cd80c470206244734a77fe540848e299e87dab9f
-  data.tar.gz: 28b464e9012345a46ddc5595d29541d52a358bf4
+  metadata.gz: 1b51607dcaee12f000a23ee83033925bf03dcee7
+  data.tar.gz: c367dd718de8264432f332ff626fc8aff05581e3
 SHA512:
-  metadata.gz: 46d54cc3e2e66387916f7f1edfe03f3de9cb09578a8b485ea084bd68ba854f9003d1fd00de18a6d7c40984a0b0d2fe1b2d7bc4b3610e7d421c724e2f5af7a9f1
-  data.tar.gz: cb2506c237a22fc3dc04869791d15f85614ac33096ccff60fa5a6dd40830d2325375ed13cdc3abf2adc02c958a336362027393c6ee0351bc463cf47cb0b9020f
+  metadata.gz: 4a3750ab5b7758679ed9ca66fc35f04cf69347a09bc03070fd514ccbd3c111f129f907e6c4e387cf253441daf7e8e79a1045ea64da43296803434711c56a2b84
+  data.tar.gz: d82ff5d11b0ebae4112277283706e3bd9774517e6f4a7bece806360deda054c811ccebccfefd59c05244dd05e5351f21672932ba8071a8c2626077ba76bc585d

data/CHANGELOG.md

@@ -1,6 +1,9 @@
 # CHANGELOG
 
-## 4.3.0 (not yet released)
+## 4.3.0
+
+ * add support for multiple state machines per class (see [issue #158](https://github.com/aasm/aasm/issues/158) and [issue #240](https://github.com/aasm/aasm/issues/240) for details)
+    * special thanks to [@evadne](https://github.com/evadne) for testing this feature, and providing comments and patches (see [issue #245](https://github.com/aasm/aasm/issues/245) for details)
 
 ## 4.2.0
 

data/Gemfile

@@ -9,7 +9,7 @@ gem 'mongoid', '~>4.0' if Gem::Version.create(RUBY_VERSION.dup) >= Gem::Version.
 gem 'sequel'
 # Since mongoid V4 requires incompatible bson V2, cannot have mongoid (V4 or greater)
 # and mongo_mapper ( or mongo ) in the same application
-#gem 'mongo_mapper', '~> 0.13'
-#gem 'bson_ext',                          :platforms => :ruby
+# gem 'mongo_mapper', '~> 0.13'
+# gem 'bson_ext',                          :platforms => :ruby
 
 gemspec

data/PLANNED_CHANGES.md

@@ -1,7 +1,27 @@
-# Planned changes for AASM 4.1
+# Planned changes
 
- * remove support for `:on_transition` callback
+## later
 
-# Planned changes for AASM 4.0
+   * drop support for aasm_column ?
 
- * nothing left
+# Currently working on
+
+
+# Changes so far
+
+## version 4.3
+
+ * add support for multiple state machines per class
+   * class- and instance-level `aasm` methods accept a state machine selector
+     (aka the state machine _name_)
+     * if no selector/name is provided, `:default` will be used
+   * duplicate definitions of states and events will issue warnings
+   * check all tests
+     * _ActiveRecord_
+     * _Mongoid_
+     * _MongoMapper_
+     * _Sequel_
+   * what happen's if someone accesses `aasm`, but has defined a
+     state machine for `aasm(:my_name)`?
+   * documentation
+ * drop support for find_in_state, count_in_state, calculate_in_state, with_state_scope

data/README.md

@@ -99,11 +99,11 @@ class Job
     state :running
 
     event :run, :after => :notify_somebody do
-      transitions :from => :sleeping, :to => :running, :after => Proc.new {|*args| set_process(*args) } do
-        before do
-          log('Preparing to run')
-        end
+      before do
+        log('Preparing to run')
       end
+
+      transitions :from => :sleeping, :to => :running, :after => Proc.new {|*args| set_process(*args) }
     end
 
     event :sleep do
@@ -312,9 +312,79 @@ job.stage1_completed
 job.aasm.current_state # stage3
 ```
 
+
+### Multiple state machine per class
+
+Multiple state machines per class are supported. Be aware though, that _AASM_ has been
+built with one state machine per class in mind. Nonetheless, here's how to do it:
+
+```ruby
+class SimpleMultipleExample
+  include AASM
+  aasm(:move) do
+    state :standing, :initial => true
+    state :walking
+    state :running
+
+    event :walk do
+      transitions :from => :standing, :to => :walking
+    end
+    event :run do
+      transitions :from => [:standing, :walking], :to => :running
+    end
+    event :hold do
+      transitions :from => [:walking, :running], :to => :standing
+    end
+  end
+
+  aasm(:work) do
+    state :sleeping, :initial => true
+    state :processing
+
+    event :start do
+      transitions :from => :sleeping, :to => :processing
+    end
+    event :stop do
+      transitions :from => :processing, :to => :sleeping
+    end
+  end
+end
+
+simple = SimpleMultipleExample.new
+
+simple.aasm(:move).current_state
+# => :standing
+simple.aasm(:work).current
+# => :sleeping
+
+simple.start
+simple.aasm(:move).current_state
+# => :standing
+simple.aasm(:work).current
+# => :processing
+
+```
+
+_AASM_ doesn't prohibit to define the same event in both state machines. The
+latest definition "wins" and overrides previous definitions. A warning is issued:
+`SimpleMultipleExample: The event name run is already used!`.
+
+All _AASM_ class- and instance-level `aasm` methods accept a state machine selector.
+So, for example, to use inspection on a class level, you have to use
+
+```ruby
+SimpleMultipleExample.aasm(:work).states
+# => [:standing, :walking, :running]
+```
+
+*Final note*: Support for multiple state machines per class is a pretty new feature
+(since version `4.3`), so please bear with us in case it doesn't as expected.
+
+
+
 ### ActiveRecord
 
-AASM comes with support for ActiveRecord and allows automatical persisting of the object's
+AASM comes with support for ActiveRecord and allows automatic persisting of the object's
 state in the database.
 
 ```ruby

data/lib/aasm/aasm.rb

@@ -8,36 +8,50 @@ module AASM
 
     # do not overwrite existing state machines, which could have been created by
     # inheritance, see class method inherited
-    AASM::StateMachine[base] ||= AASM::StateMachine.new
+    AASM::StateMachine[base] ||= {}
 
     AASM::Persistence.load_persistence(base)
     super
   end
 
   module ClassMethods
-
     # make sure inheritance (aka subclassing) works with AASM
     def inherited(base)
-      AASM::StateMachine[base] = AASM::StateMachine[self].clone
+      AASM::StateMachine[base] = {}
+      AASM::StateMachine[self].keys.each do |state_machine_name|
+        AASM::StateMachine[base][state_machine_name] = AASM::StateMachine[self][state_machine_name].clone
+      end
       super
     end
 
     # this is the entry point for all state and event definitions
-    def aasm(options={}, &block)
-      @aasm ||= AASM::Base.new(self, options)
-      @aasm.instance_eval(&block) if block # new DSL
-      @aasm
-    end
+    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
+        # using the default state_machine_name
+        state_machine_name = :default
+        options = args[0] || {}
+      end
+
+      AASM::StateMachine[self][state_machine_name] ||= AASM::StateMachine.new(state_machine_name)
 
-    # deprecated, remove in version 4.1
-    def aasm_human_event_name(event) # event_name?
-      warn '[DEPRECATION] AASM: aasm_human_event_name is deprecated, use aasm.human_event_name instead'
-      aasm.human_event_name(event)
+      @aasm ||= {}
+      @aasm[state_machine_name] ||= AASM::Base.new(self, state_machine_name, AASM::StateMachine[self][state_machine_name], options)
+      @aasm[state_machine_name].instance_eval(&block) if block # new DSL
+      @aasm[state_machine_name]
     end
   end # ClassMethods
 
-  def aasm
-    @aasm ||= AASM::InstanceBase.new(self)
+  # this is the entry point for all instance-level access to AASM
+  def aasm(name=:default)
+    unless AASM::StateMachine[self.class][name.to_sym]
+      raise AASM::UnknownStateMachineError.new("There is no state machine with the name '#{name}' defined in #{self.class.name}!")
+    end
+    @aasm ||= {}
+    @aasm[name.to_sym] ||= AASM::InstanceBase.new(self, name.to_sym)
   end
 
 private
@@ -56,72 +70,72 @@ private
     return args
   end
 
-  def aasm_fire_event(event_name, options, *args, &block)
-    event = self.class.aasm.state_machine.events[event_name]
+  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_object_for_name(aasm.current_state)
+      old_state = aasm(state_machine_name).state_object_for_name(aasm(state_machine_name).current_state)
 
       # new event before callback
       event.fire_callbacks(
         :before,
         self,
-        *process_args(event, aasm.current_state, *args)
+        *process_args(event, aasm(state_machine_name).current_state, *args)
       )
 
       if may_fire_to = event.may_fire?(self, *args)
         old_state.fire_callbacks(:before_exit, self,
-          *process_args(event, aasm.current_state, *args))
+          *process_args(event, aasm(state_machine_name).current_state, *args))
         old_state.fire_callbacks(:exit, self,
-          *process_args(event, aasm.current_state, *args)) # TODO: remove for AASM 4?
+          *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(event, old_state, new_state_name, options, *args, &block)
+          aasm_fired(state_machine_name, event, old_state, new_state_name, options, *args, &block)
         else
-          aasm_failed(event_name, old_state)
+          aasm_failed(state_machine_name, event_name, old_state)
         end
       else
-        aasm_failed(event_name, old_state)
+        aasm_failed(state_machine_name, event_name, old_state)
       end
     rescue StandardError => e
-      event.fire_callbacks(:error, self, e, *process_args(event, aasm.current_state, *args)) || raise(e)
+      event.fire_callbacks(:error, self, e, *process_args(event, aasm(state_machine_name).current_state, *args)) || raise(e)
     end
   end
 
-  def aasm_fired(event, old_state, new_state_name, options, *args)
+  def aasm_fired(state_machine_name, event, old_state, new_state_name, options, *args)
     persist = options[:persist]
 
-    new_state = aasm.state_object_for_name(new_state_name)
+    new_state = aasm(state_machine_name).state_object_for_name(new_state_name)
 
     new_state.fire_callbacks(:before_enter, self,
-      *process_args(event, aasm.current_state, *args))
+      *process_args(event, aasm(state_machine_name).current_state, *args))
 
     new_state.fire_callbacks(:enter, self,
-      *process_args(event, aasm.current_state, *args)) # TODO: remove for AASM 4?
+      *process_args(event, aasm(state_machine_name).current_state, *args)) # TODO: remove for AASM 4?
 
     persist_successful = true
     if persist
-      persist_successful = aasm.set_current_state_with_persistence(new_state_name)
+      persist_successful = aasm(state_machine_name).set_current_state_with_persistence(new_state_name)
       if persist_successful
         yield if block_given?
         event.fire_callbacks(:success, self)
       end
     else
-      aasm.current_state = new_state_name
+      aasm(state_machine_name).current_state = new_state_name
       yield if block_given?
     end
 
     if persist_successful
       old_state.fire_callbacks(:after_exit, self,
-        *process_args(event, aasm.current_state, *args))
+        *process_args(event, aasm(state_machine_name).current_state, *args))
       new_state.fire_callbacks(:after_enter, self,
-        *process_args(event, aasm.current_state, *args))
+        *process_args(event, aasm(state_machine_name).current_state, *args))
       event.fire_callbacks(
         :after,
         self,
         *process_args(event, old_state.name, *args)
       )
 
-      self.aasm_event_fired(event.name, old_state.name, aasm.current_state) if self.respond_to?(:aasm_event_fired)
+      self.aasm_event_fired(event.name, old_state.name, aasm(state_machine_name).current_state) if self.respond_to?(:aasm_event_fired)
     else
       self.aasm_event_failed(event.name, old_state.name) if self.respond_to?(:aasm_event_failed)
     end
@@ -129,13 +143,13 @@ private
     persist_successful
   end
 
-  def aasm_failed(event_name, old_state)
+  def aasm_failed(state_machine_name, event_name, old_state)
     if self.respond_to?(:aasm_event_failed)
       self.aasm_event_failed(event_name, old_state.name)
     end
 
-    if AASM::StateMachine[self.class].config.whiny_transitions
-      raise AASM::InvalidTransition.new(self, event_name) 
+    if AASM::StateMachine[self.class][state_machine_name].config.whiny_transitions
+      raise AASM::InvalidTransition.new(self, event_name, state_machine_name)
     else
       false
     end

data/lib/aasm/base.rb

@@ -3,10 +3,12 @@ module AASM
 
     attr_reader :state_machine
 
-    def initialize(klass, options={}, &block)
+    def initialize(klass, name, state_machine, options={}, &block)
       @klass = klass
-      @state_machine = AASM::StateMachine[@klass]
-      @state_machine.config.column ||= (options[:column] || :aasm_state).to_sym # aasm4
+      @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
 
@@ -31,7 +33,7 @@ module AASM
       # and attribute is directly assigned though
       @klass.class_eval %Q(
         def #{@state_machine.config.column}=(state_name)
-          if self.class.aasm.state_machine.config.no_direct_assignment
+          if self.class.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)'
             )
@@ -64,10 +66,16 @@ module AASM
     def state(name, options={})
       @state_machine.add_state(name, @klass, options)
 
-      @klass.send(:define_method, "#{name}?") do
-        aasm.current_state == name
+      if @klass.instance_methods.include?("#{name}?")
+        warn "#{@klass.name}: The state name #{name} is already used!"
       end
 
+      @klass.class_eval <<-EORUBY, __FILE__, __LINE__ + 1
+        def #{name}?
+          aasm(:#{@name}).current_state == :#{name}
+        end
+      EORUBY
+
       unless @klass.const_defined?("STATE_#{name.upcase}")
         @klass.const_set("STATE_#{name.upcase}", name)
       end
@@ -75,24 +83,30 @@ module AASM
 
     # define an event
     def event(name, options={}, &block)
-      @state_machine.events[name] = AASM::Core::Event.new(name, options, &block)
+      @state_machine.add_event(name, options, &block)
+
+      if @klass.instance_methods.include?("may_#{name}?".to_sym)
+        warn "#{@klass.name}: The event name #{name} is already used!"
+      end
 
       # 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.
-      @klass.send(:define_method, "may_#{name}?") do |*args|
-        aasm.may_fire_event?(name, *args)
-      end
+      @klass.class_eval <<-EORUBY, __FILE__, __LINE__ + 1
+        def may_#{name}?(*args)
+          aasm(:#{@name}).may_fire_event?(:#{name}, *args)
+        end
 
-      @klass.send(:define_method, "#{name}!") do |*args, &block|
-        aasm.current_event = "#{name}!".to_sym
-        aasm_fire_event(name, {:persist => true}, *args, &block)
-      end
+        def #{name}!(*args, &block)
+          aasm(:#{@name}).current_event = :#{name}!
+          aasm_fire_event(:#{@name}, :#{name}, {:persist => true}, *args, &block)
+        end
 
-      @klass.send(:define_method, "#{name}") do |*args, &block|
-        aasm.current_event = name.to_sym
-        aasm_fire_event(name, {:persist => false}, *args, &block)
-      end
+        def #{name}(*args, &block)
+          aasm(:#{@name}).current_event = :#{name}
+          aasm_fire_event(:#{@name}, :#{name}, {:persist => false}, *args, &block)
+        end
+      EORUBY
     end
 
     def states
@@ -122,6 +136,10 @@ module AASM
 
     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])

data/lib/aasm/core/event.rb

@@ -2,10 +2,11 @@ module AASM::Core
   class Event
     include DslHelper
 
-    attr_reader :name, :options
+    attr_reader :name, :state_machine, :options
 
-    def initialize(name, options = {}, &block)
+    def initialize(name, state_machine, options = {}, &block)
       @name = name
+      @state_machine = state_machine
       @transitions = []
       @guards = Array(options[:guard] || options[:guards] || options[:if])
       @unless = Array(options[:unless]) #TODO: This could use a better name
@@ -61,11 +62,11 @@ module AASM::Core
       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(attach_event_guards(definitions.merge(:from => s.to_sym)), &block)
+          @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 @transitions.empty? && definitions[:to]
-          @transitions << AASM::Core::Transition.new(attach_event_guards(definitions), &block)
+          @transitions << AASM::Core::Transition.new(self, attach_event_guards(definitions), &block)
         end
       end
       @transitions
@@ -89,7 +90,7 @@ module AASM::Core
     def _fire(obj, options={}, to_state=nil, *args)
       result = options[:test_only] ? false : nil
       if @transitions.map(&:from).any?
-        transitions = @transitions.select { |t| t.from == obj.aasm.current_state }
+        transitions = @transitions.select { |t| t.from == obj.aasm(state_machine.name).current_state }
         return result if transitions.size == 0
       else
         transitions = @transitions