rails-workflow 1.4.4.4 → 1.4.5.4

data/lib/active_support/overloads.rb

@@ -0,0 +1,32 @@
+require 'active_support/callbacks'
+
+module ActiveSupport
+  # Overloads for {ActiveSupport::Callbacks::Callback} so it can recognize
+  # {Workflow::Callbacks::TransitionCallback}, which is duck-type equivalent
+  # to a lambda for the present purposes.
+  module CallbackOverloads
+    private
+    def make_lambda(filter)
+      if filter.kind_of? Workflow::Callbacks::TransitionCallback
+        super(filter.wrapper)
+      else
+        super
+      end
+    end
+
+    def compute_identifier(filter)
+      if filter.kind_of? Workflow::Callbacks::TransitionCallback
+        super(filter.raw_proc)
+      else
+        super
+      end
+    end
+  end
+end
+
+# Overload {ActiveSupport::Callbacks::Callback} with methods from {ActiveSupport::CallbackOverloads}.
+# {Workflow::Callbacks::TransitionCallback}, which is duck-type equivalent
+# to a lambda for the present purposes.
+class ::ActiveSupport::Callbacks::Callback
+  prepend ActiveSupport::CallbackOverloads
+end

data/lib/workflow.rb

@@ -1,5 +1,6 @@
 require 'rubygems'
 require 'active_support/concern'
+require 'active_support/callbacks'
 require 'workflow/version'
 require 'workflow/configuration'
 require 'workflow/specification'
@@ -8,6 +9,8 @@ require 'workflow/adapters/active_record'
 require 'workflow/adapters/remodel'
 require 'workflow/adapters/active_record_validations'
 require 'workflow/transition_context'
+require 'active_support/overloads'
+
 
 # See also README.markdown for documentation
 module Workflow
@@ -18,35 +21,16 @@ module Workflow
   include Callbacks
   include Errors
 
-  module ComputeIdentifier
-    private
-    def make_lambda(filter)
-      if filter.kind_of? Workflow::Callbacks::TransitionCallbackWrapper
-        super(filter.wrapper)
-      else
-        super
-      end
-    end
-
-    def compute_identifier(filter)
-      if filter.kind_of? Workflow::Callbacks::TransitionCallbackWrapper
-        super(filter.raw_proc)
-      else
-        super
-      end
-    end
-  end
-
-  class ::ActiveSupport::Callbacks::Callback
-    prepend ComputeIdentifier
-  end
+  # The application-wide Workflow configuration object
+  CONFIGURATION = Configuration.new
 
-  def self.configure(&block)
-    block.call(config) if block_given?
-  end
-
-  def self.config
-    @@configuration ||= Configuration.new
+  # Helper method for setting configuration options on {Workflow.config}
+  #
+  # @yield [Workflow::Configuration] config {Configuration} object to be manipulated.
+  # @return [nil]
+  def self.config(&block)
+    block.call(CONFIGURATION) if block_given?
+    return CONFIGURATION
   end
 
   included do
@@ -75,7 +59,7 @@ module Workflow
   end
 
   # Deprecated.  Check for false return value from {#transition!}
-  # @return true if the last transition was halted by one of the transition callbacks.
+  # @return [Boolean] true if the last transition was halted by one of the transition callbacks.
   def halted?
     @halted
   end
@@ -84,11 +68,21 @@ module Workflow
   # @return [String] The reason the transition was aborted.
   attr_reader :halted_because
 
+  # @api private
+  # @return [Workflow::TransitionContext] During transition, or nil if no transition is underway.
+  # During a state transition, contains transition-specific information:
+  # * The name of the {Workflow::State} being exited,
+  # * The name of the {Workflow::State} being entered,
+  # * The name of the {Workflow::Event} that was fired,
+  # * And whatever arguments were passed to the {Workflow#transition!} method.
+  attr_reader :transition_context
+
   # 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
+  # @param [Array] args State transition arguments.
+  # @return [Symbol] The name of the new state, or `false` if the transition failed.
+  # TODO: connect args to documentation on how arguments are accessed during state transitions.
   def transition!(name, *args, **attributes)
     name = name.to_sym
     event = current_state.find_event(name)
@@ -128,8 +122,8 @@ module Workflow
 
   # Stop the current transition and set the reason for the abort.
   #
-  # @param optional [String] reason Reason for halting transition.
-  # @return [void]
+  # @param [String] reason Optional reason for halting transition.
+  # @return [nil]
   def halt(reason = nil)
     @halted_because = reason
     @halted = true
@@ -138,8 +132,8 @@ module Workflow
 
   # Sets halt reason and raises [TransitionHaltedError] error.
   #
-  # @param optional [String] reason Reason for halting
-  # @return [void]
+  # @param [String] reason Optional reason for halting
+  # @return [nil]
   def halt!(reason = nil)
     @halted_because = reason
     @halted = true
@@ -214,8 +208,8 @@ module Workflow
 
     # Instructs Workflow which column to use to persist workflow state.
     #
-    # @param optional [Symbol] column_name name of column on table
-    # @return [void]
+    # @param [Symbol] column_name If provided, will set a new workflow column name.
+    # @return [Symbol] The current (or new) name for the workflow column on this class.
     def workflow_column(column_name=nil)
       if column_name
         @workflow_state_column_name = column_name.to_sym

data/lib/workflow/callbacks.rb

@@ -1,6 +1,7 @@
 require 'workflow/callbacks/callback'
-require 'workflow/callbacks/transition_callback_wrapper'
-require 'workflow/callbacks/transition_callback_method_wrapper'
+require 'workflow/callbacks/transition_callback'
+require 'workflow/callbacks/transition_callbacks/method_wrapper'
+require 'workflow/callbacks/transition_callbacks/proc_wrapper'
 
 module Workflow
   module Callbacks
@@ -19,7 +20,6 @@ module Workflow
     #   @return [TransitionContext] representation of current state transition
     #
     included do
-      attr_reader :transition_context
       CALLBACK_MAP.keys.each do |type|
         define_callbacks type,
           skip_after_callbacks_if_terminated: true
@@ -247,13 +247,13 @@ module Workflow
         CALLBACK_MAP.each do |type, context_attribute|
           define_method "#{callback}_#{type}" do |*names, &blk|
             _insert_callbacks(names, context_attribute, blk) do |name, options|
-              set_callback(type, callback, TransitionCallbackWrapper.build_wrapper(callback, name, self), options)
+              set_callback(type, callback, Callbacks::TransitionCallback.build_wrapper(callback, name, self), options)
             end
           end
 
           define_method "prepend_#{callback}_#{type}" do |*names, &blk|
             _insert_callbacks(names, context_attribute, blk) do |name, options|
-              set_callback(type, callback, TransitionCallbackWrapper.build_wrapper(callback, name, self), options.merge(prepend: true))
+              set_callback(type, callback, Callbacks::TransitionCallback.build_wrapper(callback, name, self), options.merge(prepend: true))
             end
           end
 

data/lib/workflow/callbacks/{transition_callback_wrapper.rb → transition_callback.rb}

@@ -1,8 +1,8 @@
 
 module Workflow
   module Callbacks
-    class TransitionCallbackWrapper
-      attr_reader :callback_type, :raw_proc
+    class TransitionCallback
+      attr_reader :callback_type, :raw_proc, :calling_class
       def initialize(callback_type, raw_proc, calling_class)
         @callback_type = callback_type
         @raw_proc      = raw_proc
@@ -11,29 +11,34 @@ module Workflow
 
       def self.build_wrapper(callback_type, raw_proc, calling_class)
         if raw_proc.kind_of? ::Proc
-          new(callback_type, raw_proc, calling_class).wrapper
+          TransitionCallbacks::ProcWrapper.new(callback_type, raw_proc, calling_class)
         elsif raw_proc.kind_of? ::Symbol
-          TransitionCallbackMethodWrapper.new(callback_type, raw_proc, calling_class)
+          if zero_arity_method?(raw_proc, calling_class)
+            raw_proc
+          else
+            TransitionCallbacks::MethodWrapper.new(callback_type, raw_proc, calling_class)
+          end
         else
           raw_proc
         end
       end
 
       def wrapper
-        arguments = [
-          name_arguments_string,
-          rest_param_string,
-          kw_arguments_string,
-          keyrest_string,
-          procedure_string].compact.join(', ')
-
-        raw_proc = self.raw_proc
-        str = build_proc("target.instance_exec(#{arguments})")
-        eval(str)
+        raise NotImplementedError.new "Abstract Method Called"
       end
 
       protected
 
+      # Returns true if the method has arity zero.
+      # Returns false if the method is defined and has non-zero arity.
+      # Returns nil if the method has not been defined.
+      def self.zero_arity_method?(method, calling_class)
+        if calling_class.instance_methods.include?(method)
+          method = calling_class.instance_method(method)
+          method.arity == 0
+        end
+      end
+
       def build_proc(proc_body)
         <<-EOF
           Proc.new do |target#{', callbacks' if around_callback?}|
@@ -56,12 +61,7 @@ module Workflow
       end
 
       def name_arguments_string
-        params = name_params
-        names  = []
-        names << 'target'   if params.shift
-        (names << 'callbacks') && params.shift if around_callback?
-        names += params.map{|name| "name_proc.call(:#{name})"}
-        return names.join(', ') if names.any?
+        raise NotImplementedError.new "Abstract Method Called"
       end
 
       def kw_arguments_string
@@ -80,7 +80,7 @@ module Workflow
       end
 
       def procedure_string
-        '&raw_proc'
+        raise NotImplementedError.new "Abstract Method Called"
       end
 
       def name_params
@@ -106,11 +106,11 @@ module Workflow
       end
 
       def parameters
-        raw_proc.parameters
+        raise NotImplementedError.new "Abstract Method Called"
       end
 
       def arity
-        raw_proc.arity
+        raise NotImplementedError.new "Abstract Method Called"
       end
     end
   end

data/lib/workflow/callbacks/transition_callbacks/method_wrapper.rb

@@ -0,0 +1,102 @@
+module Workflow
+  module Callbacks
+    module TransitionCallbacks
+      # A {Workflow::Callbacks::TransitionCallback} that wraps an instance method
+      # With arity != 0.
+      # Because the wrapped method may not have been defined at the time the callback
+      # is defined, the string representing the method call is built at runtime
+      # rather than at compile time.
+      class MethodWrapper < ::Workflow::Callbacks::TransitionCallback
+        attr_reader :calling_class
+
+        # Builds a proc object that will correctly call the {#raw_proc}
+        # by inspecting its parameters and pulling arguments from the {Workflow::TransitionContext}
+        # object for the transition.
+        # Given an overloaded `==` operator so for {Workflow#skip_before_transition} and other
+        # `skip_transition` calls.
+        # @return [Type] description of returned object
+        def wrapper
+          cb_object = self
+          proc_string = build_proc(<<-EOF)
+            arguments = [
+              cb_object.send(:raw_proc).inspect,
+              cb_object.send(:name_arguments_string),
+              cb_object.send(:rest_param_string),
+              cb_object.send(:kw_arguments_string),
+              cb_object.send(:keyrest_string),
+              cb_object.send(:procedure_string)].compact.join(', ')
+            target.instance_eval("send(\#{arguments})")
+          EOF
+          _wrapper = eval(proc_string)
+          _wrapper.instance_exec(raw_proc, &OVERLOAD_EQUALITY_OPERATOR_PROC)
+          _wrapper
+        end
+
+        private
+
+        # A that is instanced_exec'd on a new proc object within {#wrapper}
+        #
+        # Enables comparison of two wrapper procs to determine if they wrap the same
+        # Method.
+        OVERLOAD_EQUALITY_OPERATOR_PROC = Proc.new do |method_name|
+          def method_name
+            method_name
+          end
+
+          # Equality operator overload.
+          # If other is a {Symbol}, matches this object against {#method_name} defined above.
+          # If other is a {Proc}:
+          # * If it responds to {#method_name}, matches the method names of the two objects.
+          # * Otherwise false
+          #
+          # @param [Symbol] other A method name to compare against.
+          # @param [Proc] other A proc to compare against.
+          # @return [Boolean] Whether the two should be considered equivalent
+          def ==(other)
+            case other
+            when ::Proc
+              if other.respond_to?(:raw_proc)
+                self.method_name == other.method_name
+              else
+                false
+              end
+            when ::Symbol
+              self.method_name == other
+            else
+              false
+            end
+          end
+        end
+
+        def name_arguments_string
+          if name_params.any?
+            name_params.map{|name|
+              "name_proc.call(:#{name})"
+            }.join(', ')
+          end
+        end
+
+        def procedure_string
+          '&callbacks' if around_callback?
+        end
+
+        # @return [UnboundMethod] Method representation from class {#calling_class}, named by {#raw_proc}
+        def callback_method
+          @meth ||= calling_class.instance_method(raw_proc)
+        end
+
+        # Parameter definition for the object.  See {UnboundMethod#parameters}
+        #
+        # @return [Array] Parameters
+        def parameters
+          callback_method.parameters
+        end
+
+        # @return [Fixnum] Arity of the callback method
+        def arity
+          callback_method.arity
+        end
+      end
+    end
+  end
+end

data/lib/workflow/callbacks/transition_callbacks/proc_wrapper.rb

@@ -0,0 +1,48 @@
+
+module Workflow
+  module Callbacks
+    module TransitionCallbacks
+      # A {Workflow::Callbacks::TransitionCallback} that wraps a callback proc.
+      class ProcWrapper < ::Workflow::Callbacks::TransitionCallback
+        # Builds a proc object that will correctly call the {#raw_proc}
+        # by inspecting its parameters and pulling arguments from the {Workflow::TransitionContext}
+        # object for the transition.
+        def wrapper
+          arguments = [
+            name_arguments_string,
+            rest_param_string,
+            kw_arguments_string,
+            keyrest_string,
+            procedure_string].compact.join(', ')
+
+          raw_proc = self.raw_proc
+          str = build_proc("target.instance_exec(#{arguments})")
+          eval(str)
+        end
+
+        private
+
+        def name_arguments_string
+          params = name_params
+          names  = []
+          names << 'target'   if params.shift
+          (names << 'callbacks') && params.shift if around_callback?
+          names += params.map{|name| "name_proc.call(:#{name})"}
+          return names.join(', ') if names.any?
+        end
+
+        def procedure_string
+          '&raw_proc'
+        end
+
+        def parameters
+          raw_proc.parameters
+        end
+
+        def arity
+          raw_proc.arity
+        end
+      end
+    end
+  end
+end

data/lib/workflow/event.rb

@@ -1,8 +1,18 @@
 module Workflow
   class Event
+    # @!attribute [r] name
+    #   @return [Symbol] The name of the event.
+    # @!attribute [r] transitions
+    #   @return [Array] Array of {Workflow::Event::Transition}s defined for this event.
+    # @!attribute [r] meta
+    #   @return [Hash] Extra information defined for this event.
     attr_reader :name, :transitions, :meta
 
-    def initialize(name, meta)
+    # @api private
+    # See {Workflow::State#on} for creating objects of this class.
+    # @param [Symbol] name The name of the event to create.
+    # @param [Hash] meta: Optional Metadata for this object.
+    def initialize(name, meta: {})
       @name = name.to_sym
       @transitions = []
       @meta = meta || {}
@@ -12,27 +22,51 @@ module Workflow
       "<Event name=#{name.inspect} transitions(#{transitions.length})=#{transitions.inspect}>"
     end
 
+    # Returns the {Workflow::State} that the target object should enter.
+    # This will be the first one in the list of transitions, whose conditions apply
+    # to the target object in its present state.
+    # @param [Object] target An object of the class that this event was defined on.
+    # @return [Workflow::State] The first applicable destination state, or nil if none.
     def evaluate(target)
-      transition = transitions.find{|t| t.apply? target}
-      if transition
-        return transition.target_state
-      else
-        nil
-      end
+      transitions.find{|transition|
+        transition.matches? target
+      }&.target_state
     end
 
+    # Add a {Workflow::Transition} to the possible {#transitions} for this event.
+    #
+    # @param [Symbol] target_state the name of the state target state if this transition matches.
+    # @option conditions_def [Symbol] :if Name of instance method to evaluate. e.g. `:valid?`
+    # @option conditions_def [Array] :if Mixed array of Symbol, String or Proc conditions.  All must match for the transition to apply.
+    # @option conditions_def [String] :if A string to evaluate on the target. e.g. `"self.foo == :bar"`
+    # @option conditions_def [Proc] :if A proc which will be evaluated on the object e.g. `->{self.foo == :bar}`
+    # @option conditions_def [Symbol] :unless Same as `:if` except all conditions must **not** match.
+    # @yield [] Optional block which, if provided, becomes an `:if` condition for the transition.
+    # @return [nil]
     def to(target_state, **conditions_def, &block)
       conditions = Conditions.new &&conditions_def, block
       self.transitions << Transition.new(target_state, conditions_def, &block)
     end
 
     private
+
+    # @api private
+    # Represents a possible transition via the event on which it is defined.
     class Transition
-      attr_accessor :target_state, :conditions
-      def apply?(target)
+      # @!attribute [r] target_state
+      #   @return [Workflow::State] The target state for this transition.
+      attr_accessor :target_state
+
+      # Whether or not the conditions match for the target object.
+      #
+      # @param [Object] target an object of the class for which this event/transition was defined.
+      # @return [Boolean] True if all conditions apply.
+      def matches?(target)
         conditions.apply?(target)
       end
-      # delegate :apply?, to: :conditions
+
+      # @param [Symbol] target_state the name of the state target state if this transition matches.
+      # @param [Hash] conditions_def See {Event#to}
       def initialize(target_state, conditions_def, &block)
         @target_state = target_state
         @conditions = Conditions.new conditions_def, &block
@@ -41,9 +75,19 @@ module Workflow
       def inspect
         "<to=#{target_state.inspect} conditions=#{conditions.inspect}"
       end
+
+      private
+      # @!attribute [r] conditions
+      #   @return [Workflow::Event::Conditions] Conditions for this transition.
+      attr_reader :conditions
     end
 
-    class Conditions #:nodoc:#
+    # @api private
+    # Maintains a list of callback procs which are evaluted to determine if the
+    # transition on which they were defined is valid for an object in its current state.
+    # Borrowed from ActiveSupport::Callbacks
+    # See [original source here](https://github.com/rails/rails/blob/bca2e69b785fa3cdbe148b0d2dd5d3b58f6daf53/activesupport/lib/active_support/callbacks.rb#L419)
+    class Conditions
       def initialize(**options, &block)
         @if      = Array(options[:if])
         @unless  = Array(options[:unless])
@@ -61,7 +105,6 @@ module Workflow
 
       private
 
-      # From https://github.com/rails/rails/blob/bca2e69b785fa3cdbe148b0d2dd5d3b58f6daf53/activesupport/lib/active_support/callbacks.rb#L419
       def conditions_lambdas
         @if.map { |c| Callbacks::Callback.new c } +
           @unless.map { |c| Callbacks::Callback.new c, true }