rails-workflow 1.4.5.4 → 1.4.6.4

data/lib/workflow/configuration.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Workflow
   class Configuration
     attr_accessor :persist_workflow_state_immediately, :touch_on_update_column

data/lib/workflow/definition.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+module Workflow
+  module Definition
+    extend ActiveSupport::Concern
+
+    # 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
+
+    #   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
+      c = c.superclass until c.workflow_spec || !(c.include? Workflow)
+      c.workflow_spec
+    end
+
+    module ClassMethods
+      attr_reader :workflow_spec
+
+      ##
+      # 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)
+        @workflow_spec = Specification.new({}, &specification)
+        HelperMethodConfigurator.new(@workflow_spec, self).configure!
+      end
+    end
+  end
+end

data/lib/workflow/errors.rb

@@ -1,29 +1,60 @@
+# frozen_string_literal: true
 module Workflow
   module Errors
     class TransitionHaltedError < StandardError
-
       attr_reader :halted_because
 
       def initialize(msg = nil)
         @halted_because = msg
         super msg
       end
-
     end
 
     class NoMatchingTransitionError < StandardError
     end
 
-    class NoTransitionAllowed < StandardError
+    class WorkflowDefinitionError < StandardError
     end
 
-    class WorkflowError < StandardError
+    class NoTransitionsDefinedError < WorkflowDefinitionError
+      def initialize(state, event)
+        super("No transitions defined for event [#{event.name}] on state [#{state.name}]")
+      end
     end
 
-    class CallbackArityError < StandardError
+    class DualEventDefinitionError < WorkflowDefinitionError
+      def initialize
+        super('Event target can only be received in the method call or the block, not both.')
+      end
     end
 
-    class WorkflowDefinitionError < StandardError
+    class EventNameCollisionError < WorkflowDefinitionError
+      def initialize(state, event_name)
+        super("Already defined an event [#{event_name}] for state[#{state.name}]")
+      end
+    end
+
+    class StateComparisonError < StandardError
+      def initialize(state)
+        super("Other State #{state} is a #{state.class}.
+              I can only be compared with a Workflow::State.".squish)
+      end
+    end
+
+    class NoSuchStateError < WorkflowDefinitionError
+      def initialize(event, transition)
+        super("Event #{event.name} transitions to
+              #{transition.target_state} but there is no such state.".squish)
+      end
+    end
+
+    class NoTransitionAllowed < StandardError
+      def initialize(state, event_name)
+        super("There is no event #{event_name} defined for the #{state.name} state")
+      end
+    end
+
+    class WorkflowError < StandardError
     end
   end
 end

data/lib/workflow/event.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Workflow
   class Event
     # @!attribute [r] name
@@ -11,13 +12,17 @@ module Workflow
     # @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.
+    # @param [Hash] meta Optional Metadata for this object.
     def initialize(name, meta: {})
       @name = name.to_sym
       @transitions = []
       @meta = meta || {}
     end
 
+    def valid?
+      transitions.any?
+    end
+
     def inspect
       "<Event name=#{name.inspect} transitions(#{transitions.length})=#{transitions.inspect}>"
     end
@@ -28,28 +33,37 @@ module Workflow
     # @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)
-      transitions.find{|transition|
+      transitions.find do |transition|
         transition.matches? target
-      }&.target_state
+      end&.target_state
+    end
+
+    def evaluate!(target)
+      state_name = evaluate(target)
+      unless state_name
+        raise NoMatchingTransitionError, "No matching transition found on #{name}
+          for target #{target}.  Consider adding a catchall transition.".squish
+      end
+      state_name
     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.
+    # @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 Like `:if` but 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)
+      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
@@ -77,6 +91,7 @@ module Workflow
       end
 
       private
+
       # @!attribute [r] conditions
       #   @return [Workflow::Event::Conditions] Conditions for this transition.
       attr_reader :conditions
@@ -91,7 +106,7 @@ module Workflow
       def initialize(**options, &block)
         @if      = Array(options[:if])
         @unless  = Array(options[:unless])
-        @if      << block if block_given?
+        @if << block if block_given?
         @conditions_lambdas = conditions_lambdas
       end
 
@@ -100,14 +115,14 @@ module Workflow
       end
 
       def apply?(target)
-        @conditions_lambdas.all?{|l| l.call(target)}
+        @conditions_lambdas.all? { |l| l.call(target) }
       end
 
       private
 
       def conditions_lambdas
-        @if.map { |c| Callbacks::Callback.new c } +
-          @unless.map { |c| Callbacks::Callback.new c, true }
+        @if.map { |c| Callbacks::Callback.build c } +
+          @unless.map { |c| Callbacks::Callback.inverted c }
       end
     end
   end

data/lib/workflow/helper_method_configurator.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+module Workflow
+  class HelperMethodConfigurator
+    attr_reader :workflow_spec, :workflow_class
+
+    def initialize(workflow_spec, workflow_class)
+      @workflow_spec  = workflow_spec
+      @workflow_class = workflow_class
+    end
+
+    def configure!
+      undefine_methods_defined_by_workflow_spec if inherited_workflow_spec?
+      define_revert_events if workflow_spec.define_revert_events?
+      create_instance_methods
+    end
+
+    def create_instance_methods
+      workflow_spec.states.each do |state|
+        state_name = state.name
+        workflow_class.module_eval do
+          define_method "#{state_name}?" do
+            state_name == current_state.name
+          end
+        end
+
+        state.events.each do |event|
+          define_method_for_event(event) unless event_method?(event)
+        end
+      end
+    end
+
+    private
+
+    def define_revert_events
+      workflow_spec.states.each do |state|
+        reversible_events(state).each do |event|
+          revert_event_name = "revert_#{event.name}".to_sym
+          from_state_for_revert = event.transitions.first.target_state
+          from_state_for_revert.on revert_event_name, to: state
+        end
+      end
+    end
+
+    def reversible_events(state)
+      state.events.select do |e|
+        e.name !~ /^revert_/ && e.transitions.length == 1
+      end
+    end
+
+    def event_method?(event)
+      workflow_class.instance_methods.include?(event_method_name(event))
+    end
+
+    def event_method_name(event)
+      "#{event.name}!".to_sym
+    end
+
+    def define_method_for_event(event)
+      workflow_class.module_eval do
+        define_method "#{event.name}!".to_sym do |*args|
+          transition!(event.name, *args)
+        end
+
+        define_method "can_#{event.name}?" do
+          current_state.find_event(event.name)&.evaluate(self)
+        end
+      end
+    end
+
+    def inherited_workflow_spec?
+      workflow_class.superclass.respond_to?(:workflow_spec, true) &&
+        workflow_class.superclass.workflow_spec
+    end
+
+    def undefine_methods_defined_by_workflow_spec
+      superclass_workflow_spec.states.each do |state|
+        workflow_class.class_exec(state.name, &undef_state_method_proc)
+
+        state.events.each do |event|
+          workflow_class.class_exec(event.name, &undef_event_method_procs)
+        end
+      end
+    end
+
+    def superclass_workflow_spec
+      workflow_class.superclass.workflow_spec
+    end
+
+    def undef_state_method_proc
+      -> (state) { undef_method "#{state}?" }
+    end
+
+    def undef_event_method_procs
+      lambda do |event_name|
+        undef_method "#{event_name}!"
+        undef_method "can_#{event_name}?"
+      end
+    end
+  end
+end

data/lib/workflow/specification.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 require 'workflow/state'
 require 'workflow/event'
 require 'workflow/errors'
@@ -24,17 +25,6 @@ module Workflow
     attr_reader :named_arguments
 
     define_callbacks :spec_definition
-    set_callback(:spec_definition, :after, if: :define_revert_events?) do |spec|
-      spec.states.each do |state|
-        state.events.reject{ |e|
-          e.name.to_s =~ /^revert_/
-        }.select{|e| e.transitions.length == 1}.each do |event|
-          revert_event_name = "revert_#{event.name}".to_sym
-          from_state_for_revert = event.transitions.first.target_state
-          from_state_for_revert.on revert_event_name, to: state
-        end
-      end
-    end
 
     set_callback(:spec_definition, :after) do |spec|
       spec.states.each do |state|
@@ -42,7 +32,7 @@ module Workflow
           event.transitions.each do |transition|
             target_state = spec.find_state(transition.target_state)
             if target_state.nil?
-              raise Workflow::Errors::WorkflowDefinitionError.new("Event #{event.name} transitions to #{transition.target_state} but there is no such state.")
+              raise Errors::NoSuchStateError.new(event, transition)
             end
             transition.target_state = target_state
           end
@@ -50,12 +40,14 @@ module Workflow
       end
     end
 
+    set_callback(:spec_definition, :after, :define_tag_methods)
+
     # Find the state with the given name.
     #
     # @param [Symbol] name Name of state to find.
     # @return [Workflow::State] The state with the given name.
     def find_state(name)
-      states.find{|t| t.name == name.to_sym}
+      states.find { |t| t.name == name.to_sym }
     end
 
     # @api private
@@ -75,18 +67,17 @@ module Workflow
     #
     # @param [Symbol] name name of state
     # @param [Hash] meta Metadata to be stored with the state within the {Specification} object
+    # @param [Array] tags Tags to apply to the {Workflow::State} object
     # @yield [] block defining events for this state.
     # @return [nil]
-    def state(name, meta: {}, &events)
+    def state(name, tags: [], meta: {}, &events)
       name = name.to_sym
-      new_state = Workflow::State.new(name, @states.length, meta: meta)
+      new_state = Workflow::State.new(name, @states.length, tags: tags, meta: meta)
       @initial_state ||= new_state
       @states << new_state
       new_state.instance_eval(&events) if block_given?
     end
 
-
-
     # Specify attributes to make available on the {TransitionContext} object
     # during transitions taking place in this specification.
     # The attributes' values will be taken in order from the arguments passed to
@@ -98,13 +89,12 @@ module Workflow
       @named_arguments = names
     end
 
-
     # Also create additional event transitions that will move each configured transition
     # in the reverse direction.
     #
     # @return [nil]
     #
-    #```ruby
+    # ```ruby
     # class Article
     #   include Workflow
     #   workflow do
@@ -121,17 +111,50 @@ module Workflow
     # a.current_state.name          # => :bax
     # a.transition! :revert_bar
     # a.current_state.name          # => :foo
-    #```
+    # ```
     def define_revert_events!
       @define_revert_events = true
     end
 
+    def unique_event_names
+      states.collect(&:events).flatten.collect(&:name).flatten.uniq
+    end
+
+    def define_revert_events?
+      @define_revert_events
+    end
+
     private
 
+    module TagHelpers
+      def initial?
+        sequence.zero?
+      end
 
-    def define_revert_events?
-      !!@define_revert_events
+      def terminal?
+        events.empty?
+      end
     end
 
+    def define_tag_methods
+      tags = states.map(&:tags).flatten.uniq
+      tag_method_module = build_tag_method_module(tags)
+      states.each do |state|
+        state.send :extend, tag_method_module
+      end
+    end
+
+    def build_tag_method_module(tags)
+      tag_method_module = Module.new
+      tag_method_module.send :include, TagHelpers
+      tag_method_module.class_eval do
+        tags.each do |tag|
+          define_method "#{tag}?" do
+            self.tags.include?(tag)
+          end
+        end
+      end
+      tag_method_module
+    end
   end
 end