rails-workflow 1.4.5.4 → 1.4.6.4

data/lib/workflow/state.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Workflow
   # Represents one state for the defined workflow,
   # with a list of {Workflow::Event}s that can transition to
@@ -11,35 +12,45 @@ module Workflow
     #   @return [Array] Array of {Workflow::Event}s defined for this state.
     # @!attribute [r] meta
     #   @return [Hash] Extra information defined for this state.
-    attr_reader :name, :events, :meta
+    # @!attribute [r] tags
+    #   @return [Array] Tags for this state.
+    attr_reader :name, :events, :meta, :tags
 
     # @api private
     # For creating {Workflow::State} objects please see {Specification#state}
-    # @param [Symbol] name The name of the state being created.  Should be unique within its workflow.
-    # @param [Fixnum] sequence Sequencing number that will affect sorting comparisons with other states.
-    # @param [Hash] meta: Optional metadata for this state.
-    def initialize(name, sequence, meta: {})
-      @name, @sequence, @events, @meta = name.to_sym, sequence, [], meta
+    # @param [Symbol] name Name of the state being created. Must be unique within its workflow.
+    # @param [Fixnum] sequence Sort location among states on this workflow.
+    # @param [Hash] meta Optional metadata for this state.
+    def initialize(name, sequence, tags: [], meta: {})
+      @name = name.to_sym
+      @sequence = sequence
+      @events = []
+      @meta = meta
+      @tags = [tags].flatten
+      unless @tags.reject { |t| t.is_a? Symbol }
+        raise WorkflowDefinitionError, "Tags can only include symbols, state: #{name}"
+      end
     end
 
     # Returns the event with the given name.
     # @param [Symbol] name name of event to find
     # @return [Workflow::Event] The event with the given name, or `nil`
     def find_event(name)
-      events.find{|t| t.name == 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}.
+    # Must be called within the scope of the block within a call to {Workflow::Specification#state}.
     #
     # @param [Symbol] name The name of the event
-    # @param [Symbol] to: Optional name of {Workflow::State} this event will transition to.  Must be omitted if a block is provided.
-    # @param [Hash] meta: Optional hash of metadata to be stored on the event object.
+    # @param [Symbol] to Optional name of {Workflow::State} this event will transition to.
+    #                     Must be omitted if a block is provided.
+    # @param [Hash] meta Optional hash of metadata to be stored on the event object.
     # @yield [] Transitions definition for this event.
     # @return [nil]
     #
-    #```ruby
-    #workflow do
+    # ```ruby
+    # workflow do
     #  state :new do
     #    on :review, to: :being_reviewed
     #
@@ -58,21 +69,10 @@ module Workflow
     #  state :kitchen
     #  state :the_bar
     #  state :the_diner
-    #end
-    #```
+    # end
+    # ```
     def on(name, to: nil, meta: {}, &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
-
+      check_can_add_transition!(name, to: to, &transitions)
       event = Workflow::Event.new(name, meta: meta)
 
       if to
@@ -81,14 +81,24 @@ module Workflow
         event.instance_eval(&transitions)
       end
 
-      if event.transitions.empty?
-        raise Errors::WorkflowDefinitionError.new("No transitions defined for event [#{name}] on state [#{self.name}]")
+      unless event.valid?
+        raise Errors::NoTransitionsDefinedError.new(self, event)
       end
 
       events << event
       nil
     end
 
+    private def check_can_add_transition!(name, to: nil)
+      raise Errors::DualEventDefinitionError if to && block_given?
+
+      unless to || block_given?
+        raise Errors::WorkflowDefinitionError, "No event target given for event #{name}"
+      end
+
+      raise Errors::EventNameCollisionError.new(self, name) if find_event(name)
+    end
+
     # @return [String] String representation of object
     def inspect
       "<State name=#{name.inspect} events(#{events.length})=#{events.inspect}>"
@@ -97,20 +107,19 @@ module Workflow
     # Overloaded comparison operator.  Workflow states are sorted according to the order
     # in which they were defined.
     #
-    # @param [Workflow::State] other_state state to be compared against.
+    # @param [Workflow::State] other state to be compared against.
     # @return [Integer]
-    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.send(:sequence)
+    def <=>(other)
+      raise Errors::StateComparisonError, other unless other.is_a?(State)
+      sequence <=> other.send(:sequence)
     end
 
     private
+
     # @api private
     # @!attribute [r] sequence
-    #   @return [Fixnum] The position of this state within the order it was defined for in its workflow.
+    #   @return [Fixnum] The position of this state within the
+    #                     order it was defined for in its workflow.
     attr_reader :sequence
-
   end
 end

data/lib/workflow/transition_context.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Workflow
   # During transitions, an instance of this class can be found
   # on the object as `transition_context`.
@@ -30,20 +31,20 @@ module Workflow
   # 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: [])
+    def initialize(from:, to:, event:, event_args:, **args)
       @from = from
       @to = to
       @event = event
       @event_args = event_args
-      @attributes = attributes
-      @named_arguments = (named_arguments || []).zip(event_args).to_h
+      @attributes = args[:attributes] || {}
+      @named_arguments = (args[:named_arguments] || []).zip(event_args).to_h
     end
 
     def values
       [from, to, event, event_args.dup, attributes.dup]
     end
 
-    def respond_to?(method)
+    def respond_to_missing?(method, _include_private = false)
       named_arguments.key?(method) || super
     end
 

data/lib/workflow/transitions.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+module Workflow
+  module Transitions
+    extend ActiveSupport::Concern
+
+    # @api private
+    # @!attribute [r] transition_context
+    # @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.
+    included do
+      attr_reader :transition_context
+    end
+
+    # Initiates state transition via the named event
+    #
+    # @param [Symbol] name name of event to initiate
+    # @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)
+      @transition_context = prepare_transition(name, args, attributes)
+
+      run_all_callbacks do
+        persist_workflow_state(@transition_context.to)
+      end
+    ensure
+      @transition_context = nil
+    end
+
+    # Stop the current transition and set the reason for the abort.
+    #
+    # @param [String] reason Optional reason for halting transition.
+    # @return [nil]
+    def halt(reason = nil)
+      @halted_because = reason
+      @halted = true
+      throw :abort
+    end
+
+    # Sets halt reason and raises [TransitionHaltedError] error.
+    #
+    # @param [String] reason Optional reason for halting
+    # @return [nil]
+    def halt!(reason = nil)
+      @halted_because = reason
+      @halted = true
+      raise Errors::TransitionHaltedError, reason
+    end
+
+    # Deprecated.  Check for false return value from {#transition!}
+    # @return [Boolean] 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
+
+    # 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
+
+    def prepare_transition(name, args, attributes)
+      event = current_state.find_event(name.to_sym)
+      raise Errors::NoTransitionAllowed.new(current_state, name) unless event
+
+      target = event.evaluate(self)
+
+      TransitionContext.new \
+        from: current_state.name,
+        to: target.name,
+        event: event.name,
+        event_args: args,
+        attributes: attributes,
+        named_arguments: workflow_spec.named_arguments
+    end
+  end
+end

data/lib/workflow/version.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Workflow
-  VERSION = "1.4.5.4"
+  VERSION = '1.4.6.4'
 end

data/rails-workflow.gemspec

@@ -1,41 +1,42 @@
 # coding: utf-8
+# frozen_string_literal: true
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'workflow/version'
 Gem::Specification.new do |spec|
-  spec.name          = "rails-workflow"
+  spec.name          = 'rails-workflow'
   spec.version       = Workflow::VERSION
-  spec.authors       = ["Tyler Gannon"]
-  spec.email         = ["tyler@aprilseven.co"]
+  spec.authors       = ['Tyler Gannon']
+  spec.email         = ['tyler@aprilseven.co']
 
-  spec.summary       = %q{A finite-state-machine-inspired API for managing state changes in ActiveModel objects.  Based on Vladimir Dobriakov's Workflow gem (https://github.com/geekq/workflow)}
-  spec.description   = %q{Workflow specifically for ActiveModel objects.}
-  spec.homepage      = "https://tylergannon.github.io/rails-workflow/"
-  spec.license       = "MIT"
+  spec.summary       = "A finite-state-machine-inspired API for managing state changes in ActiveModel objects.  Based on Vladimir Dobriakov's Workflow gem (https://github.com/geekq/workflow)"
+  spec.description   = 'Workflow specifically for ActiveModel objects.'
+  spec.homepage      = 'https://tylergannon.github.io/rails-workflow/'
+  spec.license       = 'MIT'
 
   # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
   # to allow pushing to a single host or delete this section to allow pushing to any host.
   if spec.respond_to?(:metadata)
-    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+    spec.metadata['allowed_push_host'] = 'https://rubygems.org'
   else
-    raise "RubyGems 2.0 or newer is required to protect against " \
-      "public gem pushes."
+    raise 'RubyGems 2.0 or newer is required to protect against ' \
+      'public gem pushes.'
   end
 
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features|doc)/})
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
   spec.extra_rdoc_files = [
-    "README.markdown"
+    'README.markdown'
   ]
 
   spec.add_dependency 'activerecord', '~> 5.0'
   spec.add_dependency 'activesupport', '~> 5.0'
 
-  spec.add_development_dependency 'rdoc',    [">= 3.12"]
+  spec.add_development_dependency 'rdoc', ['>= 3.12']
   spec.add_development_dependency 'sqlite3'
   spec.add_development_dependency 'mocha'
   spec.add_development_dependency 'yard'
@@ -44,8 +45,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'test-unit'
   spec.add_development_dependency 'ruby-graphviz', ['~> 1.0.0']
-  spec.add_development_dependency "bundler", "~> 1.13"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency 'bundler', '~> 1.13'
+  spec.add_development_dependency 'rspec', '~> 3.0'
   spec.required_ruby_version = '>= 2.3'
-
 end

data/tags.markdown

@@ -0,0 +1,31 @@
+---
+layout: page
+---
+
+# Tagging States
+
+Place your workflow states into groups by tagging them.
+Also note the helper methods `initial?` and `terminal?`.
+
+```ruby
+class Foo
+  include Workflow
+  state :new, tags: :bar do
+    on :complete, to: :completed
+  end
+  state :completed, tags: [:awesome, :congrats]
+end
+
+a = Foo.new
+a.current_state.bar?
+# => true
+a.current_state.initial?
+# => true
+a.awesome?
+# => false
+a.transition! :complete
+a.terminal?
+# => true
+a.awesome?
+# => true
+```

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-workflow
 version: !ruby/object:Gem::Version
-  version: 1.4.5.4
+  version: 1.4.6.4
 platform: ruby
 authors:
 - Tyler Gannon
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-25 00:00:00.000000000 Z
+date: 2016-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -201,6 +201,7 @@ extra_rdoc_files:
 - README.markdown
 files:
 - ".gitignore"
+- ".rubocop.yml"
 - ".travis.yml"
 - ".yardopts"
 - Gemfile
@@ -219,22 +220,29 @@ files:
 - lib/workflow.rb
 - lib/workflow/adapters/active_record.rb
 - lib/workflow/adapters/active_record_validations.rb
+- lib/workflow/adapters/adapter.rb
 - lib/workflow/adapters/remodel.rb
 - lib/workflow/callbacks.rb
 - lib/workflow/callbacks/callback.rb
+- lib/workflow/callbacks/method_callback.rb
+- lib/workflow/callbacks/proc_callback.rb
+- lib/workflow/callbacks/string_callback.rb
 - lib/workflow/callbacks/transition_callback.rb
-- lib/workflow/callbacks/transition_callbacks/method_wrapper.rb
-- lib/workflow/callbacks/transition_callbacks/proc_wrapper.rb
+- lib/workflow/callbacks/transition_callbacks/method_caller.rb
+- lib/workflow/callbacks/transition_callbacks/proc_caller.rb
 - lib/workflow/configuration.rb
-- lib/workflow/draw.rb
+- lib/workflow/definition.rb
 - lib/workflow/errors.rb
 - lib/workflow/event.rb
+- lib/workflow/helper_method_configurator.rb
 - lib/workflow/specification.rb
 - lib/workflow/state.rb
 - lib/workflow/transition_context.rb
+- lib/workflow/transitions.rb
 - lib/workflow/version.rb
 - orders_workflow.png
 - rails-workflow.gemspec
+- tags.markdown
 homepage: https://tylergannon.github.io/rails-workflow/
 licenses:
 - MIT

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

@@ -1,102 +0,0 @@
-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