workflow 0.8.1 → 0.8.3

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://www.rubygems.org"
+
+group :development do
+  gem "rdoc", "~> 3.12"
+  gem "bundler", ">= 1.0.0"
+  gem "jeweler", "~> 1.8.4"
+end
+
+gemspec

data/README.markdown

@@ -67,6 +67,18 @@ of possible events and other meta information:
         @transitions_to=:awaiting_review, @name=:submit, @meta={}>}, 
       name:new, meta{}
 
+On Ruby 1.9 and above, you can check whether a state comes before or
+after another state (by the order they were defined):
+
+    article.current_state
+    => being_reviewed
+    article.current_state < :accepted
+    => true
+    article.current_state >= :accepted
+    => false
+    article.between? :awaiting_review, :rejected
+    => true
+
 Now we can call the submit event, which transitions to the
 <tt>:awaiting_review</tt> state:
 
@@ -330,6 +342,26 @@ example][advanced_hooks_and_validation_test].
 
 [advanced_hooks_and_validation_test]: http://github.com/geekq/workflow/blob/master/test/advanced_hooks_and_validation_test.rb
 
+### on_error
+
+If you want to do custom exception handling internal to workflow, you can define an `on_error` hook in your workflow.  
+For example:
+
+    workflow do
+      state :first do
+        event :forward, :transitions_to => :second
+      end
+      state :second
+
+      on_error do |error, from, to, event, *args|
+        Log.info "Exception(#error.class) on #{from} -> #{to}" 
+      end
+    end
+
+If forward! results in an exception, `on_error` is invoked and the workflow stays in a 'first' state.  This capability 
+is particularly useful if your errors are transient and you want to queue up a job to retry in the future without 
+affecting the existing workflow state.
+
 ### Guards
 
 If you want to halt the transition conditionally, you can just raise an

data/Rakefile

@@ -1,10 +1,20 @@
 require 'rubygems'
+require 'bundler'
 require 'rubygems/package_task'
 require 'rake/testtask'
 require 'rdoc/task'
 
 task :default => [:test]
 
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
 Rake::TestTask.new do |t|
   t.verbose = true
   t.warning = true
@@ -16,16 +26,16 @@ Rake::RDocTask.new do |rdoc|
   rdoc.options << "-S"
 end
 
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gemspec|
-    gemspec.name = "workflow"
-    gemspec.rubyforge_project = 'workflow'
-    gemspec.email = "vladimir@geekq.net"
-    gemspec.homepage = "http://www.geekq.net/workflow/"
-    gemspec.authors = ["Vladimir Dobriakov"]
-    gemspec.summary = "A replacement for acts_as_state_machine."
-    gemspec.description = <<-EOS
+require 'jeweler'
+
+Jeweler::Tasks.new do |gemspec|
+  gemspec.name = "workflow"
+  gemspec.rubyforge_project = 'workflow'
+  gemspec.email = "vladimir@geekq.net"
+  gemspec.homepage = "http://www.geekq.net/workflow/"
+  gemspec.authors = ["Vladimir Dobriakov"]
+  gemspec.summary = "A replacement for acts_as_state_machine."
+  gemspec.description = <<-EOS
     Workflow is a finite-state-machine-inspired API for modeling and interacting
     with what we tend to refer to as 'workflow'.
 
@@ -34,11 +44,7 @@ begin
     * various hooks for single transitions, entering state etc.
     * convenient access to the workflow specification: list states, possible events
       for particular state
-    EOS
+  EOS
 
-    Jeweler::GemcutterTasks.new
-  end
-rescue LoadError
-  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+  Jeweler::GemcutterTasks.new
 end
-

data/VERSION

@@ -1 +1 @@
-0.8.1
+0.8.3

data/lib/workflow.rb

@@ -6,7 +6,7 @@ module Workflow
   class Specification
 
     attr_accessor :states, :initial_state, :meta,
-      :on_transition_proc, :before_transition_proc, :after_transition_proc
+      :on_transition_proc, :before_transition_proc, :after_transition_proc, :on_error_proc
 
     def initialize(meta = {}, &specification)
       @states = Hash.new
@@ -22,7 +22,7 @@ module Workflow
 
     def state(name, meta = {:meta => {}}, &events_and_etc)
       # meta[:meta] to keep the API consistent..., gah
-      new_state = Workflow::State.new(name, meta[:meta])
+      new_state = Workflow::State.new(name, self, meta[:meta])
       @initial_state = new_state if @states.empty?
       @states[name.to_sym] = new_state
       @scoped_state = new_state
@@ -57,6 +57,10 @@ module Workflow
     def on_transition(&proc)
       @on_transition_proc = proc
     end
+
+    def on_error(&proc)
+      @on_error_proc = proc
+    end
   end
 
   class TransitionHalted < Exception
@@ -79,9 +83,26 @@ module Workflow
   class State
 
     attr_accessor :name, :events, :meta, :on_entry, :on_exit
-
-    def initialize(name, meta = {})
-      @name, @events, @meta = name, Hash.new, meta
+    attr_reader :spec
+
+    def initialize(name, spec, meta = {})
+      @name, @spec, @events, @meta = name, spec, Hash.new, meta
+    end
+
+    unless RUBY_VERSION < '1.9'
+      include Comparable
+  
+      def <=>(other_state)
+        states = spec.states.keys
+        raise ArgumentError, "state `#{other_state}' does not exist" unless other_state.in? states
+        if states.index(self.to_sym) < states.index(other_state.to_sym)
+          -1
+        elsif states.index(self.to_sym) > states.index(other_state.to_sym)
+          1
+        else
+          0
+        end
+      end
     end
 
     def to_s
@@ -143,6 +164,7 @@ module Workflow
   end
 
   module WorkflowInstanceMethods
+
     def current_state
       loaded_state = load_workflow_state
       res = spec.states[loaded_state.to_sym] if loaded_state
@@ -177,7 +199,12 @@ module Workflow
       run_before_transition(from, to, name, *args)
       return false if @halted
 
-      return_value = run_action(event.action, *args) || run_action_callback(event.name, *args)
+      begin
+        return_value = run_action(event.action, *args) || run_action_callback(event.name, *args)
+      rescue Exception => e
+        run_on_error(e, from, to, name, *args)
+      end
+
       return false if @halted
 
       run_on_transition(from, to, name, *args)
@@ -236,6 +263,15 @@ module Workflow
         spec.before_transition_proc
     end
 
+    def run_on_error(error, from, to, event, *args)
+      if spec.on_error_proc
+        instance_exec(error, from.name, to.name, event, *args, &spec.on_error_proc)
+        halt(error.message)
+      else
+        raise error
+      end
+    end
+
     def run_on_transition(from, to, event, *args)
       instance_exec(from.name, to.name, event, *args, &spec.on_transition_proc) if spec.on_transition_proc
     end
@@ -248,9 +284,14 @@ module Workflow
     def run_action(action, *args)
       instance_exec(*args, &action) if action
     end
+    
+    def has_callback?(action)
+      self.respond_to?(action) or self.class.private_method_defined?(action)
+    end
 
     def run_action_callback(action_name, *args)
-      self.send action_name.to_sym, *args if self.respond_to?(action_name.to_sym)
+      action = action_name.to_sym
+      self.send(action, *args) if has_callback?(action)
     end
 
     def run_on_entry(state, prior_state, triggering_event, *args)
@@ -297,7 +338,7 @@ module Workflow
     # On transition the new workflow state is immediately saved in the
     # database.
     def persist_workflow_state(new_value)
-      update_attribute self.class.workflow_column, new_value
+      update_attributes self.class.workflow_column => new_value
     end
 
     private

data/test/advanced_hooks_and_validation_test.rb

@@ -51,8 +51,9 @@ class Article < ActiveRecord::Base
           }
         end
 
-        singleton.send :define_method, :validate, &validations
-        halt! "Event[#{triggering_event}]'s transitions_to[#{to}] is not valid." if self.invalid?
+        singleton.send :define_method, :validate_for_transition, &validations
+        validate_for_transition
+        halt! "Event[#{triggering_event}]'s transitions_to[#{to}] is not valid." unless self.errors.empty?
       end
     end
   end

data/test/main_test.rb

@@ -244,6 +244,17 @@ class MainTest < ActiveRecordTestCase
     assert !o.shipped?
   end
 
+  unless RUBY_VERSION < '1.9'
+    test 'compare states' do
+      o = assert_state 'some order', 'accepted'
+      assert o.current_state < :shipped
+      assert o.current_state > :submitted
+      assert_raise ArgumentError do
+        o.current_state > :unknown
+      end
+    end
+  end
+
   test 'correct exception for event, that is not allowed in current state' do
     o = assert_state 'some order', 'accepted'
     assert_raise Workflow::NoTransitionAllowed do
@@ -268,8 +279,36 @@ class MainTest < ActiveRecordTestCase
         end
         state :two
       end
+
+      private
+      def another_transition(args)
+        args.another_tran
+      end
+    end
+    a = c.new
+    a.my_transition!(args)
+  end
+
+  test '#53 Support for private transition callbacks' do
+    args = mock()
+    args.expects(:log).once
+    c = Class.new
+    c.class_eval do
+      include Workflow
+      workflow do
+        state :new do
+          event :assign, :transitions_to => :assigned
+        end
+        state :assigned
+      end
+
+      private
+      def assign(args)
+        args.log('Assigned')
+      end
     end
-    c.new.my_transition!(args)
+    a = c.new
+    a.assign!(args)
   end
 
   test 'Single table inheritance (STI)' do

data/test/on_error_test.rb

@@ -0,0 +1,52 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+require 'workflow'
+
+class OnErrorTest < Test::Unit::TestCase
+  # A class that does not handle errors in an error block
+  class NoErrorBlock
+    include Workflow
+    workflow do
+      state :first do
+        event :forward, :transitions_to => :second do
+          raise "This is some random runtime error"
+        end
+      end
+      state :second
+    end
+  end
+
+  # A class that handles errors in an error block
+  class ErrorBlock
+    attr_reader :errors
+
+    def initialize
+      @errors = {}
+    end
+
+    include Workflow
+    workflow do
+      state :first do
+        event :forward, :transitions_to => :second do
+          raise "This is some random runtime error"
+        end
+      end
+      state :second
+      on_error { |error, from, to, event, *args| @errors.merge!({:error => error.class, :from => from, :to => to, :event => event, :args => args}) }
+    end
+  end
+
+
+  test 'that an exception is raised if there is no associated on_error block' do
+    flow = NoErrorBlock.new
+    assert_raise( RuntimeError, "This is some random runtime error" ) { flow.forward! }
+    assert_equal(true, flow.first?)
+  end
+  
+  test 'that on_error block is called when an exception is raised and the transition is halted' do
+    flow = ErrorBlock.new
+    assert_nothing_raised { flow.forward! }
+    assert_equal({:error => RuntimeError, :from=>:first, :to=>:second, :event=>:forward, :args=>[]}, flow.errors)
+    # transition should not happen
+    assert_equal(true, flow.first?)
+  end
+end

data/workflow.gemspec

@@ -4,26 +4,19 @@
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
-  s.name = %q{workflow}
-  s.version = "0.8.1"
+  s.name = "workflow"
+  s.version = "0.8.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Vladimir Dobriakov"]
-  s.date = %q{2011-08-20}
-  s.description = %q{    Workflow is a finite-state-machine-inspired API for modeling and interacting
-    with what we tend to refer to as 'workflow'.
-
-    * nice DSL to describe your states, events and transitions
-    * robust integration with ActiveRecord and non relational data stores
-    * various hooks for single transitions, entering state etc.
-    * convenient access to the workflow specification: list states, possible events
-      for particular state
-}
-  s.email = %q{vladimir@geekq.net}
+  s.date = "2012-12-04"
+  s.description = "    Workflow is a finite-state-machine-inspired API for modeling and interacting\n    with what we tend to refer to as 'workflow'.\n\n    * nice DSL to describe your states, events and transitions\n    * robust integration with ActiveRecord and non relational data stores\n    * various hooks for single transitions, entering state etc.\n    * convenient access to the workflow specification: list states, possible events\n      for particular state\n"
+  s.email = "vladimir@geekq.net"
   s.extra_rdoc_files = [
     "README.markdown"
   ]
   s.files = [
+    "Gemfile",
     "MIT-LICENSE",
     "README.markdown",
     "Rakefile",
@@ -34,26 +27,50 @@ Gem::Specification.new do |s|
     "test/couchtiny_example.rb",
     "test/main_test.rb",
     "test/multiple_workflows_test.rb",
+    "test/on_error_test.rb",
     "test/readme_example.rb",
     "test/test_helper.rb",
     "test/without_active_record_test.rb",
     "workflow.gemspec",
     "workflow.rb"
   ]
-  s.homepage = %q{http://www.geekq.net/workflow/}
+  s.homepage = "http://www.geekq.net/workflow/"
   s.require_paths = ["lib"]
-  s.rubyforge_project = %q{workflow}
-  s.rubygems_version = %q{1.3.6}
-  s.summary = %q{A replacement for acts_as_state_machine.}
+  s.rubyforge_project = "workflow"
+  s.rubygems_version = "1.8.24"
+  s.summary = "A replacement for acts_as_state_machine."
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<workflow>, [">= 0"])
+      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_development_dependency(%q<bundler>, [">= 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.8.4"])
+      s.add_development_dependency(%q<rake>, [">= 0"])
+      s.add_development_dependency(%q<mocha>, [">= 0"])
+      s.add_development_dependency(%q<activerecord>, [">= 0"])
+      s.add_development_dependency(%q<sqlite3>, [">= 0"])
     else
+      s.add_dependency(%q<workflow>, [">= 0"])
+      s.add_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_dependency(%q<bundler>, [">= 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
+      s.add_dependency(%q<rake>, [">= 0"])
+      s.add_dependency(%q<mocha>, [">= 0"])
+      s.add_dependency(%q<activerecord>, [">= 0"])
+      s.add_dependency(%q<sqlite3>, [">= 0"])
     end
   else
+    s.add_dependency(%q<workflow>, [">= 0"])
+    s.add_dependency(%q<rdoc>, ["~> 3.12"])
+    s.add_dependency(%q<bundler>, [">= 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.8.4"])
+    s.add_dependency(%q<rake>, [">= 0"])
+    s.add_dependency(%q<mocha>, [">= 0"])
+    s.add_dependency(%q<activerecord>, [">= 0"])
+    s.add_dependency(%q<sqlite3>, [">= 0"])
   end
 end
 

metadata

@@ -1,32 +1,157 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: workflow
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 8
-  - 1
-  version: 0.8.1
+version: !ruby/object:Gem::Version
+  version: 0.8.3
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Vladimir Dobriakov
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-08-20 00:00:00 +02:00
-default_executable: 
-dependencies: []
-
-description: "    Workflow is a finite-state-machine-inspired API for modeling and interacting\n    with what we tend to refer to as 'workflow'.\n\n    * nice DSL to describe your states, events and transitions\n    * robust integration with ActiveRecord and non relational data stores\n    * various hooks for single transitions, entering state etc.\n    * convenient access to the workflow specification: list states, possible events\n      for particular state\n"
+date: 2012-12-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: workflow
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.4
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! "    Workflow is a finite-state-machine-inspired API for modeling and
+  interacting\n    with what we tend to refer to as 'workflow'.\n\n    * nice DSL
+  to describe your states, events and transitions\n    * robust integration with ActiveRecord
+  and non relational data stores\n    * various hooks for single transitions, entering
+  state etc.\n    * convenient access to the workflow specification: list states,
+  possible events\n      for particular state\n"
 email: vladimir@geekq.net
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.markdown
-files: 
+files:
+- Gemfile
 - MIT-LICENSE
 - README.markdown
 - Rakefile
@@ -37,40 +162,37 @@ files:
 - test/couchtiny_example.rb
 - test/main_test.rb
 - test/multiple_workflows_test.rb
+- test/on_error_test.rb
 - test/readme_example.rb
 - test/test_helper.rb
 - test/without_active_record_test.rb
 - workflow.gemspec
 - workflow.rb
-has_rdoc: true
 homepage: http://www.geekq.net/workflow/
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
+      hash: 3639477061676612937
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: workflow
-rubygems_version: 1.3.6
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: A replacement for acts_as_state_machine.
 test_files: []
-