aasm 2.2.0 → 2.3.1

data/.gitignore

@@ -5,3 +5,7 @@
 coverage
 pkg
 rdoc
+Gemfile.lock
+spec/debug.log
+spec/*.db
+TODO

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/{README.rdoc → README.md}

@@ -1,72 +1,64 @@
-= Alternatives
-
-If you are looking for an alternative to AASM, I would highly suggest transitions: http://github.com/qoobaa/transitions
-
-= AASM - Ruby state machines
+# AASM - Ruby state machines #
 
 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 that no longer targets only ActiveRecord models.
 
-AASM has the following features:
+## Features ##
 
 * States
 * Machines
 * Events
 * Transitions
 
-== New Callbacks
+## New Callbacks ##
 
 The callback chain & order on a successful event looks like:
 
-  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*
+    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*
 
-  (*) marks old callbacks
+    (*) marks old callbacks
 
 
-== Download
+## Download ##
 
 The latest AASM can currently be pulled from the git repository on github.
 
 * http://github.com/rubyist/aasm/tree/master
 
 
-== Installation
-
-=== From gemcutter
-
-  % sudo gem install gemcutter
-  % sudo gem tumble
-  % sudo gem install aasm
+## Installation ##
 
-=== From GitHub hosted gems (only older releases are available)
+### From RubyGems.org ###
 
-  % sudo gem sources -a http://gems.github.com # (you only need to do this once)
-  % sudo gem install rubyist-aasm
+```sh
+% gem install aasm
+```
 
-=== Building your own gems
+### Building your own gems ###
 
-  % rake gemspec
-  % rake build
-  % sudo gem install pkg/aasm-2.1.gem
+```sh
+% rake build
+% sudo gem install pkg/aasm-x.y.z.gem
+```
 
-
-== Simple Example
+## Simple Example ##
 
 Here's a quick example highlighting some of the features.
 
+```ruby
   class Conversation
     include AASM
 
@@ -87,11 +79,13 @@ Here's a quick example highlighting some of the features.
       transitions :to => :closed, :from => [:read, :unread]
     end
   end
+```
 
-== A Slightly More Complex Example
+## A Slightly More Complex Example ##
 
 This example uses a few of the more complex features available.
 
+```ruby
   class Relationship
     include AASM
 
@@ -121,15 +115,33 @@ This example uses a few of the more complex features available.
     def give_up_intimacy; end
     def buy_exotic_car_and_wear_a_combover; end
   end
+```
+
+## Callbacks around events
+```ruby
+  class Relationship
+    include AASM
+
+    aasm_state :dating
+    aasm_state :married
+
+    aasm_event :get_married,
+      :before => :make_vows,
+      :after => :eat_wedding_cake do
+      transitions :to => :married, :from => [:dating]
+    end
+  end
+```
+
 
-= Other Stuff
+# Other Stuff #
 
 Author::  Scott Barron <scott at elitists dot net>
 License:: Original code Copyright 2006, 2007, 2008 by Scott Barron.
           Released under an MIT-style license.  See the LICENSE  file
           included in the distribution.
 
-== Warranty
+## Warranty ##
 
 This software is provided "as is" and without any express or
 implied warranties, including, without limitation, the implied

data/Rakefile

@@ -1,108 +1,27 @@
-require 'rubygems'
-require 'rake'
+require 'bundler/gem_tasks'
 
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "aasm"
-    gem.summary = %Q{State machine mixin for Ruby objects}
-    gem.description = %Q{AASM is a continuation of the acts as state machine rails plugin, built for plain Ruby objects.}
-    gem.homepage = "http://rubyist.github.com/aasm/"
-    gem.authors = ["Scott Barron", "Scott Petersen", "Travis Tilley"]
-    gem.email = "scott@elitists.net, ttilley@gmail.com"
-    gem.add_development_dependency "rspec"
-    gem.add_development_dependency "shoulda"
-    gem.add_development_dependency 'sdoc'
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
 end
 
-require 'spec/rake/spectask'
 require 'rake/testtask'
-
 Rake::TestTask.new(:test) do |test|
   test.libs << 'lib' << 'test'
   test.pattern = 'test/**/*_test.rb'
   test.verbose = true
 end
 
-begin
-  require 'rcov/rcovtask'
-  Rcov::RcovTask.new(:rcov_shoulda) do |test|
-    test.libs << 'test'
-    test.pattern = 'test/**/*_test.rb'
-    test.verbose = true
-  end
-rescue LoadError
-  task :rcov do
-    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
-  end
-end
-
-Spec::Rake::SpecTask.new(:spec) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.spec_files = FileList['spec/**/*_spec.rb']
-  spec.spec_opts = ['-cfs']
-end
-
-Spec::Rake::SpecTask.new(:rcov_rspec) do |spec|
-  spec.libs << 'lib' << 'spec'
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov = true
-end
-
-task :test => :check_dependencies
-task :spec => :check_dependencies
-
-begin
-  require 'reek/rake_task'
-  Reek::RakeTask.new do |t|
-    t.fail_on_error = true
-    t.verbose = false
-    t.source_files = 'lib/**/*.rb'
-  end
-rescue LoadError
-  task :reek do
-    abort "Reek is not available. In order to run reek, you must: sudo gem install reek"
-  end
-end
-
-begin
-  require 'roodi'
-  require 'roodi_task'
-  RoodiTask.new do |t|
-    t.verbose = false
-  end
-rescue LoadError
-  task :roodi do
-    abort "Roodi is not available. In order to run roodi, you must: sudo gem install roodi"
-  end
-end
-
 task :default => :test
 
-begin
-  require 'rake/rdoctask'
-  require 'sdoc'
-  Rake::RDocTask.new do |rdoc|
-    if File.exist?('VERSION')
-      version = File.read('VERSION')
-    else
-      version = ""
-    end
-
-    rdoc.rdoc_dir = 'rdoc'
-    rdoc.title = "aasm #{version}"
-    rdoc.rdoc_files.include('README*')
-    rdoc.rdoc_files.include('lib/**/*.rb')
+require 'rdoc/task'
+require 'aasm/version'
+require 'sdoc'
 
-    rdoc.options << '--fmt' << 'shtml'
-    rdoc.template = 'direct'
-  end
-rescue LoadError
-  puts "aasm makes use of the sdoc gem. Install it with: sudo gem install sdoc"
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "aasm #{AASM::VERSION}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
 end
-

data/aasm.gemspec

@@ -1,94 +1,28 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
 # -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "aasm/version"
 
 Gem::Specification.new do |s|
-  s.name = %q{aasm}
-  s.version = "2.2.0"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Scott Barron", "Scott Petersen", "Travis Tilley"]
-  s.date = %q{2010-09-13}
+  s.name        = "aasm"
+  s.version     = AASM::VERSION
+  s.authors     = ["Scott Barron", "Scott Petersen", "Travis Tilley", "Thorsten Böttger"]
+  s.email       = %q{scott@elitists.net, ttilley@gmail.com}
+  s.homepage    = %q{http://rubyist.github.com/aasm/}
+  s.summary     = %q{State machine mixin for Ruby objects}
   s.description = %q{AASM is a continuation of the acts as state machine rails plugin, built for plain Ruby objects.}
-  s.email = %q{scott@elitists.net, ttilley@gmail.com}
-  s.extra_rdoc_files = [
-    "LICENSE",
-     "README.rdoc"
-  ]
-  s.files = [
-    ".document",
-     ".gitignore",
-     "LICENSE",
-     "README.rdoc",
-     "Rakefile",
-     "VERSION",
-     "aasm.gemspec",
-     "lib/aasm.rb",
-     "lib/aasm/aasm.rb",
-     "lib/aasm/event.rb",
-     "lib/aasm/persistence.rb",
-     "lib/aasm/persistence/active_record_persistence.rb",
-     "lib/aasm/state.rb",
-     "lib/aasm/state_machine.rb",
-     "lib/aasm/state_transition.rb",
-     "lib/aasm/supporting_classes.rb",
-     "spec/functional/conversation.rb",
-     "spec/functional/conversation_spec.rb",
-     "spec/spec_helper.rb",
-     "spec/unit/aasm_spec.rb",
-     "spec/unit/active_record_persistence_spec.rb",
-     "spec/unit/before_after_callbacks_spec.rb",
-     "spec/unit/event_spec.rb",
-     "spec/unit/state_spec.rb",
-     "spec/unit/state_transition_spec.rb",
-     "test/functional/auth_machine_test.rb",
-     "test/test_helper.rb",
-     "test/unit/aasm_test.rb",
-     "test/unit/event_test.rb",
-     "test/unit/state_test.rb",
-     "test/unit/state_transition_test.rb"
-  ]
-  s.homepage = %q{http://rubyist.github.com/aasm/}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
-  s.summary = %q{State machine mixin for Ruby objects}
-  s.test_files = [
-    "spec/functional/conversation.rb",
-     "spec/functional/conversation_spec.rb",
-     "spec/spec_helper.rb",
-     "spec/unit/aasm_spec.rb",
-     "spec/unit/active_record_persistence_spec.rb",
-     "spec/unit/before_after_callbacks_spec.rb",
-     "spec/unit/event_spec.rb",
-     "spec/unit/state_spec.rb",
-     "spec/unit/state_transition_spec.rb",
-     "test/functional/auth_machine_test.rb",
-     "test/test_helper.rb",
-     "test/unit/aasm_test.rb",
-     "test/unit/event_test.rb",
-     "test/unit/state_test.rb",
-     "test/unit/state_transition_test.rb"
-  ]
 
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
+  s.add_dependency             'activerecord'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'sdoc'
+  s.add_development_dependency 'rspec', '~> 2.0'
+  s.add_development_dependency 'rr'
+  s.add_development_dependency 'shoulda'
+  s.add_development_dependency 'sqlite3'
+  s.add_development_dependency 'minitest'
+  s.add_development_dependency 'ruby-debug-completion'
 
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<rspec>, [">= 0"])
-      s.add_development_dependency(%q<shoulda>, [">= 0"])
-      s.add_development_dependency(%q<sdoc>, [">= 0"])
-    else
-      s.add_dependency(%q<rspec>, [">= 0"])
-      s.add_dependency(%q<shoulda>, [">= 0"])
-      s.add_dependency(%q<sdoc>, [">= 0"])
-    end
-  else
-    s.add_dependency(%q<rspec>, [">= 0"])
-    s.add_dependency(%q<shoulda>, [">= 0"])
-    s.add_dependency(%q<sdoc>, [">= 0"])
-  end
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
 end
-

data/lib/aasm/aasm.rb

@@ -7,6 +7,7 @@ module AASM
 
   def self.included(base) #:nodoc:
     base.extend AASM::ClassMethods
+
     AASM::Persistence.set_persistence(base)
     unless AASM::StateMachine[base]
       AASM::StateMachine[base] = AASM::StateMachine.new('')
@@ -41,7 +42,7 @@ module AASM
         aasm_current_state == name
       end
     end
-
+    
     def aasm_event(name, options = {}, &block)
       sm = AASM::StateMachine[self]
 
@@ -49,6 +50,13 @@ module AASM
         sm.events[name] = AASM::SupportingClasses::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.
+      define_method("may_#{name.to_s}?") do |*args|
+        aasm_test_event(name, *args)
+      end
+      
       define_method("#{name.to_s}!") do |*args|
         aasm_fire_event(name, true, *args)
       end
@@ -70,8 +78,11 @@ module AASM
       AASM::StateMachine[self].states.map { |state| state.for_select }
     end
 
+    def human_event_name(event)
+      AASM::Localizer.new.human_event_name(self, event)
+    end
   end
-
+  
   # Instance methods
   def aasm_current_state
     return @aasm_current_state if @aasm_current_state
@@ -100,11 +111,21 @@ module AASM
     aasm_events_for_state(aasm_current_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) }
+  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)
+  end
+
   private
 
   def set_aasm_current_state_with_persistence(state)
@@ -141,6 +162,11 @@ module AASM
     obj
   end
 
+  def aasm_test_event(name, *args)
+    event = self.class.aasm_events[name]
+    event.may_fire?(self, *args)
+  end
+  
   def aasm_fire_event(name, persist, *args)
     event = self.class.aasm_events[name]
     begin

data/lib/aasm/event.rb

@@ -7,6 +7,24 @@ class AASM::SupportingClasses::Event
     update(options, &block)
   end
 
+  # a neutered version of fire - it doesn't actually fir the event, it just
+  # executes the transition guards to determine if a transition is even
+  # an option given current conditions.
+  def may_fire?(obj, to_state=nil)
+    transitions = @transitions.select { |t| t.from == obj.aasm_current_state }
+    return false if transitions.size == 0
+    
+    result = false
+    transitions.each do |transition|
+      next if to_state and !Array(transition.to).include?(to_state)
+      if transition.perform(obj)
+        result = true
+        break
+      end
+    end
+    result
+  end
+  
   def fire(obj, to_state=nil, *args)
     transitions = @transitions.select { |t| t.from == obj.aasm_current_state }
     raise AASM::InvalidTransition, "Event '#{name}' cannot transition from '#{obj.aasm_current_state}'" if transitions.size == 0
@@ -14,7 +32,7 @@ class AASM::SupportingClasses::Event
     next_state = nil
     transitions.each do |transition|
       next if to_state and !Array(transition.to).include?(to_state)
-      if transition.perform(obj)
+      if transition.perform(obj, *args)
         next_state = to_state || Array(transition.to).first
         transition.execute(obj, *args)
         break

data/lib/aasm/localizer.rb

@@ -0,0 +1,36 @@
+class AASM::Localizer
+  def human_event_name(klass, event)
+    defaults = ancestors_list(klass).map do |ancestor|
+      :"#{i18n_scope(klass)}.events.#{i18n_klass(ancestor)}.#{event}"
+    end << event.to_s.humanize
+
+    I18n.translate(defaults.shift, :default => defaults, :raise => true)
+  end
+
+  def human_state(obj)
+    klass = obj.class
+    defaults = ancestors_list(klass).map do |ancestor|
+      :"#{i18n_scope(klass)}.attributes.#{i18n_klass(ancestor)}.#{klass.aasm_column}.#{obj.aasm_current_state}"
+    end << obj.aasm_current_state.to_s.humanize
+
+    I18n.translate(defaults.shift, :default => defaults, :raise => true)
+  end
+
+  private
+
+  # added for rails 2.x compatibility
+  def i18n_scope(klass)
+    klass.respond_to?(:i18n_scope) ? klass.i18n_scope : :activerecord
+  end
+
+  # added for rails < 3.0.3 compatibility
+  def i18n_klass(klass)
+    klass.model_name.respond_to?(:i18n_key) ? klass.model_name.i18n_key : klass.name.underscore
+  end
+
+  def ancestors_list(klass)
+    klass.ancestors.select do |ancestor|
+      ancestor.respond_to?(:model_name) unless ancestor == ActiveRecord::Base
+    end
+  end
+end

data/lib/aasm/state_machine.rb

@@ -1,13 +1,12 @@
 class AASM::StateMachine
-  def self.[](*args)
-    (@machines ||= {})[args]
+  def self.[](clazz)
+    (@machines ||= {})[clazz.to_s]
   end
-
-  def self.[]=(*args)
-    val = args.pop
-    (@machines ||= {})[args] = val
+  
+  def self.[]=(clazz, machine)
+    (@machines ||= {})[clazz.to_s] = machine
   end
-
+  
   attr_accessor :states, :events, :initial_state, :config
   attr_reader :name
 

data/lib/aasm/state_transition.rb

@@ -7,12 +7,12 @@ class AASM::SupportingClasses::StateTransition
     @opts = opts
   end
 
-  def perform(obj)
+  def perform(obj, *args)
     case @guard
       when Symbol, String
-        obj.send(@guard)
+        obj.send(@guard, *args)
       when Proc
-        @guard.call(obj)
+        @guard.call(obj, *args)
       else
         true
     end
@@ -36,10 +36,10 @@ class AASM::SupportingClasses::StateTransition
 
   def _execute(obj, on_transition, *args)
     case on_transition
-      when Symbol, String
-        obj.send(on_transition, *args)
-      when Proc
-        on_transition.call(obj, *args)
+    when Proc
+      on_transition.arity == 0 ? on_transition.call : on_transition.call(obj, *args)
+    when Symbol, String
+      obj.send(:method, on_transition.to_sym).arity == 0 ? obj.send(on_transition) : obj.send(on_transition, *args)
     end
   end
 

data/lib/aasm/version.rb

@@ -0,0 +1,3 @@
+module AASM
+  VERSION = "2.3.1"
+end

data/lib/aasm.rb

@@ -7,3 +7,4 @@ require File.join(File.dirname(__FILE__), 'aasm', 'supporting_classes')
 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')

data/spec/database.yml

@@ -0,0 +1,3 @@
+sqlite3:
+  adapter: sqlite3
+  database: spec/aasm.sqlite3.db

data/spec/en.yml

@@ -0,0 +1,10 @@
+en:
+  activerecord:
+    events:
+      localizer_test_model:
+        close: "Let's close it!"
+
+    attributes:
+      localizer_test_model:
+        aasm_state:
+          open: "It's opened now!"

data/spec/schema.rb

@@ -0,0 +1,7 @@
+ActiveRecord::Schema.define(:version => 0) do
+
+  %w{gates readers writers transients simples thieves localizer_test_models}.each do |table_name|
+    create_table table_name, :force => true
+  end
+
+end

data/spec/spec_helper.rb

@@ -1,11 +1,16 @@
 $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__)))
 $LOAD_PATH.unshift(File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib')))
-
 require 'aasm'
 
-require 'spec'
-require 'spec/autorun'
+require 'rspec'
+require 'rspec/autorun'
+
+# require 'ruby-debug'; Debugger.settings[:autoeval] = true; debugger; rubys_debugger = 'annoying'
+# require 'ruby-debug/completion'
 
-Spec::Runner.configure do |config|
-  
+def load_schema
+  config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
+  ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/debug.log")
+  ActiveRecord::Base.establish_connection(config['sqlite3'])
+  load(File.dirname(__FILE__) + "/schema.rb")
 end