aasm 3.0.16 → 3.0.17

data/.gitignore

@@ -10,3 +10,4 @@ spec/debug.log
 spec/*.db
 TODO
 .rvmrc
+alto

data/.travis.yml

@@ -3,8 +3,9 @@ rvm:
   - 1.8.7
   - 1.9.2
   - 1.9.3
+  - 2.0.0
   # - jruby-18mode # JRuby in 1.8 mode
   # - jruby-19mode # JRuby in 1.9 mode
   - rbx-18mode
   - rbx-19mode
-services: mongodb
+services: mongodb

data/API

@@ -0,0 +1,34 @@
+
+Overwrite method to read the current state. Used to provide another storage mechanism,
+different from the standard Rails read_attribute method.
+
+  class MyClass
+    include AASM
+
+    def aasm_read_state
+      # retrieve the current state manually
+    end
+  end
+
+
+Overwrite method to write the current state (and actually persist it). Used to provide
+another storage mechanism, different from the standard Rails write_attribute method.
+
+  class MyClass
+    include AASM
+
+    def aasm_write_state
+      # store and persist the current state manually
+    end
+  end
+
+
+Overwrite method to write the current state (without persisting it).
+
+  class MyClass
+    include AASM
+
+    def aasm_write_state_without_persistence
+      # store the current state manually
+    end
+  end

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # CHANGELOG
 
+## Unreleased
+
+## 3.0.17
+
+ * supporting instance level inspection for states (including permissible state, see issue #54)
+ * added autocreation of constants for each state ([@jherdman](https://github.com/jherdman))
+
 ## 3.0.16
 
  * added autocreation of state scopes for Mongoid (thanks to [@jonnyshields](https://github.com/johnnyshields))

data/Gemfile

@@ -1,3 +1,3 @@
-source :rubygems
+source 'https://rubygems.org'
 
 gemspec

data/HOWTO

@@ -0,0 +1,12 @@
+How to
+
+1. Run tests for Mongoid
+
+Start MongoDB
+
+  $> mongod
+
+Run the specs
+
+  $> rspec spec/unit/persistence/mongoid_persistance_spec.rb
+

data/README.md

@@ -1,4 +1,4 @@
-# AASM - Ruby state machines [![Build Status](https://secure.travis-ci.org/aasm/aasm.png)](http://travis-ci.org/aasm/aasm) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/aasm/aasm)
+# AASM - Ruby state machines [![Build Status](https://secure.travis-ci.org/aasm/aasm.png)](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.
 
@@ -81,14 +81,24 @@ class Job
     state :running
 
     event :run, :after => :notify_somebody do
-      transitions :from => :sleeping, :to => :running
+      transitions :from => :sleeping, :to => :running, :on_transition => Proc.new {|obj, *args| obj.set_process(*args) }
     end
 
     event :sleep do
+      after do
+        ...
+      end
+      error do |e|
+        ...
+      end
       transitions :from => :running, :to => :sleeping
     end
   end
 
+  def set_process(name)
+    ...
+  end
+
   def do_something
     ...
   end
@@ -116,6 +126,18 @@ Here you can see a list of all possible callbacks, together with their order of
   event:after
 ```
 
+Also, you can pass parameters to events:
+
+```ruby
+  job = Job.new
+  job.run(:running, :defragmentation)
+```
+
+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.
+
 ### Guards
 
 Let's assume you want to allow particular transitions only if a defined condition is
@@ -277,12 +299,36 @@ class AddJobState < ActiveRecord::Migration
   end
 
   def self.down
-    remove_column :job, :aasm_state
+    remove_column :jobs, :aasm_state
   end
 end
 ```
 
-## Installation ##
+### <a id="inspection">Inspection
+
+AASM supports a couple of methods to find out which states or events are provided or permissible.
+
+Given the `Job` class from above:
+
+```ruby
+job = Job.new
+
+job.states
+=> [:sleeping, :running, :cleaning]
+
+job.states(:permissible => true)
+=> [:running]
+job.run
+job.states(:permissible => true)
+=> [:cleaning, :sleeping]
+
+job.events
+=> [:run, :clean, :sleep]
+```
+
+
+
+## <a id="installation">Installation ##
 
 ### Manually from RubyGems.org ###
 
@@ -308,6 +354,13 @@ gem 'aasm'
 
 Look at the [CHANGELOG](https://github.com/aasm/aasm/blob/master/CHANGELOG.md) for details.
 
+## Questions? ##
+
+Feel free to
+
+* [create an issue on GitHub](https://github.com/aasm/aasm/issues)
+* [ask a question on StackOverflow](http://stackoverflow.com) (tag with `aasm`)
+* send us a tweet [@aasm](http://twitter.com/aasm)
 
 ## Authors ##
 

data/aasm.gemspec

@@ -23,7 +23,9 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'sqlite3'
   s.add_development_dependency 'minitest'
   # s.add_development_dependency 'debugger'
+  # s.add_development_dependency 'pry'
   s.add_development_dependency 'ruby-debug-completion'
+  s.add_development_dependency 'coveralls'
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

data/lib/aasm.rb

@@ -4,10 +4,11 @@ require 'ostruct'
 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', 'instance_base')
+require File.join(File.dirname(__FILE__), 'aasm', 'transition')
+require File.join(File.dirname(__FILE__), 'aasm', 'event')
+require File.join(File.dirname(__FILE__), 'aasm', 'state')
+require File.join(File.dirname(__FILE__), 'aasm', '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')

data/lib/aasm/aasm.rb

@@ -3,18 +3,19 @@ module AASM
   def self.included(base) #:nodoc:
     base.extend AASM::ClassMethods
     AASM::StateMachine[base] ||= AASM::StateMachine.new('')
-    AASM::Persistence.set_persistence(base)
+    AASM::Persistence.load_persistence(base)
     super
   end
 
   module ClassMethods
 
     # make sure inheritance (aka subclassing) works with AASM
-    def inherited(klass)
-      AASM::StateMachine[klass] = AASM::StateMachine[self].clone
+    def inherited(base)
+      AASM::StateMachine[base] = AASM::StateMachine[self].clone
       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
@@ -31,6 +32,7 @@ module AASM
       end
     end
 
+    # is this better?: aasm.states.name.from_states
     def aasm_from_states_for_state(state, options={})
       if options[:transition]
         aasm.events[options[:transition]].transitions_to_state(state).flatten.map(&:from).flatten
@@ -71,100 +73,73 @@ module AASM
 
     # aasm.event(:event_name).human?
     def aasm_human_event_name(event) # event_name?
-      AASM::SupportingClasses::Localizer.new.human_event_name(self, event)
+      AASM::Localizer.new.human_event_name(self, event)
     end
   end # ClassMethods
 
-  # 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.fire_callbacks(:before_enter, self)
-    state.fire_callbacks(:enter, self)
-    self.aasm_current_state = state_name
-    state.fire_callbacks(:after_enter, self)
-
-    state_name
+  def aasm
+    @aasm ||= AASM::InstanceBase.new(self)
   end
 
-  # private?
-  def aasm_events_for_current_state
-    aasm_events_for_state(aasm_current_state)
+  # may be overwritten by persistence mixins
+  def aasm_read_state
+    aasm.enter_initial_state
   end
 
-  # filters the results of events_for_current_state so that only those that
-  # are really currently possible (given transition guards) are shown.
-  def aasm_permissible_events_for_current_state
-    aasm_events_for_current_state.select{ |e| self.send(("may_" + e.to_s + "?").to_sym) }
+  # may be overwritten by persistence mixins
+  def aasm_write_state(new_state)
+    true
   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}
+  # may be overwritten by persistence mixins
+  def aasm_write_state_without_persistence(new_state)
+    true
   end
 
-  def aasm_human_state
-    AASM::SupportingClasses::Localizer.new.human_state_name(self.class, aasm_current_state)
+  # deprecated
+  def aasm_current_state
+    # warn "#aasm_current_state is deprecated and will be removed in version 3.2.0; please use #aasm.state instead!"
+    aasm.current_state
   end
 
-private
-
-  def aasm_persistable?
-    self.respond_to?(:aasm_read_state) || self.private_methods.include?('aasm_read_state')
+  # deprecated
+  def aasm_enter_initial_state
+    # warn "#aasm_enter_initial_state is deprecated and will be removed in version 3.2.0; please use #aasm.enter_initial_state instead!"
+    aasm.enter_initial_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)
-    end
-    self.aasm_current_state = state if save_success
-
-    save_success
+  # deprecated
+  def aasm_events_for_current_state
+    # warn "#aasm_events_for_current_state is deprecated and will be removed in version 3.2.0; please use #aasm.events instead!"
+    aasm.events(aasm.current_state)
   end
 
-  def aasm_current_state=(state)
-    if self.respond_to?(:aasm_write_state_without_persistence) || self.private_methods.include?('aasm_write_state_without_persistence')
-      aasm_write_state_without_persistence(state)
-    end
-    @aasm_current_state = state
+  # deprecated
+  def aasm_permissible_events_for_current_state
+    # warn "#aasm_permissible_events_for_current_state is deprecated and will be removed in version 3.2.0; please use #aasm.permissible_events instead!"
+    aasm.permissible_events
   end
 
-  def aasm_determine_state_name(state)
-    case state
-      when Symbol, String
-        state
-      when Proc
-        state.call(self)
-      else
-        raise NotImplementedError, "Unrecognized state-type given.  Expected Symbol, String, or Proc."
-    end
+  # deprecated
+  def aasm_events_for_state(state_name)
+    # warn "#aasm_events_for_state(state_name) is deprecated and will be removed in version 3.2.0; please use #aasm.events(state_name) instead!"
+    aasm.events(state_name)
   end
 
-  def aasm_state_object_for_state(name)
-    obj = self.class.aasm_states.find {|s| s == name}
-    raise AASM::UndefinedState, "State :#{name} doesn't exist" if obj.nil?
-    obj
+  # deprecated
+  def aasm_human_state
+    # warn "#aasm_human_state is deprecated and will be removed in version 3.2.0; please use #aasm.human_state instead!"
+    aasm.human_state
   end
 
-  def aasm_may_fire_event?(name, *args)
-    event = self.class.aasm_events[name]
-    event.may_fire?(self, *args)
-  end
+private
 
   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 = aasm.state_object_for_name(aasm.current_state)
 
 
       old_state.fire_callbacks(:exit, self)
@@ -173,7 +148,7 @@ private
       event.fire_callbacks(:before, self)
 
       if new_state_name = event.fire(self, *args)
-        new_state = aasm_state_object_for_state(new_state_name)
+        new_state = aasm.state_object_for_name(new_state_name)
 
         # new before_ callbacks
         old_state.fire_callbacks(:before_exit, self)
@@ -183,10 +158,10 @@ private
 
         persist_successful = true
         if persist
-          persist_successful = aasm_set_current_state_with_persistence(new_state_name)
-          event.execute_success_callback(self) if persist_successful
+          persist_successful = aasm.set_current_state_with_persistence(new_state_name)
+          event.fire_callbacks(:success, self) if persist_successful
         else
-          self.aasm_current_state = new_state_name
+          aasm.current_state = new_state_name
         end
 
         if persist_successful
@@ -194,7 +169,7 @@ private
           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)
+          self.aasm_event_fired(name, old_state.name, aasm.current_state) if self.respond_to?(:aasm_event_fired)
         else
           self.aasm_event_failed(name, old_state.name) if self.respond_to?(:aasm_event_failed)
         end
@@ -207,13 +182,13 @@ private
         end
 
         if AASM::StateMachine[self.class].config.whiny_transitions
-          raise AASM::InvalidTransition, "Event '#{event.name}' cannot transition from '#{self.aasm_current_state}'"
+          raise AASM::InvalidTransition, "Event '#{event.name}' cannot transition from '#{aasm.current_state}'"
         else
           false
         end
       end
     rescue StandardError => e
-      event.execute_error_callback(self, e)
+      event.fire_callbacks(:error, self, e) || raise(e)
     end
   end
 end

data/lib/aasm/base.rb

@@ -3,50 +3,54 @@ module AASM
 
     def initialize(clazz, options={}, &block)
       @clazz = clazz
-      sm = AASM::StateMachine[@clazz]
-      sm.config.column = options[:column].to_sym if options[:column]
+      @state_machine = AASM::StateMachine[@clazz]
+      @state_machine.config.column = options[:column].to_sym if options[:column]
 
       if options.key?(:whiny_transitions)
-        sm.config.whiny_transitions = options[:whiny_transitions]
-      elsif sm.config.whiny_transitions.nil?
-        sm.config.whiny_transitions = true # this is the default, so let's cry
+        @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
 
       if options.key?(:skip_validation_on_save)
-        sm.config.skip_validation_on_save = options[:skip_validation_on_save]
-      elsif sm.config.skip_validation_on_save.nil?
-        sm.config.skip_validation_on_save = false # this is the default, so don't store any new state if the model is invalid
+        @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
     end
 
     def initial_state
-      AASM::StateMachine[@clazz].initial_state
+      @state_machine.initial_state
     end
 
+    # define a state
     def state(name, options={})
       # @clazz.aasm_state(name, options)
-      sm = AASM::StateMachine[@clazz]
-      sm.create_state(name, @clazz, options)
-      sm.initial_state = name if options[:initial] || !sm.initial_state
+      @state_machine.add_state(name, @clazz, options)
+      @state_machine.initial_state = name if options[:initial] || !@state_machine.initial_state
 
       @clazz.send(:define_method, "#{name.to_s}?") do
         aasm_current_state == name
       end
+
+      unless @clazz.const_defined?("STATE_#{name.to_s.upcase}")
+        @clazz.const_set("STATE_#{name.to_s.upcase}", name)
+      end
     end
 
+    # define an event
     def event(name, options={}, &block)
       # @clazz.aasm_event(name, options, &block)
-      sm = AASM::StateMachine[@clazz]
 
-      unless sm.events.has_key?(name)
-        sm.events[name] = AASM::SupportingClasses::Event.new(name, options, &block)
+      unless @state_machine.events.has_key?(name)
+        @state_machine.events[name] = AASM::Event.new(name, options, &block)
       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.
       @clazz.send(:define_method, "may_#{name.to_s}?") do |*args|
-        aasm_may_fire_event?(name, *args)
+        aasm.may_fire_event?(name, *args)
       end
 
       @clazz.send(:define_method, "#{name.to_s}!") do |*args|
@@ -59,11 +63,11 @@ module AASM
     end
 
     def states
-      AASM::StateMachine[@clazz].states
+      @state_machine.states
     end
 
     def events
-      AASM::StateMachine[@clazz].events
+      @state_machine.events
     end
 
     def states_for_select