workflow-rails4 1.1.0

data/Rakefile

@@ -0,0 +1,31 @@
+require 'rubygems'
+require 'rake/testtask'
+require 'rdoc/task'
+
+require 'bundler'
+Bundler.setup
+Bundler::GemHelper.install_tasks
+
+task :default => [:test]
+
+require 'rake'
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.verbose = true
+  t.warning = true
+  t.test_files = FileList['test/*_test.rb'] + FileList['test/new_versions/*_test.rb']
+end
+
+Rake::TestTask.new do |t|
+  t.name = 'test_without_new_versions'
+  t.libs << 'test'
+  t.verbose = true
+  t.warning = true
+  t.pattern = 'test/*_test.rb'
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_files.include("lib/**/*.rb")
+  rdoc.options << "-S"
+end
+

data/gemfiles/Gemfile.rails-2.3.x

@@ -0,0 +1,11 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "rdoc", ">= 3.12"
+  gem "bundler", ">= 1.0.0"
+  gem "activerecord", "~>2.3.15"
+  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

@@ -0,0 +1,277 @@
+require 'rubygems'
+
+require 'workflow/specification'
+require 'workflow/adapters/active_record'
+require 'workflow/adapters/remodel'
+
+# See also README.markdown for documentation
+module Workflow
+  module ClassMethods
+    attr_reader :workflow_spec
+
+    def workflow_column(column_name=nil)
+      if column_name
+        @workflow_state_column_name = column_name.to_sym
+      end
+      if !@workflow_state_column_name && superclass.respond_to?(:workflow_column)
+        @workflow_state_column_name = superclass.workflow_column
+      end
+      @workflow_state_column_name ||= :workflow_state
+    end
+
+    def workflow(&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
+          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
+
+            define_method "can_#{event_name}?" do
+              return self.current_state.events.include?(event_name)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  module InstanceMethods
+
+    def current_state
+      loaded_state = load_workflow_state
+      res = spec.states[loaded_state.to_sym] if loaded_state
+      res || spec.initial_state
+    end
+
+    # See the 'Guards' section in the README
+    # @return true if the last transition was halted by one of the transition callbacks.
+    def halted?
+      @halted
+    end
+
+    # @return the reason of the last transition abort as set by the previous
+    # call of `halt` or `halt!` method.
+    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
+
+      check_transition(event)
+
+      from = current_state
+      to = spec.states[event.transitions_to]
+
+      run_before_transition(from, to, name, *args)
+      return false if @halted
+
+      begin
+        return_value = run_action(event.action, *args) || run_action_callback(event.name, *args)
+      rescue Exception => e
+        run_on_error(e, from, to, name, *args)
+      end
+
+      return false if @halted
+
+      run_on_transition(from, to, name, *args)
+
+      run_on_exit(from, to, name, *args)
+
+      transition_value = persist_workflow_state to.to_s
+
+      run_on_entry(to, from, name, *args)
+
+      run_after_transition(from, to, name, *args)
+
+      return_value.nil? ? transition_value : return_value
+    end
+
+    def halt(reason = nil)
+      @halted_because = reason
+      @halted = true
+    end
+
+    def halt!(reason = nil)
+      @halted_because = reason
+      @halted = true
+      raise TransitionHalted.new(reason)
+    end
+
+    def spec
+      # check the singleton class first
+      class << self
+        return workflow_spec if workflow_spec
+      end
+
+      c = self.class
+      # using a simple loop instead of class_inheritable_accessor to avoid
+      # dependency on Rails' ActiveSupport
+      until c.workflow_spec || !(c.include? Workflow)
+        c = c.superclass
+      end
+      c.workflow_spec
+    end
+
+    private
+
+    def check_transition(event)
+      # Create a meaningful error message instead of
+      # "undefined method `on_entry' for nil:NilClass"
+      # Reported by Kyle Burton
+      if !spec.states[event.transitions_to]
+        raise WorkflowError.new("Event[#{event.name}]'s " +
+            "transitions_to[#{event.transitions_to}] is not a declared state.")
+      end
+    end
+
+    def run_before_transition(from, to, event, *args)
+      instance_exec(from.name, to.name, event, *args, &spec.before_transition_proc) if
+        spec.before_transition_proc
+    end
+
+    def run_on_error(error, from, to, event, *args)
+      if spec.on_error_proc
+        instance_exec(error, from.name, to.name, event, *args, &spec.on_error_proc)
+        halt(error.message)
+      else
+        raise error
+      end
+    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_after_transition(from, to, event, *args)
+      instance_exec(from.name, to.name, event, *args, &spec.after_transition_proc) if
+        spec.after_transition_proc
+    end
+
+    def run_action(action, *args)
+      instance_exec(*args, &action) if action
+    end
+
+    def has_callback?(action)
+      # 1. public callback method or
+      # 2. protected method somewhere in the class hierarchy or
+      # 3. private in the immediate class (parent classes ignored)
+      self.respond_to?(action) or
+        self.class.protected_method_defined?(action) or
+        self.private_methods(false).map(&:to_sym).include?(action)
+    end
+
+    def run_action_callback(action_name, *args)
+      action = action_name.to_sym
+      self.send(action, *args) if has_callback?(action)
+    end
+
+    def run_on_entry(state, prior_state, triggering_event, *args)
+      if state.on_entry
+        instance_exec(prior_state.name, triggering_event, *args, &state.on_entry)
+      else
+        hook_name = "on_#{state}_entry"
+        self.send hook_name, prior_state, triggering_event, *args if self.respond_to? hook_name
+      end
+    end
+
+    def run_on_exit(state, new_state, triggering_event, *args)
+      if state
+        if state.on_exit
+          instance_exec(new_state.name, triggering_event, *args, &state.on_exit)
+        else
+          hook_name = "on_#{state}_exit"
+          self.send hook_name, new_state, triggering_event, *args if self.respond_to? hook_name
+        end
+      end
+    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
+
+  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
+
+    klass.extend ClassMethods
+
+    if Object.const_defined?(:ActiveRecord)
+      if klass < ActiveRecord::Base
+        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 < Adapter::Remodel::Entity
+        klass.send :include, Remodel::InstanceMethods
+      end
+    end
+  end
+end

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