workflow 1.0.0 → 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6c18ece78f869cf0939fd801a99b63a93b99eafd
+  data.tar.gz: 949a3b5bff0e79ced88e7ba5a3050820f58efd40
+SHA512:
+  metadata.gz: 801d65a4147f19643d429d38e794f9529ff760147cf63185ab19762ddf618deb8f8ff19deb0ec590b8a3cd7166c99bfa129fdf716dc8b261c7cb98478685a494
+  data.tar.gz: 5cc6722b3029ab9a96a2247215706315561735f6f7fa5950727f22b969040c53bba907532e3fada31d485c9c9ac6a39a66b130ed956f61b8ef68a2f566018332

data/.travis.yml

@@ -2,8 +2,9 @@ before_install:
   - sudo apt-get install -qq graphviz
 
 rvm:
-  - 1.9.3
   - 2.0.0
+gemfile:
+  - gemfiles/Gemfile.rails-edge
 
 matrix:
   include:
@@ -12,3 +13,9 @@ matrix:
       gemfile: gemfiles/Gemfile.rails-2.3.x
       # running a smaller test set for old Rails and Ruby
       script: rake test_without_new_versions
+
+    - rvm: 1.9.3
+      gemfile: gemfiles/Gemfile.rails-3.x
+
+    - rvm: 2.0.0
+      gemfile: gemfiles/Gemfile.rails-3.x

data/Gemfile

@@ -1,4 +1,3 @@
 source "http://rubygems.org"
 
 gemspec
-

data/README.markdown

@@ -1,5 +1,6 @@
 [![Build Status](https://travis-ci.org/geekq/workflow.png?branch=master)](https://travis-ci.org/geekq/workflow)
 
+
 What is workflow?
 -----------------
 
@@ -63,10 +64,10 @@ Let's create an article instance and check in which state it is:
 You can also access the whole `current_state` object including the list
 of possible events and other meta information:
 
-    article.current_state 
+    article.current_state
     => #<Workflow::State:0x7f1e3d6731f0 @events={
-      :submit=>#<Workflow::Event:0x7f1e3d6730d8 @action=nil, 
-        @transitions_to=:awaiting_review, @name=:submit, @meta={}>}, 
+      :submit=>#<Workflow::Event:0x7f1e3d6730d8 @action=nil,
+        @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
@@ -86,7 +87,7 @@ Now we can call the submit event, which transitions to the
 
     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.
@@ -101,18 +102,20 @@ Installation
 
     gem install workflow
 
-Alternatively you can just download the lib/workflow.rb and put it in
-the lib folder of your Rails or Ruby application.
+**Important**: If you're interested in graphing your workflow state machine, you will also need to
+install the `active_support` and `ruby-graphviz` gems.
 
+Versions up to and including 1.0.0 are also available as a single file download -
+[lib/workflow.rb file](https://github.com/geekq/workflow/blob/v1.0.0/lib/workflow.rb).
 
 Ruby 1.9
 --------
 
-Workflow gem does not work with some (but very widespread) Ruby 1.9
-builds due to a known bug in Ruby 1.9. Either 
+Workflow gem does not work with some Ruby 1.9
+builds due to a known bug in Ruby 1.9. Either
 
 * use newer ruby build, 1.9.2-p136 and -p180 tested to work
-* or compile your Ruby 1.9 from source 
+* or compile your Ruby 1.9 from source
 * or [comment out some lines in workflow](http://github.com/geekq/workflow/issues#issue/6)
 (reduces functionality).
 
@@ -148,6 +151,13 @@ be:
 (if integrated with ActiveRecord) and invoke this user defined reject
 method.
 
+Note: on successful transition from one state to another the workflow
+gem immediately persists the new workflow state with `update_column()`,
+bypassing any ActiveRecord callbacks including `updated_at` update.
+This way it is possible to deal with the validation and to save the
+pending changes to a record at some later point instead of the moment
+when transition occurs.
+
 You can also define event handler accepting/requiring additional
 arguments:
 
@@ -175,7 +185,7 @@ 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 decided to invoke an optional user defined callback method with the same
 name as the event (convention over configuration) as explained before.
-      
+
 
 Integration with ActiveRecord
 -----------------------------
@@ -193,7 +203,7 @@ and include the workflow mixin in your model class as usual:
 
 On a database record loading all the state check methods e.g.
 `article.state`, `article.awaiting_review?` are immediately available.
-For new records or if the workflow_state field is not set the state
+For new records or if the `workflow_state` field is not set the state
 defaults to the first state declared in the workflow specification. In
 our example it is `:new`, so `Article.new.new?` returns true and
 `Article.new.approved?` returns false.
@@ -204,6 +214,25 @@ new state is immediately saved in the database.
 You can change this behaviour by overriding `persist_workflow_state`
 method.
 
+### Scopes
+
+Workflow library also adds automatically generated scopes with names based on
+states names:
+
+    class Order < ActiveRecord::Base
+      include Workflow
+      workflow do
+        state :approved
+        state :pending
+      end
+    end
+
+    # returns all orders with `approved` state
+    Order.with_approved_state
+
+    # returns all orders with `pending` state
+    Order.with_pending_state
+
 
 ### Custom workflow database column
 
@@ -212,7 +241,7 @@ custom persistence column easily, e.g. for a legacy database schema:
 
     class LegacyOrder < ActiveRecord::Base
       include Workflow
-      
+
       workflow_column :foo_bar # use this legacy database column for
                                # persistence
     end
@@ -234,8 +263,8 @@ need to override `load_workflow_state` and
 `persist_workflow_state(new_value)` methods. Next section contains an example for
 using CouchDB, a document oriented database.
 
-[Tim Lossen](http://tim.lossen.de/) implemented support 
-for [remodel](http://github.com/tlossen/remodel) / [redis](http://github.com/antirez/redis) 
+[Tim Lossen](http://tim.lossen.de/) implemented support
+for [remodel](http://github.com/tlossen/remodel) / [redis](http://github.com/antirez/redis)
 key-value store.
 
 Integration with CouchDB
@@ -268,7 +297,7 @@ couchrest library.
       end
     end
 
-Please also have a look at 
+Please also have a look at
 [the full source code](http://github.com/geekq/workflow/blob/master/test/couchtiny_example.rb).
 
 Integration with Mongoid
@@ -310,7 +339,7 @@ state and every event:
 
 The workflow library itself uses this feature to tweak the graphical
 representation of the workflow. See below.
- 
+
 
 Advanced transition hooks
 -------------------------
@@ -346,7 +375,7 @@ example][advanced_hooks_and_validation_test].
 
 ### on_error
 
-If you want to do custom exception handling internal to workflow, you can define an `on_error` hook in your workflow.  
+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
@@ -356,12 +385,12 @@ For example:
       state :second
 
       on_error do |error, from, to, event, *args|
-        Log.info "Exception(#error.class) on #{from} -> #{to}" 
+        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 
+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
@@ -400,7 +429,7 @@ Multiple Workflows
 ------------------
 
 I am frequently asked if it's possible to represent multiple "workflows"
-in an ActiveRecord class. 
+in an ActiveRecord class.
 
 The solution depends on your business logic and how you want to
 structure your implementation.
@@ -462,8 +491,17 @@ example][multiple_workflow_test]!
 Documenting with diagrams
 -------------------------
 
-You can generate a graphical representation of your workflow for
-documentation purposes. S. Workflow::create_workflow_diagram.
+You can generate a graphical representation of the workflow for
+a particular class for documentation purposes.
+Use `Workflow::create_workflow_diagram(class)` in your rake task like:
+
+    namespace :doc do
+      desc "Generate a workflow graph for a model passed e.g. as 'MODEL=Order'."
+      task :workflow => :environment do
+        require 'workflow/draw'
+        Workflow::Draw::workflow_diagram(ENV['MODEL'].constantize)
+      end
+    end
 
 
 Earlier versions
@@ -472,7 +510,7 @@ Earlier versions
 The `workflow` library was originally written by Ryan Allen.
 
 The version 0.3 was almost completely (including ActiveRecord
-integration, API for accessing workflow specification, 
+integration, API for accessing workflow specification,
 method_missing free implementation) rewritten by Vladimir Dobriakov
 keeping the original workflow DSL spirit.
 
@@ -503,6 +541,14 @@ when using both a block and a callback method for an event, the block executes p
 Changelog
 ---------
 
+### New in the version 1.1.0
+
+* Tested with ActiveRecord 4.0 (Rails 4.0)
+* Tested with Ruby 2.0
+* automatically generated scopes with names based on state names
+* clean workflow definition override for class inheritance - undefining
+  the old convinience methods, s. <http://git.io/FZO02A>
+
 ### New in the version 1.0.0
 
 * **Support to private/protected callback methods.**
@@ -568,7 +614,7 @@ 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 
+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:
@@ -579,7 +625,7 @@ block:
       end
     end
 
-you can hook in by defining method 
+you can hook in by defining method
 
     def on_pending_exit(new_state, event, *args)
       # your implementation here
@@ -590,7 +636,7 @@ like `def on_pending_exit(*args)` if your are not interested in
 arguments.  Please note: `def on_pending_exit()` with an empty list
 would not work.
 
-If both a function with a name according to naming convention and the 
+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.
 
 

data/Rakefile

@@ -1,17 +1,11 @@
 require 'rubygems'
-require "bundler/gem_tasks"
 require 'rake/testtask'
 require 'rdoc/task'
 
-task :default => [:test]
+require 'bundler'
+Bundler.setup
 
-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
+task :default => [:test]
 
 require 'rake'
 Rake::TestTask.new do |t|

data/gemfiles/Gemfile.rails-2.3.x

@@ -7,4 +7,5 @@ group :development do
   gem "sqlite3"
   gem "mocha"
   gem "rake"
+  gem "ruby-graphviz", ">= 1.0"
 end

data/gemfiles/Gemfile.rails-3.x

@@ -0,0 +1,11 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "rdoc", ">= 3.12"
+  gem "bundler", ">= 1.0.0"
+  gem "activerecord", "~>3.2"
+  gem "sqlite3"
+  gem "mocha"
+  gem "rake"
+  gem "ruby-graphviz", ">= 1.0"
+end

data/gemfiles/Gemfile.rails-edge

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "rdoc", ">= 3.12"
+  gem "bundler", ">= 1.0.0"
+  gem "activerecord"
+  gem "sqlite3"
+  gem "mocha"
+  gem "rake"
+  gem "ruby-graphviz", ">= 1.0"
+  gem 'protected_attributes'
+end

data/lib/workflow.rb

@@ -1,130 +1,12 @@
 require 'rubygems'
 
+require 'workflow/specification'
+require 'workflow/adapters/active_record'
+require 'workflow/adapters/remodel'
+
 # See also README.markdown for documentation
 module Workflow
-
-  class Specification
-
-    attr_accessor :states, :initial_state, :meta,
-      :on_transition_proc, :before_transition_proc, :after_transition_proc, :on_error_proc
-
-    def initialize(meta = {}, &specification)
-      @states = Hash.new
-      @meta = meta
-      instance_eval(&specification)
-    end
-
-    def state_names
-      states.keys
-    end
-
-    private
-
-    def state(name, meta = {:meta => {}}, &events_and_etc)
-      # meta[:meta] to keep the API consistent..., gah
-      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
-      instance_eval(&events_and_etc) if events_and_etc
-    end
-
-    def event(name, args = {}, &action)
-      target = args[:transitions_to] || args[:transition_to]
-      raise WorkflowDefinitionError.new(
-        "missing ':transitions_to' in workflow event definition for '#{name}'") \
-        if target.nil?
-      @scoped_state.events[name.to_sym] =
-        Workflow::Event.new(name, target, (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 after_transition(&proc)
-      @after_transition_proc = proc
-    end
-
-    def before_transition(&proc)
-      @before_transition_proc = proc
-    end
-
-    def on_transition(&proc)
-      @on_transition_proc = proc
-    end
-
-    def on_error(&proc)
-      @on_error_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 WorkflowError < Exception; end
-
-  class WorkflowDefinitionError < Exception; end
-
-  class State
-
-    attr_accessor :name, :events, :meta, :on_entry, :on_exit
-    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
-      "#{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
+  module ClassMethods
     attr_reader :workflow_spec
 
     def workflow_column(column_name=nil)
@@ -138,7 +20,35 @@ module Workflow
     end
 
     def workflow(&specification)
-      @workflow_spec = Specification.new(Hash.new, &specification)
+      assign_workflow Specification.new(Hash.new, &specification)
+    end
+
+    private
+
+    # Creates the convinience methods like `my_transition!`
+    def assign_workflow(specification_object)
+
+      # Merging two workflow specifications can **not** be done automically, so
+      # just make the latest specification win. Same for inheritance -
+      # definition in the subclass wins.
+      if respond_to? :inherited_workflow_spec # undefine methods defined by the old workflow_spec
+        inherited_workflow_spec.states.values.each do |state|
+          state_name = state.name
+          module_eval do
+            undef_method "#{state_name}?"
+          end
+
+          state.events.values.each do |event|
+            event_name = event.name
+            module_eval do
+              undef_method "#{event_name}!".to_sym
+              undef_method "can_#{event_name}?"
+            end
+          end
+        end
+      end
+
+      @workflow_spec = specification_object
       @workflow_spec.states.values.each do |state|
         state_name = state.name
         module_eval do
@@ -163,7 +73,7 @@ module Workflow
     end
   end
 
-  module WorkflowInstanceMethods
+  module InstanceMethods
 
     def current_state
       loaded_state = load_workflow_state
@@ -335,118 +245,33 @@ module Workflow
     end
   end
 
-  module ActiveRecordInstanceMethods
-    def load_workflow_state
-      read_attribute(self.class.workflow_column)
-    end
-
-    # On transition the new workflow state is immediately saved in the
-    # database.
-    def persist_workflow_state(new_value)
-      if self.respond_to? :update_column
-        # Rails 3.1 or newer
-        update_column self.class.workflow_column, new_value
-      else
-        # older Rails; beware of side effect: other (pending) attribute changes will be persisted too
-        update_attribute self.class.workflow_column, new_value
+  def self.included(klass)
+    klass.send :include, InstanceMethods
+
+    # backup the parent workflow spec, making accessible through #inherited_workflow_spec
+    if klass.superclass.respond_to?(:workflow_spec, true)
+      klass.module_eval do
+        # see http://stackoverflow.com/a/2495650/111995 for implementation explanation
+        pro = Proc.new { klass.superclass.workflow_spec }
+        singleton_class = class << self; self; end
+        singleton_class.send(:define_method, :inherited_workflow_spec) do
+          pro.call
+        end
       end
     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 self.class.workflow_column, current_state.to_s
-    end
-  end
-
-  module RemodelInstanceMethods
-    def load_workflow_state
-      send(self.class.workflow_column)
-    end
-
-    def persist_workflow_state(new_value)
-      update(self.class.workflow_column => new_value)
-    end
-  end
+    klass.extend ClassMethods
 
-  def self.included(klass)
-    klass.send :include, WorkflowInstanceMethods
-    klass.extend WorkflowClassMethods
     if Object.const_defined?(:ActiveRecord)
       if klass < ActiveRecord::Base
-        klass.send :include, ActiveRecordInstanceMethods
+        klass.send :include, Adapter::ActiveRecord::InstanceMethods
+        klass.send :extend, Adapter::ActiveRecord::Scopes
         klass.before_validation :write_initial_state
       end
     elsif Object.const_defined?(:Remodel)
-      if klass < Remodel::Entity
-        klass.send :include, RemodelInstanceMethods
-      end
-    end
-  end
-
-  # Generates a `dot` graph of the workflow.
-  # Prerequisite: the `dot` binary. (Download from http://www.graphviz.org/)
-  # You can use this method in your own Rakefile like this:
-  #
-  #     namespace :doc do
-  #       desc "Generate a graph of the workflow."
-  #       task :workflow => :environment do # needs access to the Rails environment
-  #         Workflow::create_workflow_diagram(Order)
-  #       end
-  #     end
-  #
-  # You can influence the placement of nodes by specifying
-  # additional meta information in your states and transition descriptions.
-  # You can assign higher `doc_weight` value to the typical transitions
-  # in your workflow. All other states and transitions will be arranged
-  # around that main line. See also `weight` in the graphviz documentation.
-  # Example:
-  #
-  #     state :new do
-  #       event :approve, :transitions_to => :approved, :meta => {:doc_weight => 8}
-  #     end
-  #
-  #
-  # @param klass A class with the Workflow mixin, for which you wish the graphical workflow representation
-  # @param [String] target_dir Directory, where to save the dot and the pdf files
-  # @param [String] graph_options You can change graph orientation, size etc. See graphviz documentation
-  def self.create_workflow_diagram(klass, target_dir='.', graph_options='rankdir="LR", size="7,11.6", ratio="fill"')
-    workflow_name = "#{klass.name.tableize}_workflow".gsub('/', '_')
-    fname = File.join(target_dir, "generated_#{workflow_name}")
-    File.open("#{fname}.dot", 'w') do |file|
-      file.puts %Q|
-digraph #{workflow_name} {
-  graph [#{graph_options}];
-  node [shape=box];
-  edge [len=1];
-      |
-
-      klass.workflow_spec.states.each do |state_name, state|
-        file.puts %Q{  #{state.name} [label="#{state.name}"];}
-        state.events.each do |event_name, event|
-          meta_info = event.meta
-          if meta_info[:doc_weight]
-            weight_prop = ", weight=#{meta_info[:doc_weight]}"
-          else
-            weight_prop = ''
-          end
-          file.puts %Q{  #{state.name} -> #{event.transitions_to} [label="#{event_name.to_s.humanize}" #{weight_prop}];}
-        end
+      if klass < Adapter::Remodel::Entity
+        klass.send :include, Remodel::InstanceMethods
       end
-      file.puts "}"
-      file.puts
     end
-    `dot -Tpdf -o'#{fname}.pdf' '#{fname}.dot'`
-    puts "
-Please run the following to open the generated file:
-
-open '#{fname}.pdf'
-
-"
   end
 end