workflow 0.2.0 → 0.3.0

data/{LICENSE → MIT-LICENSE}

@@ -1,3 +1,4 @@
+Copyright (c) 2008-2009 Vodafone
 Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -16,4 +17,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE.

data/README.rdoc

@@ -71,23 +71,83 @@ are very problematic.
 
 == Installation
 
-You can just download the lib/workflow.rb and put it in the lib folder of your 
+    gem install workflow
+
+Alternatively you can just download the lib/workflow.rb and put it in the lib folder of your 
 Rails application.
 
-Later I'll probable create a gem.
+
+== Migration from the original Ryan's library
+
+Credit: Michael (rockrep)
+
+* Accessing workflow specification
+    my_instance.workflow # old
+    MyClass.workflow_spec # new
+
+* Accessing states, events, meta, e.g.
+    my_instance.workflow.states(:some_state).events(:some_event).meta[:some_meta_tag] # old
+    MyClass.workflow_spec.states[:some_state].events[:some_event].meta[:some_meta_tag] # new
+
+* Causing state transitions
+    my_instance.workflow.my_event # old
+    my_instance.my_event! # new
+
+* when using both a block and a callback method for an event, the block executes prior to the callback
 
 
 == About
 
 Author: Vladimir Dobriakov, http://www.innoq.com/blog/vd, http://blog.geekq.net/
 
-Parts copyright 2009 Vodafone
+Copyright (c) 2008-2009 Vodafone
+
+Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd
 
 Based on the work of Ryan Allen and Scott Barron
 
+Licensed under MIT license, see the MIT-LICENSE file.
+
+
+== New in the version 0.3.0
+
+Intermixing of transition graph definition (states, transitions)
+on the one side and implementation of the actions on the other side
+for a bigger state machine can introduce clutter.
+
+To reduce this clutter it is now possible to use state entry- and 
+exit- hooks defined through a naming convention. For example, if there
+is a state :pending, then instead of using a
+block:
+
+    state :pending do
+      on_entry do
+        # your implementation here
+      end
+    end
+
+you can hook in by defining method 
+
+def on_pending_exit(new_state, event, *args)
+  # your implementation here
+end
+
+anywhere in your class. You can also use a simpler function signature
+like `def on_pending_exit(*args)` if your are not interested in arguments -
+`def on_pending_exit()` with an empty list would not work.
+
+If both a function with a name according to naming convention and the 
+on_entry/on_exit block are given, then only on_entry/on_exit block is used.
+
 
 = Original readme
 
+Disclaimer: my fork is not 100% API compatible to the original library by Ryan.
+I'll update/merge the readme as soon as posssible.
+In the mean time please use the original readme in conjunction with
+the API changes and migration hints listed above.
+
+
 === New Mailing List!
 
 Hi! We've now got a mailing list to talk about Workflow, and that's good! Come visit and post your problems or ideas or anything!!!
@@ -108,35 +168,50 @@ Now, all that's a mouthful, but we'll demonstrate the API bit by bit with a real
 
 Let's say we're modeling article submission from journalists. An article is written, then submitted. When it's submitted, it's awaiting review. Someone reviews the article, and then either accepts or rejects it. Explaining all that is a pain in the arse. Here is the expression of this workflow using the API:
 
-  Workflow.specify 'Article Workflow' do
-    state :new do
-      event :submit, :transitions_to => :awaiting_review
-    end
-    state :awaiting_review do
-      event :review, :transitions_to => :being_reviewed
-    end
-    state :being_reviewed do
-      event :accept, :transitions_to => :accepted
-      event :reject, :transitions_to => :rejected
+
+  class Article
+    include Workflow
+    workflow do
+      state :new do
+        event :submit, :transitions_to => :awaiting_review
+      end
+      state :awaiting_review do
+        event :review, :transitions_to => :being_reviewed
+      end
+      state :being_reviewed do
+        event :accept, :transitions_to => :accepted
+        event :reject, :transitions_to => :rejected
+      end
+      state :accepted
+      state :rejected
     end
-    state :accepted
-    state :rejected
   end
-  
+
 Much better, isn't it!
 
-The initial state is <tt>:new</tt> – in this example that's somewhat meaningless. (?) However, the <tt>:submit</tt> event <tt>:transitions_to => :being_reviewed</tt>. So, lets instantiate an instance of this Workflow:
+Let's create an article instance and check in which state it is:
+
+  article = Article.new
+  article.accepted? # => false
+  article.new? # => true
+
+You can also access the whole +current_state+ object including the list of possible events and other meta information:
+
+  article.current_state 
+  => #<Workflow::State:0x7f1e3d6731f0 @events={
+    :submit=>#<Workflow::Event:0x7f1e3d6730d8 @action=nil, 
+      @transitions_to=:awaiting_review, @name=:submit, @meta={}>}, 
+    name:new, meta{}
 
-  workflow = Workflow.new('Article Workflow')
-  workflow.state # => :new
-  
 Now we can call the submit event, which transitions to the <tt>:awaiting_review</tt> state:
 
-  workflow.submit
-  workflow.state # => :awaiting_review
+  article.submit!
+  article.awaiting_review? # => true
   
 Events are actually instance methods on a workflow, and depending on the state you're in, you'll have a different set of events used to transition to other states.
 
+TODO - continue editing
+
 Given this workflow is now <tt>:awaiting_approval</tt>, we have a <tt>:review</tt> event, that we call when someone begins to review the article, which puts the workflow into the <tt>:being_reviewed</tt> state.
 
 States can also be queried via predicates for convenience like so:

data/Rakefile

@@ -8,11 +8,12 @@ task :default => [:test]
 Rake::TestTask.new do |t|
   t.verbose = true
   t.warning = true
+  t.pattern = 'test/*_test.rb'
 end
 
-PKG_VERSION = "0.2.0"
+PKG_VERSION = "0.3.0"
 PKG_FILES = FileList[
-  'LICENSE',
+  'MIT-LICENSE',
   'README.rdoc',
   'Rakefile',
   'lib/**/*.rb',
@@ -33,7 +34,7 @@ end
 
 Rake::RDocTask.new do |rdoc|
   rdoc.main = "README"
-  rdoc.rdoc_files.include("README", "lib/**/*.rb")
+  rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
   rdoc.options << "-S"
 end
 

data/lib/workflow.rb

@@ -55,6 +55,8 @@ module Workflow
 
   class NoTransitionAllowed < Exception; end
 
+  class WorkflowError < Exception; end
+
   class State
     
     attr_accessor :name, :events, :meta, :on_entry, :on_exit
@@ -138,6 +140,7 @@ module Workflow
           false
         end
       else
+        check_transition(event)
         run_on_transition(current_state, spec.states[event.transitions_to], name, *args)
         transition(current_state, spec.states[event.transitions_to], name, *args)
         return_value
@@ -146,6 +149,16 @@ module Workflow
 
     private
 
+    def check_transition(event)
+      # Create a meaningful error message instead of 
+      # "undefined method `on_entry' for nil:NilClass"
+      # Reported by Kyle Burton
+      if !spec.states[event.transitions_to]
+        raise WorkflowError.new("Event[#{event.name}]'s " + 
+            "transitions_to[#{event.transitions_to}] is not a declared state.")
+      end
+    end
+
     def spec
       c = self.class
       # using a simple loop instead of class_inheritable_accessor to avoid 
@@ -187,11 +200,23 @@ module Workflow
     end
 
     def run_on_entry(state, prior_state, triggering_event, *args)     
-      instance_exec(prior_state.name, triggering_event, *args, &state.on_entry) if state.on_entry
+      if state.on_entry
+        instance_exec(prior_state.name, triggering_event, *args, &state.on_entry) 
+      else
+        hook_name = "on_#{state}_entry"
+        self.send hook_name, prior_state, triggering_event, *args if self.respond_to? hook_name
+      end
     end
 
     def run_on_exit(state, new_state, triggering_event, *args)
-      instance_exec(new_state.name, triggering_event, *args, &state.on_exit) if state and state.on_exit
+      if state
+        if state.on_exit
+          instance_exec(new_state.name, triggering_event, *args, &state.on_exit)
+        else
+          hook_name = "on_#{state}_exit"
+          self.send hook_name, new_state, triggering_event, *args if self.respond_to? hook_name
+        end
+      end
     end
 
     # load_workflow_state and persist_workflow_state
@@ -236,9 +261,11 @@ module Workflow
   def self.included(klass)
     klass.send :include, WorkflowInstanceMethods
     klass.extend WorkflowClassMethods
-    if klass < ActiveRecord::Base
+    if Object.const_defined?(:ActiveRecord)
+      if klass < ActiveRecord::Base
       klass.send :include, ActiveRecordInstanceMethods
       klass.before_validation :write_initial_state
+      end
     end
   end
 end

data/test/test_helper.rb

@@ -0,0 +1,16 @@
+require 'rubygems'
+require 'test/unit'
+
+class << Test::Unit::TestCase
+  def test(name, &block)
+    test_name = :"test_#{name.gsub(' ','_')}"
+    raise ArgumentError, "#{test_name} is already defined" if self.instance_methods.include? test_name.to_s
+    if block
+      define_method test_name, &block
+    else  
+      puts "PENDING: #{name}"
+    end   
+  end   
+end
+
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: workflow
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Vladimir Dobriakov
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-29 00:00:00 +02:00
+date: 2009-08-10 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
@@ -22,12 +22,12 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
-- LICENSE
+- MIT-LICENSE
 - README.rdoc
 - Rakefile
 - lib/workflow.rb
-- test/test_workflow.rb
-has_rdoc: false
+- test/test_helper.rb
+has_rdoc: true
 homepage: http://blog.geekQ.net/
 licenses: []
 
@@ -51,7 +51,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.1.2403
+rubygems_version: 1.3.3
 signing_key: 
 specification_version: 3
 summary: A replacement for acts_as_state_machine.

data/test/test_workflow.rb

@@ -1,252 +0,0 @@
-require 'rubygems'
-require 'test/unit'
-old_verbose, $VERBOSE = $VERBOSE, nil
-require 'active_record'
-require 'sqlite3'
-$VERBOSE = old_verbose
-require 'workflow'
-require 'mocha'
-#require 'ruby-debug'
-
-ActiveRecord::Migration.verbose = false
-
-class << Test::Unit::TestCase
-  def test(name, &block)
-    test_name = :"test_#{name.gsub(' ','_')}"
-    raise ArgumentError, "#{test_name} is already defined" if self.instance_methods.include? test_name.to_s
-    if block
-      define_method test_name, &block
-    else
-      puts "PENDING: #{name}"
-    end
-  end
-end
-
-class Order < ActiveRecord::Base
-  include Workflow
-  workflow do
-    state :submitted do
-      event :accept, :transitions_to => :accepted, :meta => {:doc_weight => 8} do |reviewer, args|
-      end
-    end
-    state :accepted do
-      event :ship, :transitions_to => :shipped
-    end
-    state :shipped
-  end
-  
-end
-
-class WorkflowTest < Test::Unit::TestCase
-
-  def exec(sql)
-    ActiveRecord::Base.connection.execute sql
-  end
-
-  def setup
-    old_verbose, $VERBOSE = $VERBOSE, nil # eliminate sqlite3 warning. TODO: delete as soon as sqlite-ruby is fixed
-    ActiveRecord::Base.establish_connection(
-      :adapter => "sqlite3",
-      :database  => ":memory:" #"tmp/test"
-    )
-    ActiveRecord::Base.connection.reconnect! # eliminate ActiveRecord warning. TODO: delete as soon as ActiveRecord is fixed
-    
-    ActiveRecord::Schema.define do
-      create_table :orders do |t|
-        t.string :title, :null => false
-        t.string :workflow_state
-      end
-    end
-
-    exec "INSERT INTO orders(title, workflow_state) VALUES('some order', 'accepted')"
-    $VERBOSE = old_verbose
-  end
-
-  def teardown
-    ActiveRecord::Base.connection.disconnect!
-  end
-
-  def assert_state(title, expected_state)
-    o = Order.find_by_title(title)
-    assert_equal expected_state, o.read_attribute(:workflow_state)
-    o
-  end
-
-  test 'immediatly save the new workflow_state on state machine transition' do
-    o = assert_state 'some order', 'accepted'
-    o.ship!
-    assert_state 'some order', 'shipped'
-  end
-
-  test 'persist workflow_state in the db and reload' do
-    o = assert_state 'some order', 'accepted'
-    assert_equal :accepted, o.current_state.name
-    o.ship!
-    o.save!
-
-    assert_state 'some order', 'shipped'
-
-    o.reload
-    assert_equal 'shipped', o.read_attribute(:workflow_state)
-  end
-
-  test 'access workflow specification' do
-    assert_equal 3, Order.workflow_spec.states.length
-  end
-
-  test 'current state object' do
-    o = assert_state 'some order', 'accepted'
-    assert_equal 'accepted', o.current_state.to_s
-    assert_equal 1, o.current_state.events.length
-  end
-
-  test 'on_entry and on_exit invoked' do
-    c = Class.new
-    callbacks = mock()
-    callbacks.expects(:my_on_exit_new).once
-    callbacks.expects(:my_on_entry_old).once
-    c.class_eval do
-      include Workflow
-      workflow do
-        state :new do
-          event :age, :transitions_to => :old
-        end
-        on_exit do
-          callbacks.my_on_exit_new
-        end
-        state :old
-        on_entry do
-          callbacks.my_on_entry_old
-        end
-        on_exit do
-          fail "wrong on_exit executed"
-        end
-      end
-    end
-
-    o = c.new
-    assert_equal 'new', o.current_state.to_s
-    o.age!
-  end
-
-  test 'on_transition invoked' do
-    callbacks = mock()
-    callbacks.expects(:on_tran).once # this is validated at the end
-    c = Class.new
-    c.class_eval do
-      include Workflow
-      workflow do
-        state :one do
-          event :increment, :transitions_to => :two
-        end
-        state :two
-        on_transition do |from, to, triggering_event, *event_args|
-          callbacks.on_tran
-        end
-      end
-    end
-    assert_not_nil c.workflow_spec.on_transition_proc
-    c.new.increment!
-  end
-
-  test 'access event meta information' do
-    c = Class.new
-    c.class_eval do
-      include Workflow
-      workflow do
-        state :main, :meta => {:importance => 8}
-        state :supplemental, :meta => {:importance => 1}
-      end
-    end
-    assert_equal 1, c.workflow_spec.states[:supplemental].meta[:importance]
-  end
-
-  test 'initial state' do
-    c = Class.new
-    c.class_eval do
-      include Workflow
-      workflow { state :one; state :two }
-    end
-    assert_equal 'one', c.new.current_state.to_s
-  end
-
-  test 'nil as initial state' do
-    exec "INSERT INTO orders(title, workflow_state) VALUES('nil state', NULL)"
-    o = Order.find_by_title('nil state')
-    assert o.submitted?, 'if workflow_state is nil, the initial state should be assumed'
-    assert !o.shipped?
-  end
-
-  test 'initial state immediately set as ActiveRecord attribute for new objects' do
-    o = Order.create(:title => 'new object')
-    assert_equal 'submitted', o.read_attribute(:workflow_state)
-  end
-
-  test 'question methods for state' do
-    o = assert_state 'some order', 'accepted'
-    assert o.accepted?
-    assert !o.shipped?
-  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
-      o.accept!
-    end
-  end
-
-  test 'multiple events with the same name and different arguments lists from different states'
-
-  test 'implicit transition callback' do
-    args = mock()
-    args.expects(:my_tran).once # this is validated at the end
-    c = Class.new
-    c.class_eval do
-      include Workflow
-      def my_transition(args)
-        args.my_tran
-      end
-      workflow do
-        state :one do
-          event :my_transition, :transitions_to => :two
-        end
-        state :two
-      end
-    end
-    c.new.my_transition!(args)
-  end
-
-  test 'Single table inheritance (STI)' do
-    class BigOrder < Order
-    end
-
-    bo = BigOrder.new
-    assert bo.submitted?
-    assert !bo.accepted?
-  end
-
-  test 'Two-level inheritance' do
-    class BigOrder < Order
-    end
-
-    class EvenBiggerOrder < BigOrder
-    end
-
-    assert EvenBiggerOrder.new.submitted?
-  end
-
-  test 'Iheritance with workflow definition override' do
-    class BigOrder < Order
-    end
-
-    class SpecialBigOrder < BigOrder
-      workflow do
-        state :start_big
-      end
-    end
-
-    special = SpecialBigOrder.new
-    assert_equal 'start_big', special.current_state.to_s
-  end
-end
-