aasm 3.0.13 → 3.0.14

data/CHANGELOG.md

@@ -1,24 +1,28 @@
 # CHANGELOG
 
+## 3.0.14
+
+ * supporting event inspection for to-states transitions (`Event#transitions_to_state?`)
+
 ## 3.0.13
 
- * supporting ActiveRecord transactions when firing an event
+ * supporting *ActiveRecord* transactions when firing an event
 
 ## 3.0.12
 
- * aasm_from_states_for_state now supports to filter for specific transition
+ * `aasm_from_states_for_state` now supports to filter for specific transition
 
 ## 3.0.11
 
- * added class method aasm_from_states_for_state to retrieve all from states (regarding transitions) for a given state
+ * added class method `aasm_from_states_for_state` to retrieve all from states (regarding transitions) for a given state
 
 ## 3.0.10
 
- * added support for transitions from all other states (thanks to Stefan 'swrobel' Wrobel)
+ * added support for transitions from all other states (thanks to *Stefan 'swrobel' Wrobel*)
 
 ## 3.0.9
 
- * guard checks (e.g. may_edit?) now support guard parameters as well
+ * guard checks (e.g. `may_edit?`) now support guard parameters as well
 
 ## 3.0.8
 
@@ -58,7 +62,7 @@
  * whiny transactions: by default, raise an exception if an event transition is not possible
  * you may disable whiny transactions
 
-## 2.4.0 
+## 2.4.0
 
  * supporting new DSL (which is much shorter)
 

data/README.md

@@ -2,170 +2,278 @@
 
 This package contains AASM, a library for adding finite state machines to Ruby classes.
 
-AASM started as the acts_as_state_machine plugin but has evolved into a more generic library
+AASM started as the *acts_as_state_machine* plugin but has evolved into a more generic library
 that no longer targets only ActiveRecord models. It currently provides adapters for
 [ActiveRecord](http://api.rubyonrails.org/classes/ActiveRecord/Base.html) and
-[Mongoid](http://mongoid.org/), but it can be used for any Ruby class, no matter its
-parent class.
+[Mongoid](http://mongoid.org/), but it can be used for any Ruby class, no matter what
+parent class it has (if any).
 
-### Transaction support
+## Usage
 
-Since version 3.0.13 AASM supports ActiveRecord transactions. So whenever a transition
-callback fails, all changes to any database record are rolled back.
+Adding a state machine is as simple as including the AASM module and start defining
+**states** and **events** together with their **transitions**:
 
-## Features ##
+```ruby
+class Job
+  include AASM
 
-* States
-* Machines
-* Events
-* Transitions
+  aasm do
+    state :sleeping, :initial => true
+    state :running
+    state :cleaning
 
-## New Callbacks ##
+    event :run do
+      transitions :from => :sleeping, :to => :running
+    end
 
-The callback chain & order on a successful event looks like:
+    event :clean do
+      transitions :from => :running, :to => :cleaning
+    end
 
-    oldstate:exit*
-      event:before
-        __find transition, if possible__
-        transition:on_transition*
-          oldstate:before_exit
-            newstate:before_enter
-              newstate:enter*
-              __update state__
-              event:success*
-            oldstate:after_exit
-          newstate:after_enter
-      event:after
-    obj:aasm_event_fired*
+    event :sleep do
+      transitions :from => [:running, :cleaning], :to => :sleeping
+    end
+  end
 
-    (*) marks old callbacks
+end
+```
 
+This provides you with a couple of public methods for instances of the class `Job`:
 
-## Installation ##
+```ruby
+job = Job.new
+job.sleeping? # => true
+job.may_run?  # => true
+job.run
+job.running?  # => true
+job.sleeping? # => false
+job.may_run?  # => false
+job.run       # => raises AASM::InvalidTransition
+```
 
-### Manually from RubyGems.org ###
+If you don't like exceptions and prefer a simple `true` or `false` as response, tell
+AASM not to be *whiny*:
 
-```sh
-% gem install aasm
+```ruby
+class Job
+  ...
+  aasm :whiny_transitions => false do
+    ...
+  end
+end
+
+job.running?  # => true
+job.may_run?  # => false
+job.run       # => false
 ```
 
-### Or if you are using Bundler ###
+### Callbacks
+
+You can define a number of callbacks for your transitions. These methods will be
+called, when certain criteria are met, like entering a particular state:
 
 ```ruby
-# Gemfile
-gem 'aasm'
-```
+class Job
+  include AASM
 
-### Building your own gems ###
+  aasm do
+    state :sleeping, :initial => true, :before_enter => :do_something
+    state :running
 
-```sh
-% rake build
-% sudo gem install pkg/aasm-x.y.z.gem
+    event :run, :after => :notify_somebody do
+      transitions :from => :sleeping, :to => :running
+    end
+
+    event :sleep do
+      transitions :from => :running, :to => :sleeping
+    end
+  end
+
+  def do_something
+    ...
+  end
+
+  def notify_somebody
+    ...
+  end
+
+end
 ```
 
-## Examples ##
+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`)
+is finished.
+
+Here you can see a list of all possible callbacks, together with their order of calling:
 
-### Simple Example ###
+```ruby
+  event:before
+    previous_state:before_exit
+      new_state:before_enter
+        ...update state...
+      previous_state:after_exit
+    new_state:after_enter
+  event:after
+```
 
-Here's a quick example highlighting some of the features.
+### Guards
+
+Let's assume you want to allow particular transitions only if a defined condition is
+given. For this you can set up a guard per transition, which will run before actually
+running the transition. If the guard returns `false` the transition will be
+denied (raising `AASM::InvalidTransition` or returning `false` itself):
 
 ```ruby
-class Conversation
+class Job
   include AASM
 
-  aasm :column => :current_state do  # defaults to aasm_state
-    state :unread, :initial => true
-    state :read
-    state :closed
+  aasm do
+    state :sleeping, :initial => true
+    state :running
+    state :cleaning
 
-    event :view do
-      transitions :to => :read, :from => [:unread]
+    event :run do
+      transitions :from => :sleeping, :to => :running
     end
 
-    event :close do
-      transitions :to => :closed, :from => [:read, :unread]
+    event :clean do
+      transitions :from => :running, :to => :cleaning
     end
+
+    event :sleep do
+      transitions :from => :running, :to => :sleeping, :guard => :cleaning_needed?
+    end
+  end
+
+  def cleaning_needed?
+    false
   end
 
 end
+
+job = Job.new
+job.run
+job.may_sleep?  # => false
+job.sleep       # => raises AASM::InvalidTransition
 ```
 
-### A Slightly More Complex Example ###
 
-This example uses a few of the more complex features available.
+### ActiveRecord
+
+AASM comes with support for ActiveRecord and allows automatical persisting of the object's
+state in the database.
 
 ```ruby
-  class Relationship
-    include AASM
-
-    aasm :column => :status do
-      state :dating,   :enter => :make_happy,        :exit => :make_depressed
-      state :intimate, :enter => :make_very_happy,   :exit => :never_speak_again
-      state :married,  :enter => :give_up_intimacy,  :exit => :buy_exotic_car_and_wear_a_combover
-
-      event :get_intimate do
-        transitions :to => :intimate, :from => [:dating], :guard => :drunk?
-      end
-
-      # Will allow transitioning from any state if guard allows it
-      event :get_married do
-        transitions :to => :married, :guard => :willing_to_give_up_manhood?
-      end
+class Job < ActiveRecord::Base
+  include AASM
+
+  aasm do # default column: aasm_state
+    state :sleeping, :initial => true
+    state :running
+
+    event :run do
+      transitions :from => :sleeping, :to => :running
+    end
+
+    event :sleep do
+      transitions :from => :running, :to => :sleeping
     end
-    aasm_initial_state Proc.new { |relationship| relationship.strictly_for_fun? ? :intimate : :dating }
-
-    def strictly_for_fun?; end
-    def drunk?; end
-    def willing_to_give_up_manhood?; end
-    def make_happy; end
-    def make_depressed; end
-    def make_very_happy; end
-    def never_speak_again; end
-    def give_up_intimacy; end
-    def buy_exotic_car_and_wear_a_combover; end
   end
+
+end
+```
+
+You can tell AASM to auto-save the object or leave it unsaved
+
+```ruby
+job = Job.new
+job.run   # not saved
+job.run!  # saved
 ```
 
-### Callbacks around events ###
+Saving includes running all validations on the `Job` class. If you want make sure
+the state gets saved without running validations (and thereby maybe persisting an
+invalid object state), simply tell AASM to skip the validations:
+
 ```ruby
-  class Relationship
-    include AASM
-
-    aasm do
-      state :dating
-      state :married
-
-      event :get_married,
-            :before => :make_vows,
-            :after => :eat_wedding_cake do
-        transitions :to => :married, :from => [:dating]
-      end
+class Job < ActiveRecord::Base
+  include AASM
+
+  aasm :skip_validation_on_save => true do
+    state :sleeping, :initial => true
+    state :running
+
+    event :run do
+      transitions :from => :sleeping, :to => :running
+    end
+
+    event :sleep do
+      transitions :from => :running, :to => :sleeping
     end
   end
+
+end
 ```
 
-### Persistence example ###
+### Transaction support
+
+Since version *3.0.13* AASM supports ActiveRecord transactions. So whenever a transition
+callback or the state update fails, all changes to any database record are rolled back.
+
+### Column name & migration
+
+As a default AASM uses the column `aasm_state` to store the states. You can override
+this by defining your favorite column name, using `:column` like this:
+
 ```ruby
-  class InvalidPersistor < ActiveRecord::Base
-    include AASM
-    aasm :column => :status, :skip_validation_on_save => true do
-      state :sleeping, :initial => true
-      state :running
-      event :run do
-        transitions :to => :running, :from => :sleeping
-      end
-      event :sleep do
-        transitions :to => :sleeping, :from => :running
-      end
-    end
-    validates_presence_of :name
+class Job < ActiveRecord::Base
+  include AASM
+
+  aasm :column => 'my_state' do
+    ...
   end
+
+end
 ```
-This model can change AASM states which are stored into the database, even if the model itself is invalid!
 
+Whatever column name is used, make sure to add a migration to provide this column
+(of type `string`):
 
+```ruby
+class AddJobState < ActiveRecord::Migration
+  def self.up
+    add_column :jobs, :aasm_state, :string
+  end
+
+  def self.down
+    remove_column :job, :aasm_state
+  end
+end
+```
+
+## Installation ##
+
+### Manually from RubyGems.org ###
+
+```sh
+% gem install aasm
+```
+
+### Or if you are using Bundler ###
+
+```ruby
+# Gemfile
+gem 'aasm'
+```
+
+### Building your own gems ###
+
+```sh
+% rake build
+% sudo gem install pkg/aasm-x.y.z.gem
+```
 
-## Changelog ##
+## Latest changes ##
 
 Look at the [CHANGELOG](https://github.com/aasm/aasm/blob/master/CHANGELOG.md) for details.
 

data/aasm.gemspec

@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'shoulda'
   s.add_development_dependency 'sqlite3'
   s.add_development_dependency 'minitest'
+  # s.add_development_dependency 'debugger'
   s.add_development_dependency 'ruby-debug-completion'
 
   s.files         = `git ls-files`.split("\n")

data/lib/aasm/persistence.rb

@@ -6,6 +6,8 @@ module AASM
       # Use a fancier auto-loading thingy, perhaps.  When there are more persistence engines.
       hierarchy = base.ancestors.map {|klass| klass.to_s}
 
+      require File.join(File.dirname(__FILE__), 'persistence', 'base')
+      require File.join(File.dirname(__FILE__), 'persistence', 'read_state')
       if hierarchy.include?("ActiveRecord::Base")
         require File.join(File.dirname(__FILE__), 'persistence', 'active_record_persistence')
         base.send(:include, AASM::Persistence::ActiveRecordPersistence)

data/lib/aasm/persistence/active_record_persistence.rb

@@ -32,9 +32,10 @@ module AASM
       #   end
       #
       def self.included(base)
+        base.extend AASM::Persistence::Base::ClassMethods
         base.extend AASM::Persistence::ActiveRecordPersistence::ClassMethods
         base.send(:include, AASM::Persistence::ActiveRecordPersistence::InstanceMethods)
-        base.send(:include, AASM::Persistence::ActiveRecordPersistence::ReadState) unless base.method_defined?(:aasm_read_state)
+        base.send(:include, AASM::Persistence::ReadState) unless base.method_defined?(:aasm_read_state)
         base.send(:include, AASM::Persistence::ActiveRecordPersistence::WriteState) unless base.method_defined?(:aasm_write_state)
         base.send(:include, AASM::Persistence::ActiveRecordPersistence::WriteStateWithoutPersistence) unless base.method_defined?(:aasm_write_state_without_persistence)
 
@@ -46,41 +47,6 @@ module AASM
       end
 
       module ClassMethods
-        # Maps to the aasm_column in the database.  Defaults to "aasm_state".  You can write:
-        #
-        #   create_table :foos do |t|
-        #     t.string :name
-        #     t.string :aasm_state
-        #   end
-        #
-        #   class Foo < ActiveRecord::Base
-        #     include AASM
-        #   end
-        #
-        # OR:
-        #
-        #   create_table :foos do |t|
-        #     t.string :name
-        #     t.string :status
-        #   end
-        #
-        #   class Foo < ActiveRecord::Base
-        #     include AASM
-        #     aasm_column :status
-        #   end
-        #
-        # This method is both a getter and a setter
-        def aasm_column(column_name=nil)
-          if column_name
-            AASM::StateMachine[self].config.column = column_name.to_sym
-            # @aasm_column = column_name.to_sym
-          else
-            AASM::StateMachine[self].config.column ||= :aasm_state
-            # @aasm_column ||= :aasm_state
-          end
-          # @aasm_column
-          AASM::StateMachine[self].config.column
-        end
 
         def find_in_state(number, state, *args)
           with_state_scope state do
@@ -203,41 +169,6 @@ module AASM
         end
       end
 
-      module ReadState
-
-        # Returns the value of the aasm_column - called from <tt>aasm_current_state</tt>
-        #
-        # If it's a new record, and the aasm state column is blank it returns the initial state:
-        #
-        #   class Foo < ActiveRecord::Base
-        #     include AASM
-        #     aasm_column :status
-        #     aasm_state :opened
-        #     aasm_state :closed
-        #   end
-        #
-        #   foo = Foo.new
-        #   foo.current_state # => :opened
-        #   foo.close
-        #   foo.current_state # => :closed
-        #
-        #   foo = Foo.find(1)
-        #   foo.current_state # => :opened
-        #   foo.aasm_state = nil
-        #   foo.current_state # => nil
-        #
-        # NOTE: intended to be called from an event
-        #
-        # This allows for nil aasm states - be sure to add validation to your model
-        def aasm_read_state
-          if new_record?
-            send(self.class.aasm_column).blank? ? aasm_determine_state_name(self.class.aasm_initial_state) : send(self.class.aasm_column).to_sym
-          else
-            send(self.class.aasm_column).nil? ? nil : send(self.class.aasm_column).to_sym
-          end
-        end
-      end
-
     end
   end
 end