workflow 1.0.0 → 1.1.0

data/lib/workflow/adapters/active_record.rb

@@ -0,0 +1,66 @@
+module Workflow
+  module Adapter
+    module ActiveRecord
+      module InstanceMethods
+        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
+          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
+
+      # This module will automatically generate ActiveRecord scopes based on workflow states.
+      # The name of each generated scope will be something like `with_<state_name>_state`
+      #
+      # Examples:
+      #
+      # Article.with_pending_state # => ActiveRecord::Relation
+      #
+      # Example above just adds `where(:state_column_name => 'pending')` to AR query and returns
+      # ActiveRecord::Relation.
+      module Scopes
+        def self.extended(object)
+          class << object
+            alias_method :workflow_without_scopes, :workflow unless method_defined?(:workflow_without_scopes)
+            alias_method :workflow, :workflow_with_scopes
+          end
+        end
+
+        def workflow_with_scopes(&specification)
+          workflow_without_scopes(&specification)
+          states     = workflow_spec.states.values
+          eigenclass = class << self; self; end
+
+          states.each do |state|
+            # Use eigenclass instead of `define_singleton_method`
+            # to be compatible with Ruby 1.8+
+            eigenclass.send(:define_method, "with_#{state}_state") do
+              where("#{table_name}.#{self.workflow_column.to_sym} = ?", state.to_s)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/workflow/adapters/remodel.rb

@@ -0,0 +1,15 @@
+module Workflow
+  module Adapter
+    module Remodel
+      module InstanceMethods
+        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
+    end
+  end
+end

data/lib/workflow/draw.rb

@@ -0,0 +1,79 @@
+begin
+  require 'rubygems'
+
+  gem 'ruby-graphviz', '>=1.0'
+  gem 'activesupport'
+
+  require 'graphviz'
+  require 'active_support/inflector'
+rescue LoadError => e
+  $stderr.puts "Could not load the ruby-graphiz or active_support gems for rendering: #{e.message}"
+end
+
+module Workflow
+  module Draw
+
+    # 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 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
+    #
+    # You can influence the placement of nodes by specifying
+    # additional meta information in your states and transition descriptions.
+    # You can assign higher `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 => {: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.workflow_diagram(klass, options={})
+      options = {
+        :name => "#{klass.name.tableize}_workflow".gsub('/', '_'),
+        :path => '.',
+        :orientation => "landscape",
+        :ratio => "fill",
+        :format => 'png',
+        :font => 'Helvetica'
+        }.merge options
+
+        graph = ::GraphViz.new('G', :rankdir => options[:orientation] == 'landscape' ? 'LR' : 'TB', :ratio => options[:ratio])
+
+      # Add nodes
+      klass.workflow_spec.states.each do |_, state|
+        node = state.draw(graph)
+        node.fontname = options[:font]
+
+        state.events.each do |_, event|
+          edge = event.draw(graph, state)
+          edge.fontname = options[:font]
+        end
+      end
+
+      # Generate the graph
+      filename = File.join(options[:path], "#{options[:name]}.#{options[:format]}")
+
+      graph.output options[:format] => "'#{filename}'"
+
+      puts "
+      Please run the following to open the generated file:
+
+      open '#{filename}'
+      "
+      graph
+    end
+  end
+end

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

@@ -1,3 +1,3 @@
 module Workflow
-  VERSION = "1.0.0"
+  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

@@ -58,4 +58,25 @@ class AdvanceExamplesTest < ActiveRecordTestCase
     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/attr_protected_test.rb

@@ -7,6 +7,7 @@ require 'sqlite3'
 require 'workflow'
 require 'mocha/setup'
 require 'stringio'
+require 'protected_attributes' if ActiveRecord::VERSION::MAJOR >= 4
 
 ActiveRecord::Migration.verbose = false
 
@@ -60,7 +61,9 @@ class AttrProtectedTest < ActiveRecordTestCase
   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)

data/test/inheritance_test.rb

@@ -0,0 +1,60 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+require 'workflow'
+class InheritanceTest < ActiveRecordTestCase
+
+  test '#69 inheritance' do
+    class Animal
+      include Workflow
+
+      workflow do
+
+        state :conceived do
+          event :birth, :transition_to => :born
+        end
+
+        state :born do
+
+        end
+      end
+    end
+
+    class Cat < Animal
+      include Workflow
+      workflow do
+
+        state :upset do
+          event :scratch, :transition_to => :hiding
+        end
+
+        state :hiding do
+
+        end
+      end
+    end
+
+    assert_equal [:born, :conceived] , sort_sym_array(Animal.workflow_spec.states.keys)
+    assert_equal [:hiding, :upset], sort_sym_array(Cat.workflow_spec.states.keys), "Workflow definitions are not inherited"
+
+    animal = Animal.new
+    cat = Cat.new
+
+    animal.birth!
+
+    assert_raise NoMethodError, 'Methods defined by the old workflow spec should have be gone away' do
+      cat.birth!
+    end
+
+    assert_equal [:birth!, :halt!, :process_event!], bang_methods(animal)
+    assert_equal [:halt!, :process_event!, :scratch!], bang_methods(cat)
+  end
+
+  def sort_sym_array(a)
+    a.sort { |a, b| a.to_s <=> b.to_s } # workaround for Ruby 1.8.7
+  end
+
+  def bang_methods(obj)
+    non_trivial_methods = obj.public_methods-Object.public_methods
+    methods_with_bang = non_trivial_methods.select {|m| m =~ /!$/}
+    sort_sym_array(methods_with_bang).map {|m| m.to_sym}
+  end
+end