rails-workflow 1.4.0

data/lib/workflow/errors.rb

@@ -0,0 +1,29 @@
+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
+    end
+
+    class WorkflowError < StandardError
+    end
+
+    class CallbackArityError < StandardError
+    end
+
+    class WorkflowDefinitionError < StandardError
+    end
+  end
+end

data/lib/workflow/event.rb

@@ -0,0 +1,129 @@
+module Workflow
+  class Event
+    attr_reader :name, :transitions, :meta
+
+    def initialize(name, meta)
+      @name = name.to_sym
+      @transitions = []
+      @meta = meta || {}
+    end
+
+    def inspect
+      "<Event name=#{name.inspect} transitions(#{transitions.length})=#{transitions.inspect}>"
+    end
+
+    def evaluate(target)
+      transition = transitions.find{|t| t.apply? target}
+      if transition
+        return transition.target_state
+      else
+        nil
+      end
+    end
+
+    def to(target_state, **conditions_def, &block)
+      conditions = Conditions.new &&conditions_def, block
+      self.transitions << Transition.new(target_state, conditions_def, &block)
+    end
+
+    private
+    class Transition
+      attr_accessor :target_state, :conditions
+      def apply?(target)
+        conditions.apply?(target)
+      end
+      # delegate :apply?, to: :conditions
+      def initialize(target_state, conditions_def, &block)
+        @target_state = target_state
+        @conditions = Conditions.new conditions_def, &block
+      end
+
+      def inspect
+        "<to=#{target_state.inspect} conditions=#{conditions.inspect}"
+      end
+    end
+
+    class Conditions #:nodoc:#
+
+      def initialize(**options, &block)
+        @if      = Array(options[:if])
+        @unless  = Array(options[:unless])
+        @if      << block if block_given?
+        @conditions_lambdas = conditions_lambdas
+      end
+
+      def inspect
+        "if: #{@if}, unless: #{@unless}"
+      end
+
+      def apply?(target)
+        # TODO: Remove the second parameter from the conditions below.
+        @conditions_lambdas.all?{|l| l.call(target, ->(){})}
+      end
+
+      private
+
+      # Copied from https://github.com/rails/rails/blob/bca2e69b785fa3cdbe148b0d2dd5d3b58f6daf53/activesupport/lib/active_support/callbacks.rb#L366
+      def invert_lambda(l)
+        lambda { |*args, &blk| !l.call(*args, &blk) }
+      end
+
+      # Filters support:
+      #
+      #   Symbols:: A method to call.
+      #   Strings:: Some content to evaluate.
+      #   Procs::   A proc to call with the object.
+      #   Objects:: An object with a <tt>before_foo</tt> method on it to call.
+      #
+      # All of these objects are converted into a lambda and handled
+      # the same after this point.
+      # Copied from https://github.com/rails/rails/blob/bca2e69b785fa3cdbe148b0d2dd5d3b58f6daf53/activesupport/lib/active_support/callbacks.rb#L379
+      def make_lambda(filter)
+        case filter
+        when Symbol
+          lambda { |target, _, &blk| target.send filter, &blk }
+        when String
+          l = eval "lambda { |value| #{filter} }"
+        lambda { |target, value| target.instance_exec(value, &l) }
+        # when Conditionals::Value then filter
+        when ::Proc
+          if filter.arity > 1
+            return lambda { |target, _, &block|
+              raise ArgumentError unless block
+              target.instance_exec(target, block, &filter)
+            }
+          end
+
+          if filter.arity <= 0
+            lambda { |target, _| target.instance_exec(&filter) }
+          else
+            lambda { |target, _| target.instance_exec(target, &filter) }
+          end
+        else
+          scopes = Array(chain_config[:scope])
+          method_to_call = scopes.map{ |s| public_send(s) }.join("_")
+
+          lambda { |target, _, &blk|
+            filter.public_send method_to_call, target, &blk
+          }
+        end
+      end
+
+      # From https://github.com/rails/rails/blob/bca2e69b785fa3cdbe148b0d2dd5d3b58f6daf53/activesupport/lib/active_support/callbacks.rb#L410
+      def compute_identifier(filter)
+        case filter
+        when String, ::Proc
+          filter.object_id
+        else
+          filter
+        end
+      end
+
+      # From https://github.com/rails/rails/blob/bca2e69b785fa3cdbe148b0d2dd5d3b58f6daf53/activesupport/lib/active_support/callbacks.rb#L419
+      def conditions_lambdas
+        @if.map { |c| make_lambda c } +
+          @unless.map { |c| invert_lambda make_lambda c }
+      end
+    end
+  end
+end

data/lib/workflow/specification.rb

@@ -0,0 +1,137 @@
+require 'workflow/state'
+require 'workflow/event'
+require 'workflow/errors'
+require 'active_support/callbacks'
+
+module Workflow
+  # Metadata object describing available states and state transitions.
+  class Specification
+    include ActiveSupport::Callbacks
+
+    # The state objects defined for this specification, keyed by name
+    # @return [Hash]
+    attr_reader :states
+
+    # State object to be given to newly created objects under this workflow.
+    # @return [State]
+    attr_reader :initial_state
+
+    # Optional metadata stored with this workflow specification
+    # @return [Hash]
+    attr_reader :meta
+
+    # List of symbols, for attribute accessors to be added to {TransitionContext} object
+    # @return [Array]
+    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|
+        state.events.each do |event|
+          event.transitions.each do |transition|
+            target_state = spec.find_state(transition.target_state)
+            unless target_state.present?
+              raise Workflow::Errors::WorkflowDefinitionError.new("Event #{event.name} transitions to #{transition.target_state} but there is no such state.")
+            end
+            transition.target_state = target_state
+          end
+        end
+      end
+    end
+
+    def find_state(name)
+      states.find{|t| t.name == name.to_sym}
+    end
+
+
+
+
+    # @api private
+    #
+    # @param [Hash] meta Metadata
+    # @yield [] Block for workflow definition
+    # @return [Specification]
+    def initialize(meta = {}, &specification)
+      @states = []
+      @meta = meta
+      run_callbacks :spec_definition do
+        instance_eval(&specification)
+      end
+    end
+
+    # Define a new state named [name]
+    #
+    # @param [Symbol] name name of state
+    # @param [Hash] meta Metadata to be stored with the state within the {Specification} object
+    # @yield [] block defining events for this state.
+    # @return [nil]
+    def state(name, meta: {}, &events)
+      name = name.to_sym
+      new_state = Workflow::State.new(name, self, 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
+    # the event transit method call.
+    #
+    # @param [Array] names A list of symbols
+    # @return [nil]
+    def event_args(*names)
+      @named_arguments = names
+    end
+
+
+    # Also create additional event transitions that will move each configured transition
+    # in the reverse direction.
+    #
+    # @return [nil]
+    #
+    #```ruby
+    # class Article
+    #   include Workflow
+    #   workflow do
+    #     define_revert_events!
+    #     state :foo do
+    #       event :bar, transitions_to: :bax
+    #     end
+    #     state :bax
+    #   end
+    # end
+    #
+    # a = Article.new
+    # a.process_event! :foo
+    # a.current_state.name          # => :bax
+    # a.process_event! :revert_bar
+    # a.current_state.name          # => :foo
+    #```
+    def define_revert_events!
+      @define_revert_events = true
+    end
+
+    private
+
+
+    def define_revert_events?
+      !!@define_revert_events
+    end
+
+  end
+end

data/lib/workflow/state.rb

@@ -0,0 +1,88 @@
+module Workflow
+  class State
+    include Comparable
+
+    attr_accessor :name, :events, :meta, :on_entry, :on_exit
+    attr_reader :sequence
+
+    def initialize(name, sequence, **meta)
+      @name, @sequence, @events, @meta = name.to_sym, sequence, [], meta
+    end
+
+    def find_event(name)
+      events.find{|t| t.name == name}
+    end
+
+    # Define an event on this specification.
+    # Must be called within the scope of the block within a call to {#state}.
+    #
+    # @param [Symbol] name The name of the event
+    # @param [Hash] args
+    # @option args [Symbol] :transitions_to The state this event transitions to.
+    # @option args [Symbol] :if optional instance method name or [Proc] that will receive the object when called.
+    # @option args [Hash] :meta Optional metadata to be stored on the event object
+    # @return [nil]
+    #
+    #```ruby
+    #workflow do
+    #  state :new do
+    #    on :review, to: :being_reviewed
+    #
+    #    on :submit do
+    #      to :submitted,
+    #        if:     [ "name == 'The Dude'", :abides?, -> (rug) {rug.tied_the_room_together?}],
+    #        unless: :nihilist?
+    #
+    #      to :trash, unless: :body?
+    #      to :another_place do |article|
+    #        article.foo?
+    #      end
+    #   end
+    # end
+    #
+    #  state :kitchen
+    #  state :the_bar
+    #  state :the_diner
+    #end
+    #```
+    def on(name, to: nil, meta: nil, &transitions)
+      if to && block_given?
+        raise Errors::WorkflowDefinitionError.new("Event target can only be received in the method call or the block, not both.")
+      end
+
+      unless to || block_given?
+        raise Errors::WorkflowDefinitionError.new("No event target given for event #{name}")
+      end
+
+      if find_event(name)
+        raise Errors::WorkflowDefinitionError.new("Already defined an event [#{name}] for state[#{self.name}]")
+      end
+
+      event = Workflow::Event.new(name, meta)
+
+      if to
+        event.to to
+      else
+        event.instance_eval(&transitions)
+      end
+
+      if event.transitions.empty?
+        raise Errors::WorkflowDefinitionError.new("No transitions defined for event [#{name}] on state [#{self.name}]")
+      end
+
+      events << event
+      nil
+    end
+
+    def inspect
+      "<State name=#{name.inspect} events(#{events.length})=#{events.inspect}>"
+    end
+
+    def <=>(other_state)
+      unless other_state.is_a?(State)
+        raise StandardError.new "Other State #{other_state} is a #{other_state.class}.  I can only be compared with a Workflow::State."
+      end
+      self.sequence <=> other_state.sequence
+    end
+  end
+end

data/lib/workflow/transition_context.rb

@@ -0,0 +1,54 @@
+module Workflow
+  # During transitions, an instance of this class can be found
+  # on the object as `transition_context`.
+  # Contains metadata related to the current transition underway.
+  #
+  # == To name parameters:
+  #
+  # During workflow definition, do the following:
+  #
+  #     before_transition :transition_handler
+  #
+  #     def transition_handler
+  #       transition_context.name1 #  will equal 1
+  #       transition_context.name2 #  will equal 2
+  #       transition_context.name3 #  will equal 3
+  #     end
+  #
+  #     workflow do
+  #       event_args :name1, :name2, :name3
+  #       state :foo do
+  #         event :bar, transitions_to: :bax
+  #       end
+  #     end
+  #
+  # Then later call:
+  #
+  #     my_obj.submit! 1, 2, 3
+  #
+  # The entire list of passed parameters will still be available on +event_args+.
+  # If you pass fewer parameters, the later ones will simply be nil.
+  class TransitionContext
+    attr_reader :from, :to, :event, :event_args, :attributes, :named_arguments
+    def initialize(from:, to:, event:, event_args:, attributes:, named_arguments: [])
+      @from = from
+      @to = to
+      @event = event
+      @event_args = event_args
+      @attributes = attributes
+      @named_arguments = (named_arguments || []).zip(event_args).to_h
+    end
+
+    def values
+      [from, to, event, event_args]
+    end
+
+    def method_missing(method, *args)
+      if named_arguments.key?(method)
+        named_arguments[method]
+      else
+        super
+      end
+    end
+  end
+end

data/lib/workflow/version.rb

@@ -0,0 +1,3 @@
+module Workflow
+  VERSION = "1.4.0"
+end