rails-workflow 1.4.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/asdf

@@ -0,0 +1,18 @@
+
+[:before, :after, :around].each do |callback|
+puts <<-EOF
+##
+# :method: #{callback}_transition
+#
+# :call-seq:
+#   #{callback}_transition(*instance_method_names, options={})
+#   #{callback}_transition(*instance_method_names)
+#   #{callback}_transition(*instance_method_names)
+#
+# Append a callback #{callback} transitions.
+# Instance methods used for `before` and `after` transitions
+# receive no 
+#
+
+EOF
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "workflow"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

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.0"
+end

data/gemfiles/Gemfile.rails-4.0

@@ -0,0 +1,14 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "minitest", "< 5.0.0" # 5.0.0 introduced incompatible changes renaming all the classes
+  gem "rdoc", ">= 3.12"
+  gem "bundler", ">= 1.0.0"
+  gem "activerecord", "~>4.0"
+  gem 'protected_attributes'
+  gem "sqlite3"
+  gem "mocha"
+  gem "rake"
+  gem "test-unit"
+  gem "ruby-graphviz", "~> 1.0.0"
+end

data/gemfiles/Gemfile.rails-5.0

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "rdoc", ">= 3.12"
+  gem "bundler", ">= 1.0.0"
+  gem "activerecord", "~>5.0"
+  # gem 'protected_attributes' only supported until Rails 5.0
+  gem "sqlite3"
+  gem "mocha"
+  gem "rake"
+  gem "test-unit"
+  gem "ruby-graphviz", "~> 1.0.0"
+end

data/gemfiles/Gemfile.rails-edge

@@ -0,0 +1,13 @@
+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 "test-unit"
+  gem "ruby-graphviz", "~> 1.0.0"
+  gem 'protected_attributes'
+end

data/lib/workflow.rb

@@ -0,0 +1,295 @@
+require 'rubygems'
+require 'active_support/concern'
+require 'workflow/version'
+require 'workflow/configuration'
+require 'workflow/specification'
+require 'workflow/callbacks'
+require 'workflow/adapters/active_record'
+require 'workflow/adapters/remodel'
+require 'workflow/adapters/active_record_validations'
+require 'workflow/transition_context'
+
+# See also README.markdown for documentation
+module Workflow
+  # @!parse include Callbacks
+  # @!parse extend Callbacks::ClassMethods
+
+  extend ActiveSupport::Concern
+  include Callbacks
+  include Errors
+
+  def self.configure(&block)
+    block.call(config) if block_given?
+  end
+
+  def self.config
+    @@configuration ||= Configuration.new
+  end
+
+  included do
+
+    # Look for a hook; otherwise detect based on ancestor class.
+    if respond_to?(:workflow_adapter)
+      include self.workflow_adapter
+    else
+      if Object.const_defined?(:ActiveRecord) && self < ActiveRecord::Base
+        include Adapter::ActiveRecord
+        include Adapter::ActiveRecordValidations
+      end
+      if Object.const_defined?(:Remodel) && klass < Adapter::Remodel::Entity
+        include Adapter::Remodel::InstanceMethods
+      end
+    end
+  end
+
+  # Returns a state object representing the current workflow state.
+  #
+  # @return [State] Current workflow state
+  def current_state
+    loaded_state = load_workflow_state
+    res = workflow_spec.states.find{|t| t.name==loaded_state.to_sym} if loaded_state
+    res || workflow_spec.initial_state
+  end
+
+  # Deprecated.  Check for false return value from {#process_event!}
+  # @return true if the last transition was halted by one of the transition callbacks.
+  def halted?
+    @halted
+  end
+
+  # Returns the reason given to a call to {#halt} or {#halt!}, if any.
+  # @return [String] The reason the transition was aborted.
+  attr_reader :halted_because
+
+  # Initiates state transition via the named event
+  #
+  # @param [Symbol] name name of event to initiate
+  # @param [Mixed] *args Arguments passed to state transition. Available also to callbacks
+  # @return [Type] description of returned object
+  def process_event!(name, *args, **attributes)
+    name = name.to_sym
+    event = current_state.find_event(name)
+    raise NoTransitionAllowed.new(
+      "There is no event #{name} defined for the #{current_state.name} state") \
+      if event.nil?
+
+    @halted_because = nil
+    @halted = false
+
+    target = event.evaluate(self)
+    unless target
+      raise NoMatchingTransitionError.new("No matching transition found on #{name} for target #{target}.  Consider adding a catchall transition.")
+    end
+
+    from = current_state
+    return_value = false
+    begin
+      @transition_context = TransitionContext.new \
+        from: from.name,
+        to: target.name,
+        event: name,
+        event_args: args,
+        attributes: attributes,
+        named_arguments: workflow_spec.named_arguments
+
+      run_all_callbacks do
+        callback_value = run_action_callback name, *args
+        return_value   = callback_value
+        return_value ||= persist_workflow_state(target.name) || true
+      end
+    ensure
+      @transition_context = nil
+    end
+    return_value
+  end
+
+  # Stop the current transition and set the reason for the abort.
+  #
+  # @param optional [String] reason Reason for halting transition.
+  # @return [void]
+  def halt(reason = nil)
+    @halted_because = reason
+    @halted = true
+    throw :abort
+  end
+
+  # Sets halt reason and raises [TransitionHaltedError] error.
+  #
+  # @param optional [String] reason Reason for halting
+  # @return [void]
+  def halt!(reason = nil)
+    @halted_because = reason
+    @halted = true
+    raise TransitionHaltedError.new(reason)
+  end
+
+  #   The specification for this object.
+  #   Could be set on a singleton for the object, on the object's class,
+  #   Or else on a superclass of the object.
+  # @return [Specification] The Specification that applies to this object.
+  def workflow_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 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)
+    action = action.to_sym
+    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
+    if has_callback?(action)
+      meth = method(action)
+      check_method_arity! meth, *args
+      meth.call *args
+    end
+  end
+
+  def check_method_arity!(method, *args)
+    arity = method.arity
+
+    unless (arity >= 0 && args.length == arity) || (arity < 0 && (args.length + 1) >= arity.abs)
+      raise CallbackArityError.new("Method #{method.name} has arity #{arity} but was called with #{args.length} arguments.")
+    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
+
+  module ClassMethods
+    attr_reader :workflow_spec
+
+    # Instructs Workflow which column to use to persist workflow state.
+    #
+    # @param optional [Symbol] column_name name of column on table
+    # @return [void]
+    def workflow_column(column_name=nil)
+      if column_name
+        @workflow_state_column_name = column_name.to_sym
+      end
+      if !instance_variable_defined?('@workflow_state_column_name') && superclass.respond_to?(:workflow_column)
+        @workflow_state_column_name = superclass.workflow_column
+      end
+      @workflow_state_column_name ||= :workflow_state
+    end
+
+
+    ##
+    # Define workflow for the class.
+    #
+    # @yield [] Specification of workflow. Example below and in README.markdown
+    # @return [nil]
+    #
+    # Workflow definition takes place inside the yielded block.
+    # @see Specification::state
+    # @see Specification::event
+    #
+    # ~~~ruby
+    #
+    # 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
+    #     state :rejected
+    #   end
+    # 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 self.superclass.respond_to?(:workflow_spec, true) && self.superclass.workflow_spec
+        undefine_methods_defined_by_workflow_spec superclass.workflow_spec
+      end
+
+      @workflow_spec = specification_object
+      @workflow_spec.states.each do |state|
+        state_name = state.name
+        module_eval do
+          define_method "#{state_name}?" do
+            state_name == current_state.name
+          end
+        end
+
+        state.events.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 !!current_state.find_event(event_name)&.evaluate(self)
+            end
+          end
+        end
+      end
+    end
+
+    def undefine_methods_defined_by_workflow_spec(inherited_workflow_spec)
+      inherited_workflow_spec.states.each do |state|
+        state_name = state.name
+        module_eval do
+          undef_method "#{state_name}?"
+        end
+
+        state.events.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
+  end
+end

data/lib/workflow/adapters/active_record.rb

@@ -0,0 +1,78 @@
+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).to_sym
+        end
+
+        # On transition the new workflow state is immediately saved in the
+        # database, if configured to do so.
+        def persist_workflow_state(new_value)
+          # Rails 3.1 or newer
+          if persisted? && Workflow.config.persist_workflow_state_immediately
+            attrs = {self.class.workflow_column => new_value}
+            if Workflow.config.touch_on_update_column
+              attrs[:updated_at] = DateTime.now
+            end
+            update_columns attrs
+          else
+            self[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.name
+        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(&specification)
+          workflow_without_scopes(&specification)
+          states = workflow_spec.states
+
+          states.map(&:name).each do |state|
+            define_singleton_method("with_#{state}_state") do
+              where(self.workflow_column.to_sym => state.to_s)
+            end
+
+            define_singleton_method("without_#{state}_state") do
+              where.not(self.workflow_column.to_sym => state.to_s)
+            end
+          end
+        end
+      end
+    end
+  end
+end