workflow 0.1.0

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

data/README.rdoc

@@ -0,0 +1,377 @@
+= Motivation for the fork
+
+Why to overflow the world with yet another fork of the workflow library?
+
+Well, while the workflow definition API of the original library is nice,
+the implementation of the ActiveRecord integration and the remaining API
+are very problematic.
+
+== API improvements
+
+* Fixed fuzzy API. For example, the states() function returned a state object
+  or an array of strings, depending on function parameters!
+  While somebody could find the usage like `states(states.first)` funny,
+  it leads to a maintanence nightmare and the usage is difficult to explain
+  to the new team members.
+
+* When we activate the state transition, we typically do not make any other
+  changes to the attributes of the entity. So by default the event
+  invokation now immediately saves the new state to the database.
+  `update_attribute` is used for implementation. This can be overriden 
+  with the `persist_workflow_state` method.
+
+* We've noticed, that mixing the list of events and states with the blocks
+  invoked for particular transitions leads to a bumpy and poorly readable code
+  due to a deep nesting. We tried (and dismissed) lambdas for this. Eventually
+  we desided to invoke an optional user defined callback method with the same
+  name as the event (convention over configuration)
+      
+      event :my_transition, :transitions_to => other_state
+
+  defines a transition method `my_transition!` and invokes user defined callback 
+  function `my_transition` (with no exclamation mark). The old way - using
+  a block or a combination of both is also possible.
+
+* In the API the workflow specification is clearly separated from the object
+  state. The former is accessible through the class method
+  `MyEntityClass.workflow_spec` (including all the meta data) and the latter
+  is integrated in the instance of the my_entity, e.g. my_entity.current_state
+  or my_entity.my_event!
+
+
+== Implementation improvements
+
+* Replaced the extensive usage of method_missing with a simple generation
+  of needed functions like `my_state?` and `my_event`. Advantages:
+
+  * shorter and more meaningful stack during debugging
+  * public_methods shows the methods
+  * autocompletion in irb works
+
+* Do not use ActiveRecord hooks leading to the divergence of `workflow_state`
+  table attribute and wokflow.current_state.
+
+* Fixed all the warnings and usage of obsolete API.
+
+* The messy and fuzzy API is probably partially caused by RSpec driven
+  development. While RSpec can be useful for gathering and mapping business
+  requirements, it is IMHO totally unsuitable for driving a clean, explicit,
+  orthogonal API. If I say `state` in the natural language or in a RSpec, it is
+  not clear, what I mean - a string, a symbol, an object of class State, a hash?
+  This(?) led to this fuzzy API.
+  So I switched to the plain old unit tests.
+
+* Eliminated bidirectional connection between the model
+  class and Workflow::Instance - the bind_to, @context, @workflow.
+
+* Only one file with 240 lines of code and no interdependencies between classes.
+  As little meta programming as needed - not as much as possible. ;-)
+  So you can easily extend or modify it to suit your needs.
+
+
+== Installation
+
+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.
+
+
+== About
+
+Author: Vladimir Dobriakov, http://www.innoq.com/blog/vd, http://blog.geekq.net/
+
+Parts copyright 2009 Vodafone
+
+Based on the work of Ryan Allen and Scott Barron
+
+
+= Original readme
+
+=== 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!!!
+
+  http://groups.google.com/group/ruby-workflow
+
+See you there!
+
+=== What is workflow?
+
+Workflow is a finite-state-machine-inspired API for modeling and interacting with what we tend to refer to as 'workflow'.
+
+A lot of business modeling tends to involve workflow-like concepts, and the aim of this library is to make the expression of these concepts as clear as possible, using similar terminology as found in state machine theory.
+
+So, a workflow has a state. It can only be in one state at a time. When a workflow changes state, we call that a transition. Transitions occur on an event, so events cause transitions to occur. Additionally, when an event fires, other random code can be executed, we call those actions. So any given state has a bunch of events, any event in a state causes a transition to another state and potentially causes code to be executed (an action). We can hook into states when they are entered, and exited from, and we can cause transitions to fail (guards), and we can hook in to every transition that occurs ever for whatever reason we can come up with.
+
+Now, all that's a mouthful, but we'll demonstrate the API bit by bit with a real-ish world example.
+
+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
+    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:
+
+  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
+  
+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.
+
+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:
+
+  workflow = Workflow.new('Article Workflow')
+  workflow.new?             # => true
+  workflow.awaiting_review? # => false  
+  workflow.submit
+  workflow.new?             # => false
+  workflow.awaiting_review? # => true  
+
+Lets say that the business rule is that only one person can review an article at a time – having a state <tt>:being_reviewed</tt> allows for doing things like checking which articles are being reviewed, and being able to select from a pool of articles that are awaiting review, etc. (rewrite?)
+
+Now lets say another business rule is that we need to keep track of who is currently reviewing what, how do we do this? We'll now introduce the concept of an action by rewriting our <tt>:review</tt> event.
+
+  event :review, :transitions_to => :being_reviewed do |reviewer|
+    # store the reviewer somewhere for later
+  end
+
+By using Ruby blocks we've now introduced extra code to be fired when an event is called. The block parameters are treated as method arguments on the event, so, given we have a reference to the reviewer, the event call becomes:
+
+  # we gots a reviewer
+  workflow.reivew(reviewer)
+
+OK, so how do we store the reviewer? What is the scope inside that block? Ah, we'll get to that in a bit. An instance of a workflow isn't as useful as a workflow bound to an instance of another class. We'll introduce you to plain old Class integration and ActiveRecord integration later in this document.
+
+So we've covered events, states, transitions and actions (as Ruby blocks). Now we're going to go over some hooks you have access to in a workflow. These are on_exit, on_entry and on_transition.
+
+When states transition, they are entered into, and exited out of, we can hook into this and do fancy junk.
+
+  state :being_reviewed do
+    event :accept, :transitions_to => :accepted
+    event :reject, :transitions_to => :rejected
+    on_exit do |new_state, triggering_event, *event_args|
+      # do something related to coming out of :being_reviewed
+    end
+  end
+  
+  state :accepted do
+    on_entry do |prior_state, triggering_event, *event_args|
+      # do something relevant to coming in to :accepted
+    end
+  end
+
+Now why don't we just put this code into an action block? Well, you might not have only one event that transitions into a state, you may have multiple events that transition to a particular state, so by using the on_entry and on_exit hooks you're guaranteeing that a certain bit of code is executed, regardless what event fires the transition.
+
+Billy Bob the Manager comes to you and says "I need to know EVERYTHING THAT HAPPENS EVERYWHERE AT ANY TIME FOR EVERYTHING". For whatever reasons you have to record the history of the entire workflow. That's easy using on_transition.
+
+  on_transition do |from, to, triggering_event, *event_args|
+    # record everything, or something
+  end
+
+Workflow doesn't try to tell you how to store your log messages, (but we'd suggest using a *splat and storing that somewhere, and keep your log messages flexible).
+
+Finite state machines have the concept of a guard. The idea is that if a certain set of arbitrary conditions are not fulfilled, it will halt the transition from one state to another. We haven't really figured out how to do this, and we don't like the idea of going <tt>:guard => Proc.new {}</tt>, coz that's a bit lame, so instead we have <tt>halt!</tt>
+
+The <tt>halt!</tt> method is the implementation of the guard concept. Let's take a look.
+
+  state :being_reviewed do
+    event :accept, :transitions_to => :accepted do
+      halt if true # does not transition to :accepted
+    end
+  end
+
+Inline with how ActiveRecord does things, <tt>halt!</tt> also can be called via <tt>halt</tt>, which makes the event return false, so you can trap it with if workflow.event instead of using a rescue block. Using halt returns false.
+
+  # using halt
+  workflow.state   # => :being_reviewed
+  workflow.accept  # => false
+  workflow.halted? # => true
+  workflow.state   # => :being_reviewed
+  
+  # using halt!
+  workflow.state  # => :being_reviewed
+  begin
+    workflow.accept
+  rescue Workflow::Halted => e
+    # we gots an exception
+  end
+  workflow.halted? # => true
+  workflow.state   # => :being_reviewed
+
+Furthermore, <tt>halt!</tt> and <tt>halt</tt> accept an argument, which is the message why the workflow was halted.
+
+  state :being_reviewed do
+    event :accept, :transitions_to => :accepted do
+      halt 'coz I said so!' if true # does not transition to :accepted
+    end
+  end
+
+And the API for, like, getting this message, with both <tt>halt</tt> and <tt>halt!</tt>:
+
+  # using halt
+  workflow.state          # => :being_reviewed
+  workflow.accept         # => false
+  workflow.halted?        # => true
+  workflow.halted_because # => 'coz I said so!'
+  workflow.state          # => :being_reviewed
+
+  # using halt!
+  workflow.state  # => :being_reviewed
+  begin
+    workflow.accept
+  rescue Workflow::Halted => e
+    e.halted_because # => 'coz I said so!' 
+  end
+  workflow.halted? # => true
+  workflow.state   # => :being_reviewed
+
+We can reflect off the workflow to (attempt) to automate as much as we can. There are two types of reflection in Workflow - reflection and meta-reflection. We'll explain the former first.
+
+  workflow.states # => [:new, :awaiting_review, :being_reviewed, :accepted, :rejected]
+  workflow.states(:new).events # => [:submit]
+  workflow.states(:being_reviewed).events # => [:accept, :reject]
+  workflow.states(:being_reviewed).events(:accept).transitions_to # => :accepted
+
+Meta-reflection allows you to add further information to your states, events in order to allow you to build whatever interface/controller/etc you require for your application. If reflection were Batman then meta-reflection is Robin, always there to lend a helping hand when Batman just isn't enough.
+
+  state :new, :meta => :ui_widget => :radio_buttons do
+    event :submit, :meta => :label => 'Upload...'
+  end
+  
+And as per the last example, getting yo meta is very similar:
+
+  workflow.states(:new).meta # => {:ui_widget => :radio_buttons}
+  workflow.states(:new).meta[:ui_widget] # => :radio_buttons
+  workflow.states(:new).meta.ui_widget # => :radio_buttons
+
+  workflow.states(:new).events(:submit).meta # => {:label => 'Upload...'}
+  workflow.states(:new).events(:submit).meta[:label] # => 'Upload...'
+  workflow.states(:new).events(:submit).meta.label # => 'Upload...'
+  
+Thankfully, meta responds to each so you can iterate over your values if you're so inclined.
+
+  workflow.states(:new).meta.each { |key, value| puts key, value }
+
+The order of which things are fired when an event are as follows:
+
+  * action
+  * on_transition (if action didn't halt)
+  * on_exit
+  * WORKFLOW STATE CHANGES, i.e. transition
+  * on_entry
+  
+Note that any event arguments are passed by reference, so if you modify action arguments in the action, or any of the hooks, it may affect hooked fired later.
+
+We promised that we'd show you how to integrate workflow with your existing classes and instances, let look.
+
+  class Article  
+    include Workflow
+    workflow do
+      state :new do
+        event :submit, :transitions_to => :awaiting_review
+      end
+      state :awaiting_review do
+        event :approve, :transitions_to => :approved
+      end
+      state :approved
+      # ...
+    end
+  end
+
+  article = Article.new
+  article.state          # => :new
+  article.submit         
+  article.state          # => :awaiting_review
+  article.approve
+  article.state          # => :approved
+
+And as ActiveRecord is all the rage these days, all you need is a string field on the table called "workflow_state", which is used to store the current state. Workflow handles auto-setting of a state after a find, yet it doesn't save a record after a transition (though you could make it do this in on_transition).
+
+  class Article < ActiveRecord::Base
+    include Workflow
+    workflow do
+      # ...
+    end
+  end
+
+When integrating with other classes, behind the scenes, Workflow sets up a Proxy to method missing. A probable common error would be to call an event that doesn't exist, so we catch +NoMethodError+'s and helpfully let you know what available events exist:
+
+  class Article  
+    include Workflow
+    workflow do
+      state :new do
+        event :submit, :transitions_to => :awaiting_review
+      end
+      state :awaiting_review do
+        event :approve, :transitions_to => :approved
+      end
+      state :approved
+      # ...
+    end
+  end
+  
+  article = Article.new
+  article.aaaa
+  NoMethodError: undefined method `aaaa' for #<Article:0xe4e8>, conversely, if you were looking to call an event for its workflow, you're in the :new state, and the available events are [:submit]
+  
+So just incase you screw something up (like I did while testing this library), it'll give you a useful message.
+
+You can blatter existing workflows, by simply opening them up again (similar to how Ruby works!).
+
+  Workflow.specify 'Blatter' do
+    state :opened do
+      event :close, :transitions_to => :closed
+    end
+    state :closed
+  end
+  
+  workflow = Workflow.new('Blatter')
+  workflow.close
+  workflow.state # => :closed
+  workflow.open  # => raises a (nice) NoMethodError exception!
+  
+  Workflow.specify 'Blatter' do
+    state :closed do
+      event :open, :transitions_to => :opened
+    end
+  end
+  
+  workflow.open
+  workflow.state # => :opened
+
+  Workflow.specify 'Blatter' do
+    state :open do
+      event :close, :transitions_to => :jammed # the door is now faulty :)
+    end
+    state :jammed
+  end
+  
+  workflow.close
+  workflow.state # => :jammed
+
+Why can we do this? Well, we needed it for our production app, so there.
+  
+And that's about it. A update to the implementation may allow multiple workflows per instance of a class or ActiveRecord, but we haven't figured out if that's required or appropriate.
+
+Ryan Allen, March 2008.

data/Rakefile

@@ -0,0 +1,43 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+task :default => [:test]
+
+Rake::TestTask.new do |t|
+  t.verbose = true
+  t.warning = true
+end
+
+PKG_VERSION = "0.1.0"
+PKG_FILES = FileList[
+  'LICENSE',
+  'README.rdoc',
+  'Rakefile',
+  'lib/**/*.rb',
+  'test/**/test_*.rb'
+]
+
+spec = Gem::Specification.new do |s|
+  s.name = "workflow"
+  s.version = PKG_VERSION
+  s.author = "Vladimir Dobriakov"
+  s.email = "vladimir@geekq.net"
+  s.homepage = "http://blog.geekQ.net/"
+  s.platform = Gem::Platform::RUBY
+  s.summary = "A replacement for acts_as_state_machine."
+  s.files = PKG_FILES.to_a
+  s.require_path = "lib"
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.main = "README"
+  rdoc.rdoc_files.include("README", "lib/**/*.rb")
+  rdoc.options << "-S"
+end
+
+package_task = Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar_gz = true
+end

data/lib/workflow.rb

@@ -0,0 +1,238 @@
+require 'rubygems'
+require 'active_support'
+
+module Workflow
+ 
+  class Specification
+    
+    attr_accessor :states, :initial_state, :meta, :on_transition_proc
+    
+    def initialize(meta = {}, &specification)
+      @states = Hash.new
+      @meta = meta
+      instance_eval(&specification)
+    end
+    
+    private
+  
+    def state(name, meta = {:meta => {}}, &events_and_etc)
+      # meta[:meta] to keep the API consistent..., gah
+      new_state = State.new(name, meta[:meta])
+      @initial_state = new_state if @states.empty?
+      @states[name.to_sym] = new_state
+      @scoped_state = new_state
+      instance_eval(&events_and_etc) if events_and_etc
+    end
+    
+    def event(name, args = {}, &action)
+      @scoped_state.events[name.to_sym] =
+        Event.new(name, args[:transitions_to], (args[:meta] or {}), &action)
+    end
+    
+    def on_entry(&proc)
+      @scoped_state.on_entry = proc
+    end
+    
+    def on_exit(&proc)
+      @scoped_state.on_exit = proc
+    end
+
+    def on_transition(&proc)
+      @on_transition_proc = proc
+    end
+  end
+  
+  class TransitionHalted < Exception
+
+    attr_reader :halted_because
+
+    def initialize(msg = nil)
+      @halted_because = msg
+      super msg
+    end
+
+  end
+
+  class NoTransitionAllowed < Exception; end
+
+  class State
+    
+    attr_accessor :name, :events, :meta, :on_entry, :on_exit
+    
+    def initialize(name, meta = {})
+      @name, @events, @meta = name, Hash.new, meta
+    end
+    
+    def to_s
+      "#{name}"
+    end
+
+    def to_sym
+      name.to_sym
+    end
+  end
+  
+  class Event
+    
+    attr_accessor :name, :transitions_to, :meta, :action
+    
+    def initialize(name, transitions_to, meta = {}, &action)
+      @name, @transitions_to, @meta, @action = name, transitions_to.to_sym, meta, action
+    end
+    
+  end
+  
+  module WorkflowClassMethods
+    attr_reader :workflow_spec
+
+    def workflow(&specification)
+      @workflow_spec = Specification.new(Hash.new, &specification)
+      @workflow_spec.states.values.each do |state|
+        state_name = state.name
+        module_eval do
+          define_method "#{state_name}?" do
+            state_name == current_state.name
+          end
+        end
+
+        state.events.values.each do |event|
+          event_name = event.name
+          module_eval do
+            define_method "#{event_name}!".to_sym do |*args|
+              process_event!(event_name, *args)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  module WorkflowInstanceMethods
+    def current_state 
+      loaded_state = load_workflow_state
+      res = spec.states[loaded_state.to_sym] if loaded_state
+      res || spec.initial_state
+    end
+
+    def halted?
+      @halted
+    end
+
+    def halted_because
+      @halted_because
+    end
+
+    def process_event!(name, *args)
+      event = current_state.events[name.to_sym]
+      raise NoTransitionAllowed.new(
+        "There is no event #{name.to_sym} defined for the #{current_state} state") \
+        if event.nil?
+      @halted_because = nil
+      @halted = false
+      @raise_exception_on_halt = false
+      return_value = run_action(event.action, *args) || run_action_callback(event.name, *args)
+      if @halted
+        if @raise_exception_on_halt
+          raise TransitionHalted.new(@halted_because)
+        else
+          false
+        end
+      else
+        run_on_transition(current_state, spec.states[event.transitions_to], name, *args)
+        transition(current_state, spec.states[event.transitions_to], name, *args)
+        return_value
+      end
+    end
+
+    private
+
+    def spec
+      self.class.workflow_spec
+    end
+
+    def halt(reason = nil)
+      @halted_because = reason
+      @halted = true
+      @raise_exception_on_halt = false
+    end
+
+    def halt!(reason = nil)
+      @halted_because = reason
+      @halted = true
+      @raise_exception_on_halt = true
+    end
+
+    def transition(from, to, name, *args)
+      run_on_exit(from, to, name, *args)
+      persist_workflow_state to.to_s
+      run_on_entry(to, from, name, *args)
+    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
+
+    def run_action(action, *args)
+      instance_exec(*args, &action) if action
+    end
+
+    def run_action_callback(action_name, *args)
+      self.send action_name.to_sym, *args if self.respond_to?(action_name.to_sym)
+    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
+    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
+    end
+
+    # load_workflow_state and persist_workflow_state
+    # can be overriden to handle the persistence of the workflow state.
+    #
+    # Default (non ActiveRecord) implementation stores the current state
+    # in a variable.
+    #
+    # Default ActiveRecord implementation uses a 'workflow_state' database column.
+    def load_workflow_state
+      @workflow_state if instance_variable_defined? :@workflow_state
+    end
+
+    def persist_workflow_state(new_value)
+      @workflow_state = new_value
+    end
+  end
+
+  module ActiveRecordInstanceMethods
+    def load_workflow_state
+      read_attribute(:workflow_state)
+    end
+
+    # On transition the new workflow state is immediately saved in the
+    # database.
+    def persist_workflow_state(new_value)
+      update_attribute :workflow_state, new_value
+    end
+
+    private
+
+    # Motivation: even if NULL is stored in the workflow_state database column,
+    # the current_state is correctly recognized in the Ruby code. The problem
+    # arises when you want to SELECT records filtering by the value of initial
+    # state. That's why it is important to save the string with the name of the
+    # initial state in all the new records.
+    def write_initial_state
+      write_attribute :workflow_state, current_state.to_s
+    end
+  end
+
+  def self.included(klass)
+    klass.send :include, WorkflowInstanceMethods
+    klass.extend WorkflowClassMethods
+    if klass < ActiveRecord::Base
+      klass.send :include, ActiveRecordInstanceMethods
+      klass.before_validation :write_initial_state
+    end
+  end
+end

data/test/test_workflow.rb

@@ -0,0 +1,218 @@
+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
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+name: workflow
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Vladimir Dobriakov
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-25 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: 
+email: vladimir@geekq.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- LICENSE
+- README.rdoc
+- Rakefile
+- lib/workflow.rb
+- test/test_workflow.rb
+has_rdoc: false
+homepage: http://blog.geekQ.net/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.1.2403
+signing_key: 
+specification_version: 3
+summary: A replacement for acts_as_state_machine.
+test_files: []
+