aasm 3.4.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 90aa17e423f74f9397944f3e941fc539833f4a86
-  data.tar.gz: c18f24941a1ed1c7880140decfe262a88b37f3aa
+  metadata.gz: e82947e11b28a1768717833153778b493f638129
+  data.tar.gz: eb74d70ed1a8ddd968aa24db3ec1903d29d332d8
 SHA512:
-  metadata.gz: de15b7a7878ba85fe1da7f7e55bb418b499a31c3a7f3556bd66be0667e077a7c69ca2f02ce8f5066b5274a98639ca4c101f94c28c9bc113a5ba14a70876bb4eb
-  data.tar.gz: 9d3fd63e5bec19aae9234bf8a13a889934fd97202e4c30cdf85bd518176034c95c81a8bbd623298d728d706c46c51086375f162a1364f6c69de90ce8642af5e0
+  metadata.gz: 4144ba3401348e02bfda53f0eff38f7f018b3e8eef93a157bd727ab4bc499a1c645440263bbc405e07da213c553ea9f1bc697c40fcfcb0e79b72cf1bf6dd1a6d
+  data.tar.gz: c80f18c84bf32c1be09220253e438afb8ca249c63c3d68d3ba15bf0669ab71b1b79f6c926affaa3064194cee37be91f5c74e4c290ab82ac277388795c8f35621

data/.gitignore

@@ -16,4 +16,4 @@ TODO
 alto
 .rspec
 .bundle
-
+tags

data/CHANGELOG.md

@@ -1,8 +1,25 @@
 # CHANGELOG
 
-## 3.9.0 (not yet released)
-
- * deprecated old aasm_* class methods (old-style DSL), in preparation for AASM v4.0.0
+## 4.0.0
+
+ * support `if` and `unless` guard syntax: (see [issue #179](https://github.com/aasm/aasm/issues/179) and [issue #181](https://github.com/aasm/aasm/issues/181)), thanks to [@bigtunacan](https://github.com/bigtunacan)
+ * may configure to not allow direct assignment for persisted AASM models (see [issue #53](https://github.com/aasm/aasm/issues/53))
+ * **DSL change**: callbacks don't require `to_state` parameter anymore, but still support it
+   (closing issues
+   [#11](https://github.com/aasm/aasm/issues/11),
+   [#58](https://github.com/aasm/aasm/issues/58) and
+   [#80](https://github.com/aasm/aasm/issues/80)
+   thanks to [@ejlangev](https://github.com/ejlangev))
+ * **DSL change**: `after_commit` hooks are now event-based (see [issue #112](https://github.com/aasm/aasm/issues/112))
+ * **DSL change**: event and state callbacks have been re-ordered; state callbacks are not run anymore if any guard fails
+ * **DSL change**: `:on_transition` renamed to `:after`
+ * **DSL change**: `:on_transition` renamed to `:after`
+ * **DSL change**: transition `:after` binding changed (see [issue #59](https://github.com/aasm/aasm/issues/59), thanks to [@stiff](https://github.com/stiff))
+ * **DSL change**: instance-based events inspection now returns event instances (instead of the event names as symbol)
+ * **DSL change**: instance-based permissible_events has been removed in favor or events(:permissible => true)
+ * **DSL change**: class-based events now returns a list of Event instances (instead of a hash with event names as keys)
+ * **DSL change**: renamed permissible states and events to permitted states events
+ * removed deprecated methods (mostly the ones prefixed with `aasm_`)
 
 ## 3.4.0
 

data/PLANNED_CHANGES.md

@@ -0,0 +1,7 @@
+# Planned changes for AASM 4.1
+
+ * remove support for `:on_transition` callback
+
+# Planned changes for AASM 4.0
+
+ * nothing left

data/README.md

@@ -94,8 +94,12 @@ class Job
     state :sleeping, :initial => true, :before_enter => :do_something
     state :running
 
-    event :run, :after => Proc.new { do_afterwards } do
-      transitions :from => :sleeping, :to => :running, :on_transition => Proc.new {|obj, *args| obj.set_process(*args) }
+    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
+      end
     end
 
     event :sleep do
@@ -117,7 +121,7 @@ class Job
     ...
   end
 
-  def do_afterwards
+  def notify_somebody(user)
     ...
   end
 
@@ -125,19 +129,31 @@ end
 ```
 
 In this case `do_something` is called before actually entering the state `sleeping`,
-while `do_afterwards` is called after the transition `run` (from `sleeping` to `running`)
+while `notify_somebody` 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:
 
 ```ruby
-  event:before
-    previous_state:before_exit
-      new_state:before_enter
-        ...update state...
-      previous_state:after_exit
-    new_state:after_enter
-  event:after
+begin
+  event           before
+  event           guards              # test run
+  transition      guards              # test run
+  old_state       before_exit
+  old_state       exit
+  new_state       before_enter
+  new_state       enter
+    event         guards
+    transition    guards
+    ...update state...
+    transition    after
+    event         success             # if persist successful
+  old_state       after_exit
+  new_state       after_enter
+  event           after
+rescue
+  event           error
+end
 ```
 
 Also, you can pass parameters to events:
@@ -196,37 +212,37 @@ running the transition. If the guard returns `false` the transition will be
 denied (raising `AASM::InvalidTransition` or returning `false` itself):
 
 ```ruby
-class Job
+class Cleaner
   include AASM
 
   aasm do
-    state :sleeping, :initial => true
-    state :running
+    state :idle, :initial => true
     state :cleaning
 
-    event :run do
-      transitions :from => :sleeping, :to => :running
-    end
-
     event :clean do
-      transitions :from => :running, :to => :cleaning
+      transitions :from => :idle, :to => :cleaning, :guard => :cleaning_needed?
     end
 
-    event :sleep do
-      transitions :from => :running, :to => :sleeping, :guard => :cleaning_needed?
+    event :clean_if_needed do
+      transitions :from => :idle, :to => :cleaning do
+        guard do
+          cleaning_needed?
+        end
+      end
+      transitions :from => :idle, :to => :idle
     end
   end
 
   def cleaning_needed?
     false
   end
-
 end
 
-job = Job.new
-job.run
-job.may_sleep?  # => false
-job.sleep       # => raises AASM::InvalidTransition
+job = Cleaner.new
+job.may_clean?            # => false
+job.clean                 # => raises AASM::InvalidTransition
+job.may_clean_if_needed?  # => true
+job.clean_if_needed!      # idle
 ```
 
 You can even provide a number of guards, which all have to succeed to proceed
@@ -248,6 +264,52 @@ If you want to provide guards for all transitions within an event, you can use e
     end
 ```
 
+If you prefer a more Ruby-like guard syntax, you can use `if` and `unless` as well:
+
+```ruby
+    event :clean do
+      transitions :from => :running, :to => :cleaning, :unless => :cleaning_needed?
+    end
+
+    event :sleep do
+      transitions :from => :running, :to => :sleeping, :if => :cleaning_needed?
+    end
+  end
+```
+
+
+### Transitions
+
+In the event of having multiple transitions for an event, the first transition that successfully completes will stop other transitions in the same event from being processed.
+
+```ruby
+require 'aasm'
+
+class Job
+  include AASM
+
+  aasm do
+    state :stage1, :initial => true
+    state :stage2
+    state :stage3
+    state :completed
+
+    event :stage1_completed do
+      transitions from: :stage1, to: :stage3, guard: :stage2_completed?
+      transitions from: :stage1, to: :stage2
+    end
+  end
+
+  def stage2_completed?
+    true
+  end
+end
+
+job = Job.new
+job.stage1_completed
+job.aasm.current_state # stage3
+```
+
 ### ActiveRecord
 
 AASM comes with support for ActiveRecord and allows automatical persisting of the object's
@@ -305,6 +367,34 @@ class Job < ActiveRecord::Base
 end
 ```
 
+If you want to make sure that the _AASM_ column for storing the state is not directly assigned,
+configure _AASM_ to not allow direct assignment, like this:
+
+```ruby
+class Job < ActiveRecord::Base
+  include AASM
+
+  aasm :no_direct_assignment => true do
+    state :sleeping, :initial => true
+    state :running
+
+    event :run do
+      transitions :from => :sleeping, :to => :running
+    end
+  end
+
+end
+```
+
+resulting in this:
+
+```ruby
+job = Job.create
+job.aasm_state # => 'sleeping'
+job.aasm_state = :running # => raises AASM::NoDirectAssignmentError
+job.aasm_state # => 'sleeping'
+```
+
 #### ActiveRecord enums
 
 You can use
@@ -387,7 +477,7 @@ class Job < ActiveRecord::Base
   end
 
   def self.sleeping
-    "This method name is in already use"
+    "This method name is already in use"
   end
 end
 ```
@@ -398,7 +488,7 @@ class JobsController < ApplicationController
     @running_jobs = Job.running
     @recent_cleaning_jobs = Job.cleaning.where('created_at >=  ?', 3.days.ago)
 
-    # @sleeping_jobs = Job.sleeping   #=> "This method name is in already use"
+    # @sleeping_jobs = Job.sleeping   #=> "This method name is already in use"
   end
 end
 ```
@@ -434,9 +524,9 @@ class Job < ActiveRecord::Base
 
   aasm do
     state :sleeping, :initial => true
-    state :running, :after_commit => :notify_about_running_job
+    state :running
 
-    event :run do
+    event :run, :after_commit => :notify_about_running_job do
       transitions :from => :sleeping, :to => :running
     end
   end
@@ -502,24 +592,27 @@ end
 
 ### Inspection
 
-AASM supports a couple of methods to find out which states or events are provided or permissible.
+AASM supports a couple of methods to find out which states or events are provided or permitted.
 
-Given the `Job` class from above:
+Given this `Job` class:
 
 ```ruby
-job = Job.new
-
-job.aasm.states.map(&:name)
+# show all states
+Job.aasm.states.map(&:name)
 => [:sleeping, :running, :cleaning]
 
-job.aasm.states(:permissible => true).map(&:name)
+job = Job.new
+
+# show all permitted (reachable / possible) states
+job.aasm.states(:permitted => true).map(&:name)
 => [:running]
 job.run
-job.aasm.states(:permissible => true).map(&:name)
+job.aasm.states(:permitted => true).map(&:name)
 => [:cleaning, :sleeping]
 
-job.aasm.events
-=> [:run, :clean, :sleep]
+# show all possible (triggerable) events (allowed by transitions)
+job.aasm.events.map(&:name)
+=> [:sleep]
 ```
 
 

data/README_FROM_VERSION_3_TO_4.md

@@ -0,0 +1,240 @@
+# Migrating from _AASM_ version 3 to 4
+
+## Must
+
+### Callback order has been changed
+
+The first callback to be run is `:before` of the event. A state's `:before_exit' callback
+is now run directly before its `:exit` callback. Event-based guards are now run before
+any of the transition guards are run. And finally, before running any state callbacks,
+all (event- and transition-based) guards are run to check whether the state callbacks
+can be run or not.
+
+
+### Callback `:on_transition` renamed to `:after` and changed its binding
+
+The transition callback `:on_transition` has been renamed to `:after` in order
+to make clear it is being called (namely _after_ doing the transition).
+
+Furthermore, in alignment with the other callbacks, it's not receiving the object
+at hand as first parameter and binds the current object to self.
+
+In summary, change from
+
+```ruby
+  aasm do
+    ...
+      transitions :from => :from_state, :to => :to_state, :on_transition => :do_something
+    ...
+  end
+
+  ...
+  def some_other_method(arg)
+    ...
+  end
+
+  def do_something(obj, arg1, arg2)
+    obj.some_other_method(arg1)
+  end
+```
+
+to
+
+```ruby
+  aasm do
+    ...
+      transitions :from => :from_state, :to => :to_state, :after => :do_something
+    ...
+  end
+
+  ...
+  def some_other_method(arg)
+    ...
+  end
+
+  def do_something(arg1, arg2)
+    some_other_method(arg1) # run on the object as self
+  end
+```
+
+
+### `after_commit` hooks are now event-based
+
+The `after_commit` hooks have been move from the state level to the event level.
+So, if you want some code block to be executed after the _AASM_ state has been
+saved **AND** committed, change this code
+
+```ruby
+class Job < ActiveRecord::Base
+  include AASM
+
+  aasm do
+    state :sleeping, :initial => true
+    state :running, :after_commit => :notify_about_running_job
+
+    event :run do
+      transitions :from => :sleeping, :to => :running
+    end
+  end
+
+  def notify_about_running_job
+    ...
+  end
+end
+```
+
+to
+
+```ruby
+class Job < ActiveRecord::Base
+  include AASM
+
+  aasm do
+    state :sleeping, :initial => true
+    state :running
+
+    event :run, :after_commit => :notify_about_running_job do
+      transitions :from => :sleeping, :to => :running
+    end
+  end
+
+  def notify_about_running_job
+    ...
+  end
+end
+```
+
+
+### Instance-level inspection
+
+Listing events for the current state now returns Event objects instead of event names (as symbols). So, change from
+
+```ruby
+job = Job.new
+
+job.aasm.events
+# => [:run]
+```
+
+to
+
+```ruby
+job = Job.new
+
+job.aasm.events.map(&:name)
+# => [:run]
+```
+
+Retrieving the list of permitted events has now been integrated into the `events` method. Change from
+
+```ruby
+job = Job.new
+
+job.aasm.permissible_events
+# => [:run]
+```
+
+to
+
+```ruby
+job = Job.new
+
+job.aasm.events(:permitted => true)
+# => [:run]
+```
+
+Class-based events now return a list of `Event` instances. Change from
+
+```ruby
+Job.aasm.events.values.map(&:name)
+# => [:run]
+```
+
+to
+
+```ruby
+Job.aasm.events.map(&:name)
+# => [:run]
+```
+
+
+## Could
+
+### Triggering an event without _to_state_
+
+When providing parameters to callbacks it is not required to provide the `to_state`
+anymore. So, assuming you have the following class:
+
+```ruby
+class Job
+  include AASM
+
+  aasm do
+    state :sleeping, :initial => true
+    state :running
+
+    event :run do
+      transitions :from => :sleeping, :to => :running, :after => :log
+    end
+  end
+
+  def log(message)
+    logger.info message
+  end
+end
+```
+
+then you could change from
+
+```ruby
+job = Job.new
+job.run(:running, "we want to run")
+```
+
+to this:
+
+```ruby
+job = Job.new
+job.run("we want to run")
+
+job.run(:running, "we want to run") # still supported to select the target state (the _to_state_)
+```
+
+On the other hand, you have to accept the arguments for **all** callback methods (and procs)
+you provide and use. If you don't want to provide these, you can splat them
+
+```ruby
+def before(*args); end
+# or
+def before(*_); end # to indicate that you don't want to use the arguments
+```
+
+### New configuration option: `no_direct_assignment`
+
+If you want to make sure that the _AASM_ column for storing the state is not directly assigned,
+configure _AASM_ to not allow direct assignment, like this:
+
+```ruby
+class Job < ActiveRecord::Base
+  include AASM
+
+  aasm :no_direct_assignment => true do
+    state :sleeping, :initial => true
+    state :running
+
+    event :run do
+      transitions :from => :sleeping, :to => :running
+    end
+  end
+
+end
+```
+
+resulting in this:
+
+```ruby
+job = Job.create
+job.aasm_state # => 'sleeping'
+job.aasm_state = :running # => raises AASM::NoDirectAssignmentError
+job.aasm_state # => 'sleeping'
+```