workflow 0.3.0 → 0.4.1

data/test/readme_example.rb

@@ -0,0 +1,37 @@
+require 'workflow'
+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
+end
+
+article = Article.new
+article.accepted? # => false
+article.new? # => true
+article.submit!
+article.review!
+
+puts article.current_state # => being_reviewed
+
+
+class Article
+  def reject
+    puts "send email to the author here explaining the reason for the rejection"
+  end
+end
+
+article.reject! # will cause a state transition, would persist the new
+  # state (if inherited from ActiveRecord), and invoke the callback -
+  # send email to the author.

data/test/without_active_record_test.rb

@@ -0,0 +1,54 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+require 'workflow'
+
+class WithoutWorkflowTest < Test::Unit::TestCase
+  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
+  end
+
+  def test_readme_example_article
+    article = Article.new
+    assert article.new?
+  end
+
+  test 'better error message on transitions_to typo' do
+    assert_raise Workflow::WorkflowDefinitionError do
+      Class.new do
+        include Workflow
+        workflow do
+          state :new do
+            event :event1, :transitionnn => :next # missing transitions_to target
+          end
+          state :next
+        end
+      end
+    end
+  end
+
+  test 'check transition_to alias' do
+    Class.new do
+      include Workflow
+      workflow do
+        state :new do
+          event :event1, :transition_to => :next
+        end
+        state :next
+      end
+    end
+  end
+end
+

data/workflow.rb

@@ -0,0 +1 @@
+Dir["#{File.dirname(__FILE__)}/lib/*.rb"].each { |rb| require rb }

metadata

@@ -1,7 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: workflow
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  prerelease: false
+  segments: 
+  - 0
+  - 4
+  - 1
+  version: 0.4.1
 platform: ruby
 authors: 
 - Vladimir Dobriakov
@@ -9,51 +14,64 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-10 00:00:00 +02:00
+date: 2010-06-23 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
-description: 
+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: 
+- .gitignore
 - MIT-LICENSE
-- README.rdoc
+- README.markdown
 - Rakefile
+- VERSION
 - lib/workflow.rb
+- test/couchtiny_example.rb
+- test/main_test.rb
+- test/readme_example.rb
 - test/test_helper.rb
+- test/without_active_record_test.rb
+- workflow.rb
 has_rdoc: true
 homepage: http://blog.geekQ.net/
 licenses: []
 
 post_install_message: 
-rdoc_options: []
-
+rdoc_options: 
+- --charset=UTF-8
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
-rubyforge_project: 
-rubygems_version: 1.3.3
+rubyforge_project: workflow
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: A replacement for acts_as_state_machine.
-test_files: []
-
+test_files: 
+- test/couchtiny_example.rb
+- test/main_test.rb
+- test/test_helper.rb
+- test/without_active_record_test.rb
+- test/readme_example.rb

data/README.rdoc

@@ -1,452 +0,0 @@
-= 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
-
-    gem install workflow
-
-Alternatively you can just download the lib/workflow.rb and put it in the lib folder of your 
-Rails application.
-
-
-== 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/
-
-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!!!
-
-  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:
-
-
-  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
-  end
-
-Much better, isn't it!
-
-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{}
-
-Now we can call the submit event, which transitions to the <tt>:awaiting_review</tt> state:
-
-  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:
-
-  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.