workflow-orchestrator 1.3.0

data/Rakefile

@@ -0,0 +1,30 @@
+require 'rubygems'
+require 'rake/testtask'
+require 'rdoc/task'
+
+require 'bundler'
+Bundler.setup
+
+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-3.x

@@ -0,0 +1,12 @@
+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.0"
+  gem "test-unit"
+end

data/gemfiles/Gemfile.rails-4.0

@@ -0,0 +1,14 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "minitest", "~> 5.1.0"
+  gem "rdoc", ">= 3.12"
+  gem "bundler", ">= 1.0.0"
+  gem "activerecord", "~>4.1"
+  gem 'protected_attributes'
+  gem "sqlite3"
+  gem "mocha"
+  gem "rake"
+  gem "ruby-graphviz", "~> 1.0.0"
+  gem "test-unit"
+end

data/gemfiles/Gemfile.rails-4.1

@@ -0,0 +1,14 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "minitest", "~> 5.1.0"
+  gem "rdoc", ">= 3.12"
+  gem "bundler", ">= 1.0.0"
+  gem "activerecord", "~>4.0"
+  gem "protected_attributes"
+  gem "sqlite3"
+  gem "mocha"
+  gem "rake"
+  gem "ruby-graphviz", "~> 1.0.0"
+  gem "test-unit"
+end

data/gemfiles/Gemfile.rails-4.2

@@ -0,0 +1,14 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "minitest", "~> 5.1.0"
+  gem "rdoc", ">= 3.12"
+  gem "bundler", ">= 1.0.0"
+  gem "activerecord", "~>4.2"
+  gem "protected_attributes"
+  gem "sqlite3"
+  gem "mocha"
+  gem "rake"
+  gem "ruby-graphviz", "~> 1.0.0"
+  gem "test-unit"
+end

data/gemfiles/Gemfile.rails-edge

@@ -0,0 +1,14 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "minitest", "~> 5.1.0"
+  gem "rdoc", ">= 3.12"
+  gem "bundler", ">= 1.0.0"
+  gem "activerecord"
+  gem "sqlite3"
+  gem "mocha"
+  gem "rake"
+  gem "ruby-graphviz", "~> 1.0.0"
+  gem "protected_attributes"
+  gem "test-unit"
+end

data/lib/workflow/adapters/active_record.rb

@@ -0,0 +1,75 @@
+module Workflow
+  module Adapter
+    module ActiveRecord
+      def self.included(klass)
+        klass.send :include, Adapter::ActiveRecord::InstanceMethods
+        klass.send :extend, Adapter::ActiveRecord::Scopes
+        klass.before_validation :write_initial_state
+      end
+
+      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)
+          # Rails 3.1 or newer
+          update_column self.class.workflow_column, new_value
+        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 value of the
+        # initial state in all the new records.
+        def write_initial_state
+          write_attribute self.class.workflow_column, current_state.value
+        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
+      # Payment.without_refunded_state # => ActiveRecord::Relation
+      #`
+      # Example above just adds `where(:state_column_name => 'pending')` or
+      # `where.not(: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(column=nil, &specification)
+          workflow_without_scopes(column, &specification)
+          states = workflow_spec.states.values
+
+          states.each do |state|
+            define_singleton_method("with_#{state}_state") do
+              where("#{table_name}.#{self.workflow_column.to_sym} = ?", state.value)
+            end
+
+            define_singleton_method("without_#{state}_state") do
+              where("#{table_name}.#{self.workflow_column.to_sym} != ?", state.value)
+            end
+
+            define_method("without_#{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.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.flat.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,20 @@
+module Workflow
+  class Error < StandardError; end
+
+  class TransitionHalted < Error
+
+    attr_reader :halted_because
+
+    def initialize(msg = nil)
+      @halted_because = msg
+      super msg
+    end
+
+  end
+
+  class NoTransitionAllowed < Error; end
+
+  class WorkflowError < Error; end
+
+  class WorkflowDefinitionError < Error; end
+end

data/lib/workflow/event.rb

@@ -0,0 +1,38 @@
+module Workflow
+  class Event
+
+    attr_accessor :name, :transitions_to, :meta, :action, :condition
+
+    def initialize(name, transitions_to, condition = nil, meta = {}, &action)
+      @name = name
+      @transitions_to = transitions_to.to_sym
+      @meta = meta
+      @action = action
+      @condition = if condition.nil? || condition.is_a?(Symbol) || condition.respond_to?(:call)
+                     condition
+                   else
+                     raise TypeError, 'condition must be nil, an instance method name symbol or a callable (eg. a proc or lambda)'
+                   end
+    end
+
+    def condition_applicable?(object)
+      if condition
+        if condition.is_a?(Symbol)
+          object.send(condition)
+        else
+          condition.call(object)
+        end
+      else
+        true
+      end
+    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/event_collection.rb

@@ -0,0 +1,36 @@
+module Workflow
+  class EventCollection < Hash
+
+    def [](name)
+      super name.to_sym # Normalize to symbol
+    end
+
+    def push(name, event)
+      key = name.to_sym
+      self[key] ||= []
+      self[key] << event
+    end
+
+    def flat
+      self.values.flatten.uniq do |event|
+        [:name, :transitions_to, :meta, :action].map { |m| event.send(m) }
+      end
+    end
+
+    def include?(name_or_obj)
+      case name_or_obj
+      when Event
+        flat.include? name_or_obj
+      else
+        !(self[name_or_obj].nil?)
+      end
+    end
+
+    def first_applicable(name, object_context)
+      (self[name] || []).detect do |event|
+        event.condition_applicable?(object_context) && event
+      end
+    end
+
+  end
+end

data/lib/workflow/specification.rb

@@ -0,0 +1,83 @@
+require 'workflow/state'
+require 'workflow/event'
+require 'workflow/event_collection'
+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, :on_unavailable_transition_proc
+
+    def initialize(meta = {}, &specification)
+      @states = Hash.new
+      @meta = meta
+      instance_eval(&specification)
+    end
+
+    def state_names
+      states.keys
+    end
+
+    private
+
+    def state(name, value=nil, options=nil, &events_and_etc)
+
+      if value.is_a? Hash
+        value = nil
+        options = value
+      end
+
+      value ||= name
+      options ||= {}
+      meta.reverse_merge! meta: {}
+
+      new_state = Workflow::State.new(name, value, self, options[: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]
+      condition = args[:if]
+      raise WorkflowDefinitionError.new(
+        "missing ':transitions_to' in workflow event definition for '#{name}'") \
+        if target.nil?
+      @scoped_state.events.push(
+        name, Workflow::Event.new(name, target, condition, (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
+
+    def on_unavailable_transition(&proc)
+      @on_unavailable_transition_proc = proc
+    end
+
+  end
+end

data/lib/workflow/state.rb

@@ -0,0 +1,44 @@
+module Workflow
+  class State
+    attr_accessor :name, :value, :events, :meta, :on_entry, :on_exit
+    attr_reader :spec
+
+    def initialize(name, value, spec, meta = {})
+      @name, @value, @spec, @events, @meta = name, value, spec, EventCollection.new, meta
+    end
+
+    def draw(graph)
+      defaults = {
+        :label => to_s,
+        :width => '1',
+        :height => '1',
+        :shape => 'ellipse'
+      }
+
+      node = graph.add_nodes(to_s, defaults)
+
+      # 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.3.0"
+end