aasm 2.4.0 → 3.0.0

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## 3.0.0
+
+ * switched documentation to the new DSL
+ * whiny transactions: by default, raise an exception if an event transition is not possible
+ * you may disable whiny transactions
+
 ## 2.4.0 
 
  * supporting new DSL (which is much shorter)

data/README.md

@@ -59,26 +59,24 @@ gem 'aasm'
 Here's a quick example highlighting some of the features.
 
 ```ruby
-  class Conversation
-    include AASM
-
-    aasm_column :current_state # defaults to aasm_state
-
-    aasm_initial_state :unread
+class Conversation
+  include AASM
 
-    aasm_state :unread
-    aasm_state :read
-    aasm_state :closed
+  aasm :column => :current_state do  # defaults to aasm_state
+    state :unread, :initial => true
+    state :read
+    state :closed
 
-
-    aasm_event :view do
+    event :view do
       transitions :to => :read, :from => [:unread]
     end
 
-    aasm_event :close do
+    event :close do
       transitions :to => :closed, :from => [:read, :unread]
     end
   end
+
+end
 ```
 
 ## A Slightly More Complex Example ##
@@ -89,22 +87,21 @@ This example uses a few of the more complex features available.
   class Relationship
     include AASM
 
-    aasm_column :status
-    
-    aasm_initial_state Proc.new { |relationship| relationship.strictly_for_fun? ? :intimate : :dating }
-    
-    aasm_state :dating,   :enter => :make_happy,        :exit => :make_depressed
-    aasm_state :intimate, :enter => :make_very_happy,   :exit => :never_speak_again
-    aasm_state :married,  :enter => :give_up_intimacy,  :exit => :buy_exotic_car_and_wear_a_combover
-    
-    aasm_event :get_intimate do
-      transitions :to => :intimate, :from => [:dating], :guard => :drunk?
-    end
-    
-    aasm_event :get_married do
-      transitions :to => :married, :from => [:dating, :intimate], :guard => :willing_to_give_up_manhood?
+    aasm :column => :status
+      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
+
+      event :get_married do
+        transitions :to => :married, :from => [:dating, :intimate], :guard => :willing_to_give_up_manhood?
+      end
     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
@@ -122,14 +119,15 @@ This example uses a few of the more complex features available.
   class Relationship
     include AASM
 
-    aasm_state :dating
-    aasm_state :married
+    aasm do
+      state :dating
+      state :married
 
-    aasm_event :get_married,
-      :before => :make_vows,
-      :after => :eat_wedding_cake do
-      transitions :to => :married, :from => [:dating]
-    end
+      event :get_married,
+            :before => :make_vows,
+            :after => :eat_wedding_cake do
+        transitions :to => :married, :from => [:dating]
+      end
   end
 ```
 
@@ -142,7 +140,7 @@ Look at the [CHANGELOG](https://github.com/rubyist/aasm/blob/master/CHANGELOG.md
 
 * [Scott Barron](https://github.com/rubyist)
 * [Travis Tilley](https://github.com/ttilley)
-* [Thorsten Böttger](http://github.com/alto),
+* [Thorsten Böttger](http://github.com/alto)
 
 
 ## Warranty ##

data/lib/aasm.rb

@@ -1,10 +1,15 @@
-module AASM
-end
-
 require 'ostruct'
 
-require File.join(File.dirname(__FILE__), 'aasm', 'supporting_classes')
+require File.join(File.dirname(__FILE__), 'aasm', 'version')
+require File.join(File.dirname(__FILE__), 'aasm', 'errors')
+require File.join(File.dirname(__FILE__), 'aasm', 'base')
+require File.join(File.dirname(__FILE__), 'aasm', 'supporting_classes', 'state_transition')
+require File.join(File.dirname(__FILE__), 'aasm', 'supporting_classes', 'event')
+require File.join(File.dirname(__FILE__), 'aasm', 'supporting_classes', 'state')
+require File.join(File.dirname(__FILE__), 'aasm', 'supporting_classes', 'localizer')
 require File.join(File.dirname(__FILE__), 'aasm', 'state_machine')
 require File.join(File.dirname(__FILE__), 'aasm', 'persistence')
 require File.join(File.dirname(__FILE__), 'aasm', 'aasm')
-require File.join(File.dirname(__FILE__), 'aasm', 'localizer')
+
+# load the deprecated methods and modules
+Dir[File.join(File.dirname(__FILE__), 'aasm', 'deprecated', '*.rb')].sort.each { |f| require File.expand_path(f) }

data/lib/aasm/aasm.rb

@@ -1,9 +1,4 @@
 module AASM
-  class InvalidTransition < RuntimeError
-  end
-
-  class UndefinedState < RuntimeError
-  end
 
   def self.included(base) #:nodoc:
     base.extend AASM::ClassMethods
@@ -45,7 +40,7 @@ module AASM
     def aasm_state(name, options={})
       aasm.state(name, options)
     end
-    
+
     # deprecated
     def aasm_event(name, options = {}, &block)
       aasm.event(name, options, &block)
@@ -66,35 +61,31 @@ module AASM
       aasm.states_for_select
     end
 
-    def human_event_name(event)
-      AASM::Localizer.new.human_event_name(self, event)
+    def aasm_human_event_name(event)
+      AASM::SupportingClasses::Localizer.new.human_event_name(self, event)
     end
   end
-  
-  # Instance methods
-  def aasm_current_state
-    return @aasm_current_state if @aasm_current_state
 
-    if self.respond_to?(:aasm_read_state) || self.private_methods.include?('aasm_read_state')
-      @aasm_current_state = aasm_read_state
-    end
-    return @aasm_current_state if @aasm_current_state
-
-    aasm_enter_initial_state
+  # this method does what? does it deliver the current state?
+  def aasm_current_state
+    @aasm_current_state ||=
+      aasm_persistable? ? aasm_read_state : aasm_enter_initial_state
   end
 
+  # private?
   def aasm_enter_initial_state
     state_name = aasm_determine_state_name(self.class.aasm_initial_state)
     state = aasm_state_object_for_state(state_name)
 
-    state.call_action(:before_enter, self)
-    state.call_action(:enter, self)
+    state.fire_callbacks(:before_enter, self)
+    state.fire_callbacks(:enter, self)
     self.aasm_current_state = state_name
-    state.call_action(:after_enter, self)
+    state.fire_callbacks(:after_enter, self)
 
     state_name
   end
 
+  # private?
   def aasm_events_for_current_state
     aasm_events_for_state(aasm_current_state)
   end
@@ -104,19 +95,23 @@ module AASM
   def aasm_permissible_events_for_current_state
     aasm_events_for_current_state.select{ |e| self.send(("may_" + e.to_s + "?").to_sym) }
   end
-  
+
   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
 
-  def human_state
-    AASM::Localizer.new.human_state(self)
+  def aasm_human_state
+    AASM::SupportingClasses::Localizer.new.human_state(self)
   end
 
 private
 
-  def set_aasm_current_state_with_persistence(state)
+  def aasm_persistable?
+    self.respond_to?(:aasm_read_state) || self.private_methods.include?('aasm_read_state')
+  end
+
+  def aasm_set_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)
@@ -150,45 +145,45 @@ private
     obj
   end
 
-  def aasm_test_event(name, *args)
+  def aasm_may_fire_event?(name, *args)
     event = self.class.aasm_events[name]
     event.may_fire?(self, *args)
   end
-  
-  def aasm_fire_event(name, persist, *args)
+
+  def aasm_fire_event(name, options, *args)
+    persist = options[:persist]
+
     event = self.class.aasm_events[name]
     begin
       old_state = aasm_state_object_for_state(aasm_current_state)
 
 
-      old_state.call_action(:exit, self)
+      old_state.fire_callbacks(:exit, self)
 
       # new event before callback
-      event.call_action(:before, self)
+      event.fire_callbacks(:before, self)
 
-      new_state_name = event.fire(self, *args)
-
-      unless new_state_name.nil?
+      if new_state_name = event.fire(self, *args)
         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)
+        old_state.fire_callbacks(:before_exit, self)
+        new_state.fire_callbacks(:before_enter, self)
 
-        new_state.call_action(:enter, self)
+        new_state.fire_callbacks(:enter, self)
 
         persist_successful = true
         if persist
-          persist_successful = set_aasm_current_state_with_persistence(new_state_name)
+          persist_successful = aasm_set_current_state_with_persistence(new_state_name)
           event.execute_success_callback(self) if persist_successful
         else
           self.aasm_current_state = new_state_name
         end
 
         if persist_successful
-          old_state.call_action(:after_exit, self)
-          new_state.call_action(:after_enter, self)
-          event.call_action(:after, self)
+          old_state.fire_callbacks(:after_exit, self)
+          new_state.fire_callbacks(:after_enter, self)
+          event.fire_callbacks(:after, self)
 
           self.aasm_event_fired(name, old_state.name, self.aasm_current_state) if self.respond_to?(:aasm_event_fired)
         else
@@ -196,12 +191,17 @@ private
         end
 
         persist_successful
+
       else
         if self.respond_to?(:aasm_event_failed)
           self.aasm_event_failed(name, old_state.name)
         end
 
-        false
+        if AASM::StateMachine[self.class].config.whiny_transitions
+          raise AASM::InvalidTransition, "Event '#{event.name}' cannot transition from '#{self.aasm_current_state}'"
+        else
+          false
+        end
       end
     rescue StandardError => e
       event.execute_error_callback(self, e)

data/lib/aasm/base.rb

@@ -4,6 +4,11 @@ module AASM
       @clazz = clazz
       sm = AASM::StateMachine[@clazz]
       sm.config.column = options[:column].to_sym if options[:column]
+      if options.key?(:whiny_transitions)
+        sm.config.whiny_transitions = options[:whiny_transitions]
+      else
+        sm.config.whiny_transitions = true # this is the default, so let's cry
+      end
     end
 
     def state(name, options={})
@@ -29,15 +34,15 @@ module AASM
       # may_event? and get back a boolean that tells you whether the guard method
       # on the transition will let this happen.
       @clazz.send(:define_method, "may_#{name.to_s}?") do |*args|
-        aasm_test_event(name, *args)
+        aasm_may_fire_event?(name, *args)
       end
 
       @clazz.send(:define_method, "#{name.to_s}!") do |*args|
-        aasm_fire_event(name, true, *args)
+        aasm_fire_event(name, {:persist => true}, *args)
       end
 
       @clazz.send(:define_method, "#{name.to_s}") do |*args|
-        aasm_fire_event(name, false, *args)
+        aasm_fire_event(name, {:persist => false}, *args)
       end
     end
 
@@ -52,5 +57,6 @@ module AASM
     def states_for_select
       states.map { |state| state.for_select }
     end
+
   end
 end

data/lib/aasm/deprecated/aasm.rb

@@ -0,0 +1,15 @@
+module AASM
+
+  module ClassMethods
+    def human_event_name(*args)
+      warn "AASM.human_event_name is deprecated and will be removed in version 3.1.0; please use AASM.aasm_human_event_name instead!"
+      aasm_human_event_name(*args)
+    end
+  end
+
+  def human_state
+    warn "AASM#human_state is deprecated and will be removed in version 3.1.0; please use AASM#aasm_human_state instead!"
+    aasm_human_state
+  end
+
+end

data/lib/aasm/errors.rb

@@ -0,0 +1,4 @@
+module AASM
+  class InvalidTransition < RuntimeError; end
+  class UndefinedState < RuntimeError; end
+end

data/lib/aasm/persistence.rb

@@ -1,14 +1,15 @@
-module AASM::Persistence
+module AASM
+  module Persistence
+    # Checks to see this class or any of it's superclasses inherit from
+    # ActiveRecord::Base and if so includes ActiveRecordPersistence
+    def self.set_persistence(base)
+      # Use a fancier auto-loading thingy, perhaps.  When there are more persistence engines.
+      hierarchy = base.ancestors.map {|klass| klass.to_s}
 
-  # Checks to see this class or any of it's superclasses inherit from
-  # ActiveRecord::Base and if so includes ActiveRecordPersistence
-  def self.set_persistence(base)
-    # Use a fancier auto-loading thingy, perhaps.  When there are more persistence engines.
-    hierarchy = base.ancestors.map {|klass| klass.to_s}
-
-    if hierarchy.include?("ActiveRecord::Base")
-      require File.join(File.dirname(__FILE__), 'persistence', 'active_record_persistence')
-      base.send(:include, AASM::Persistence::ActiveRecordPersistence)
+      if hierarchy.include?("ActiveRecord::Base")
+        require File.join(File.dirname(__FILE__), 'persistence', 'active_record_persistence')
+        base.send(:include, AASM::Persistence::ActiveRecordPersistence)
+      end
     end
   end
-end
+end # AASM

data/lib/aasm/state_machine.rb

@@ -1,31 +1,33 @@
-class AASM::StateMachine
-  def self.[](clazz)
-    (@machines ||= {})[clazz.to_s]
-  end
+module AASM
+  class StateMachine
+    def self.[](clazz)
+      (@machines ||= {})[clazz.to_s]
+    end
   
-  def self.[]=(clazz, machine)
-    (@machines ||= {})[clazz.to_s] = machine
-  end
+    def self.[]=(clazz, machine)
+      (@machines ||= {})[clazz.to_s] = machine
+    end
   
-  attr_accessor :states, :events, :initial_state, :config
-  attr_reader :name
+    attr_accessor :states, :events, :initial_state, :config
+    attr_reader :name
 
-  def initialize(name)
-    @name = name
-    @initial_state = nil
-    @states = []
-    @events = {}
-    @config = OpenStruct.new
-  end
+    def initialize(name)
+      @name = name
+      @initial_state = nil
+      @states = []
+      @events = {}
+      @config = OpenStruct.new
+    end
 
-  def clone
-    klone = super
-    klone.states = states.clone
-    klone.events = events.clone
-    klone
-  end
+    def clone
+      klone = super
+      klone.states = states.clone
+      klone.events = events.clone
+      klone
+    end
 
-  def create_state(name, options)
-    @states << AASM::SupportingClasses::State.new(name, options) unless @states.include?(name)
+    def create_state(name, options)
+      @states << AASM::SupportingClasses::State.new(name, options) unless @states.include?(name)
+    end
   end
-end
+end # AASM