workflow-rails4 1.1.0

data/lib/workflow/errors.rb

@@ -0,0 +1,18 @@
+module Workflow
+  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
+end

data/lib/workflow/event.rb

@@ -0,0 +1,18 @@
+module Workflow
+  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
+
+    def draw(graph, from_state)
+      graph.add_edges(from_state.name.to_s, transitions_to.to_s, meta.merge(:label => to_s))
+    end
+
+    def to_s
+      @name.to_s
+    end
+  end
+end

data/lib/workflow/specification.rb

@@ -0,0 +1,64 @@
+require 'workflow/state'
+require 'workflow/event'
+require 'workflow/errors'
+
+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
+end

data/lib/workflow/state.rb

@@ -0,0 +1,44 @@
+module Workflow
+  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
+
+    def draw(graph)
+      defaults = {
+        :label => to_s,
+        :width => '1',
+        :height => '1',
+        :shape => 'ellipse'
+      }
+
+      node = graph.add_nodes(to_s, defaults.merge(meta))
+
+      # Add open arrow for initial state
+      # graph.add_edge(graph.add_node('starting_state', :shape => 'point'), node) if initial?
+
+      node
+    end
+
+
+    if RUBY_VERSION >= '1.9'
+      include Comparable
+      def <=>(other_state)
+        states = spec.states.keys
+        raise ArgumentError, "state `#{other_state}' does not exist" unless states.include?(other_state.to_sym)
+        states.index(self.to_sym) <=> states.index(other_state.to_sym)
+      end
+    end
+
+    def to_s
+      "#{name}"
+    end
+
+    def to_sym
+      name.to_sym
+    end
+  end
+end

data/lib/workflow/version.rb

@@ -0,0 +1,3 @@
+module Workflow
+  VERSION = "1.1.0"
+end

data/test/active_record_scopes_test.rb

@@ -0,0 +1,49 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+$VERBOSE = false
+require 'active_record'
+require 'sqlite3'
+require 'workflow'
+
+ActiveRecord::Migration.verbose = false
+
+class Article < ActiveRecord::Base
+  include Workflow
+
+  workflow do
+    state :new
+    state :accepted
+  end
+end
+
+class ActiveRecordScopesTest < ActiveRecordTestCase
+
+  def setup
+    super
+
+    ActiveRecord::Schema.define do
+      create_table :articles do |t|
+        t.string :title
+        t.string :body
+        t.string :blame_reason
+        t.string :reject_reason
+        t.string :workflow_state
+      end
+    end
+  end
+
+  def assert_state(title, expected_state, klass = Order)
+    o = klass.find_by_title(title)
+    assert_equal expected_state, o.read_attribute(klass.workflow_column)
+    o
+  end
+
+  test 'have "with_new_state" scope' do
+    assert_respond_to Article, :with_new_state
+  end
+
+  test 'have "with_accepted_state" scope' do
+    assert_respond_to Article, :with_accepted_state
+  end
+end
+

data/test/advanced_examples_test.rb

@@ -0,0 +1,82 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+require 'workflow'
+class AdvanceExamplesTest < ActiveRecordTestCase
+
+  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 do
+      end
+      state :rejected do
+      end
+    end
+  end
+
+  test '#63 undoing event - automatically add revert events for every defined event' do
+    # also see https://github.com/geekq/workflow/issues/63
+    spec = Article.workflow_spec
+    spec.state_names.each do |state_name|
+      state = spec.states[state_name]
+
+        (state.events.values.reject {|e| e.name.to_s =~ /^revert_/ }).each do |event|
+          event_name = event.name
+          revert_event_name = "revert_" + event_name.to_s
+
+          # Add revert events
+          spec.states[event.transitions_to.to_sym].events[revert_event_name.to_sym] =
+            Workflow::Event.new(revert_event_name, state, {})
+
+          # Add methods for revert events
+          Article.module_eval do
+            define_method "#{revert_event_name}!".to_sym do |*args|
+              process_event!(revert_event_name, *args)
+            end
+            define_method "can_#{revert_event_name}?" do
+              return self.current_state.events.include?(revert_event_name)
+            end
+          end
+
+        end
+    end
+
+    a = Article.new
+    assert(a.new?, "should start with the 'new' state")
+    a.submit!
+    assert(a.awaiting_review?, "should now be in 'awaiting_review' state")
+    assert_equal(['revert_submit', 'review'], a.current_state.events.keys.map(&:to_s).sort)
+    a.revert_submit! # this method is added by our meta programming magic above
+    assert(a.new?, "should now be back in the 'new' state")
+  end
+
+  test '#92 Load workflow specification' do
+    c = Class.new
+    c.class_eval do
+      include Workflow
+    end
+
+    # build a Specification (you can load it from yaml file too)
+    myspec = Workflow::Specification.new do
+      state :one do
+        event :dynamic_transition, :transitions_to => :one_a
+      end
+      state :one_a
+    end
+
+    c.send :assign_workflow, myspec
+
+    a = c.new
+    a.dynamic_transition!(1)
+    assert a.one_a?, 'Expected successful transition to a new state'
+  end
+
+end

data/test/advanced_hooks_and_validation_test.rb

@@ -0,0 +1,119 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+$VERBOSE = false
+require 'active_record'
+require 'sqlite3'
+require 'workflow'
+
+ActiveRecord::Migration.verbose = false
+
+# Transition based validation
+# ---------------------------
+# If you are using ActiveRecord you might want to define different validations
+# for different transitions. There is a `validates_presence_of` hook that let's
+# you specify the attributes that need to be present for an successful transition.
+# If the object is not valid at the end of the transition event the transition
+# is halted and a TransitionHalted exception is thrown.
+#
+# Here is a sample that illustrates how to use the presence validation:
+# (use case suggested by http://github.com/southdesign)
+class Article < ActiveRecord::Base
+  include Workflow
+  workflow do
+    state :new do
+      event :accept, :transitions_to => :accepted, :meta => {:validates_presence_of => [:title, :body]}
+      event :reject, :transitions_to => :rejected
+    end
+    state :accepted do
+      event :blame, :transitions_to => :blamed, :meta => {:validates_presence_of => [:title, :body, :blame_reason]}
+      event :delete, :transitions_to => :deleted
+    end
+    state :rejected do
+      event :delete, :transitions_to => :deleted
+    end
+    state :blamed do
+      event :delete, :transitions_to => :deleted
+    end
+    state :deleted do
+      event :accept, :transitions_to => :accepted
+    end
+
+    on_transition do |from, to, triggering_event, *event_args|
+      if self.class.superclass.to_s.split("::").first == "ActiveRecord"
+        singleton = class << self; self end
+        validations = Proc.new {}
+
+        meta = Article.workflow_spec.states[from].events[triggering_event].meta
+        fields_to_validate = meta[:validates_presence_of]
+        if fields_to_validate
+          validations = Proc.new {
+            errors.add_on_blank(fields_to_validate) if fields_to_validate
+          }
+        end
+
+        singleton.send :define_method, :validate_for_transition, &validations
+        validate_for_transition
+        halt! "Event[#{triggering_event}]'s transitions_to[#{to}] is not valid." unless self.errors.empty?
+      end
+    end
+  end
+end
+
+class AdvancedHooksAndValidationTest < ActiveRecordTestCase
+
+  def setup
+    super
+
+    ActiveRecord::Schema.define do
+      create_table :articles do |t|
+        t.string :title
+        t.string :body
+        t.string :blame_reason
+        t.string :reject_reason
+        t.string :workflow_state
+      end
+    end
+
+    exec "INSERT INTO articles(title, body, blame_reason, reject_reason, workflow_state) VALUES('new1', NULL, NULL, NULL, 'new')"
+    exec "INSERT INTO articles(title, body, blame_reason, reject_reason, workflow_state) VALUES('new2', 'some content', NULL, NULL, 'new')"
+    exec "INSERT INTO articles(title, body, blame_reason, reject_reason, workflow_state) VALUES('accepted1', 'some content', NULL, NULL, 'accepted')"
+
+  end
+
+  def assert_state(title, expected_state, klass = Order)
+    o = klass.find_by_title(title)
+    assert_equal expected_state, o.read_attribute(klass.workflow_column)
+    o
+  end
+
+  test 'deny transition from new to accepted because of the missing presence of the body' do
+    a = Article.find_by_title('new1');
+    assert_raise Workflow::TransitionHalted do
+      a.accept!
+    end
+    assert_state 'new1', 'new', Article
+  end
+
+  test 'allow transition from new to accepted because body is present this time' do
+    a = Article.find_by_title('new2');
+    assert a.accept!
+    assert_state 'new2', 'accepted', Article
+  end
+
+  test 'allow transition from accepted to blamed because of a blame_reason' do
+    a = Article.find_by_title('accepted1');
+    a.blame_reason = "Provocant thesis"
+    assert a.blame!
+    assert_state 'accepted1', 'blamed', Article
+  end
+
+  test 'deny transition from accepted to blamed because of no blame_reason' do
+    a = Article.find_by_title('accepted1');
+    assert_raise Workflow::TransitionHalted do
+      assert a.blame!
+    end
+    assert_state 'accepted1', 'accepted', Article
+  end
+
+end
+

data/test/attr_protected_test.rb

@@ -0,0 +1,107 @@
+require 'test_helper'
+
+$VERBOSE = false
+require 'active_record'
+require 'logger'
+require 'sqlite3'
+require 'workflow'
+require 'mocha/setup'
+require 'stringio'
+require 'protected_attributes' if ActiveRecord::VERSION::MAJOR >= 4
+
+ActiveRecord::Migration.verbose = false
+
+class AttrProtectedTestOrder < 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
+
+  attr_accessible :title # protecting all the other attributes
+
+end
+
+AttrProtectedTestOrder.logger = Logger.new(STDOUT) # active_record 2.3 expects a logger instance
+AttrProtectedTestOrder.logger.level = Logger::WARN # switch to Logger::DEBUG to see the SQL statements
+
+class AttrProtectedTest < ActiveRecordTestCase
+
+  def setup
+    super
+
+    ActiveRecord::Schema.define do
+      create_table :attr_protected_test_orders do |t|
+        t.string :title, :null => false
+        t.string :workflow_state
+      end
+    end
+
+    exec "INSERT INTO attr_protected_test_orders(title, workflow_state) VALUES('order1', 'submitted')"
+    exec "INSERT INTO attr_protected_test_orders(title, workflow_state) VALUES('order2', 'accepted')"
+    exec "INSERT INTO attr_protected_test_orders(title, workflow_state) VALUES('order3', 'accepted')"
+    exec "INSERT INTO attr_protected_test_orders(title, workflow_state) VALUES('order4', 'accepted')"
+    exec "INSERT INTO attr_protected_test_orders(title, workflow_state) VALUES('order5', 'accepted')"
+    exec "INSERT INTO attr_protected_test_orders(title, workflow_state) VALUES('protected order', 'submitted')"
+  end
+
+  def assert_state(title, expected_state, klass = AttrProtectedTestOrder)
+    o = klass.find_by_title(title)
+    assert_equal expected_state, o.read_attribute(klass.workflow_column)
+    o
+  end
+
+  test 'cannot mass-assign workflow_state if attr_protected' do
+     o = AttrProtectedTestOrder.find_by_title('order1')
+     assert_equal 'submitted', o.read_attribute(:workflow_state)
+     AttrProtectedTestOrder.logger.level = Logger::ERROR # ignore warnings
+     o.update_attributes :workflow_state => 'some_bad_value'
+     AttrProtectedTestOrder.logger.level = Logger::WARN
+     assert_equal 'submitted', o.read_attribute(:workflow_state)
+     o.update_attribute :workflow_state, 'some_overridden_value'
+     assert_equal 'some_overridden_value', o.read_attribute(:workflow_state)
+   end
+
+  test 'immediately save the new workflow_state on state machine transition' do
+    o = assert_state 'order2', 'accepted'
+    assert o.ship!
+    assert_state 'order2', 'shipped'
+  end
+
+  test 'persist workflow_state in the db and reload' do
+    o = assert_state 'order3', 'accepted'
+    assert_equal :accepted, o.current_state.name
+    o.ship! # should save in the database, no `o.save!` needed
+
+    assert_state 'order3', 'shipped'
+
+    o.reload
+    assert_equal 'shipped', o.read_attribute(:workflow_state)
+  end
+
+  test 'default workflow column should be workflow_state' do
+    o = assert_state 'order4', 'accepted'
+    assert_equal :workflow_state, o.class.workflow_column
+  end
+
+  test 'access workflow specification' do
+    assert_equal 3, AttrProtectedTestOrder.workflow_spec.states.length
+    assert_equal ['submitted', 'accepted', 'shipped'].sort,
+      AttrProtectedTestOrder.workflow_spec.state_names.map{|n| n.to_s}.sort
+  end
+
+  test 'current state object' do
+    o = assert_state 'order5', 'accepted'
+    assert_equal 'accepted', o.current_state.to_s
+    assert_equal 1, o.current_state.events.length
+  end
+
+end
+