aasm 3.0.26 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: affc5be8f824b6ad897f4d8edca0a1809691e4b0
-  data.tar.gz: 6c777aba81646cf8d0ac801a9ecfe5d21c43929e
+  metadata.gz: 624aadcd0801dd7a8fb367c00d29ea7f5dccd6f3
+  data.tar.gz: 8f4d0f3978038a5a16fbe2696efbb1bb1f173603
 SHA512:
-  metadata.gz: 56acaaef0033789a207dbabffa8e0aa088b26f0f7c9796a692992dfea502356a1fbb45131c61bce93c850f0b8b85859a6fa8870394a268e3115c4c88305291a7
-  data.tar.gz: acb7811990e9d2bc678395f1520c553f359432327f18b745a5a4d1e11fe702f87d1166ae18da9f375aac2aca2ac1e0083f283a97d7693f388bacebd74fcbcf9b
+  metadata.gz: 9359ea9f090c25f5ae789f3ef47e3ad8829ebf7074e23cb9fee9738537f9207e96a9c5e6ddbbe592c02b2d80aac18df7673aa3427735b0766b6e9a34d4c62dd9
+  data.tar.gz: ddbfc65e9019d92b165f75ebf170c68682e829ed969d9c743df02dabaa03bc53ca6397d5d5b3bb5a8ebe66cae53621cefd8f74bffc4890536638112a6856bf88

data/.travis.yml

@@ -1,7 +1,7 @@
 language: ruby
 
 rvm:
-  - 1.8.7
+  # - 1.8.7
   - 1.9.2
   - 1.9.3
   - 2.0.0

data/CHANGELOG.md

@@ -4,9 +4,17 @@
 
  * deprecated old aasm_* class methods (old-style DSL), in preparation for AASM v4.0.0
 
+## 3.1.0
+
+ * validating the current state (see [issue #95](https://github.com/aasm/aasm/issues/95), thanks to [@ivantsepp](https://github.com/ivantsepp))
+ * allow configuring behavior of nested transactions (see [issue #107](https://github.com/aasm/aasm/issues/107))
+ * support multiple guards per transition
+ * support event guards (see [issue #85](https://github.com/aasm/aasm/issues/85))
+ * support reading from- and to-state during on_transition callback (see [issue #100](https://github.com/aasm/aasm/issues/100))
+
 ## 3.0.26
 
- * support state.human_name (aliased to state.localized_name) (see [issue #105](https://github.com/aasm/aasm/issues/105)
+ * support state.human_name (aliased to state.localized_name) (see [issue #105](https://github.com/aasm/aasm/issues/105))
 
 ## 3.0.25
 

data/README.md

@@ -1,6 +1,9 @@
 # AASM - Ruby state machines
 
-[![Gem Version](https://badge.fury.io/rb/aasm.png)](http://badge.fury.io/rb/aasm) [![Build Status](https://secure.travis-ci.org/aasm/aasm.png?branch=master)](http://travis-ci.org/aasm/aasm) [![Code Climate](https://codeclimate.com/github/aasm/aasm.png)](https://codeclimate.com/github/aasm/aasm) [![Coverage Status](https://coveralls.io/repos/aasm/aasm/badge.png?branch=master)](https://coveralls.io/r/aasm/aasm)
+<a href="http://badge.fury.io/rb/aasm"><img src="https://badge.fury.io/rb/aasm@2x.png" alt="Gem Version" height="18"></a>
+[![Build Status](https://secure.travis-ci.org/aasm/aasm.png?branch=master)](http://travis-ci.org/aasm/aasm)
+[![Code Climate](https://codeclimate.com/github/aasm/aasm.png)](https://codeclimate.com/github/aasm/aasm)
+[![Coverage Status](https://coveralls.io/repos/aasm/aasm/badge.png?branch=master)](https://coveralls.io/r/aasm/aasm)
 
 This package contains AASM, a library for adding finite state machines to Ruby classes.
 
@@ -91,7 +94,7 @@ class Job
     state :sleeping, :initial => true, :before_enter => :do_something
     state :running
 
-    event :run, :after => Proc.new { |user| notify_somebody(user) } do
+    event :run, :after => Proc.new { do_afterwards } do
       transitions :from => :sleeping, :to => :running, :on_transition => Proc.new {|obj, *args| obj.set_process(*args) }
     end
 
@@ -114,7 +117,7 @@ class Job
     ...
   end
 
-  def notify_somebody(user)
+  def do_afterwards
     ...
   end
 
@@ -122,7 +125,7 @@ end
 ```
 
 In this case `do_something` is called before actually entering the state `sleeping`,
-while `notify_somebody` is called after the transition `run` (from `sleeping` to `running`)
+while `do_afterwards` is called after the transition `run` (from `sleeping` to `running`)
 is finished.
 
 Here you can see a list of all possible callbacks, together with their order of calling:
@@ -149,6 +152,15 @@ In this case the `set_process` would be called with `:defagmentation` argument.
 In case of an error during the event processing the error is rescued and passed to `:error`
 callback, which can handle it or re-raise it for further propagation.
 
+During the `:on_transition` callback (and reliably only then) you can access the
+originating state (the from-state) and the target state (the to state), like this:
+
+```ruby
+  def set_process(name)
+    logger.info "from #{aasm.from_state} to #{aasm.to_state}"
+  end
+```
+
 ### Guards
 
 Let's assume you want to allow particular transitions only if a defined condition is
@@ -190,6 +202,24 @@ job.may_sleep?  # => false
 job.sleep       # => raises AASM::InvalidTransition
 ```
 
+You can even provide a number of guards, which all have to succeed to proceed
+
+```ruby
+    def walked_the_dog?; ...; end
+
+    event :sleep do
+      transitions :from => :running, :to => :sleeping, :guards => [:cleaning_needed?, :walked_the_dog?]
+    end
+```
+
+If you want to provide guards for all transitions withing an event, you can use event guards
+
+```ruby
+    event :sleep, :guards => [:walked_the_dog?] do
+      transitions :from => :running, :to => :sleeping, :guards => [:cleaning_needed?]
+      transitions :from => :cleaning, :to => :sleeping
+    end
+```
 
 ### ActiveRecord
 
@@ -339,6 +369,28 @@ class Job < ActiveRecord::Base
 end
 ```
 
+If you want to encapsulate state changes within an own transaction, the behavior
+of this nested transaction might be confusing. Take a look at
+[ActiveRecord Nested Transactions](http://api.rubyonrails.org/classes/ActiveRecord/Transactions/ClassMethods.html)
+if you want to know more about this. Nevertheless, AASM by default requires a new transaction
+`transaction(:requires_new => true)`. You can override this behavior by changing
+the configuration
+
+```ruby
+class Job < ActiveRecord::Base
+  include AASM
+
+  aasm :requires_new_transaction => false do
+    ...
+  end
+
+  ...
+end
+```
+
+which then leads to `transaction(:requires_new => false)`, the Rails default.
+
+
 ### Column name & migration
 
 As a default AASM uses the column `aasm_state` to store the states. You can override

data/aasm.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |s|
   # s.add_development_dependency 'mongoid' if Gem::Version.create(RUBY_VERSION.dup) >= Gem::Version.create('1.9.3')
   s.add_development_dependency 'rake'
   s.add_development_dependency 'sdoc'
-  s.add_development_dependency 'rspec', '~> 2.14'
+  s.add_development_dependency 'rspec', '>= 2.14'
   s.add_development_dependency 'rr'
   # s.add_development_dependency 'sqlite3'
   s.add_development_dependency 'minitest'

data/lib/aasm/base.rb

@@ -5,24 +5,19 @@ module AASM
       @clazz = clazz
       @state_machine = AASM::StateMachine[@clazz]
       @state_machine.config.column = options[:column].to_sym if options[:column]
+      @options = options
 
-      if options.key?(:whiny_transitions)
-        @state_machine.config.whiny_transitions = options[:whiny_transitions]
-      elsif @state_machine.config.whiny_transitions.nil?
-        @state_machine.config.whiny_transitions = true # this is the default, so let's cry
-      end
+      # let's cry if the transition is invalid
+      configure :whiny_transitions, true
 
-      if options.key?(:create_scopes)
-        @state_machine.config.create_scopes = options[:create_scopes]
-      elsif @state_machine.config.create_scopes.nil?
-        @state_machine.config.create_scopes = true # this is the default, so let's create scopes
-      end
+      # create named scopes for each state
+      configure :create_scopes, true
 
-      if options.key?(:skip_validation_on_save)
-        @state_machine.config.skip_validation_on_save = options[:skip_validation_on_save]
-      elsif @state_machine.config.skip_validation_on_save.nil?
-        @state_machine.config.skip_validation_on_save = false # this is the default, so don't store any new state if the model is invalid
-      end
+      # don't store any new state if the model is invalid
+      configure :skip_validation_on_save, false
+
+      # use requires_new for nested transactions
+      configure :requires_new_transaction, true
     end
 
     def initial_state(new_initial_state=nil)
@@ -87,5 +82,16 @@ module AASM
       end
     end
 
+    private
+
+    def configure(key, default_value)
+      @state_machine.config.send(:new_ostruct_member, key)
+      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
+
   end
 end

data/lib/aasm/event.rb

@@ -6,6 +6,7 @@ module AASM
     def initialize(name, options = {}, &block)
       @name = name
       @transitions = []
+      @guards = Array(options[:guard] || options[:guards])
       update(options, &block)
     end
 
@@ -57,18 +58,28 @@ module AASM
     ## DSL interface
     def transitions(definitions=nil)
       if definitions # define new transitions
-        # Create a separate transition for each from state to the given state
+        # Create a separate transition for each from-state to the given state
         Array(definitions[:from]).each do |s|
-          @transitions << AASM::Transition.new(definitions.merge({:from => s.to_sym}))
+          @transitions << AASM::Transition.new(attach_event_guards(definitions.merge(:from => s.to_sym)))
+        end
+        # Create a transition if :to is specified without :from (transitions from ANY state)
+        if @transitions.empty? && definitions[:to]
+          @transitions << AASM::Transition.new(attach_event_guards(definitions))
         end
-        # Create a transition if to is specified without from (transitions from ANY state)
-        @transitions << AASM::Transition.new(definitions) if @transitions.empty? && definitions[:to]
       end
       @transitions
     end
 
   private
 
+    def attach_event_guards(definitions)
+      unless @guards.empty?
+        given_guards = Array(definitions.delete(:guard) || definitions.delete(:guards))
+        definitions[:guards] = given_guards + @guards
+      end
+      definitions
+    end
+
     def update(options = {}, &block)
       @options = options
       if block then

data/lib/aasm/instance_base.rb

@@ -1,6 +1,8 @@
 module AASM
   class InstanceBase
 
+    attr_accessor :from_state, :to_state
+
     def initialize(instance)
       @instance = instance
     end

data/lib/aasm/persistence/active_record_persistence.rb

@@ -36,8 +36,12 @@ module AASM
         else
           base.before_validation_on_create(:aasm_ensure_initial_state)
         end
+
         # ensure initial aasm state even when validations are skipped
         base.before_create(:aasm_ensure_initial_state)
+
+        # ensure state is in the list of states
+        base.validate :aasm_validate_states
       end
 
       module ClassMethods
@@ -134,7 +138,7 @@ module AASM
         end
 
         def aasm_fire_event(name, options, *args, &block)
-          success = self.class.transaction(:requires_new => true) do
+          success = self.class.transaction(:requires_new => requires_new?) do
             super
           end
 
@@ -145,6 +149,18 @@ module AASM
 
           success
         end
+
+        def requires_new?
+          AASM::StateMachine[self.class].config.requires_new_transaction
+        end
+
+        def aasm_validate_states
+          unless AASM::StateMachine[self.class].config.skip_validation_on_save
+            if aasm.current_state && !aasm.states.include?(aasm.current_state)
+              self.errors.add(AASM::StateMachine[self.class].config.column , "is invalid")
+            end
+          end
+        end
       end # InstanceMethods
 
     end

data/lib/aasm/transition.rb

@@ -4,20 +4,24 @@ module AASM
     alias_method :options, :opts
 
     def initialize(opts)
-      @from, @to, @guard, @on_transition = opts[:from], opts[:to], opts[:guard], opts[:on_transition]
+      @from = opts[:from]
+      @to = opts[:to]
+      @guards = Array(opts[:guard] || opts[:guards])
+      @on_transition = opts[:on_transition]
       @opts = opts
     end
 
     # TODO: should be named allowed? or similar
     def perform(obj, *args)
-      case @guard
+      @guards.each do |guard|
+        case guard
         when Symbol, String
-          obj.send(@guard, *args)
+          return false unless obj.send(guard, *args)
         when Proc
-          @guard.call(obj, *args)
-        else
-          true
+          return false unless guard.call(obj, *args)
+        end
       end
+      true
     end
 
     def execute(obj, *args)
@@ -37,6 +41,9 @@ module AASM
     private
 
     def _execute(obj, on_transition, *args)
+      obj.aasm.from_state = @from if obj.aasm.respond_to?(:from_state=)
+      obj.aasm.to_state = @to if obj.aasm.respond_to?(:to_state=)
+
       case on_transition
       when Proc
         on_transition.arity == 0 ? on_transition.call : on_transition.call(obj, *args)

data/lib/aasm/version.rb

@@ -1,3 +1,3 @@
 module AASM
-  VERSION = "3.0.26"
+  VERSION = "3.1.0"
 end

data/spec/models/guardian.rb

@@ -0,0 +1,48 @@
+class Guardian
+  include AASM
+
+  aasm do
+    state :alpha, :initial => true
+    state :beta
+
+    event :use_one_guard_that_succeeds do
+      transitions :from => :alpha, :to => :beta, :guard => :succeed
+    end
+    event :use_one_guard_that_fails do
+      transitions :from => :alpha, :to => :beta, :guard => :fail
+    end
+
+    event :use_guards_that_succeed do
+      transitions :from => :alpha, :to => :beta, :guards => [:succeed, :another_succeed]
+    end
+    event :use_guards_where_the_first_fails do
+      transitions :from => :alpha, :to => :beta, :guards => [:succeed, :fail]
+    end
+    event :use_guards_where_the_second_fails do
+      transitions :from => :alpha, :to => :beta, :guards => [:fail, :succeed]
+    end
+
+    event :use_event_guards_that_succeed, :guards => [:succeed, :another_succeed] do
+      transitions :from => :alpha, :to => :beta
+    end
+    event :use_event_and_transition_guards_that_succeed, :guards => [:succeed, :another_succeed] do
+      transitions :from => :alpha, :to => :beta, :guards => [:more_succeed]
+    end
+    event :use_event_guards_where_the_first_fails, :guards => [:succeed, :fail] do
+      transitions :from => :alpha, :to => :beta
+    end
+    event :use_event_guards_where_the_second_fails, :guards => [:fail, :succeed] do
+      transitions :from => :alpha, :to => :beta, :guard => :another_succeed
+    end
+    event :use_event_and_transition_guards_where_third_fails, :guards => [:succeed, :another_succeed] do
+      transitions :from => :alpha, :to => :beta, :guards => [:fail]
+    end
+  end
+
+  def fail; false; end
+
+  def succeed; true; end
+  def another_succeed; true; end
+  def more_succeed; true; end
+
+end

data/spec/unit/api_spec.rb

@@ -3,19 +3,19 @@ require 'models/active_record/api.rb'
 
 describe "reading the current state" do
   it "uses the AASM default" do
-    DefaultState.new.aasm.current_state.should eql :alpha
+    expect(DefaultState.new.aasm.current_state).to eql :alpha
   end
 
   it "uses the provided method" do
-    ProvidedState.new.aasm.current_state.should eql :beta
+    expect(ProvidedState.new.aasm.current_state).to eql :beta
   end
 
   it "uses the persistence storage" do
-    PersistedState.new.aasm.current_state.should eql :alpha
+    expect(PersistedState.new.aasm.current_state).to eql :alpha
   end
 
   it "uses the provided method even if persisted" do
-    ProvidedAndPersistedState.new.aasm.current_state.should eql :gamma
+    expect(ProvidedAndPersistedState.new.aasm.current_state).to eql :gamma
   end
 end
 
@@ -23,25 +23,25 @@ describe "writing and persisting the current state" do
   it "uses the AASM default" do
     o = DefaultState.new
     o.release!
-    o.persisted_store.should be_nil
+    expect(o.persisted_store).to be_nil
   end
 
   it "uses the provided method" do
     o = ProvidedState.new
     o.release!
-    o.persisted_store.should eql :beta
+    expect(o.persisted_store).to eql :beta
   end
 
   it "uses the persistence storage" do
     o = PersistedState.new
     o.release!
-    o.persisted_store.should be_nil
+    expect(o.persisted_store).to be_nil
   end
 
   it "uses the provided method even if persisted" do
     o = ProvidedAndPersistedState.new
     o.release!
-    o.persisted_store.should eql :beta
+    expect(o.persisted_store).to eql :beta
   end
 end
 
@@ -49,24 +49,24 @@ describe "writing the current state without persisting it" do
   it "uses the AASM default" do
     o = DefaultState.new
     o.release
-    o.transient_store.should be_nil
+    expect(o.transient_store).to be_nil
   end
 
   it "uses the provided method" do
     o = ProvidedState.new
     o.release
-    o.transient_store.should eql :beta
+    expect(o.transient_store).to eql :beta
   end
 
   it "uses the persistence storage" do
     o = PersistedState.new
     o.release
-    o.transient_store.should be_nil
+    expect(o.transient_store).to be_nil
   end
 
   it "uses the provided method even if persisted" do
     o = ProvidedAndPersistedState.new
     o.release
-    o.transient_store.should eql :beta
+    expect(o.transient_store).to eql :beta
   end
 end